A4P Java SDK
Public API and usage contract | 公开 API 与使用约束
English | 简体中文
Java 17 implementation of the A4P payment-intent protocol.
Quick build
bash A4P-java-sdk/scripts/build.sh build # Explicitly compile and package
Build artifacts are located at A4P-java-sdk/target/a4p-java-sdk-*.jar.
Build and test
Requirements: JDK 17 or later, Maven 3.9 or later.
cd A4P-java-sdk
mvn test
mvn package
Generate English API documentation
From the repository root, run:
mvn -f A4P-java-sdk/pom.xml javadoc:javadoc
Open A4P-java-sdk/target/site/apidocs/index.html to browse the English documentation.
A full JDK 17+ (including javadoc) and Maven 3.9+ are required; the first run downloads plugins.
Generated pages cover the public API (including nested types), excluding tests and the standalone examples module.
Missing comments do not prevent the build; malformed Javadoc or broken references cause generation to fail.
mvn package automatically generates and attaches the English target/a4p-java-sdk-0.1.0-javadoc.jar.
To run tests, package the SDK, and generate HTML documentation together:
mvn -f A4P-java-sdk/pom.xml clean verify javadoc:javadoc
When changing an API, update its English source comments in the same change. When public usage or build instructions change,
also update docs/API.md, docs/API_zh.md, and the corresponding READMEs.
Generated files under target/ do not need to be edited manually or committed.
Build script
The script requires Bash (for example, Linux, WSL, or Git Bash on Windows). From the repository root, run:
bash A4P-java-sdk/scripts/build.sh # Default: build mode
bash A4P-java-sdk/scripts/build.sh build # Explicitly compile and package
bash A4P-java-sdk/scripts/build.sh ut # Run unit tests only
bash A4P-java-sdk/scripts/build.sh docs # Generate Javadoc documentation
bash A4P-java-sdk/scripts/build.sh --help
buildrunsclean packagewith-Dmaven.test.skip=true, skipping both compilation and execution of test code. The artifact isA4P-java-sdk/target/a4p-java-sdk-0.1.0.jar.utrunsclean test, requires tests to be present, and returns a failure if tests fail. It does not package a JAR; Surefire test reports are located atA4P-java-sdk/target/surefire-reports/.docsgenerates documentation using Javadoc.
The build and ut modes clean target/ first; docs does not. All modes return Maven's exit code.
Place additional Maven arguments after the script's mode selection, for example:
bash A4P-java-sdk/scripts/build.sh build -o
mvn -f A4P-java-sdk/examples/pom.xml test
-o enables Maven's offline mode; required dependencies and plugins must already be cached. The script locates pom.xml
relative to itself, independently of the caller's working directory.
UT script with CI reports
To run unit tests and generate CI reports, run the following command from the repository root. The script locates the
repository root relative to itself, independently of the caller's working directory. You can override the default
by setting WORKSPACE to the absolute path of the repository root.
bash A4P-java-sdk/scripts/ut.sh
The script requires Git, Maven, and standard shell utilities, including grep with -P support (for example, GNU grep).
It runs mvn clean test and returns Maven's exit code (0 for PASS, nonzero for FAILED).
Reports are written to outputs/ under the resolved repository root ($WORKSPACE/outputs/ when overridden):
| File | Contents |
|---|---|
ut.log |
Maven test log |
unit_test_report.html |
Test counts and the last 200 log lines |
junit.xml |
Combined JUnit XML, generated only when Surefire XML reports exist |
ut.json |
Status, Maven exit code, and report links |
Optional environment variables PR_ID (default 0) and OBS_BUCKET (default openjiuwen-ci) configure
report links in ut.json. The script only generates local reports; CI must upload them separately to the linked OBS locations.
Build dependencies
The artifact coordinates are io.openjiuwen:a4p-java-sdk:0.1.0. Jackson handles JSON; JUnit 5 is used only for testing. No web framework is required.
jackson-databind (2.20.1 here) is the only runtime dependency; JUnit 5 has test scope.
Run the example program
The example program depends on the external Java SDK:
<dependency>
<groupId>io.openjiuwen</groupId>
<artifactId>a4p-java-sdk</artifactId>
<version>0.1.0</version>
</dependency>
First run mvn -f A4P-java-sdk/pom.xml install to build the SDK, then run io.openjiuwen.a4p.examples.PaymentExample from the standalone examples module:
mvn -f A4P-java-sdk/examples/pom.xml compile org.codehaus.mojo:exec-maven-plugin:3.6.3:java "-Dexec.mainClass=io.openjiuwen.a4p.examples.PaymentExample"
The exec plugin is not declared in pom.xml, so this command resolves it from Maven Central on first use and requires network access.
The example uses separate Agent, intent center, and user RSA-3072 key pairs to demonstrate creating, issuing, authorizing, activating, verifying, reserving, and completing a payment.
API
For detailed API documentation, see docs/API.md.
To use the classes and functions defined in the SDK, import:
import io.openjiuwen.a4p.*;
import io.openjiuwen.a4p.Models.*;
Build AI_PAY payloads through the PaymentProfile helper class. The following snippet illustrates the calls; see
io.openjiuwen.a4p.examples.PaymentExample for a complete, compilable version that also sets up the key pairs and the L1/L2/L3 chain.
// Activate an intent created by the Agent, issued by the intent center and signed by the user.
A4pResult<IntentExecutionContext> activated = A4p.activateIntent(authorizedIntent, userVerifier, now);
if (!activated.success()) { throw new IllegalStateException("Activation failed: " + activated.code()); }
IntentExecutionContext context = activated.data();
// Reserve an order against the activated intent, then complete it.
Order order = new Order("order-1", 3000L, "CNY", List.of(new CartItem(product, 1L)), now);
Execution execution = PaymentProfile.execution("execution-1", order);
A4pResult<IntentExecutionContext> reserved = A4p.createExecution(context, execution, now);
// Persist context even on failure: the reservation attempt may mark it EXPIRED.
if (!reserved.success()) { throw new IllegalStateException("Reservation failed: " + reserved.code()); }
// Perform the external payment; complete only after success, or cancel on failure.
A4pResult<IntentExecutionContext> completed = A4p.completeExecution(context, execution.id(), now);
if (!completed.success()) { throw new IllegalStateException("Completion failed: " + completed.code()); }
PaymentExecutionInfo info = PaymentProfile.executionInfo(context);
Use new A4pIntentCodec() for serialization and restoration. Persist the context after activation and every update, and serialize database read-update-write cycles for each intent in a transaction. Context JSON is for local persistence only; restoration does not verify signatures or storage integrity.
Result codes
The following values come from A4pErrorCode, shared with the ArkTS SDK. 0 indicates success; any other value indicates a protocol failure.
A4pErrorCode.fromCode(int) resolves a code back to its constant;
unknown values map to A4P_INTERNAL_ERROR (cast the long returned by code() to int when calling it).
| Code | Constant | Meaning |
|---|---|---|
| 0 | A4P_SUCCESS |
Operation completed successfully |
| 1001 | A4P_INVALID_PARAMETER |
Invalid parameter |
| 1002 | A4P_UNSUPPORTED_VERSION |
Unsupported version |
| 1003 | A4P_DUPLICATE_ID |
Duplicate ID |
| 2001 | A4P_SIGNING_FAIL |
Signing failed |
| 2002 | A4P_VERIFY_FAIL |
Verification failed |
| 3001 | A4P_INVALID_STATUS |
Invalid status |
| 3002 | A4P_TIMESTAMP_EXPIRED |
Timestamp expired |
| 3003 | A4P_TIMESTAMP_TOO_EARLY |
Timestamp too early |
| 4001 | A4P_EXECUTION_COUNT_EXCEEDED |
Execution count limit exceeded |
| 4002 | A4P_AMOUNT_EXCEEDED |
Amount limit exceeded |
| 4003 | A4P_PERIOD_COUNT_EXCEEDED |
Reserved for ArkTS error-code compatibility; Java does not currently return this code (per-period execution count limits use 4004) |
| 4004 | A4P_PERIOD_EXECUTION_COUNT_EXCEEDED |
Per-period execution count limit exceeded |
| 4005 | A4P_CART_MISMATCH |
Cart does not match the authorized order template |
| 4006 | A4P_SINGLE_ORDER_AMOUNT_EXCEEDED |
Single-order amount limit exceeded |
| 4007 | A4P_PRODUCT_NOT_AUTHORIZED |
Product not authorized |
| 5001 | A4P_SERIALIZE_FAIL |
Serialization failed |
| 5002 | A4P_DESERIALIZE_FAIL |
Deserialization failed |
| 6001 | A4P_INTERNAL_ERROR |
Unexpected internal error |
Version and compatibility
- Current protocol version:
1.0(A4p.PROTOCOL_VERSION) - Java SDK build version:
0.1.0
More documentation
Reference documents are located in docs/:
| Document | Contents |
|---|---|
| API.md | Detailed API documentation |
| serialization_and_signature_rules.md | Serialization and signature rules |
Tests
Tests cover lifecycle, quota rollback, order idempotency, one-to-one cart matching, check ordering, expiry finalization, terminal states, consumption, whitelist validation, period boundaries, blank and structural validation, the result model, typed-union payloads, wire-format names and enum encoding, concurrent reservations, canonical vectors, detached signature metadata, malformed input, verifier result consistency, execution-context persistence and restoration (including reachable states and record timestamps), and real RSA signature verification and tampering detection. The digest signer in the test fixtures is only a deterministic test double and must not be used for authorization.