Getting Started with ECS - Java + Atmos

ECS's atmos-client package for Java allows you to connect to either ECS Atmos subtenants or native Atmos instances.  It handles all of the low-level tasks such as generating and signing requests, connecting to the server, and parsing server responses.



All dependencies are included in the binary distribution package or referenced as Maven coordinates.

  • Java 7+
  • Log4J (Apache license)
  • Slf4j (MIT license)
  • JDOM (see jdom-license.txt)
  • Commons Logging (Apache license)
  • Commons Codec (Apache license)
  • Apache HTTP Client (Apache license)
  • Jersey (GPLv2 & CDDL)
  • Cryptix JCE (non-Maven, BSD license) -- only required for SHA0 implementation


Atmos Subtenants

In the Atmos protocol, each logical namespace is referred to as a "subtenant".  This is akin to a bucket in S3 and a container in Swift.  Before you can use the Atmos protocol, you must have a subtenant created.  Refer to this article for information on how to create subtenants in ECS.




The preferred method for downloading the client is to include the dependency in a Maven project.  The Maven project dependency is:




If you are not using a Maven-compatible build system, see the Java SDK page for information on downloading a binary release of the ViPR Data Services Java SDK.




In order to use the API, you need to construct an instance of the AtmosApiClient class, passing in an instance of AtmosConfig.  This class contains the parameters used to connect to the server.


AtmosApi atmos = new AtmosApiClient( new AtmosConfig( "uid",
                                                      "shared secret",
                                                      new URI( "http://host:port" ) ) );


Where host is the hostname or IP address of a ECS or Atmos node that you're authorized to access, port is the IP port number used to connect to the server (generally 80 for Atmos or 9022 for ECS), UID is the full token ID (subtenant ID + "/" + user ID) to connect as, and the shared secret is the shared secret key assigned to the UID you're using.  The UID and shared secret are available from your Atmos tenant administrator or your user "Data Store Keys" in the ECS console.  The secret key should be a base-64 encoded string as shown in the tenant administration console, e.g "jINDh7tV/jkry7o9D+YmauupIQk=".


After you have created your AtmosApiClient object, you can use the methods on the object to manipulate data in the cloud.  For instance, to create a new, empty object in the cloud, you can simply call:


ObjectId id = atmos.createObject( null, null );


The createObject method will return an ObjectId you can use in subsequent calls to modify the object.  You can also pass in Strings, byte arrays, or File objects to the createObject method:


     String stringContent = "Hello World!";
     ObjectId oid1 = atmos.createObject( stringContent, "text/plain" );

     File fileContent = new File( "spreadsheet.xls" );
     ObjectId oid2 = atmos.createObject( fileContent, "application/" );

     byte[] binaryContent;
     ... // load binary content to store as an object
     ObjectId oid3 = atmos.createObject( binaryContent, null ); // default content-type is application/octet-stream


When reading an object, you pass the Class object of the content type you're expecting to receive, e.g.


    String stringContent = atmos.readObject( oid1, String.class );

    byte[] binaryContent = atmos.readObject( oid3, byte[].class );

If you want an input stream, use the readObjectStream method:


    InputStream fileContent = atmos.readObject( oid2, null );


You can review the javadoc for the AtmosApi class for more information on the available features of the Atmos Client.  For details about programming using Atmos, you can download the Atmos Programmers Guide from




The API uses Log4J for logging functionality.  See the file src/ for a sample logging configuration that appends all debug output to atmos.log.




Socket errors on older versions of Windows


On Windows XP and older versions of windows, a client making many requests may run out of client sockets.  The error you see will look like: Address already in use: connect


This is because Windows only allows client sockets up to port 5000 by default and when a socket is closed it remains in TIME_WAIT for 180 seconds.  Thus, if you make more than 4000 requests in 3 minutes you will likely see these errors. You can fix this problem by editing the registry and changing MaxUserPort and TCPTimedWaitDelay settings.  This is discussed in the article:


SSL Errors


If you are connecting over SSL, you may see the following error (usually on development systems):


Exception in thread "main" PKIX path building failed: unable to find valid certification path to requested target


This is because by default ECS will generate and use a self-signed SSL certificate on the data services nodes.  There are two workarounds to this issue:


1) Disable SSL validation on the client (not suitable for production)

2) Install the SSL certificate in your local keystore.


To disable SSL validation in the AtmosApiClient, call setDisableSslValidation(true) on your AtmosConfig before constructing your AtmosApiClient.  As stated above, this is OK for development work, but in production it is insecure since it is trivial for an attacker to generate any SSL certificate they want and hijack your connections with a man-in-the-middle attack.


The better solution is to download the SSL certificate from the server and install it as a trusted certificate.  To install the SSL certificate in your local keystore, see this article for a link to the InstallCert utility for Java.