Getting Started with ECS - Java + S3 (JetS3t)

The JetS3t toolkit is a popular API for connecting to S3 storage services.  While it assumes you're using Amazon services by default, starting with version 0.7.0 it is possible to reconfigure the endpoint by setting certain properties:


  • s3service.s3-endpoint - this should be set to either the IP address of your ECS node or the "Base URL" of your service, e.g. "".
  • s3service.s3-endpoint-http-port - If you are connecting directly to ECS nodes and not a load balancer, this should be set to 9020.
  • s3service.s3-endpoint-https-port - If you are connecting directly to ECS nodes and not a load balancer, this should be set to 9021.
  • s3service.disable-dns-buckets - If your ECS configuration does not support a wildcard DNS entry (e.g. * or you are connecting to ECS using IP addresses, you should set this to true to disable the use of virtually hosted (DNS) buckets.
  • s3service.https-only - If you want to connect to ECS over plain HTTP for debugging purposes, you can set this to false.


These properties can be set in two ways:

  1. Create a file named and put it on your classpath
  2. Create a Jets3tProperties object, set the name-value pairs on that, and pass it to the RestS3Service constructor.


We will take the second approach and create a sample application that will create a bucket, catch the error if it exists, and upload an object into the bucket.


First, we'll create and configure the Jets3tProperties object:


        Jets3tProperties props = new Jets3tProperties();
        props.setProperty("s3service.s3-endpoint", "");
        props.setProperty("s3service.s3-endpoint-http-port", "9020");
        props.setProperty("s3service.s3-endpoint-https-port", "9021");
        props.setProperty("s3service.disable-dns-buckets", "false");
        props.setProperty("s3service.https-only", "false");


Next, the RestS3Service object is constructed:


try {
            RestS3Service ecs = new RestS3Service(
                    new AWSCredentials("",
                    "JetS3t-sample", null, props);


We can then attempt to create the bucket.  The error "BucketAlreadyExists" will be caught, but others will be re-thrown to abort.


           String bucket = "testbucket1";
            String key = "myfile.txt";

            // Try to create the bucket.
            try {
                System.out.printf("Created bucket %s\n", bucket);
            } catch (S3ServiceException e) {
                if ("BucketAlreadyExists".equals(e.getErrorCode())) {
                    System.out.printf("Bucket %s already exists\n", bucket);
                } else {
                    throw e;


Now that we know a bucket exists, we can create the object.


            // Bucket created, create an object
            S3Object o = new S3Object(key, "Hello World!");
            o.setContentType("text/plain"); // Set content type **
            o = ecs.putObject(bucket, o);
            System.out.printf("Created object %s, etag: %s\n", o.getKey(), o.getETag());
        } catch (Exception e) {



The full sample is attached to this document.  Running the sample application yields:


Created bucket testbucket1
Created object myfile.txt, etag: ed076287532e86365e841e92bfc50d8c