tessl/maven-com-amazonaws--aws-java-sdk-core

Core foundational library for AWS SDK for Java 1.x providing authentication, HTTP transport, regions, protocols, and shared utilities for all AWS service clients

—

Pending

Overview

Eval results

Files

Protocol Support & Marshalling

Name: tessl/maven-com-amazonaws--aws-java-sdk-core
Author: tessl

The AWS Java SDK Core provides comprehensive protocol support for AWS services, including JSON, CBOR, and REST protocols with automatic marshalling and unmarshalling capabilities.

Core Protocol Framework

Protocol Types

// Protocol enumeration
enum Protocol {
    HTTP("http", 80, false),
    HTTPS("https", 443, true);
    
    public String toString();
    public int getDefaultPort(); 
    public boolean isSecure();
}

// Protocol marshaller interface
interface ProtocolMarshaller {
    <T> void marshall(T val, ProtocolRequestMarshaller<T> protocolRequestMarshaller);
}

// Protocol request marshaller interface  
interface ProtocolRequestMarshaller<T> {
    void marshall(T input, Request<T> request);
}

// Structured data object interface
interface StructuredPojo {
    void marshall(ProtocolMarshaller protocolMarshaller);
}

Marshalling Framework

// Marshalling information for fields
class MarshallingInfo<T> {
    public static <T> MarshallingInfo<T> builder(MarshallingType<T> marshallingType);
    public MarshallingInfo<T> marshallLocation(MarshallLocation marshallLocation);
    public MarshallingInfo<T> locationName(String locationName);
    public MarshallingInfo<T> defaultValueSupplier(DefaultValueSupplier<T> defaultValueSupplier);
    public MarshallingInfo<T> timestampFormat(String timestampFormat);
    public MarshallingInfo<T> isBinary(boolean isBinary);
    public MarshallingInfo<T> isExplicitPayloadMember(boolean isExplicitPayloadMember);
    public MarshallingInfo<T> isGreedy(boolean isGreedy);
    
    public MarshallingType<T> getMarshallingType();
    public MarshallLocation getMarshallLocation();
    public String getLocationName();
    public DefaultValueSupplier<T> getDefaultValueSupplier();
    public String getTimestampFormat();
    public boolean isBinary();
    public boolean isExplicitPayloadMember();
    public boolean isGreedy();
}

// Marshalling type interface
interface MarshallingType<T> {
    // Marker interface for type safety
}

// Marshalling locations
enum MarshallLocation {
    PAYLOAD,
    QUERY_PARAM,
    HEADER,
    PATH,
    GREEDY_PATH,
    STATUS_CODE
}

// Operation information
class OperationInfo {
    public static OperationInfo create();
    public OperationInfo requestUri(String requestUri);
    public OperationInfo httpMethod(HttpMethodName httpMethod);
    public OperationInfo operationIdentifier(String operationIdentifier);
    public OperationInfo serviceId(String serviceId);
    public OperationInfo hasExplicitPayloadMember(boolean hasExplicitPayloadMember);
    public OperationInfo hasPayloadMembers(boolean hasPayloadMembers);
    public OperationInfo addRequestHeader(String name, String value);
    
    public String getRequestUri();
    public HttpMethodName getHttpMethod();
    public String getOperationIdentifier();
    public String getServiceId();
    public boolean hasExplicitPayloadMember();
    public boolean hasPayloadMembers();
    public Map<String, String> getAdditionalHeaders();
}

// Default value supplier interface
interface DefaultValueSupplier<T> {
    T get();
}

JSON Protocol Support

JSON Client Configuration

// Metadata for JSON protocol clients
class JsonClientMetadata {
    public JsonClientMetadata withProtocolVersion(String protocolVersion);
    public JsonClientMetadata withSupportsCbor(boolean supportsCbor);
    public JsonClientMetadata withSupportsIon(boolean supportsIon);
    public JsonClientMetadata withContentType(String contentType);
    
    public String getProtocolVersion();
    public boolean isSupportsCbor();
    public boolean isSupportsIon();
    public String getContentType();
}

// Metadata for JSON operations
class JsonOperationMetadata {
    public JsonOperationMetadata withPayloadJson(boolean payloadJson);
    public JsonOperationMetadata withHasStreamingSuccessResponse(boolean hasStreamingSuccessResponse);
    
    public boolean isPayloadJson();
    public boolean hasStreamingSuccessResponse();
}

// Metadata for JSON error responses
class JsonErrorResponseMetadata {
    public JsonErrorResponseMetadata withCustomErrorCodeFieldName(String customErrorCodeFieldName);
    public JsonErrorResponseMetadata withErrorMessageFieldName(String errorMessageFieldName);
    
    public String getCustomErrorCodeFieldName();
    public String getErrorMessageFieldName();
}

// Metadata for JSON error shapes
class JsonErrorShapeMetadata {
    public JsonErrorShapeMetadata withErrorCode(String errorCode);
    public JsonErrorShapeMetadata withModeledClass(Class<? extends RuntimeException> modeledClass);
    public JsonErrorShapeMetadata withHttpStatusCode(int httpStatusCode);
    
    public String getErrorCode();
    public Class<? extends RuntimeException> getModeledClass();
    public int getHttpStatusCode();
}

JSON Protocol Factory

// Factory for JSON protocol handlers
class SdkJsonProtocolFactory {
    public SdkJsonProtocolFactory(JsonClientMetadata metadata);
    
    public <OrigRequest extends AmazonWebServiceRequest> ProtocolRequestMarshaller<OrigRequest> 
        createProtocolMarshaller(OperationInfo operationInfo);
        
    public <ResponseType> HttpResponseHandler<ResponseType> createResponseHandler(
        JsonOperationMetadata operationMetadata, 
        Unmarshaller<ResponseType, JsonUnmarshallerContext> responseUnmarshaller);
        
    public HttpResponseHandler<SdkBaseException> createErrorResponseHandler(
        JsonErrorResponseMetadata errorResponseMetadata,
        List<JsonErrorUnmarshallerV2> errorUnmarshallers);
}

// Builder for JSON protocol marshallers
class JsonProtocolMarshallerBuilder<T> {
    public static <T> JsonProtocolMarshallerBuilder<T> create();
    public JsonProtocolMarshallerBuilder<T> marshaller(SdkJsonMarshallerFactory marshallerFactory);
    public JsonProtocolMarshallerBuilder<T> jsonGenerator(SdkJsonGenerator jsonGenerator);
    public JsonProtocolMarshallerBuilder<T> endpoint(URI endpoint);
    public JsonProtocolMarshallerBuilder<T> operationInfo(OperationInfo operationInfo);
    public JsonProtocolMarshallerBuilder<T> originalRequest(T originalRequest);
    public ProtocolRequestMarshaller<T> build();
}

// Factory for JSON marshallers
class SdkJsonMarshallerFactory {
    public SdkJsonMarshallerFactory(SdkStructuredJsonFactory jsonFactory);
    
    public <T> StructuredJsonMarshaller<T> getMarshaller(MarshallLocation marshallLocation, 
                                                        MarshallingType<T> marshallingType);
}

JSON Generation

// JSON generator for SDK
interface SdkJsonGenerator extends StructuredJsonGenerator {
    byte[] getBytes();
    String getContentType();
}

// Structured JSON generator interface
interface StructuredJsonGenerator {
    StructuredJsonGenerator writeStartArray();
    StructuredJsonGenerator writeEndArray();
    StructuredJsonGenerator writeStartObject();
    StructuredJsonGenerator writeEndObject();
    StructuredJsonGenerator writeFieldName(String fieldName);
    StructuredJsonGenerator writeValue(String val);
    StructuredJsonGenerator writeValue(boolean bool);
    StructuredJsonGenerator writeValue(int val);
    StructuredJsonGenerator writeValue(long val);
    StructuredJsonGenerator writeValue(double val);
    StructuredJsonGenerator writeValue(float val);
    StructuredJsonGenerator writeValue(BigDecimal val);
    StructuredJsonGenerator writeValue(BigInteger val);
    StructuredJsonGenerator writeValue(Date val);
    StructuredJsonGenerator writeValue(ByteBuffer bytes);
    StructuredJsonGenerator writeNull();
    StructuredJsonGenerator flush();
    StructuredJsonGenerator close();
}

// Structured JSON marshaller interface
interface StructuredJsonMarshaller<T> {
    void marshall(T val, StructuredJsonGenerator generator);
}

// Structured JSON factory interface
interface SdkStructuredJsonFactory {
    StructuredJsonGenerator createWriter();
}

// Plain JSON factory implementation
class SdkStructuredPlainJsonFactory implements SdkStructuredJsonFactory {
    public StructuredJsonGenerator createWriter();
}

// JSON content representation
class JsonContent {
    public JsonContent(byte[] rawContent, String contentType);
    public byte[] getRawContent();
    public String getContentType();
}

RPC v2 CBOR Protocol Support

CBOR Client Configuration

// Metadata for RPC v2 CBOR clients
class RpcV2CborClientMetadata {
    public RpcV2CborClientMetadata withProtocolVersion(String protocolVersion);
    public RpcV2CborClientMetadata withServiceId(String serviceId);
    
    public String getProtocolVersion();
    public String getServiceId();
}

// Metadata for RPC v2 CBOR operations
class RpcV2CborOperationMetadata {
    public RpcV2CborOperationMetadata withHasStreamingSuccessResponse(boolean hasStreamingSuccessResponse);
    
    public boolean hasStreamingSuccessResponse();
}

// Metadata for RPC v2 CBOR error responses
class RpcV2CborErrorResponseMetadata {
    public RpcV2CborErrorResponseMetadata withCustomErrorCodeFieldName(String customErrorCodeFieldName);
    public RpcV2CborErrorResponseMetadata withErrorMessageFieldName(String errorMessageFieldName);
    
    public String getCustomErrorCodeFieldName();
    public String getErrorMessageFieldName();
}

// Metadata for RPC v2 CBOR error shapes
class RpcV2CborErrorShapeMetadata {
    public RpcV2CborErrorShapeMetadata withErrorCode(String errorCode);
    public RpcV2CborErrorShapeMetadata withModeledClass(Class<? extends RuntimeException> modeledClass);
    public RpcV2CborErrorShapeMetadata withHttpStatusCode(int httpStatusCode);
    
    public String getErrorCode();
    public Class<? extends RuntimeException> getModeledClass();
    public int getHttpStatusCode();
}

CBOR Protocol Factory

// Factory for RPC v2 CBOR protocol
class SdkRpcV2CborProtocolFactory {
    public SdkRpcV2CborProtocolFactory(RpcV2CborClientMetadata metadata);
    
    public <OrigRequest extends AmazonWebServiceRequest> ProtocolRequestMarshaller<OrigRequest> 
        createProtocolMarshaller(OperationInfo operationInfo);
        
    public <ResponseType> HttpResponseHandler<ResponseType> createResponseHandler(
        RpcV2CborOperationMetadata operationMetadata,
        Unmarshaller<ResponseType, JsonUnmarshallerContext> responseUnmarshaller);
        
    public HttpResponseHandler<SdkBaseException> createErrorResponseHandler(
        RpcV2CborErrorResponseMetadata errorResponseMetadata,
        List<JsonErrorUnmarshallerV2> errorUnmarshallers);
}

// Builder for RPC v2 CBOR protocol marshallers
class RpcV2CborProtocolMarshallerBuilder<T> {
    public static <T> RpcV2CborProtocolMarshallerBuilder<T> create();
    public RpcV2CborProtocolMarshallerBuilder<T> endpoint(URI endpoint);
    public RpcV2CborProtocolMarshallerBuilder<T> operationInfo(OperationInfo operationInfo);
    public RpcV2CborProtocolMarshallerBuilder<T> originalRequest(T originalRequest);
    public ProtocolRequestMarshaller<T> build();
}

CBOR Generation

// CBOR generator for RPC v2
interface SdkRpcV2CborGenerator extends StructuredRpcV2CborGenerator {
    byte[] getBytes();
    String getContentType();
}

// Structured CBOR generator interface
interface StructuredRpcV2CborGenerator {
    StructuredRpcV2CborGenerator writeStartArray();
    StructuredRpcV2CborGenerator writeEndArray();
    StructuredRpcV2CborGenerator writeStartObject();
    StructuredRpcV2CborGenerator writeEndObject();
    StructuredRpcV2CborGenerator writeFieldName(String fieldName);
    StructuredRpcV2CborGenerator writeValue(String val);
    StructuredRpcV2CborGenerator writeValue(boolean bool);
    StructuredRpcV2CborGenerator writeValue(int val);
    StructuredRpcV2CborGenerator writeValue(long val);
    StructuredRpcV2CborGenerator writeValue(double val);
    StructuredRpcV2CborGenerator writeValue(float val);
    StructuredRpcV2CborGenerator writeValue(BigDecimal val);
    StructuredRpcV2CborGenerator writeValue(BigInteger val);
    StructuredRpcV2CborGenerator writeValue(Date val);
    StructuredRpcV2CborGenerator writeValue(ByteBuffer bytes);
    StructuredRpcV2CborGenerator writeNull();
    StructuredRpcV2CborGenerator flush();
    StructuredRpcV2CborGenerator close();
}

// Structured RPC v2 CBOR marshaller interface
interface StructuredRpcV2CborMarshaller<T> {
    void marshall(T val, StructuredRpcV2CborGenerator generator);
}

// Structured CBOR factory interface
interface SdkStructuredRpcV2CborFactory {
    StructuredRpcV2CborGenerator createWriter();
}

// CBOR factory implementation
class SdkStructuredCborFactory implements SdkStructuredRpcV2CborFactory {
    public StructuredRpcV2CborGenerator createWriter();
}

Usage Examples

Basic JSON Protocol Configuration

import com.amazonaws.protocol.*;
import com.amazonaws.protocol.json.*;

// Create JSON client metadata
JsonClientMetadata jsonMetadata = new JsonClientMetadata()
    .withProtocolVersion("1.1")
    .withContentType("application/x-amz-json-1.1")
    .withSupportsCbor(false);

// Create JSON protocol factory
SdkJsonProtocolFactory protocolFactory = new SdkJsonProtocolFactory(jsonMetadata);

// Create operation info
OperationInfo operationInfo = OperationInfo.create()
    .requestUri("/")
    .httpMethod(HttpMethodName.POST)
    .serviceId("MyService")
    .operationIdentifier("MyOperation");

// Create protocol marshaller
ProtocolRequestMarshaller<MyRequest> marshaller = 
    protocolFactory.createProtocolMarshaller(operationInfo);

Custom Marshalling Configuration

import com.amazonaws.protocol.*;

// Define marshalling information for a field
MarshallingInfo<String> stringField = MarshallingInfo.<String>builder(MarshallingType.STRING)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .locationName("fieldName")
    .build();

MarshallingInfo<Integer> headerField = MarshallingInfo.<Integer>builder(MarshallingType.INTEGER)
    .marshallLocation(MarshallLocation.HEADER)
    .locationName("X-Custom-Header")
    .build();

MarshallingInfo<String> pathField = MarshallingInfo.<String>builder(MarshallingType.STRING)
    .marshallLocation(MarshallLocation.PATH)
    .locationName("resourceId")
    .isGreedy(false)
    .build();

MarshallingInfo<Date> timestampField = MarshallingInfo.<Date>builder(MarshallingType.DATE)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .locationName("timestamp")
    .timestampFormat("iso8601")
    .build();

Structured Pojo Implementation

import com.amazonaws.protocol.*;

public class MyRequestPojo implements StructuredPojo {
    private String name;
    private Integer count;
    private Date timestamp;
    
    // Constructors and getters/setters...
    
    @Override
    public void marshall(ProtocolMarshaller protocolMarshaller) {
        protocolMarshaller.marshall(name, NAME_BINDING);
        protocolMarshaller.marshall(count, COUNT_BINDING);  
        protocolMarshaller.marshall(timestamp, TIMESTAMP_BINDING);
    }
    
    private static final MarshallingInfo<String> NAME_BINDING = 
        MarshallingInfo.<String>builder(MarshallingType.STRING)
            .marshallLocation(MarshallLocation.PAYLOAD)
            .locationName("Name")
            .build();
            
    private static final MarshallingInfo<Integer> COUNT_BINDING = 
        MarshallingInfo.<Integer>builder(MarshallingType.INTEGER)
            .marshallLocation(MarshallLocation.PAYLOAD)
            .locationName("Count")
            .build();
            
    private static final MarshallingInfo<Date> TIMESTAMP_BINDING = 
        MarshallingInfo.<Date>builder(MarshallingType.DATE)
            .marshallLocation(MarshallLocation.PAYLOAD)
            .locationName("Timestamp")
            .timestampFormat("unixTimestamp")
            .build();
}

RPC v2 CBOR Protocol Configuration

import com.amazonaws.protocol.rpcv2cbor.*;

// Create CBOR client metadata
RpcV2CborClientMetadata cborMetadata = new RpcV2CborClientMetadata()
    .withProtocolVersion("2.0")
    .withServiceId("MyService");

// Create CBOR protocol factory
SdkRpcV2CborProtocolFactory cborFactory = new SdkRpcV2CborProtocolFactory(cborMetadata);

// Create operation metadata
RpcV2CborOperationMetadata operationMetadata = new RpcV2CborOperationMetadata()
    .withHasStreamingSuccessResponse(false);

// Create protocol marshaller
ProtocolRequestMarshaller<MyRequest> cborMarshaller = 
    cborFactory.createProtocolMarshaller(operationInfo);

Custom JSON Generator Usage

import com.amazonaws.protocol.json.*;

// Create JSON factory
SdkStructuredJsonFactory jsonFactory = new SdkStructuredPlainJsonFactory();

// Create JSON generator
StructuredJsonGenerator generator = jsonFactory.createWriter();

// Generate JSON content
generator.writeStartObject()
    .writeFieldName("name").writeValue("example")
    .writeFieldName("count").writeValue(42)
    .writeFieldName("active").writeValue(true)
    .writeFieldName("items")
        .writeStartArray()
            .writeValue("item1")
            .writeValue("item2")
        .writeEndArray()
    .writeEndObject();

// Get bytes if using SdkJsonGenerator
if (generator instanceof SdkJsonGenerator) {
    SdkJsonGenerator sdkGenerator = (SdkJsonGenerator) generator;
    byte[] jsonBytes = sdkGenerator.getBytes();
    String contentType = sdkGenerator.getContentType();
}

Error Response Handling

import com.amazonaws.protocol.json.*;
import java.util.*;

// Create error shape metadata
List<JsonErrorShapeMetadata> errorShapes = Arrays.asList(
    new JsonErrorShapeMetadata()
        .withErrorCode("InvalidRequest")
        .withModeledClass(InvalidRequestException.class)
        .withHttpStatusCode(400),
    new JsonErrorShapeMetadata()
        .withErrorCode("ResourceNotFound") 
        .withModeledClass(ResourceNotFoundException.class)
        .withHttpStatusCode(404)
);

// Create error response metadata
JsonErrorResponseMetadata errorMetadata = new JsonErrorResponseMetadata()
    .withCustomErrorCodeFieldName("__type")
    .withErrorMessageFieldName("message");

// Create error unmarshallers
List<JsonErrorUnmarshallerV2> errorUnmarshallers = new ArrayList<>();
for (JsonErrorShapeMetadata errorShape : errorShapes) {
    errorUnmarshallers.add(new JsonErrorUnmarshallerV2(
        errorShape.getModeledClass(), 
        errorShape.getErrorCode()
    ));
}

// Create error response handler
HttpResponseHandler<SdkBaseException> errorHandler = 
    protocolFactory.createErrorResponseHandler(errorMetadata, errorUnmarshallers);

Default Value Suppliers

import com.amazonaws.protocol.*;

// String default value supplier
DefaultValueSupplier<String> stringDefault = () -> "defaultValue";

// Integer default value supplier
DefaultValueSupplier<Integer> intDefault = () -> 100;

// List default value supplier
DefaultValueSupplier<List<String>> listDefault = () -> Arrays.asList("default1", "default2");

// Use in marshalling info
MarshallingInfo<String> fieldWithDefault = MarshallingInfo.<String>builder(MarshallingType.STRING)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .locationName("fieldName")
    .defaultValueSupplier(stringDefault)
    .build();

Advanced Protocol Features

Binary Data Handling

import com.amazonaws.protocol.*;
import java.nio.ByteBuffer;

// Binary field configuration
MarshallingInfo<ByteBuffer> binaryField = MarshallingInfo.<ByteBuffer>builder(MarshallingType.BYTE_BUFFER)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .locationName("binaryData")
    .isBinary(true)
    .build();

// Streaming binary payload
MarshallingInfo<InputStream> streamField = MarshallingInfo.<InputStream>builder(MarshallingType.STREAM)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .isExplicitPayloadMember(true)
    .build();

Timestamp Formats

import com.amazonaws.protocol.*;

// ISO 8601 timestamp
MarshallingInfo<Date> iso8601Field = MarshallingInfo.<Date>builder(MarshallingType.DATE)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .locationName("createdAt")
    .timestampFormat("iso8601")
    .build();

// Unix timestamp
MarshallingInfo<Date> unixField = MarshallingInfo.<Date>builder(MarshallingType.DATE)
    .marshallLocation(MarshallLocation.PAYLOAD)
    .locationName("modifiedAt")
    .timestampFormat("unixTimestamp")
    .build();

// RFC 822 timestamp (for headers)
MarshallingInfo<Date> rfc822Field = MarshallingInfo.<Date>builder(MarshallingType.DATE)
    .marshallLocation(MarshallLocation.HEADER)
    .locationName("Last-Modified")
    .timestampFormat("rfc822")
    .build();

Best Practices

Protocol Selection: Choose the appropriate protocol (JSON vs CBOR) based on service requirements and payload size considerations.
Marshalling Efficiency: Use specific marshalling types and locations to minimize serialization overhead.
Error Handling: Implement comprehensive error shape metadata to properly handle service-specific exceptions.
Binary Data: Use appropriate marshalling types for binary data to avoid unnecessary encoding/decoding.
Timestamp Handling: Use correct timestamp formats based on the target location (payload vs headers).
Default Values: Implement default value suppliers for optional fields to ensure consistent behavior.
Memory Management: Properly close generators and handle streaming content to prevent memory leaks.
Content Types: Ensure correct content type configuration for different protocol versions and formats.

The protocol support system provides comprehensive marshalling and unmarshalling capabilities for all AWS service protocols, enabling seamless data serialization and deserialization across different formats and transport mechanisms.

Install with Tessl CLI

npx tessl i tessl/maven-com-amazonaws--aws-java-sdk-core

docs

arn-support.md

authentication.md

client-builders.md

endpoint-discovery.md

exception-handling.md

http-transport.md

index.md

metrics-monitoring.md