12d907eb537d8f0b8956c4ee9de110d4a7a4f1fa - platform/external/aws-crt-java

commit	12d907eb537d8f0b8956c4ee9de110d4a7a4f1fa	[log] [tgz]
author	Dengke Tang <[email protected]>	Thu May 25 16:56:51 2023 -0700
committer	GitHub <[email protected]>	Thu May 25 16:56:51 2023 -0700
tree	3345d2a7ed756a533e5a0dd808495d77cb6470c4
parent	9ec1e1207bc11b635dfe4ffb620354116ebda580 [diff]

tree: 3345d2a7ed756a533e5a0dd808495d77cb6470c4

README.md

AWS CRT Java

Java Bindings for the AWS Common Runtime

License

This library is licensed under the Apache 2.0 License.

Building

Linux/Unix

Requirements:

Clang 3.9+ or GCC 4.4+
cmake 3.1+
Java: Any JDK8 or above, ensure JAVA_HOME is set
Maven

Building:

apt-get install cmake3 maven openjdk-8-jdk-headless -y
git clone https://github.com/awslabs/aws-crt-java.git
cd aws-crt-java
git submodule update --init --recursive
mvn compile

OSX

Requirements:

cmake 3.1
ninja
Java: Any JDK8 or above, ensure JAVA_HOME is set
Maven

brew install maven cmake (if you have homebrew installed, otherwise install these manually)
git clone https://github.com/awslabs/aws-crt-java.git
cd aws-crt-java
git submodule update --init --recursive
mvn compile

Windows

Requirements:

Visual Studio 2015 or above
CMake 3.1
Java: Any JDK8 or above, ensure JAVA_HOME is set
Maven

choco install maven (if you have chocolatey installed), otherwise install maven and the JDK manually
git clone https://github.com/awslabs/aws-crt-java.git
cd aws-crt-java
git submodule update --init --recursive
mvn compile

NOTE: Make sure you run this from a VS Command Prompt or have run VCVARSALL.BAT in your current shell so CMake can find Visual Studio.

Documentation

Java CRT Documentation

Installing

From the aws-crt-java directory: mvn install From maven: (https://search.maven.org/artifact/software.amazon.awssdk.crt/aws-crt/)

Platform-Specific JARs

The aws-crt JAR in Maven Central is a large “uber” jar that contains compiled C libraries for many different platforms (Windows, Linux, etc). If size is an issue, you can pick a smaller platform-specific JAR by setting the <classifier>.

        <!-- Platform-specific Linux x86_64 JAR -->
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.20.5</version>
            <classifier>linux-x86_64</classifier>
        </dependency>

        <!-- "Uber" JAR that works on all platforms -->
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.20.5</version>
        </dependency>

Available platform classifiers

linux-armv6
linux-armv7
linux-aarch_64
linux-x86_32
linux-x86_64
osx-aarch_64
osx-x86_64
windows-x86_32
windows-x86_64

Auto-detect

The os-maven-plugin can automatically detect your platform's classifier at build time.

NOTES: The auto-detected linux-arm_32 platform classifier is not supported, you must specify linux-armv6 or linux-armv7.

<build>
        <extensions>
            <!-- Generate os.detected.classifier property -->
            <extension>
                <groupId>kr.motd.maven</groupId>
                <artifactId>os-maven-plugin</artifactId>
                <version>1.7.0</version>
            </extension>
        </extensions>
 </build>

 <dependencies>
        <dependency>
            <groupId>software.amazon.awssdk.crt</groupId>
            <artifactId>aws-crt</artifactId>
            <version>0.20.5</version>
            <classifier>${os.detected.classifier}</classifier>
        </dependency>
  <dependencies>

Mac-Only TLS Behavior

Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v0.6.6, when a stored private key from the Keychain is used, the following will be logged at the “info” log level:

static: certificate has an existing certificate-key pair that was previously imported into the Keychain.  Using key from Keychain instead of the one provided.

Testing

Many tests require custom arguments. These tests will be quietly skipped if their arguments are not set. Arguments can be passed like so:

mvn test -Dcertificate=path/to/cert -Dprivatekey=path/to/key ...

Many tests require that you have set up an AWS IoT Thing.

Full list of test arguments:

endpoint: AWS IoT service endpoint hostname
certificate: Path to the IoT thing certificate
privatekey: Path to the IoT thing private key
privatekey_p8: Path to the IoT thing private key in PKCS#8 format
ecc_certificate: Path to the IoT thing with EC-based certificate
ecc_privatekey: Path to the IoT thing with ECC private key (The ECC key file should only contains the ECC Private Key section to working on MacOS.)
rootca: Path to the root certificate
proxyhost: Hostname of proxy
proxyport: Port of proxy
NETWORK_TESTS_DISABLED: Set this if tests are running in a constrained environment where network access is not guaranteed/allowed.

These can be set persistently via Maven settings (usually in ~/.m2/settings.xml):

<settings>
    ...
  <profiles>
    <profile>
        <activation>
            <activeByDefault>true</activeByDefault>
        </activation>
        <properties>
            <crt.test.endpoint>XXXXXXXXXX-ats.iot.us-east-1.amazonaws.com</crt.test.endpoint>
            <crt.test.certificate>/path/to/XXXXXXXX-certificate.pem.crt</crt.test.certificate>
            <crt.test.privatekey>/path/to/XXXXXXXX-private.pem.key</crt.test.privatekey>
            <crt.test.rootca>/path/to/AmazonRootCA1.pem</crt.test.rootca>
            ... etc ...
        </properties>
    </profile>
  </profiles>
</settings>%

IDEs

CMake is configured to export a compilation database at target/cmake-build/compile_commands.json
CLion: Build once with maven, then import the project as a Compilation Database Project
VSCode: will detect that this is both a java project and if you have the CMake extension, you can point that at CMakeLists.txt and the compilation database

Debugging

Tests can be debugged in Java/Kotlin via the built-in tooling in VSCode and IntelliJ. If you need to debug the native code, it's a bit trickier.

To debug native code with VSCode or CLion or any other IDE:

Find your mvn launch script(e.g. realpath $(which mvn)) and pull the command line at the bottom from it. This changes between versions of maven, so it is difficult to give consistent directions.
As an example, for Maven 3.6.0 on Linux: /path/to/java -classpath /usr/share/java/plexus-classworlds-2.5.2.jar -Dclassworlds.conf=/usr/share/maven/bin/m2.conf -Dmaven.home=/usr/share/maven -Dlibrary.jansi.path=/usr/share/maven/lib/jansi-native -Dmaven.multiModuleProjectDirectory=. org.codehaus.plexus.classworlds.launcher.Launcher test -DforkCount=0 -Ddebug.native -Dtest=HttpClientConnectionManager#testMaxParallelConnections
The important parts are:
- -DforkCount=0 - prevents the Maven process from forking to run tests, so your debugger will be attached to the right process. You can ignore this if you configure your debugger to attach to child processes.
- -Ddebug.native - Makes CMake compile the JNI bindings and core libraries in debug. By default, we compile in release with symbols, which will help for call stacks, but less so for live debugging.
Set the executable to launch to be your java binary (e.g. /usr/bin/java)
Set the parameters to be the ones used by the mvn script, as per above
Set the working directory to the aws-crt-java directory
On windows, you will need to manually load the PDB via the Modules window in Visual Studio, as it is not embedded in the JAR. It will be in the target/cmake-build/lib/windows/<arch> folder.