From dc55ad555855d790784b254f09a5330149dbfcc2 Mon Sep 17 00:00:00 2001 From: Ivan Kamkin Date: Thu, 9 Apr 2026 15:36:37 +0500 Subject: [PATCH 1/3] Add skill --- skills/aspose-barcode-cloud-java/SKILL.md | 163 ++++++++++++++++++ .../agents/openai.yaml | 4 + .../references/repo-workflow.md | 72 ++++++++ .../references/snippet-map.md | 42 +++++ 4 files changed, 281 insertions(+) create mode 100644 skills/aspose-barcode-cloud-java/SKILL.md create mode 100644 skills/aspose-barcode-cloud-java/agents/openai.yaml create mode 100644 skills/aspose-barcode-cloud-java/references/repo-workflow.md create mode 100644 skills/aspose-barcode-cloud-java/references/snippet-map.md diff --git a/skills/aspose-barcode-cloud-java/SKILL.md b/skills/aspose-barcode-cloud-java/SKILL.md new file mode 100644 index 0000000..f5a1f72 --- /dev/null +++ b/skills/aspose-barcode-cloud-java/SKILL.md @@ -0,0 +1,163 @@ +--- +name: aspose-barcode-cloud-java +description: "Write or update Java code that uses the Aspose.BarCode Cloud SDK (`com.aspose.barcode.cloud.*`; Maven artifact `com.aspose:aspose-barcode-cloud`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in Java, touches files under `submodules/java`, or mentions `ApiClient`, `Configuration`, `GenerateApi`, `RecognizeApi`, `ScanApi`, `GenerateParams`, `RecognizeBase64Request`, `ScanBase64Request`, or the `*RequestWrapper` classes. The Java SDK has several easy-to-miss idioms: generate methods return `File`, every API call goes through wrapper objects, GET recognize/scan methods require a public `URI`, base64 methods expect caller-encoded data, tests prefer `src/test/configuration.json` or `TEST_CONFIGURATION_ACCESS_TOKEN`, and repo scripts should run through WSL on Windows, so consult this skill instead of guessing." +--- + +# Aspose.BarCode Cloud SDK for Java + +The Java SDK is a thin generated client over the Aspose BarCode Cloud REST API. Most tasks boil down to choosing the right API class (`GenerateApi`, `RecognizeApi`, `ScanApi`), picking the right auth path with `ApiClient` or `Configuration`, and building the matching `*RequestWrapper`. + +The Maven artifact and package names differ. Install `com.aspose:aspose-barcode-cloud`, then import classes from `com.aspose.barcode.cloud.*`. + +## Quick start + +Use these imports in most Java examples: + +```java +import com.aspose.barcode.cloud.ApiClient; +import com.aspose.barcode.cloud.Configuration; +import com.aspose.barcode.cloud.api.GenerateApi; +import com.aspose.barcode.cloud.api.RecognizeApi; +import com.aspose.barcode.cloud.api.ScanApi; +import com.aspose.barcode.cloud.model.*; +import com.aspose.barcode.cloud.requests.*; +``` + +Prefer one of these setup patterns: + +```java +ApiClient client = new ApiClient(clientId, clientSecret); +GenerateApi generateApi = new GenerateApi(client); +RecognizeApi recognizeApi = new RecognizeApi(client); +ScanApi scanApi = new ScanApi(client); +``` + +```java +Configuration config = new Configuration(); +config.ClientId = clientId; +config.ClientSecret = clientSecret; +ApiClient client = config.buildApiClient(); +``` + +```java +Configuration config = new Configuration(); +config.AccessToken = accessToken; +ApiClient client = config.buildApiClient(); +``` + +If the task is repo maintenance inside `submodules/java`, read `references/repo-workflow.md`. If the task needs a closest existing example or snippet, read `references/snippet-map.md`. + +## Authentication + +Use one of these two auth modes: + +1. Let the SDK fetch the token for you. + +```java +ApiClient client = new ApiClient(clientId, clientSecret); +``` + +2. Inject a pre-fetched bearer token. + +```java +ApiClient client = new ApiClient(accessToken); +``` + +`Configuration.buildApiClient()` follows the same rule: if `Configuration.AccessToken` is non-null, it builds token mode and ignores `ClientId`/`ClientSecret`. + +The README still mentions Java 8, but `submodules/java/pom.xml` currently compiles with source and target level `11`. Follow the build file, not the older README note. + +The upstream README recommends one `ApiClient` instance per thread in multithreaded code. Keep that guidance when writing examples or concurrent integrations. + +## Choose the right API shape + +Pick the operation first: + +- `GenerateApi`: create a barcode image. +- `RecognizeApi`: decode one or more expected barcode types and optionally tune recognition. +- `ScanApi`: auto-detect barcode types with the smallest API surface. + +Then pick the transport variant based on what the caller has: + +- Public internet URL: use `recognize(...)` or `scan(...)` with `RecognizeRequestWrapper` or `ScanRequestWrapper`. +- Local file on disk: use `recognizeMultipart(...)` or `scanMultipart(...)`. +- Raw bytes already in memory: base64-encode them yourself and use `recognizeBase64(...)` or `scanBase64(...)`. +- Simple generation with query-like parameters: use `generate(...)`. +- Structured generation payload: use `generateBody(...)` with `GenerateParams`. +- Multipart generation: use `generateMultipart(...)` only when the caller explicitly needs the multipart form variant. + +Key method names: + +- `generate` +- `generateBody` +- `generateMultipart` +- `recognize` +- `recognizeBase64` +- `recognizeMultipart` +- `scan` +- `scanBase64` +- `scanMultipart` + +## Non-obvious SDK rules + +1. `generate`, `generateBody`, and `generateMultipart` return `java.io.File`, not bytes or an input stream. Move or copy the returned file if you need a stable destination. +2. Every public operation takes a `*RequestWrapper`. Required arguments go into the wrapper constructor; optional parameters are set on public fields or nested models after construction. +3. `RecognizeRequestWrapper` and `ScanRequestWrapper` take a public `URI`. Do not pass local filesystem paths there; use multipart or base64 for local files. +4. `RecognizeBase64Request` and `ScanBase64Request` expect an already-encoded base64 string. The SDK does not call `Base64.getEncoder().encodeToString(...)` for you. +5. `RecognizeBase64Request` takes `List`, but `RecognizeRequestWrapper` and `RecognizeMultipartRequestWrapper` take a single `DecodeBarcodeType`. +6. `ScanApi` never takes barcode types. Use it when the caller wants auto-detection. +7. `BarcodeResponseList` may contain multiple barcodes. Iterate `response.getBarcodes()` instead of assuming a single result. +8. API failures throw `ApiException`. Turn on logging with `client.setDebugging(true)` when request or response details would help. +9. Repo tests first load `src/test/configuration.json`; if that file is absent, `TestConfiguration` only falls back to `TEST_CONFIGURATION_ACCESS_TOKEN`. Client-id and client-secret environment variables are not part of the Java test harness fallback. + +## Common patterns + +Generate and save a QR code: + +```java +ApiClient client = new ApiClient(clientId, clientSecret); +GenerateApi api = new GenerateApi(client); + +GenerateRequestWrapper request = new GenerateRequestWrapper(EncodeBarcodeType.QR, "hello from Java"); +request.imageFormat = BarcodeImageFormat.PNG; +request.textLocation = CodeLocation.NONE; + +File generated = api.generate(request); +Files.move(generated.toPath(), Paths.get("qr.png"), StandardCopyOption.REPLACE_EXISTING); +``` + +Recognize specific barcode types from bytes already in memory: + +```java +byte[] bytes = Files.readAllBytes(Paths.get("many-types.png")); +String fileBase64 = Base64.getEncoder().encodeToString(bytes); + +RecognizeBase64Request body = + new RecognizeBase64Request(Arrays.asList(DecodeBarcodeType.QR, DecodeBarcodeType.CODE128), fileBase64); +BarcodeResponseList result = + new RecognizeApi(client).recognizeBase64(new RecognizeBase64RequestWrapper(body)); +``` + +Auto-scan a local file without specifying the barcode type: + +```java +File image = Paths.get("unknown.png").toFile(); +BarcodeResponseList result = + new ScanApi(client).scanMultipart(new ScanMultipartRequestWrapper(image)); +``` + +## Working in this repo + +Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, Maven metadata, README examples, or generated code in `submodules/java`. + +Read `references/snippet-map.md` when the task needs the closest existing pattern for generate, recognize, scan, auth, or repo-test scenarios. + +## Final checklist + +1. Use the correct artifact and package pair: Maven `com.aspose:aspose-barcode-cloud`, imports under `com.aspose.barcode.cloud.*`. +2. Choose `ApiClient(clientId, clientSecret)`, `ApiClient(accessToken)`, or `Configuration.buildApiClient()` deliberately. +3. Pick GET only for public `URI`s, multipart for local files, and base64 for in-memory bytes. +4. Build the right `*RequestWrapper` and set optional public fields after construction. +5. Base64-encode request bodies yourself before calling `recognizeBase64` or `scanBase64`. +6. Handle returned `File` objects from generate calls and multiple entries in `response.getBarcodes()`. +7. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`. diff --git a/skills/aspose-barcode-cloud-java/agents/openai.yaml b/skills/aspose-barcode-cloud-java/agents/openai.yaml new file mode 100644 index 0000000..0a19fcb --- /dev/null +++ b/skills/aspose-barcode-cloud-java/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Aspose BarCode Cloud Java" + short_description: "Build and maintain Java barcode SDK code" + default_prompt: "Use $aspose-barcode-cloud-java to write or update Java code with the Aspose.BarCode Cloud SDK." diff --git a/skills/aspose-barcode-cloud-java/references/repo-workflow.md b/skills/aspose-barcode-cloud-java/references/repo-workflow.md new file mode 100644 index 0000000..a565ec6 --- /dev/null +++ b/skills/aspose-barcode-cloud-java/references/repo-workflow.md @@ -0,0 +1,72 @@ +# Java submodule workflow + +Use this reference when the task edits SDK source, tests, snippets, docs, Maven metadata, or generated files inside `submodules/java`. + +## Layout + +- `src/main/java/com/aspose/barcode/cloud`: `ApiClient`, `Configuration`, `ApiException`, JSON helpers, auth, and HTTP plumbing. +- `src/main/java/com/aspose/barcode/cloud/api`: generated API clients such as `GenerateApi`, `RecognizeApi`, and `ScanApi`. +- `src/main/java/com/aspose/barcode/cloud/model`: request and response models plus enums. +- `src/main/java/com/aspose/barcode/cloud/requests`: wrapper classes that split required constructor arguments from optional public fields. +- `src/test/java/com/aspose/barcode/cloud/test`: integration-style tests for configuration, auth, generate, recognize, scan, and end-to-end flows. +- `src/test/java/com/aspose/barcode/cloud/api`: unit tests for request validation, path construction, and async/execute wiring. +- `src/test/java/com/aspose/barcode/cloud/examples/Example.java`: small standalone sample that generates then scans a barcode. +- `snippets`: documentation snippets executed by the snippet runner. +- `scripts`: post-processing, formatting, snippet execution, and README example insertion helpers. +- `pom.xml`: package metadata, Java version, dependencies, JaCoCo thresholds, and Maven plugins. + +## Validation + +On Windows, run repo scripts and Make targets through WSL. + +From `submodules/java`: + +- `make build` +- `make test` +- `make lint` +- `make format` +- `make fix` + +`make build` does: + +- `mvn compile -Dmaven.test.skip=true` +- `mvn dependency:copy-dependencies -DoutputDirectory=target/lib/` + +`make test` does more than `mvn test`: + +- runs `mvn test` +- copies dependencies into `target/lib/` +- runs `./scripts/run_snippets.sh` + +`run_snippets.sh` creates a temporary `snippets_test` directory, links `target`, and executes every snippet through `scripts/run_snippet.sh`. Treat snippet failures as package-consumer regressions, not just sample breakage. + +`make after-gen` runs `fix`, `format`, and `insert-example`. The root-level `make java` path already invokes `make after-gen` at the end of generation. + +## Test configuration + +- Minimal JSON shape lives in `src/test/configuration.example.json`. +- Tests load `src/test/configuration.json` first. +- If the config file is absent, `TestConfiguration.load()` falls back to `TEST_CONFIGURATION_ACCESS_TOKEN` only. +- The Java test harness does not fall back to `TEST_CONFIGURATION_CLIENT_ID` or `TEST_CONFIGURATION_CLIENT_SECRET`. +- Snippets commonly mirror the same choice: use `TEST_CONFIGURATION_ACCESS_TOKEN` when present, otherwise rely on placeholder credentials in sample code. + +## Regenerated code workflow + +If you change generated SDK code in this mono-repo: + +1. Make the desired SDK edit in `submodules/java` so the target behavior is clear. +2. Mirror the change in the matching template under `codegen/Templates/java` when the file is generated. If the relevant template does not exist locally, copy it in from the upstream OpenAPI Generator templates first and edit the local copy. +3. Stage the Java submodule changes. +4. From the repo root, run `make java` through WSL on Windows. +5. `codegen/generate-java.bash` regenerates into `.generated/java`, splits wrapper classes into `src/main/java/com/aspose/barcode/cloud/requests`, refreshes `api`, `model`, `docs`, `pom.xml`, and `README.template`, then runs `make after-gen` in `submodules/java`. +6. Ensure `submodules/java` has no new unstaged diffs after regeneration. +7. If regeneration reintroduces old code, keep fixing the templates until generated output matches the intended SDK change. + +## Useful anchors + +- `pom.xml`: artifact id `com.aspose:aspose-barcode-cloud`, Java compiler level `11`, and JaCoCo coverage rules. +- `src/main/java/com/aspose/barcode/cloud/Configuration.java`: access-token versus client-id/client-secret behavior. +- `src/test/java/com/aspose/barcode/cloud/test/TestConfiguration.java`: repo auth fallback rules. +- `scripts/run_snippets.sh`: snippet execution pipeline. +- `scripts/insert-example.bash`: README generation entry point. +- `codegen/generate-java.bash`: main regen script for this submodule. diff --git a/skills/aspose-barcode-cloud-java/references/snippet-map.md b/skills/aspose-barcode-cloud-java/references/snippet-map.md new file mode 100644 index 0000000..c7d05d9 --- /dev/null +++ b/skills/aspose-barcode-cloud-java/references/snippet-map.md @@ -0,0 +1,42 @@ +# Snippet and example map + +Use this reference when you want the closest existing pattern before writing new Java SDK code or when updating docs, snippets, and examples. + +## Small end-user examples + +- `src/test/java/com/aspose/barcode/cloud/examples/Example.java`: minimal generate-then-scan flow using `GenerateApi` and `ScanApi`. +- `snippets/ManualFetchToken.java`: manual OAuth client-credentials token fetch without the SDK. + +## Generate patterns + +- `snippets/generate/save/GenerateGet.java`: simple `generate(...)` and save-to-file flow. +- `snippets/generate/save/GenerateBody.java`: `generateBody(...)` with `GenerateParams`. +- `snippets/generate/save/GenerateMultipart.java`: multipart generation flow. +- `snippets/generate/set-text/*`: `EncodeData` and `EncodeDataType` examples. +- `snippets/generate/set-size/*`: width, height, resolution, and units examples. +- `snippets/generate/set-colorscheme/*`: foreground and background color examples. +- `snippets/generate/appearance/*`: richer `BarcodeImageParams` examples. + +## Recognize and scan patterns + +- `snippets/read/set-source/RecognizeGet.java`: recognize from a public URL. +- `snippets/read/set-source/RecognizeMultipart.java`: recognize from a local file. +- `snippets/read/set-source/RecognizeBody.java`: recognize from base64 bytes. +- `snippets/read/set-source/ScanGet.java`: auto-scan from a public URL. +- `snippets/read/set-source/ScanMultipart.java`: auto-scan from a local file. +- `snippets/read/set-source/ScanBody.java`: auto-scan from base64 bytes. +- `snippets/read/set-target-types/*`: choosing `DecodeBarcodeType` or `List`. +- `snippets/read/set-quality/*`: `RecognitionMode` examples. +- `snippets/read/set-image-kind/*`: `RecognitionImageKind` examples. + +## Tests worth copying + +- `src/test/java/com/aspose/barcode/cloud/test/EndToEndTest.java`: generate a barcode `File`, then scan that same file end to end. +- `src/test/java/com/aspose/barcode/cloud/test/GenerateApiTest.java`: generate via GET, body, and multipart variants. +- `src/test/java/com/aspose/barcode/cloud/test/RecognizeApiTest.java`: recognize via base64 body, multipart, and URL. +- `src/test/java/com/aspose/barcode/cloud/test/ScanApiTest.java`: scan via base64 body, multipart, and URL. +- `src/test/java/com/aspose/barcode/cloud/test/ConfigurationTest.java`: configuration defaults and `buildApiClient()` behavior. +- `src/test/java/com/aspose/barcode/cloud/test/ExceptionTest.java`: expected failures and exception behavior. +- `src/test/java/com/aspose/barcode/cloud/api/GenerateApiUnitTest.java`: request validation and generated request-path behavior. +- `src/test/java/com/aspose/barcode/cloud/api/RecognizeApiUnitTest.java`: recognize request validation, request-path behavior, and async wiring. +- `src/test/java/com/aspose/barcode/cloud/api/ScanApiUnitTest.java`: scan request validation, request-path behavior, and async wiring. From 45a176f6592f478dbbd1b44f2af96b3074242f5d Mon Sep 17 00:00:00 2001 From: Ivan Kamkin Date: Thu, 9 Apr 2026 16:02:06 +0500 Subject: [PATCH 2/3] Add AI agent skill section to README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 408d112..6de2d19 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,10 @@ This repository contains Aspose.BarCode Cloud SDK for Java source code. This SDK allows you to work with Aspose.BarCode for Cloud REST APIs in your Java applications quickly and easily. +## AI Agent Skills + +This repository includes an AI-agent skill in [`skills/aspose-barcode-cloud-java/SKILL.md`](skills/aspose-barcode-cloud-java/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns. + ## Requirements Building the API client library requires: From a2788cf6c5418fe9d73bac376c7a8d9755f571e2 Mon Sep 17 00:00:00 2001 From: Ivan Kamkin Date: Fri, 10 Apr 2026 13:46:06 +0500 Subject: [PATCH 3/3] Rename Java skill to generate-and-scan-barcode --- README.md | 3 +-- skills/aspose-barcode-cloud-java/agents/openai.yaml | 4 ---- .../SKILL.md | 4 ++-- skills/generate-and-scan-barcode-java/agents/openai.yaml | 4 ++++ .../references/repo-workflow.md | 0 .../references/snippet-map.md | 0 6 files changed, 7 insertions(+), 8 deletions(-) delete mode 100644 skills/aspose-barcode-cloud-java/agents/openai.yaml rename skills/{aspose-barcode-cloud-java => generate-and-scan-barcode-java}/SKILL.md (99%) create mode 100644 skills/generate-and-scan-barcode-java/agents/openai.yaml rename skills/{aspose-barcode-cloud-java => generate-and-scan-barcode-java}/references/repo-workflow.md (100%) rename skills/{aspose-barcode-cloud-java => generate-and-scan-barcode-java}/references/snippet-map.md (100%) diff --git a/README.md b/README.md index 6de2d19..7c031a6 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ This repository contains Aspose.BarCode Cloud SDK for Java source code. This SDK ## AI Agent Skills -This repository includes an AI-agent skill in [`skills/aspose-barcode-cloud-java/SKILL.md`](skills/aspose-barcode-cloud-java/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns. +This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-java/SKILL.md`](skills/generate-and-scan-barcode-java/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns. ## Requirements @@ -221,4 +221,3 @@ Authentication schemes defined for the API: ## Recommendation It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues. - diff --git a/skills/aspose-barcode-cloud-java/agents/openai.yaml b/skills/aspose-barcode-cloud-java/agents/openai.yaml deleted file mode 100644 index 0a19fcb..0000000 --- a/skills/aspose-barcode-cloud-java/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Aspose BarCode Cloud Java" - short_description: "Build and maintain Java barcode SDK code" - default_prompt: "Use $aspose-barcode-cloud-java to write or update Java code with the Aspose.BarCode Cloud SDK." diff --git a/skills/aspose-barcode-cloud-java/SKILL.md b/skills/generate-and-scan-barcode-java/SKILL.md similarity index 99% rename from skills/aspose-barcode-cloud-java/SKILL.md rename to skills/generate-and-scan-barcode-java/SKILL.md index f5a1f72..4006035 100644 --- a/skills/aspose-barcode-cloud-java/SKILL.md +++ b/skills/generate-and-scan-barcode-java/SKILL.md @@ -1,9 +1,9 @@ --- -name: aspose-barcode-cloud-java +name: generate-and-scan-barcode-java description: "Write or update Java code that uses the Aspose.BarCode Cloud SDK (`com.aspose.barcode.cloud.*`; Maven artifact `com.aspose:aspose-barcode-cloud`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in Java, touches files under `submodules/java`, or mentions `ApiClient`, `Configuration`, `GenerateApi`, `RecognizeApi`, `ScanApi`, `GenerateParams`, `RecognizeBase64Request`, `ScanBase64Request`, or the `*RequestWrapper` classes. The Java SDK has several easy-to-miss idioms: generate methods return `File`, every API call goes through wrapper objects, GET recognize/scan methods require a public `URI`, base64 methods expect caller-encoded data, tests prefer `src/test/configuration.json` or `TEST_CONFIGURATION_ACCESS_TOKEN`, and repo scripts should run through WSL on Windows, so consult this skill instead of guessing." --- -# Aspose.BarCode Cloud SDK for Java +# Generate and scan barcode in Java The Java SDK is a thin generated client over the Aspose BarCode Cloud REST API. Most tasks boil down to choosing the right API class (`GenerateApi`, `RecognizeApi`, `ScanApi`), picking the right auth path with `ApiClient` or `Configuration`, and building the matching `*RequestWrapper`. diff --git a/skills/generate-and-scan-barcode-java/agents/openai.yaml b/skills/generate-and-scan-barcode-java/agents/openai.yaml new file mode 100644 index 0000000..be6df51 --- /dev/null +++ b/skills/generate-and-scan-barcode-java/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Generate and scan barcode in Java" + short_description: "Use Aspose.BarCode Cloud from Java" + default_prompt: "Use $generate-and-scan-barcode-java to write or update Java code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud." diff --git a/skills/aspose-barcode-cloud-java/references/repo-workflow.md b/skills/generate-and-scan-barcode-java/references/repo-workflow.md similarity index 100% rename from skills/aspose-barcode-cloud-java/references/repo-workflow.md rename to skills/generate-and-scan-barcode-java/references/repo-workflow.md diff --git a/skills/aspose-barcode-cloud-java/references/snippet-map.md b/skills/generate-and-scan-barcode-java/references/snippet-map.md similarity index 100% rename from skills/aspose-barcode-cloud-java/references/snippet-map.md rename to skills/generate-and-scan-barcode-java/references/snippet-map.md