Java Manta Client SDK

java-manta is a community-maintained Java SDK for interacting with Joyent's Manta system.

Projects Using the Java Manta Client SDK

• Apache Commons VFS Manta Provider (Virtual File System)
• Hadoop Filesystem Driver for Manta
• Manta Logback Rollover
• COSBench Adaptor for Manta - Object Store Benchmarks
• Manta Monitor
• Java Manta Test Harness

Installation

Java 1.8 is required for SDK compilation. It effectively supports both Java 8 and Java 11 in application usage. The main client module can be installed by adding the following dependency using Maven 3.1.x:

<dependency>
    <groupId>com.joyent.manta</groupId>
    <artifactId>java-manta-client</artifactId>
    <version>LATEST</version>
</dependency>

and the unshaded module can be installed by adding the following dependency using Maven 3.1.x:

<dependency>
    <groupId>com.joyent.manta</groupId>
    <artifactId>java-manta-client-unshaded</artifactId>
    <version>LATEST</version>
</dependency>

Please refer to the installation documentation for more details about the following topics:

• 192-bit and 256-bit AES encryption requiring Java Cryptography Extensions
• PKCS#11 configuration for faster encryption using libnss
• Native implementation of MD5 calculations for faster digest operations

Configuration

Configuration can be done through system properties or environment variables. Listed below are the most commonly used configuration options:

• manta.url ( MANTA_URL ) The URL of the manta service endpoint to test against
• manta.user ( MANTA_USER ) The account name used to access the manta service. If accessing via a subuser, you will specify the account name as "user/subuser".
• manta.key_id: ( MANTA_KEY_ID) The fingerprint for the public key used to access the manta service. Can be obtained using ssh-keygen -l -f ${MANTA_KEY_PATH} -E md5 | cut -d' ' -f 2
• manta.key_path ( MANTA_KEY_PATH) The name of the file that will be loaded for the account used to access the manta service.

Please refer to the configuration documentation for example code and the full list of configuration options which include retry and performance tuning in addition to encryption and authentication parameters.

Usage

You'll need a manta login, an associated key, and its corresponding key fingerprint.

You will then create or use an implementation of ConfigContext to set up your configuration. Once you have an instance of your configuration class, you will then construct a MantaClient instance. The MantaClient class is intended to be used per Manta account. It is thread-safe and you should share one instance across multiple threads.

For detailed usage instructions consult the provided JavaDoc and examples. The JavaDoc can also be browsed online at javadoc.io

General Examples

• Get request and client setup
• Multipart upload
• Client-side Encryption

Job Examples

Jobs can be created directly with the MantaClient class or they can be created using the MantaJobBuilder class. MantaJobBuilder provides a fluent interface that allows for an easier API for job creation and it provides a number of useful functions for common use cases.

• Jobs using MantaClient
• Jobs using MantaJobBuilder

For more examples, check the included examples module and the integration test module.

FAQs

Known edge cases and other topics are covered in the FAQ.

Contributions

Contributions are welcome! Please read the CONTRIBUTING.md document for details on getting started.

Developing

There are portions of the SDK that are somewhat complex or fiddly. Please read the DEVELOPING.md document for details, before developing the Java SDK.

Testing

Contributing developers are strongly encouraged to add unit-tests and integration-tests. Refer to the testing documentation for information on full test suite requirements.

Releasing

Please refer to the release documentation.

Bugs

See https://github.com/joyent/java-manta/issues.

License

Java Manta is licensed under the MPLv2. Please see the LICENSE.txt file for more details. The license was changed from the MIT license to the MPLv2 license starting at version 2.3.0.

Credits

We are grateful for the functionality provided by the libraries that this project depends on. Without them, we would be building everything from scratch. A thank you goes out to:

• The Apache Commons Project
• The Apache HTTP Components Project
• The FastXML Project
• The Legion of the Bouncy Castle Project
• The SLF4J Project
• The JNAGMP Project
• The TestNG Project
• The Mockito Project
• Timothy W Macinta's FastMD5 Project
• Remko Popma's picocli Project