Programmer Guide

This document will help Java developers get up and running with the jets3t toolkit.

Sample code fragments are available in the Code Samples.

Prerequisites

  • Sign-up for an Amazon Simple Storage Service account (credit card required)
  • Download the jets3t toolkit.
  • Obtain the latest Technical Documentation for the Amazon S3 service, in particular the API guide which will help you understand how S3 works and what you can do with it

Set-up your project

Required libraries

To use jets3t you must add at least the following libraries to your classpath:

  • jets3t-0.6.1.jar (the jets3t 'toolkit' library)
  • commons-logging-1.1.1.jar
  • commons-codec-1.3.jar
  • log4j-1.2.15.jar

In addition to these libraries, you must also add any libraries required by the S3 Service implementation you intend to use (see below).

S3 Service Implementations

jets3t includes two service implementations: REST/HTTP based on HttpClient 3; and SOAP based on Axis 1.4.

We strongly advise that you use the HttpClient-based REST/HTTP implementation as the SOAP version does not stream uploaded data and is therefore highly susceptible to OutOfMemory errors.

REST/HTTP
Class org.jets3t.service.impl.rest.httpclient.RestS3Service
Based on HttpClient 3.1
Required Libraries
  • Commons HttpClient : commons-httpclient-3.1.jar

 

SOAP
Class org.jets3t.service.impl.soap.axis.SoapS3Service
Based on Apache Axis 1.4
Required Libraries
  • Apache Axis : axis.jar, commons-discovery-0.2.jar, jaxrpc.jar, saaj.jar, wsdl4j-1.5.1.jar
  • Castor : castor-1.0.1.jar
  • Java Activation Framework : activation.jar
  • JavaMail : mail.jar
  • Xerces : xercesImpl.jar, xmlParserAPIs.jar
Known Issues Uploaded data is buffered in memory prior to being sent, and is therefore limited to the size of the available memory.
S3 requires use of DIME attachments for upload objects greater than 1MB; this implementation does not use DIME and therefore cannot support large uploads.

Note: If you would prefer to use your own favourite HTTP or SOAP library, you can write your own S3Service implementation based on the class org.jets3t.service.S3Service.

Logging

The jets3t toolkit uses Commons Logging. To configure the information logged by the toolkit, you must include a commons-logging.properties file in the classpath.

For example, to configure Commons Logging to use the Log4j logging library, add the Log4j library and configuration file to the classpath and use the following line in the Commons Logging config file:

org.apache.commons.logging.Log=org.apache.commons.logging.impl.Log4JLogger