Skip to content

Commit dc55ad5

Browse files
ivankamkinivankamkin
committed
Add skill
1 parent 6344365 commit dc55ad5

4 files changed

Lines changed: 281 additions & 0 deletions

File tree

‎skills/aspose-barcode-cloud-java/SKILL.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
---
2+
name: aspose-barcode-cloud-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+
# Aspose.BarCode Cloud SDK for 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/aspose-barcode-cloud-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: "Aspose BarCode Cloud Java"
3+
short_description: "Build and maintain Java barcode SDK code"
4+
default_prompt: "Use $aspose-barcode-cloud-java to write or update Java code with the Aspose.BarCode Cloud SDK."

‎skills/aspose-barcode-cloud-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/aspose-barcode-cloud-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)