org.jets3t.service.impl.soap.axis
Class SoapS3Service

java.lang.Object
  extended by org.jets3t.service.S3Service
      extended by org.jets3t.service.impl.soap.axis.SoapS3Service
All Implemented Interfaces:
java.io.Serializable

public class SoapS3Service
extends S3Service

SOAP implementation of an S3Service based on the Apache Axis 1.4 library.

Note: This SOAP implementation does not support IO streaming uploads to S3. Any documents uploaded by this implementation must fit inside memory allocated to the Java program running this class if OutOfMemory errors are to be avoided.

Note 2: The SOAP implementation does not perform retries when communication with s3 fails.

The preferred S3Service implementation in JetS3t is RestS3Service. This SOAP implementation class is provided with JetS3t as a proof-of-concept, showing that alternative service implementations are possible and what a SOAP service might look like. We do not recommend that this service be used to perform any real work.

Author:
James Murty
See Also:
Serialized Form

Field Summary
 
Fields inherited from class org.jets3t.service.S3Service
BUCKET_STATUS__ALREADY_CLAIMED, BUCKET_STATUS__DOES_NOT_EXIST, BUCKET_STATUS__MY_BUCKET, jets3tProperties, timeOffset, VERSION_NO__JETS3T_TOOLKIT
 
Constructor Summary
SoapS3Service(AWSCredentials awsCredentials)
          Constructs the SOAP service implementation and, based on the value of S3Service.isHttpsOnly sets the SOAP endpoint to use HTTP or HTTPS protocols.
SoapS3Service(AWSCredentials awsCredentials, java.lang.String invokingApplicationDescription)
          Constructs the SOAP service implementation and, based on the value of S3Service.isHttpsOnly sets the SOAP endpoint to use HTTP or HTTPS protocols.
SoapS3Service(AWSCredentials awsCredentials, java.lang.String invokingApplicationDescription, Jets3tProperties jets3tProperties)
          Constructs the SOAP service implementation and, based on the value of S3Service.isHttpsOnly sets the SOAP endpoint to use HTTP or HTTPS protocols.
 
Method Summary
 int checkBucketStatus(java.lang.String bucketName)
          Find out the status of an S3 bucket with the given name.
protected  java.util.Map copyObjectImpl(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, java.lang.String destinationObjectKey, AccessControlList acl, java.util.Map destinationMetadata, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags, java.lang.String versionId)
          Copy an object within your S3 account.
protected  S3Bucket createBucketImpl(java.lang.String bucketName, java.lang.String location, AccessControlList acl)
          Creates a bucket.
protected  void deleteBucketImpl(java.lang.String bucketName)
           
protected  void deleteObjectImpl(java.lang.String bucketName, java.lang.String objectKey, java.lang.String versionId, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode)
           
protected  S3Owner getAccountOwnerImpl()
           
protected  AccessControlList getBucketAclImpl(java.lang.String bucketName)
           
protected  java.lang.String getBucketLocationImpl(java.lang.String bucketName)
           
protected  S3BucketLoggingStatus getBucketLoggingStatusImpl(java.lang.String bucketName)
           
protected  S3BucketVersioningStatus getBucketVersioningStatusImpl(java.lang.String bucketName)
           
protected  AccessControlList getObjectAclImpl(java.lang.String bucketName, java.lang.String objectKey, java.lang.String versionId)
           
protected  S3Object getObjectDetailsImpl(java.lang.String bucketName, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags, java.lang.String versionId)
           
protected  S3Object getObjectImpl(java.lang.String bucketName, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags, java.lang.Long byteRangeStart, java.lang.Long byteRangeEnd, java.lang.String versionId)
           
 boolean isBucketAccessible(java.lang.String bucketName)
          Indicates whether a bucket exists and is accessible to a service user.
protected  boolean isRequesterPaysBucketImpl(java.lang.String bucketName)
           
protected  S3Bucket[] listAllBucketsImpl()
           
protected  S3ObjectsChunk listObjectsChunkedImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey, boolean completeListing)
          Lists objects in a bucket up to the maximum listing length specified.
protected  S3Object[] listObjectsImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength)
          Lists objects in a bucket.
protected  S3ObjectsChunk listObjectsInternalImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, boolean automaticallyMergeChunks, java.lang.String priorLastKey)
           
protected  VersionOrDeleteMarkersChunk listVersionedObjectsChunkedImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey, java.lang.String priorLastVersion, boolean completeListing)
          Lists version or delete markers in a versioned bucket, up to the maximum listing length specified.
protected  BaseVersionOrDeleteMarker[] listVersionedObjectsImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, java.lang.String keyMarker, java.lang.String versionMarker, long maxListingLength)
           
protected  void putBucketAclImpl(java.lang.String bucketName, AccessControlList acl)
           
protected  void putObjectAclImpl(java.lang.String bucketName, java.lang.String objectKey, AccessControlList acl, java.lang.String versionId)
           
protected  S3Object putObjectImpl(java.lang.String bucketName, S3Object object)
           
protected  void setBucketLoggingStatusImpl(java.lang.String bucketName, S3BucketLoggingStatus status)
           
protected  void setRequesterPaysBucketImpl(java.lang.String bucketName, boolean requesterPays)
           
protected  void shutdownImpl()
           
protected  void updateBucketVersioningStatusImpl(java.lang.String bucketName, boolean enabled, boolean multiFactorAuthDeleteEnabled, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode)
           
 
Methods inherited from class org.jets3t.service.S3Service
assertAuthenticatedConnection, assertValidBucket, assertValidObject, assertValidObject, buildPostForm, buildPostForm, buildPostForm, copyObject, copyObject, copyVersionedObject, copyVersionedObject, createBucket, createBucket, createBucket, createSignedDeleteUrl, createSignedDeleteUrl, createSignedGetUrl, createSignedGetUrl, createSignedHeadUrl, createSignedHeadUrl, createSignedPutUrl, createSignedPutUrl, createSignedUrl, createSignedUrl, createSignedUrl, createTorrentUrl, deleteBucket, deleteBucket, deleteObject, deleteObject, deleteVersionedObject, deleteVersionedObjectWithMFA, disableMFAForVersionedBucket, enableBucketVersioning, enableBucketVersioningWithMFA, generatePostPolicyCondition_AllowAnyValue, generatePostPolicyCondition_Equality, generatePostPolicyCondition_Equality, generatePostPolicyCondition_Equality, generatePostPolicyCondition_Range, generatePostPolicyCondition, generateS3HostnameForBucket, 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, isBucketNameValidDNSName, isHttpsOnly, isObjectInBucket, isRequesterPaysBucket, isRequesterPaysEnabled, isShutdown, listAllBuckets, listObjects, listObjects, listObjects, listObjects, listObjectsChunked, listObjectsChunked, listVersionedObjects, listVersionedObjectsChunked, moveObject, putBucketAcl, putBucketAcl, putObject, putObject, putObjectAcl, putObjectAcl, putVersionedObjectAcl, putVersionedObjectAcl, renameObject, setBucketLoggingStatus, setDevPayProductToken, setDevPayUserToken, setRequesterPaysBucket, setRequesterPaysEnabled, shutdown, sleepOnInternalError, suspendBucketVersioning, suspendBucketVersioningWithMFA, updateObjectMetadata
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

SoapS3Service

public SoapS3Service(AWSCredentials awsCredentials,
                     java.lang.String invokingApplicationDescription,
                     Jets3tProperties jets3tProperties)
              throws S3ServiceException
Constructs the SOAP service implementation and, based on the value of S3Service.isHttpsOnly sets the SOAP endpoint to use HTTP or HTTPS protocols.

Parameters:
awsCredentials -
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
jets3tProperties - JetS3t properties that will be applied within this service.
Throws:
S3ServiceException

SoapS3Service

public SoapS3Service(AWSCredentials awsCredentials,
                     java.lang.String invokingApplicationDescription)
              throws S3ServiceException
Constructs the SOAP service implementation and, based on the value of S3Service.isHttpsOnly sets the SOAP endpoint to use HTTP or HTTPS protocols.

Parameters:
awsCredentials -
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
Throws:
S3ServiceException

SoapS3Service

public SoapS3Service(AWSCredentials awsCredentials)
              throws S3ServiceException
Constructs the SOAP service implementation and, based on the value of S3Service.isHttpsOnly sets the SOAP endpoint to use HTTP or HTTPS protocols.

Parameters:
awsCredentials -
Throws:
S3ServiceException
Method Detail

shutdownImpl

protected void shutdownImpl()
                     throws S3ServiceException
Specified by:
shutdownImpl in class S3Service
Throws:
S3ServiceException

listAllBucketsImpl

protected S3Bucket[] listAllBucketsImpl()
                                 throws S3ServiceException
Specified by:
listAllBucketsImpl in class S3Service
Returns:
the buckets in an S3 account.
Throws:
S3ServiceException

getAccountOwnerImpl

protected S3Owner getAccountOwnerImpl()
                               throws S3ServiceException
Specified by:
getAccountOwnerImpl in class S3Service
Returns:
the owner of an S3 account.
Throws:
S3ServiceException

isBucketAccessible

public boolean isBucketAccessible(java.lang.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(java.lang.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

listObjectsImpl

protected S3Object[] listObjectsImpl(java.lang.String bucketName,
                                     java.lang.String prefix,
                                     java.lang.String delimiter,
                                     long maxListingLength)
                              throws S3ServiceException
Description copied from class: S3Service
Lists objects in a bucket. Implementation notes

The implementation of this method is expected to return all the objects in a bucket, not a subset. This may require repeating the S3 list operation if the first one doesn't include all the available objects, such as when the number of objects is greater than maxListingLength.

Specified by:
listObjectsImpl in class S3Service
Returns:
the objects in a bucket.
Throws:
S3ServiceException

listObjectsChunkedImpl

protected S3ObjectsChunk listObjectsChunkedImpl(java.lang.String bucketName,
                                                java.lang.String prefix,
                                                java.lang.String delimiter,
                                                long maxListingLength,
                                                java.lang.String priorLastKey,
                                                boolean completeListing)
                                         throws S3ServiceException
Description copied from class: S3Service
Lists objects in a bucket up to the maximum listing length specified.

Implementation notes The implementation of this method returns only as many objects as requested in the chunk size. It is the responsibility of the caller to build a complete object listing from multiple chunks, should this be necessary.

Specified by:
listObjectsChunkedImpl in class S3Service
Throws:
S3ServiceException

listObjectsInternalImpl

protected S3ObjectsChunk listObjectsInternalImpl(java.lang.String bucketName,
                                                 java.lang.String prefix,
                                                 java.lang.String delimiter,
                                                 long maxListingLength,
                                                 boolean automaticallyMergeChunks,
                                                 java.lang.String priorLastKey)
                                          throws S3ServiceException
Throws:
S3ServiceException

createBucketImpl

protected S3Bucket createBucketImpl(java.lang.String bucketName,
                                    java.lang.String location,
                                    AccessControlList acl)
                             throws S3ServiceException
Description copied from class: S3Service
Creates a bucket. Implementation notes

The implementing method must populate the bucket object's metadata with the results of the operation before returning the object. It must also apply any AccessControlList settings included with the bucket.

Specified by:
createBucketImpl in class S3Service
Parameters:
bucketName - the name of the bucket to create.
location - the geographical location where the bucket will be stored (see S3Bucket.getLocation(). A null string value will cause the bucket to be stored in the default S3 location: US.
acl - an access control object representing the initial acl values for the bucket. May be null, in which case the default permissions are applied.
Returns:
the created bucket object, populated with all metadata made available by the creation operation.
Throws:
S3ServiceException

getBucketLocationImpl

protected java.lang.String getBucketLocationImpl(java.lang.String bucketName)
                                          throws S3ServiceException
Specified by:
getBucketLocationImpl in class S3Service
Throws:
S3ServiceException

deleteBucketImpl

protected void deleteBucketImpl(java.lang.String bucketName)
                         throws S3ServiceException
Specified by:
deleteBucketImpl in class S3Service
Throws:
S3ServiceException

putObjectImpl

protected S3Object putObjectImpl(java.lang.String bucketName,
                                 S3Object object)
                          throws S3ServiceException
Specified by:
putObjectImpl in class S3Service
Throws:
S3ServiceException

deleteObjectImpl

protected void deleteObjectImpl(java.lang.String bucketName,
                                java.lang.String objectKey,
                                java.lang.String versionId,
                                java.lang.String multiFactorSerialNumber,
                                java.lang.String multiFactorAuthCode)
                         throws S3ServiceException
Specified by:
deleteObjectImpl in class S3Service
Throws:
S3ServiceException

copyObjectImpl

protected java.util.Map copyObjectImpl(java.lang.String sourceBucketName,
                                       java.lang.String sourceObjectKey,
                                       java.lang.String destinationBucketName,
                                       java.lang.String destinationObjectKey,
                                       AccessControlList acl,
                                       java.util.Map destinationMetadata,
                                       java.util.Calendar ifModifiedSince,
                                       java.util.Calendar ifUnmodifiedSince,
                                       java.lang.String[] ifMatchTags,
                                       java.lang.String[] ifNoneMatchTags,
                                       java.lang.String versionId)
                                throws S3ServiceException
Description copied from class: S3Service
Copy an object within your S3 account. Copies within a single bucket or between buckets, and optionally updates the object's metadata at the same time. An object can be copied over itself, allowing you to update the metadata without making any other changes.

Specified by:
copyObjectImpl in class S3Service
Parameters:
sourceBucketName - the name of the bucket that contains the original object.
sourceObjectKey - the key name of the original object.
destinationBucketName - the name of the destination bucket to which the object will be copied.
destinationObjectKey - the key name for the copied object.
acl - the access control settings that will be applied to the copied object. If this parameter is null, the default (private) ACL setting will be applied to the copied object.
destinationMetadata - metadata items to apply to the copied object. If this parameter is null, the metadata will be copied unchanged from the original object. If this parameter is not null, the copied object will have only the supplied metadata.
Returns:
a map of the header and result information returned by S3 after the object copy. The map includes the object's MD5 hash value (ETag), its size (Content-Length), and update timestamp (Last-Modified).
Throws:
S3ServiceException

getObjectDetailsImpl

protected S3Object getObjectDetailsImpl(java.lang.String bucketName,
                                        java.lang.String objectKey,
                                        java.util.Calendar ifModifiedSince,
                                        java.util.Calendar ifUnmodifiedSince,
                                        java.lang.String[] ifMatchTags,
                                        java.lang.String[] ifNoneMatchTags,
                                        java.lang.String versionId)
                                 throws S3ServiceException
Specified by:
getObjectDetailsImpl in class S3Service
Throws:
S3ServiceException

getObjectImpl

protected S3Object getObjectImpl(java.lang.String bucketName,
                                 java.lang.String objectKey,
                                 java.util.Calendar ifModifiedSince,
                                 java.util.Calendar ifUnmodifiedSince,
                                 java.lang.String[] ifMatchTags,
                                 java.lang.String[] ifNoneMatchTags,
                                 java.lang.Long byteRangeStart,
                                 java.lang.Long byteRangeEnd,
                                 java.lang.String versionId)
                          throws S3ServiceException
Specified by:
getObjectImpl in class S3Service
Throws:
S3ServiceException

putObjectAclImpl

protected void putObjectAclImpl(java.lang.String bucketName,
                                java.lang.String objectKey,
                                AccessControlList acl,
                                java.lang.String versionId)
                         throws S3ServiceException
Specified by:
putObjectAclImpl in class S3Service
Throws:
S3ServiceException

putBucketAclImpl

protected void putBucketAclImpl(java.lang.String bucketName,
                                AccessControlList acl)
                         throws S3ServiceException
Specified by:
putBucketAclImpl in class S3Service
Throws:
S3ServiceException

getObjectAclImpl

protected AccessControlList getObjectAclImpl(java.lang.String bucketName,
                                             java.lang.String objectKey,
                                             java.lang.String versionId)
                                      throws S3ServiceException
Specified by:
getObjectAclImpl in class S3Service
Throws:
S3ServiceException

getBucketAclImpl

protected AccessControlList getBucketAclImpl(java.lang.String bucketName)
                                      throws S3ServiceException
Specified by:
getBucketAclImpl in class S3Service
Throws:
S3ServiceException

getBucketLoggingStatusImpl

protected S3BucketLoggingStatus getBucketLoggingStatusImpl(java.lang.String bucketName)
                                                    throws S3ServiceException
Specified by:
getBucketLoggingStatusImpl in class S3Service
Throws:
S3ServiceException

setBucketLoggingStatusImpl

protected void setBucketLoggingStatusImpl(java.lang.String bucketName,
                                          S3BucketLoggingStatus status)
                                   throws S3ServiceException
Specified by:
setBucketLoggingStatusImpl in class S3Service
Throws:
S3ServiceException

isRequesterPaysBucketImpl

protected boolean isRequesterPaysBucketImpl(java.lang.String bucketName)
                                     throws S3ServiceException
Specified by:
isRequesterPaysBucketImpl in class S3Service
Throws:
S3ServiceException

setRequesterPaysBucketImpl

protected void setRequesterPaysBucketImpl(java.lang.String bucketName,
                                          boolean requesterPays)
                                   throws S3ServiceException
Specified by:
setRequesterPaysBucketImpl in class S3Service
Throws:
S3ServiceException

getBucketVersioningStatusImpl

protected S3BucketVersioningStatus getBucketVersioningStatusImpl(java.lang.String bucketName)
                                                          throws S3ServiceException
Specified by:
getBucketVersioningStatusImpl in class S3Service
Throws:
S3ServiceException

listVersionedObjectsChunkedImpl

protected VersionOrDeleteMarkersChunk listVersionedObjectsChunkedImpl(java.lang.String bucketName,
                                                                      java.lang.String prefix,
                                                                      java.lang.String delimiter,
                                                                      long maxListingLength,
                                                                      java.lang.String priorLastKey,
                                                                      java.lang.String priorLastVersion,
                                                                      boolean completeListing)
                                                               throws S3ServiceException
Description copied from class: S3Service
Lists version or delete markers in a versioned bucket, up to the maximum listing length specified.

Implementation notes The implementation of this method returns only as many items as requested in the chunk size. It is the responsibility of the caller to build a complete object listing from multiple chunks, should this be necessary.

Specified by:
listVersionedObjectsChunkedImpl in class S3Service
Throws:
S3ServiceException

listVersionedObjectsImpl

protected BaseVersionOrDeleteMarker[] listVersionedObjectsImpl(java.lang.String bucketName,
                                                               java.lang.String prefix,
                                                               java.lang.String delimiter,
                                                               java.lang.String keyMarker,
                                                               java.lang.String versionMarker,
                                                               long maxListingLength)
                                                        throws S3ServiceException
Specified by:
listVersionedObjectsImpl in class S3Service
Throws:
S3ServiceException

updateBucketVersioningStatusImpl

protected void updateBucketVersioningStatusImpl(java.lang.String bucketName,
                                                boolean enabled,
                                                boolean multiFactorAuthDeleteEnabled,
                                                java.lang.String multiFactorSerialNumber,
                                                java.lang.String multiFactorAuthCode)
                                         throws S3ServiceException
Specified by:
updateBucketVersioningStatusImpl in class S3Service
Throws:
S3ServiceException