The AWS SDK for Java v2 carries a large transitive dependency tree — Netty, Jackson, the SDK's own HTTP client and their downstream closures — that conflicts with the versions already bound inside the Axional runtime. Co-existence on a single classpath would manifest as NoSuchMethodError and ClassCastException failures at runtime, the classic Java "JAR hell" pattern that has no robust resolution through dependency exclusion alone.
The isolation boundary
Each AWS service client loads inside a dedicated child URLClassLoader that holds the SDK JARs and their transitive dependencies. The main classloader holds only the platform's own dependencies plus a thin set of gateway interfaces ; the child classloader holds the AWS SDK. The two classloaders share the JDK and the gateway-interface classes, and nothing else.
The three-tier delegation model
- Tier 1 — the JavaScript wrapper (main classloader). The
Ax.cloud.aws.S3object that scripts call. Its methods accept and return JDK types only — strings, numbers, byte arrays,java.util.List,java.util.Map. - Tier 2 — the gateway interface (main classloader, visible to both sides). A pure-Java interface declaring the SDK-agnostic contract. Its method signatures reference only JDK types and other gateway types, never SDK classes.
- Tier 3 — the gateway implementation (child classloader). The class that imports the AWS SDK, makes the API call, and translates the SDK's responses back into JDK types before returning across the boundary.
Why this works
The gateway interfaces are the same Class objects on both sides of the boundary. The child URLClassLoader delegates parent-first for the gateway interfaces and the JDK ; it delegates child-first for everything else, which is how it resolves the SDK's bundled Netty and Jackson without leaking them to the main classpath. The result : the main classloader can hold a reference to a gateway-interface implementation that was loaded inside the child without a ClassCastException at the downcast — the interface is the same type to both sides.
The AWS surface is available without forking the platform's HTTP client, the platform's JSON library, or any other shared dependency. Future SDK upgrades affect only the JARs the child classloader loads ; the rest of the runtime is unaffected. The same pattern is the basis for adding more cloud-vendor SDKs (Azure, Google Cloud) without spreading their dependency closures across the platform.