org.jets3t.service.impl.rest.httpclient
Class RestS3Service

java.lang.Object
  extended by org.jets3t.service.S3Service
      extended by org.jets3t.service.impl.rest.httpclient.RestS3Service
All Implemented Interfaces:
Serializable, AWSRequestAuthorizer, SignedUrlHandler

public class RestS3Service
extends S3Service
implements SignedUrlHandler, AWSRequestAuthorizer

REST/HTTP implementation of an S3Service based on the HttpClient library.

This class uses properties obtained through Jets3tProperties. For more information on these properties please refer to JetS3t Configuration

Author:
James Murty
See Also:
Serialized Form

Nested Class Summary
 class RestS3Service.HttpMethodAndByteCount
          Simple container object to store an HttpMethod object representing a request connection, and a count of the byte size of the S3 object associated with the request.
 
Field Summary
static String VERSION
           
static String XML_NAMESPACE
           
 
Fields inherited from class org.jets3t.service.S3Service
BUCKET_STATUS__ALREADY_CLAIMED, BUCKET_STATUS__DOES_NOT_EXIST, BUCKET_STATUS__MY_BUCKET, VERSION_NO__JETS3T_TOOLKIT
 
Constructor Summary
RestS3Service(AWSCredentials awsCredentials)
          Constructs the service and initialises the properties.
RestS3Service(AWSCredentials awsCredentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
          Constructs the service and initialises the properties.
RestS3Service(AWSCredentials awsCredentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties)
          Constructs the service and initialises the properties.
RestS3Service(AWSCredentials awsCredentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties, org.apache.commons.httpclient.HostConfiguration hostConfig)
          Constructs the service and initialises the properties.
 
Method Summary
 void authorizeHttpRequest(org.apache.commons.httpclient.HttpMethod httpMethod)
          Authorizes an HTTP request by signing it.
 int checkBucketStatus(String bucketName)
          Find out the status of an S3 bucket with the given name.
 void deleteObjectWithSignedUrl(String signedDeleteUrl)
          Deletes an object using a pre-signed DELETE URL generated for that object.
 org.apache.commons.httpclient.auth.CredentialsProvider getCredentialsProvider()
           
 org.apache.commons.httpclient.HttpClient getHttpClient()
           
 org.apache.commons.httpclient.HttpConnectionManager getHttpConnectionManager()
           
 AccessControlList getObjectAclWithSignedUrl(String signedAclUrl)
          Gets an object's ACL details using a pre-signed GET URL generated for that object.
 S3Object getObjectDetailsWithSignedUrl(String signedHeadUrl)
          Gets an object's details using a pre-signed HEAD URL generated for that object.
 S3Object getObjectWithSignedUrl(String signedGetUrl)
          Gets an object using a pre-signed GET URL generated for that object.
 boolean isBucketAccessible(String bucketName)
          Indicates whether a bucket exists and is accessible to a service user.
 void putObjectAclWithSignedUrl(String signedAclUrl, AccessControlList acl)
          Sets an object's ACL details using a pre-signed PUT URL generated for that object.
 S3Object putObjectWithSignedUrl(String signedPutUrl, S3Object object)
          Puts an object using a pre-signed PUT URL generated for that object.
 void setCredentialsProvider(org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
          Sets the credentials provider this service will use to authenticate itself.
 void setHttpClient(org.apache.commons.httpclient.HttpClient httpClient)
          Replaces the service's default HTTP client.
 void setHttpConnectionManager(org.apache.commons.httpclient.HttpConnectionManager httpConnectionManager)
          Replaces the service's default HTTP connection manager.
 
Methods inherited from class org.jets3t.service.S3Service
buildPostForm, buildPostForm, buildPostForm, copyObject, copyObject, copyVersionedObject, copyVersionedObject, createBucket, createBucket, createBucket, createSignedDeleteUrl, createSignedDeleteUrl, createSignedDeleteUrl, createSignedDeleteUrl, createSignedGetUrl, createSignedGetUrl, createSignedGetUrl, createSignedGetUrl, createSignedHeadUrl, createSignedHeadUrl, createSignedHeadUrl, createSignedHeadUrl, createSignedPutUrl, createSignedPutUrl, createSignedPutUrl, createSignedPutUrl, createSignedUrl, createSignedUrl, createSignedUrl, createSignedUrl, createSignedUrl, createSignedUrl, createTorrentUrl, createTorrentUrl, createUnsignedObjectUrl, deleteBucket, deleteBucket, deleteObject, deleteObject, deleteVersionedObject, deleteVersionedObjectWithMFA, disableMFAForVersionedBucket, enableBucketVersioning, enableBucketVersioningAndMFA, enableBucketVersioningWithMFA, generatePostPolicyCondition_AllowAnyValue, generatePostPolicyCondition_Equality, generatePostPolicyCondition_Equality, generatePostPolicyCondition_Equality, generatePostPolicyCondition_Range, generatePostPolicyCondition, getAccountOwner, getAWSCredentials, getBucket, getBucketAcl, getBucketAcl, getBucketLocation, getBucketLoggingStatus, getBucketVersioningStatus, getCurrentTimeWithOffset, getDevPayProductToken, getDevPayUserToken, getInternalErrorRetryMax, getInvokingApplicationDescription, getJetS3tProperties, getObject, getObject, getObject, getObject, getObjectAcl, getObjectAcl, getObjectDetails, getObjectDetails, getObjectDetails, getObjectDetails, getObjectVersions, getOrCreateBucket, getOrCreateBucket, getVersionedObject, getVersionedObject, getVersionedObject, getVersionedObjectAcl, getVersionedObjectAcl, getVersionedObjectDetails, getVersionedObjectDetails, getVersionedObjectDetails, isAuthenticatedConnection, isHttpsOnly, isObjectInBucket, isRequesterPaysBucket, isRequesterPaysEnabled, isShutdown, listAllBuckets, listObjects, listObjects, listObjects, listObjects, listObjects, listObjectsChunked, listObjectsChunked, listVersionedObjects, listVersionedObjectsChunked, moveObject, putBucketAcl, putBucketAcl, putObject, putObject, putObjectAcl, putObjectAcl, putVersionedObjectAcl, putVersionedObjectAcl, renameObject, setBucketLoggingStatus, setDevPayProductToken, setDevPayUserToken, setRequesterPaysBucket, setRequesterPaysEnabled, shutdown, suspendBucketVersioning, suspendBucketVersioningWithMFA, updateObjectMetadata
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final String VERSION
See Also:
Constant Field Values

XML_NAMESPACE

public static final String XML_NAMESPACE
See Also:
Constant Field Values
Constructor Detail

RestS3Service

public RestS3Service(AWSCredentials awsCredentials)
              throws S3ServiceException
Constructs the service and initialises the properties.

Parameters:
awsCredentials - the S3 user credentials to use when communicating with S3, may be null in which case the communication is done as an anonymous user.
Throws:
S3ServiceException

RestS3Service

public RestS3Service(AWSCredentials awsCredentials,
                     String invokingApplicationDescription,
                     org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
              throws S3ServiceException
Constructs the service and initialises the properties.

Parameters:
awsCredentials - the S3 user credentials to use when communicating with S3, may be null in which case the communication is done as an anonymous user.
invokingApplicationDescription - a short description of the application using the service, suitable for inclusion in a user agent string for REST/HTTP requests. Ideally this would include the application's version number, for example: Cockpit/0.7.3 or My App Name/1.0
credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
Throws:
S3ServiceException

RestS3Service

public RestS3Service(AWSCredentials awsCredentials,
                     String invokingApplicationDescription,
                     org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                     Jets3tProperties jets3tProperties)
              throws S3ServiceException
Constructs the service and initialises the properties.

Parameters:
awsCredentials - the S3 user credentials to use when communicating with S3, may be null in which case the communication is done as an anonymous user.
invokingApplicationDescription - a short description of the application using the service, suitable for inclusion in a user agent string for REST/HTTP requests. Ideally this would include the application's version number, for example: Cockpit/0.7.3 or My App Name/1.0
credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
jets3tProperties - JetS3t properties that will be applied within this service.
Throws:
S3ServiceException

RestS3Service

public RestS3Service(AWSCredentials awsCredentials,
                     String invokingApplicationDescription,
                     org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                     Jets3tProperties jets3tProperties,
                     org.apache.commons.httpclient.HostConfiguration hostConfig)
              throws S3ServiceException
Constructs the service and initialises the properties.

Parameters:
awsCredentials - the S3 user credentials to use when communicating with S3, may be null in which case the communication is done as an anonymous user.
invokingApplicationDescription - a short description of the application using the service, suitable for inclusion in a user agent string for REST/HTTP requests. Ideally this would include the application's version number, for example: Cockpit/0.7.3 or My App Name/1.0
credentialsProvider - an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
jets3tProperties - JetS3t properties that will be applied within this service.
hostConfig - Custom HTTP host configuration; e.g to register a custom Protocol Socket Factory
Throws:
S3ServiceException
Method Detail

getHttpConnectionManager

public org.apache.commons.httpclient.HttpConnectionManager getHttpConnectionManager()
Returns:
the manager of HTTP connections for this service.

setHttpConnectionManager

public void setHttpConnectionManager(org.apache.commons.httpclient.HttpConnectionManager httpConnectionManager)
Replaces the service's default HTTP connection manager. This method should only be used by advanced users.

Parameters:
httpConnectionManager - the connection manager that will replace the default manager created by the class constructor.

getHttpClient

public org.apache.commons.httpclient.HttpClient getHttpClient()
Returns:
the HTTP client for this service.

setHttpClient

public void setHttpClient(org.apache.commons.httpclient.HttpClient httpClient)
Replaces the service's default HTTP client. This method should only be used by advanced users.

Parameters:
httpClient - the client that will replace the default client created by the class constructor.

getCredentialsProvider

public org.apache.commons.httpclient.auth.CredentialsProvider getCredentialsProvider()
Returns:
the credentials provider this service will use to authenticate itself, or null if no provider is set.

setCredentialsProvider

public void setCredentialsProvider(org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
Sets the credentials provider this service will use to authenticate itself. Changing the credentials provider with this method will have no effect until the initHttpConnection(HostConfiguration) method is called.

Parameters:
credentialsProvider -

authorizeHttpRequest

public void authorizeHttpRequest(org.apache.commons.httpclient.HttpMethod httpMethod)
                          throws Exception
Authorizes an HTTP request by signing it. The signature is based on the target URL, and the signed authorization string is added to the HttpMethod object as an Authorization header.

Specified by:
authorizeHttpRequest in interface AWSRequestAuthorizer
Parameters:
httpMethod - the request object
Throws:
S3ServiceException
Exception

isBucketAccessible

public boolean isBucketAccessible(String bucketName)
                           throws S3ServiceException
Description copied from class: S3Service
Indicates whether a bucket exists and is accessible to a service user. Caution: After changes to the way S3 operates, this check started to cause issues in situations where you need to immediately create a bucket when it does not exist. To conditionally create a bucket, use the S3Service.getOrCreateBucket(String) method instead.

This method can be performed by anonymous services.

Implementation notes

This method can be implemented by attempting to list the objects in a bucket. If the listing is successful return true, if the listing failed for any reason return false.

Specified by:
isBucketAccessible in class S3Service
Returns:
true if the bucket exists and is accessible to the service user, false otherwise.
Throws:
S3ServiceException

checkBucketStatus

public int checkBucketStatus(String bucketName)
                      throws S3ServiceException
Description copied from class: S3Service
Find out the status of an S3 bucket with the given name. This method is only implemented in the RestS3Service client.

Warning! S3 can act strangely when you use this method in some circumstances. If you check the status of a bucket and find that it does not exist, then create the bucket, S3 will continue to tell you the bucket does not exists for up to 30 seconds. This problem has something to do with connection caching (I think).

This S3 quirk makes it a bad idea to use this method to check for a bucket's existence before creating that bucket. Use the S3Service.getOrCreateBucket(String) method for this purpose instead.

Specified by:
checkBucketStatus in class S3Service
Returns:
S3Service.BUCKET_STATUS__MY_BUCKET if you already own the bucket, S3Service.BUCKET_STATUS__DOES_NOT_EXIST if the bucket does not yet exist in S3, or S3Service.BUCKET_STATUS__ALREADY_CLAIMED if someone else has already created a bucket with the given name.
Throws:
S3ServiceException

putObjectWithSignedUrl

public S3Object putObjectWithSignedUrl(String signedPutUrl,
                                       S3Object object)
                                throws S3ServiceException
Puts an object using a pre-signed PUT URL generated for that object. This method is an implementation of the interface SignedUrlHandler.

This operation does not required any S3 functionality as it merely uploads the object by performing a standard HTTP PUT using the signed URL.

Specified by:
putObjectWithSignedUrl in interface SignedUrlHandler
Parameters:
signedPutUrl - a signed PUT URL.
object - the object to upload, which must correspond to the object for which the URL was signed. The object must have the correct content length set, and to apply a non-standard ACL policy only the REST canned ACLs can be used (eg AccessControlList.REST_CANNED_PUBLIC_READ_WRITE).
Returns:
the S3Object put to S3. The S3Object returned will represent the object created in S3.
Throws:
S3ServiceException

deleteObjectWithSignedUrl

public void deleteObjectWithSignedUrl(String signedDeleteUrl)
                               throws S3ServiceException
Deletes an object using a pre-signed DELETE URL generated for that object. This method is an implementation of the interface SignedUrlHandler.

This operation does not required any S3 functionality as it merely deletes the object by performing a standard HTTP DELETE using the signed URL.

Specified by:
deleteObjectWithSignedUrl in interface SignedUrlHandler
Parameters:
signedDeleteUrl - a signed DELETE URL.
Throws:
S3ServiceException

getObjectWithSignedUrl

public S3Object getObjectWithSignedUrl(String signedGetUrl)
                                throws S3ServiceException
Gets an object using a pre-signed GET URL generated for that object. This method is an implementation of the interface SignedUrlHandler.

This operation does not required any S3 functionality as it merely uploads the object by performing a standard HTTP GET using the signed URL.

Specified by:
getObjectWithSignedUrl in interface SignedUrlHandler
Parameters:
signedGetUrl - a signed GET URL.
Returns:
the S3Object in S3 including all metadata and the object's data input stream.
Throws:
S3ServiceException

getObjectDetailsWithSignedUrl

public S3Object getObjectDetailsWithSignedUrl(String signedHeadUrl)
                                       throws S3ServiceException
Gets an object's details using a pre-signed HEAD URL generated for that object. This method is an implementation of the interface SignedUrlHandler.

This operation does not required any S3 functionality as it merely uploads the object by performing a standard HTTP HEAD using the signed URL.

Specified by:
getObjectDetailsWithSignedUrl in interface SignedUrlHandler
Parameters:
signedHeadUrl - a signed HEAD URL.
Returns:
the S3Object in S3 including all metadata, but without the object's data input stream.
Throws:
S3ServiceException

getObjectAclWithSignedUrl

public AccessControlList getObjectAclWithSignedUrl(String signedAclUrl)
                                            throws S3ServiceException
Gets an object's ACL details using a pre-signed GET URL generated for that object. This method is an implementation of the interface SignedUrlHandler.

Specified by:
getObjectAclWithSignedUrl in interface SignedUrlHandler
Parameters:
signedAclUrl - a signed URL.
Returns:
the AccessControlList settings of the object in S3.
Throws:
S3ServiceException

putObjectAclWithSignedUrl

public void putObjectAclWithSignedUrl(String signedAclUrl,
                                      AccessControlList acl)
                               throws S3ServiceException
Sets an object's ACL details using a pre-signed PUT URL generated for that object. This method is an implementation of the interface SignedUrlHandler.

Specified by:
putObjectAclWithSignedUrl in interface SignedUrlHandler
Parameters:
signedAclUrl - a signed URL.
acl - the ACL settings to apply to the object represented by the signed URL.
Throws:
S3ServiceException