Skip to content

Commit abfde04

Browse files
ivankamkinDenis-Averin
ivankamkin
and
Denis-Averin
authored
Add skill for AI Agent (#107)
* Add skill * Add AI agent skill section to README * Rename Java skill to generate-and-scan-barcode --------- Co-authored-by: Denis Averin <[email protected]>
1 parent 423017d commit abfde04

File tree

5 files changed

+285
-1
lines changed

5 files changed

+285
-1
lines changed

‎README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@
2424

2525
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.
2626

27+
## AI Agent Skills
28+
29+
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.
30+
2731
## Requirements
2832

2933
Building the API client library requires:
@@ -217,4 +221,3 @@ Authentication schemes defined for the API:
217221
## Recommendation
218222

219223
It's recommended to create an instance of `ApiClient` per thread in a multithreaded environment to avoid any potential issues.
220-

‎skills/generate-and-scan-barcode-java/SKILL.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: generate-and-scan-barcode-java
3+
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."
4+
---
5+
6+
# Generate and scan barcode in Java
7+
8+
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`.
9+
10+
The Maven artifact and package names differ. Install `com.aspose:aspose-barcode-cloud`, then import classes from `com.aspose.barcode.cloud.*`.
11+
12+
## Quick start
13+
14+
Use these imports in most Java examples:
15+
16+
```java
17+
import com.aspose.barcode.cloud.ApiClient;
18+
import com.aspose.barcode.cloud.Configuration;
19+
import com.aspose.barcode.cloud.api.GenerateApi;
20+
import com.aspose.barcode.cloud.api.RecognizeApi;
21+
import com.aspose.barcode.cloud.api.ScanApi;
22+
import com.aspose.barcode.cloud.model.*;
23+
import com.aspose.barcode.cloud.requests.*;
24+
```
25+
26+
Prefer one of these setup patterns:
27+
28+
```java
29+
ApiClient client = new ApiClient(clientId, clientSecret);
30+
GenerateApi generateApi = new GenerateApi(client);
31+
RecognizeApi recognizeApi = new RecognizeApi(client);
32+
ScanApi scanApi = new ScanApi(client);
33+
```
34+
35+
```java
36+
Configuration config = new Configuration();
37+
config.ClientId = clientId;
38+
config.ClientSecret = clientSecret;
39+
ApiClient client = config.buildApiClient();
40+
```
41+
42+
```java
43+
Configuration config = new Configuration();
44+
config.AccessToken = accessToken;
45+
ApiClient client = config.buildApiClient();
46+
```
47+
48+
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`.
49+
50+
## Authentication
51+
52+
Use one of these two auth modes:
53+
54+
1. Let the SDK fetch the token for you.
55+
56+
```java
57+
ApiClient client = new ApiClient(clientId, clientSecret);
58+
```
59+
60+
2. Inject a pre-fetched bearer token.
61+
62+
```java
63+
ApiClient client = new ApiClient(accessToken);
64+
```
65+
66+
`Configuration.buildApiClient()` follows the same rule: if `Configuration.AccessToken` is non-null, it builds token mode and ignores `ClientId`/`ClientSecret`.
67+
68+
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.
69+
70+
The upstream README recommends one `ApiClient` instance per thread in multithreaded code. Keep that guidance when writing examples or concurrent integrations.
71+
72+
## Choose the right API shape
73+
74+
Pick the operation first:
75+
76+
- `GenerateApi`: create a barcode image.
77+
- `RecognizeApi`: decode one or more expected barcode types and optionally tune recognition.
78+
- `ScanApi`: auto-detect barcode types with the smallest API surface.
79+
80+
Then pick the transport variant based on what the caller has:
81+
82+
- Public internet URL: use `recognize(...)` or `scan(...)` with `RecognizeRequestWrapper` or `ScanRequestWrapper`.
83+
- Local file on disk: use `recognizeMultipart(...)` or `scanMultipart(...)`.
84+
- Raw bytes already in memory: base64-encode them yourself and use `recognizeBase64(...)` or `scanBase64(...)`.
85+
- Simple generation with query-like parameters: use `generate(...)`.
86+
- Structured generation payload: use `generateBody(...)` with `GenerateParams`.
87+
- Multipart generation: use `generateMultipart(...)` only when the caller explicitly needs the multipart form variant.
88+
89+
Key method names:
90+
91+
- `generate`
92+
- `generateBody`
93+
- `generateMultipart`
94+
- `recognize`
95+
- `recognizeBase64`
96+
- `recognizeMultipart`
97+
- `scan`
98+
- `scanBase64`
99+
- `scanMultipart`
100+
101+
## Non-obvious SDK rules
102+
103+
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.
104+
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.
105+
3. `RecognizeRequestWrapper` and `ScanRequestWrapper` take a public `URI`. Do not pass local filesystem paths there; use multipart or base64 for local files.
106+
4. `RecognizeBase64Request` and `ScanBase64Request` expect an already-encoded base64 string. The SDK does not call `Base64.getEncoder().encodeToString(...)` for you.
107+
5. `RecognizeBase64Request` takes `List<DecodeBarcodeType>`, but `RecognizeRequestWrapper` and `RecognizeMultipartRequestWrapper` take a single `DecodeBarcodeType`.
108+
6. `ScanApi` never takes barcode types. Use it when the caller wants auto-detection.
109+
7. `BarcodeResponseList` may contain multiple barcodes. Iterate `response.getBarcodes()` instead of assuming a single result.
110+
8. API failures throw `ApiException`. Turn on logging with `client.setDebugging(true)` when request or response details would help.
111+
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.
112+
113+
## Common patterns
114+
115+
Generate and save a QR code:
116+
117+
```java
118+
ApiClient client = new ApiClient(clientId, clientSecret);
119+
GenerateApi api = new GenerateApi(client);
120+
121+
GenerateRequestWrapper request = new GenerateRequestWrapper(EncodeBarcodeType.QR, "hello from Java");
122+
request.imageFormat = BarcodeImageFormat.PNG;
123+
request.textLocation = CodeLocation.NONE;
124+
125+
File generated = api.generate(request);
126+
Files.move(generated.toPath(), Paths.get("qr.png"), StandardCopyOption.REPLACE_EXISTING);
127+
```
128+
129+
Recognize specific barcode types from bytes already in memory:
130+
131+
```java
132+
byte[] bytes = Files.readAllBytes(Paths.get("many-types.png"));
133+
String fileBase64 = Base64.getEncoder().encodeToString(bytes);
134+
135+
RecognizeBase64Request body =
136+
new RecognizeBase64Request(Arrays.asList(DecodeBarcodeType.QR, DecodeBarcodeType.CODE128), fileBase64);
137+
BarcodeResponseList result =
138+
new RecognizeApi(client).recognizeBase64(new RecognizeBase64RequestWrapper(body));
139+
```
140+
141+
Auto-scan a local file without specifying the barcode type:
142+
143+
```java
144+
File image = Paths.get("unknown.png").toFile();
145+
BarcodeResponseList result =
146+
new ScanApi(client).scanMultipart(new ScanMultipartRequestWrapper(image));
147+
```
148+
149+
## Working in this repo
150+
151+
Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, Maven metadata, README examples, or generated code in `submodules/java`.
152+
153+
Read `references/snippet-map.md` when the task needs the closest existing pattern for generate, recognize, scan, auth, or repo-test scenarios.
154+
155+
## Final checklist
156+
157+
1. Use the correct artifact and package pair: Maven `com.aspose:aspose-barcode-cloud`, imports under `com.aspose.barcode.cloud.*`.
158+
2. Choose `ApiClient(clientId, clientSecret)`, `ApiClient(accessToken)`, or `Configuration.buildApiClient()` deliberately.
159+
3. Pick GET only for public `URI`s, multipart for local files, and base64 for in-memory bytes.
160+
4. Build the right `*RequestWrapper` and set optional public fields after construction.
161+
5. Base64-encode request bodies yourself before calling `recognizeBase64` or `scanBase64`.
162+
6. Handle returned `File` objects from generate calls and multiple entries in `response.getBarcodes()`.
163+
7. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`.

‎skills/generate-and-scan-barcode-java/agents/openai.yaml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
interface:
2+
display_name: "Generate and scan barcode in Java"
3+
short_description: "Use Aspose.BarCode Cloud from Java"
4+
default_prompt: "Use $generate-and-scan-barcode-java to write or update Java code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud."

‎skills/generate-and-scan-barcode-java/references/repo-workflow.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Java submodule workflow
2+
3+
Use this reference when the task edits SDK source, tests, snippets, docs, Maven metadata, or generated files inside `submodules/java`.
4+
5+
## Layout
6+
7+
- `src/main/java/com/aspose/barcode/cloud`: `ApiClient`, `Configuration`, `ApiException`, JSON helpers, auth, and HTTP plumbing.
8+
- `src/main/java/com/aspose/barcode/cloud/api`: generated API clients such as `GenerateApi`, `RecognizeApi`, and `ScanApi`.
9+
- `src/main/java/com/aspose/barcode/cloud/model`: request and response models plus enums.
10+
- `src/main/java/com/aspose/barcode/cloud/requests`: wrapper classes that split required constructor arguments from optional public fields.
11+
- `src/test/java/com/aspose/barcode/cloud/test`: integration-style tests for configuration, auth, generate, recognize, scan, and end-to-end flows.
12+
- `src/test/java/com/aspose/barcode/cloud/api`: unit tests for request validation, path construction, and async/execute wiring.
13+
- `src/test/java/com/aspose/barcode/cloud/examples/Example.java`: small standalone sample that generates then scans a barcode.
14+
- `snippets`: documentation snippets executed by the snippet runner.
15+
- `scripts`: post-processing, formatting, snippet execution, and README example insertion helpers.
16+
- `pom.xml`: package metadata, Java version, dependencies, JaCoCo thresholds, and Maven plugins.
17+
18+
## Validation
19+
20+
On Windows, run repo scripts and Make targets through WSL.
21+
22+
From `submodules/java`:
23+
24+
- `make build`
25+
- `make test`
26+
- `make lint`
27+
- `make format`
28+
- `make fix`
29+
30+
`make build` does:
31+
32+
- `mvn compile -Dmaven.test.skip=true`
33+
- `mvn dependency:copy-dependencies -DoutputDirectory=target/lib/`
34+
35+
`make test` does more than `mvn test`:
36+
37+
- runs `mvn test`
38+
- copies dependencies into `target/lib/`
39+
- runs `./scripts/run_snippets.sh`
40+
41+
`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.
42+
43+
`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.
44+
45+
## Test configuration
46+
47+
- Minimal JSON shape lives in `src/test/configuration.example.json`.
48+
- Tests load `src/test/configuration.json` first.
49+
- If the config file is absent, `TestConfiguration.load()` falls back to `TEST_CONFIGURATION_ACCESS_TOKEN` only.
50+
- The Java test harness does not fall back to `TEST_CONFIGURATION_CLIENT_ID` or `TEST_CONFIGURATION_CLIENT_SECRET`.
51+
- Snippets commonly mirror the same choice: use `TEST_CONFIGURATION_ACCESS_TOKEN` when present, otherwise rely on placeholder credentials in sample code.
52+
53+
## Regenerated code workflow
54+
55+
If you change generated SDK code in this mono-repo:
56+
57+
1. Make the desired SDK edit in `submodules/java` so the target behavior is clear.
58+
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.
59+
3. Stage the Java submodule changes.
60+
4. From the repo root, run `make java` through WSL on Windows.
61+
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`.
62+
6. Ensure `submodules/java` has no new unstaged diffs after regeneration.
63+
7. If regeneration reintroduces old code, keep fixing the templates until generated output matches the intended SDK change.
64+
65+
## Useful anchors
66+
67+
- `pom.xml`: artifact id `com.aspose:aspose-barcode-cloud`, Java compiler level `11`, and JaCoCo coverage rules.
68+
- `src/main/java/com/aspose/barcode/cloud/Configuration.java`: access-token versus client-id/client-secret behavior.
69+
- `src/test/java/com/aspose/barcode/cloud/test/TestConfiguration.java`: repo auth fallback rules.
70+
- `scripts/run_snippets.sh`: snippet execution pipeline.
71+
- `scripts/insert-example.bash`: README generation entry point.
72+
- `codegen/generate-java.bash`: main regen script for this submodule.

‎skills/generate-and-scan-barcode-java/references/snippet-map.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Snippet and example map
2+
3+
Use this reference when you want the closest existing pattern before writing new Java SDK code or when updating docs, snippets, and examples.
4+
5+
## Small end-user examples
6+
7+
- `src/test/java/com/aspose/barcode/cloud/examples/Example.java`: minimal generate-then-scan flow using `GenerateApi` and `ScanApi`.
8+
- `snippets/ManualFetchToken.java`: manual OAuth client-credentials token fetch without the SDK.
9+
10+
## Generate patterns
11+
12+
- `snippets/generate/save/GenerateGet.java`: simple `generate(...)` and save-to-file flow.
13+
- `snippets/generate/save/GenerateBody.java`: `generateBody(...)` with `GenerateParams`.
14+
- `snippets/generate/save/GenerateMultipart.java`: multipart generation flow.
15+
- `snippets/generate/set-text/*`: `EncodeData` and `EncodeDataType` examples.
16+
- `snippets/generate/set-size/*`: width, height, resolution, and units examples.
17+
- `snippets/generate/set-colorscheme/*`: foreground and background color examples.
18+
- `snippets/generate/appearance/*`: richer `BarcodeImageParams` examples.
19+
20+
## Recognize and scan patterns
21+
22+
- `snippets/read/set-source/RecognizeGet.java`: recognize from a public URL.
23+
- `snippets/read/set-source/RecognizeMultipart.java`: recognize from a local file.
24+
- `snippets/read/set-source/RecognizeBody.java`: recognize from base64 bytes.
25+
- `snippets/read/set-source/ScanGet.java`: auto-scan from a public URL.
26+
- `snippets/read/set-source/ScanMultipart.java`: auto-scan from a local file.
27+
- `snippets/read/set-source/ScanBody.java`: auto-scan from base64 bytes.
28+
- `snippets/read/set-target-types/*`: choosing `DecodeBarcodeType` or `List<DecodeBarcodeType>`.
29+
- `snippets/read/set-quality/*`: `RecognitionMode` examples.
30+
- `snippets/read/set-image-kind/*`: `RecognitionImageKind` examples.
31+
32+
## Tests worth copying
33+
34+
- `src/test/java/com/aspose/barcode/cloud/test/EndToEndTest.java`: generate a barcode `File`, then scan that same file end to end.
35+
- `src/test/java/com/aspose/barcode/cloud/test/GenerateApiTest.java`: generate via GET, body, and multipart variants.
36+
- `src/test/java/com/aspose/barcode/cloud/test/RecognizeApiTest.java`: recognize via base64 body, multipart, and URL.
37+
- `src/test/java/com/aspose/barcode/cloud/test/ScanApiTest.java`: scan via base64 body, multipart, and URL.
38+
- `src/test/java/com/aspose/barcode/cloud/test/ConfigurationTest.java`: configuration defaults and `buildApiClient()` behavior.
39+
- `src/test/java/com/aspose/barcode/cloud/test/ExceptionTest.java`: expected failures and exception behavior.
40+
- `src/test/java/com/aspose/barcode/cloud/api/GenerateApiUnitTest.java`: request validation and generated request-path behavior.
41+
- `src/test/java/com/aspose/barcode/cloud/api/RecognizeApiUnitTest.java`: recognize request validation, request-path behavior, and async wiring.
42+
- `src/test/java/com/aspose/barcode/cloud/api/ScanApiUnitTest.java`: scan request validation, request-path behavior, and async wiring.

0 commit comments

Comments
 (0)