Java

Guide to using Soxom-generated Java SDKs.

Configuration

targets:
  java:
    group_id: com.acme
    artifact_id: acme-sdk

Option	Default	Description
`group_id`	`com.example`	Maven group ID
`artifact_id`	`sdk.name`	Maven artifact ID

Installation

<dependency>
    <groupId>com.acme</groupId>
    <artifactId>acme-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

implementation 'com.acme:acme-sdk:1.0.0'

implementation("com.acme:acme-sdk:1.0.0")

Client Initialization

import com.acme.sdk.AcmeClient;

// With token
AcmeClient client = AcmeClient.builder()
    .token(System.getenv("ACME_API_TOKEN"))
    .build();

// With options
AcmeClient client = AcmeClient.builder()
    .token(System.getenv("ACME_API_TOKEN"))
    .baseUrl("https://api.acme.com/v2")
    .timeout(Duration.ofSeconds(30))
    .build();

// From environment (if configured)
AcmeClient client = AcmeClient.builder().build();

Builder Pattern

Soxom generates builder classes for all request objects:

import com.acme.sdk.models.*;

// Create user with builder
User user = client.users().create(UserCreate.builder()
    .email("john@example.com")
    .name("John Doe")
    .build());

// Update with builder
User updated = client.users().update("user-123", UserUpdate.builder()
    .name("Jane Doe")
    .status(UserStatus.ACTIVE)
    .build());

// Complex objects
Order order = client.orders().create(OrderCreate.builder()
    .addItem(OrderItem.builder()
        .productId("prod-123")
        .quantity(2)
        .build())
    .addItem(OrderItem.builder()
        .productId("prod-456")
        .quantity(1)
        .build())
    .shippingAddress(Address.builder()
        .street("123 Main St")
        .city("San Francisco")
        .country("US")
        .build())
    .build());

Basic Operations

// Get
User user = client.users().get("user-123");
System.out.println(user.getName());

// List
UserListResponse response = client.users().list();
for (User u : response.getData()) {
    System.out.println(u.getEmail());
}

// List with parameters
UserListResponse response = client.users().list(ListUsersParams.builder()
    .status(UserStatus.ACTIVE)
    .limit(50)
    .build());

// Delete
client.users().delete("user-123");

Type Safety

Java SDK uses strongly typed classes:

// Enum types
UserStatus status = UserStatus.ACTIVE;

// Response types with getters
User user = client.users().get("user-123");
String id = user.getId();
String email = user.getEmail();
UserStatus status = user.getStatus();
OffsetDateTime createdAt = user.getCreatedAt();

// Optional fields
Optional<String> description = user.getDescription();
description.ifPresent(d -> System.out.println(d));

Union Types

// Union types use sealed interfaces (Java 17+) or abstract classes
PaymentMethod method = payment.getPaymentMethod();

if (method instanceof CreditCard card) {
    System.out.println("Card: " + card.getCardNumber());
} else if (method instanceof BankAccount bank) {
    System.out.println("Account: " + bank.getAccountNumber());
}

// Or with visitor pattern
method.accept(new PaymentMethodVisitor<Void>() {
    @Override
    public Void visit(CreditCard card) {
        System.out.println("Card: " + card.getCardNumber());
        return null;
    }

    @Override
    public Void visit(BankAccount bank) {
        System.out.println("Account: " + bank.getAccountNumber());
        return null;
    }
});

Pagination

Iterator Pattern

// Iterate through all pages
for (User user : client.users().listAll()) {
    System.out.println(user.getName());
}

// With stream
client.users().listAll()
    .stream()
    .filter(u -> u.getStatus() == UserStatus.ACTIVE)
    .forEach(u -> System.out.println(u.getEmail()));

// Collect to list
List<User> allUsers = client.users().listAll()
    .stream()
    .collect(Collectors.toList());

Manual Pagination

// Get first page
UserListResponse page = client.users().list(ListUsersParams.builder()
    .limit(10)
    .build());

for (User user : page.getData()) {
    System.out.println(user.getName());
}

// Get next page
if (page.getHasMore()) {
    UserListResponse nextPage = client.users().list(ListUsersParams.builder()
        .after(page.getNextCursor())
        .limit(10)
        .build());
}

Streaming

// SSE streaming
Stream<ChatCompletionChunk> stream = client.chat().completions()
    .createStream(ChatCompletionRequest.builder()
        .model("gpt-4")
        .addMessage(ChatMessage.builder()
            .role(Role.USER)
            .content("Hello")
            .build())
        .build());

stream.forEach(chunk -> {
    String content = chunk.getChoices().get(0).getDelta().getContent();
    if (content != null) {
        System.out.print(content);
    }
});

Exception Handling

import com.acme.sdk.exceptions.*;

try {
    User user = client.users().get("user-123");
} catch (AuthenticationException e) {
    // 401 - Invalid or expired token
    System.err.println("Authentication failed: " + e.getMessage());
} catch (NotFoundException e) {
    // 404 - Resource not found
    System.err.println("User not found");
} catch (RateLimitException e) {
    // 429 - Too many requests
    System.err.println("Rate limited. Retry after " + e.getRetryAfter() + "s");
} catch (ValidationException e) {
    // 400 - Invalid request
    for (ValidationError error : e.getErrors()) {
        System.err.println(error.getField() + ": " + error.getMessage());
    }
} catch (ApiException e) {
    // Other API errors
    System.err.println("API error: " + e.getStatusCode() + " - " + e.getMessage());
}

Exception Properties

catch (ApiException e) {
    int status = e.getStatusCode();      // HTTP status code
    String message = e.getMessage();     // Error message
    String code = e.getCode();           // API error code
    String requestId = e.getRequestId(); // Request ID
    Map<String, String> headers = e.getHeaders();
}

Request Options

Override settings per-request:

// Custom timeout
Report report = client.reports().generate(params,
    RequestOptions.builder()
        .timeout(Duration.ofMinutes(2))
        .build());

// Disable retries
Payment payment = client.payments().create(data,
    RequestOptions.builder()
        .retries(RetryConfig.disabled())
        .build());

// Custom headers
UserListResponse result = client.users().list(
    RequestOptions.builder()
        .header("X-Custom-Header", "value")
        .build());

// Idempotency key
Order order = client.orders().create(data,
    RequestOptions.builder()
        .idempotencyKey("unique-request-123")
        .build());

Async Support

Java SDK provides CompletableFuture-based async methods:

import java.util.concurrent.CompletableFuture;

// Async get
CompletableFuture<User> userFuture = client.users().getAsync("user-123");
userFuture.thenAccept(user -> System.out.println(user.getName()));

// Parallel requests
CompletableFuture<User> user = client.users().getAsync("user-123");
CompletableFuture<OrderListResponse> orders = client.orders().listAsync();

CompletableFuture.allOf(user, orders).join();

// Process results
System.out.println(user.get().getName());
System.out.println(orders.get().getData().size());

Generated Package Structure

com.acme.sdk/
├── AcmeClient.java          # Main client
├── AcmeClientBuilder.java   # Client builder
├── resources/
│   ├── Users.java           # Users resource
│   └── Orders.java          # Orders resource
├── models/
│   ├── User.java            # User model
│   ├── UserCreate.java      # Create request
│   └── UserUpdate.java      # Update request
├── exceptions/
│   ├── ApiException.java    # Base exception
│   └── NotFoundException.java
├── pom.xml
├── build.gradle
└── README.md