org.jets3t.service
Class S3Service

java.lang.Object
  extended by org.jets3t.service.S3Service
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
RestS3Service, SoapS3Service

public abstract class S3Service
extends java.lang.Object
implements java.io.Serializable

A service that handles communication with S3, offering all the operations that can be performed on S3 accounts.

This class must be extended by implementation classes that perform the communication with S3 via a particular interface, such as REST or SOAP. Implementations provided with the JetS3t suite include RestS3Service and SoapS3Service.

Implementations of S3Service must be thread-safe as they will probably be used by the multi-threaded service class S3ServiceMulti.

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

Author:
James Murty, Nikolas Coukouma
See Also:
Serialized Form

Field Summary
static int BUCKET_STATUS__ALREADY_CLAIMED
           
static int BUCKET_STATUS__DOES_NOT_EXIST
           
static int BUCKET_STATUS__MY_BUCKET
           
protected  Jets3tProperties jets3tProperties
           
protected  long timeOffset
          The approximate difference in the current time between your computer and Amazon's S3 server, measured in milliseconds.
static java.lang.String VERSION_NO__JETS3T_TOOLKIT
          The JetS3t suite version number implemented by this service.
 
Constructor Summary
protected S3Service(AWSCredentials awsCredentials)
          Construct an S3Service identified by the given user credentials.
protected S3Service(AWSCredentials awsCredentials, java.lang.String invokingApplicationDescription)
          Construct an S3Service identified by the given user credentials.
protected S3Service(AWSCredentials awsCredentials, java.lang.String invokingApplicationDescription, Jets3tProperties jets3tProperties)
          Construct an S3Service identified by the given user credentials.
 
Method Summary
protected  void assertAuthenticatedConnection(java.lang.String action)
          Throws an exception if this service is anonymous (that is, it was created without an AWSCredentials object representing an S3 user account.
protected  void assertValidBucket(S3Bucket bucket, java.lang.String action)
          Throws an exception if a bucket is null or contains a null/empty name.
protected  void assertValidObject(S3Object object, java.lang.String action)
          Throws an exception if an object is null or contains a null/empty key.
protected  void assertValidObject(java.lang.String key, java.lang.String action)
          Throws an exception if an object's key name is null or empty.
static java.lang.String buildPostForm(java.lang.String bucketName, java.lang.String key)
          Generates an unauthenticated HTML POST form that can be used to upload files or data to S3 from a standard web browser.
static java.lang.String buildPostForm(java.lang.String bucketName, java.lang.String key, AWSCredentials awsCredentials, java.util.Date expiration, java.lang.String[] conditions, java.lang.String[] inputFields, java.lang.String textInput, boolean isSecureHttp)
          Generates an HTML POST form that can be used to upload files or data to S3 from a standard web browser.
static java.lang.String buildPostForm(java.lang.String bucketName, java.lang.String key, AWSCredentials awsCredentials, java.util.Date expiration, java.lang.String[] conditions, java.lang.String[] inputFields, java.lang.String textInput, boolean isSecureHttp, boolean usePathStyleUrl, java.lang.String submitButtonName)
          Generates an HTML POST form that can be used to upload files or data to S3 from a standard web browser.
abstract  int checkBucketStatus(java.lang.String bucketName)
          Find out the status of an S3 bucket with the given name.
 java.util.Map copyObject(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, S3Object destinationObject, boolean replaceMetadata)
          Copy an object within your S3 account.
 java.util.Map copyObject(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, S3Object destinationObject, boolean replaceMetadata, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags)
          Copy an object within your S3 account.
protected abstract  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.
 java.util.Map copyVersionedObject(java.lang.String versionId, java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, S3Object destinationObject, boolean replaceMetadata)
          Copy an object with a specific version within your S3 account.
 java.util.Map copyVersionedObject(java.lang.String versionId, java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, S3Object destinationObject, boolean replaceMetadata, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags)
          Copy an object with a specific version within your S3 account.
 S3Bucket createBucket(S3Bucket bucket)
          Creates a bucket in S3 based on the provided bucket object.
 S3Bucket createBucket(java.lang.String bucketName)
          Creates a bucket.
 S3Bucket createBucket(java.lang.String bucketName, java.lang.String location)
          Creates a bucket in a specific location, without checking whether the bucket already exists.
protected abstract  S3Bucket createBucketImpl(java.lang.String bucketName, java.lang.String location, AccessControlList acl)
          Creates a bucket.
static java.lang.String createSignedDeleteUrl(java.lang.String bucketName, java.lang.String objectKey, AWSCredentials awsCredentials, java.util.Date expiryTime)
          Generates a signed DELETE URL.
static java.lang.String createSignedDeleteUrl(java.lang.String bucketName, java.lang.String objectKey, AWSCredentials awsCredentials, java.util.Date expiryTime, boolean isVirtualHost)
          Generates a signed DELETE URL.
static java.lang.String createSignedGetUrl(java.lang.String bucketName, java.lang.String objectKey, AWSCredentials awsCredentials, java.util.Date expiryTime)
          Generates a signed GET URL.
static java.lang.String createSignedGetUrl(java.lang.String bucketName, java.lang.String objectKey, AWSCredentials awsCredentials, java.util.Date expiryTime, boolean isVirtualHost)
          Generates a signed GET URL.
static java.lang.String createSignedHeadUrl(java.lang.String bucketName, java.lang.String objectKey, AWSCredentials awsCredentials, java.util.Date expiryTime)
          Generates a signed HEAD URL.
static java.lang.String createSignedHeadUrl(java.lang.String bucketName, java.lang.String objectKey, AWSCredentials awsCredentials, java.util.Date expiryTime, boolean isVirtualHost)
          Generates a signed HEAD URL.
static java.lang.String createSignedPutUrl(java.lang.String bucketName, java.lang.String objectKey, java.util.Map headersMap, AWSCredentials awsCredentials, java.util.Date expiryTime)
          Generates a signed PUT URL.
static java.lang.String createSignedPutUrl(java.lang.String bucketName, java.lang.String objectKey, java.util.Map headersMap, AWSCredentials awsCredentials, java.util.Date expiryTime, boolean isVirtualHost)
          Generates a signed PUT URL.
static java.lang.String createSignedUrl(java.lang.String method, java.lang.String bucketName, java.lang.String objectKey, java.lang.String specialParamName, java.util.Map headersMap, AWSCredentials awsCredentials, long secondsSinceEpoch)
          Generates a signed URL string that will grant access to an S3 resource (bucket or object) to whoever uses the URL up until the time specified.
static java.lang.String createSignedUrl(java.lang.String method, java.lang.String bucketName, java.lang.String objectKey, java.lang.String specialParamName, java.util.Map headersMap, AWSCredentials awsCredentials, long secondsSinceEpoch, boolean isVirtualHost)
          Generates a signed URL string that will grant access to an S3 resource (bucket or object) to whoever uses the URL up until the time specified.
static java.lang.String createSignedUrl(java.lang.String method, java.lang.String bucketName, java.lang.String objectKey, java.lang.String specialParamName, java.util.Map headersMap, AWSCredentials awsCredentials, long secondsSinceEpoch, boolean isVirtualHost, boolean isHttps, boolean isDnsBucketNamingDisabled)
          Generates a signed URL string that will grant access to an S3 resource (bucket or object) to whoever uses the URL up until the time specified.
static java.lang.String createTorrentUrl(java.lang.String bucketName, java.lang.String objectKey)
          Generates a URL string that will return a Torrent file for an object in S3, which file can be downloaded and run in a BitTorrent client.
 void deleteBucket(S3Bucket bucket)
          Deletes an S3 bucket.
 void deleteBucket(java.lang.String bucketName)
          Deletes an S3 bucket.
protected abstract  void deleteBucketImpl(java.lang.String bucketName)
           
 void deleteObject(S3Bucket bucket, java.lang.String objectKey)
          Deletes an object from a bucket in S3.
 void deleteObject(java.lang.String bucketName, java.lang.String objectKey)
          Deletes an object from a bucket in S3.
protected abstract  void deleteObjectImpl(java.lang.String bucketName, java.lang.String objectKey, java.lang.String versionId, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode)
           
 void deleteVersionedObject(java.lang.String versionId, java.lang.String bucketName, java.lang.String objectKey)
          Deletes a object version from a bucket in S3.
 void deleteVersionedObjectWithMFA(java.lang.String versionId, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode, java.lang.String bucketName, java.lang.String objectKey)
          Deletes a object version from a bucket in S3.
 void disableMFAForVersionedBucket(java.lang.String bucketName, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode)
          Disable the multi-factor authentication (MFA) feature for a bucket that already has S3 object versioning and MFA enabled.
 void enableBucketVersioning(java.lang.String bucketName)
          Enable the S3 object versioning feature for a bucket.
 void enableBucketVersioningWithMFA(java.lang.String bucketName)
          Enable the S3 object versioning feature and enable the multi-factor authentication (MFA) feature for a bucket which does not yet have MFA enabled.
static java.lang.String generatePostPolicyCondition_AllowAnyValue(java.lang.String name)
          Generates a policy document condition statement that will allow the named data item in a POST request to take on any value.
static java.lang.String generatePostPolicyCondition_Equality(java.lang.String name, java.util.List values)
          Generates a policy document condition statement to represent an equality test.
static java.lang.String generatePostPolicyCondition_Equality(java.lang.String name, java.lang.String value)
          Generates a policy document condition statement to represent an equality test.
static java.lang.String generatePostPolicyCondition_Equality(java.lang.String name, java.lang.String[] values)
          Generates a policy document condition statement to represent an equality test.
static java.lang.String generatePostPolicyCondition_Range(int min, int max)
          Generates a policy document condition statement to represent a test that imposes a limit on the minimum and maximum amount of data the user can upload via a POST form.
static java.lang.String generatePostPolicyCondition(java.lang.String operation, java.lang.String name, java.lang.String value)
          Generates a policy document condition statement to represent an operation.
static java.lang.String generateS3HostnameForBucket(java.lang.String bucketName, boolean isDnsBucketNamingDisabled)
           
 S3Owner getAccountOwner()
          Returns the owner of an S3 account, using information available in the ListAllBuckets response.
protected abstract  S3Owner getAccountOwnerImpl()
           
 AWSCredentials getAWSCredentials()
           
 S3Bucket getBucket(java.lang.String bucketName)
          Returns a bucket in your S3 account by listing all your buckets (using listAllBuckets()), and looking for the named bucket in this list.
 AccessControlList getBucketAcl(S3Bucket bucket)
          Retrieves the access control settings of a bucket.
 AccessControlList getBucketAcl(java.lang.String bucketName)
          Retrieves the access control settings of a bucket.
protected abstract  AccessControlList getBucketAclImpl(java.lang.String bucketName)
           
 java.lang.String getBucketLocation(java.lang.String bucketName)
          Retrieves the location of a bucket.
protected abstract  java.lang.String getBucketLocationImpl(java.lang.String bucketName)
           
 S3BucketLoggingStatus getBucketLoggingStatus(java.lang.String bucketName)
          Retrieves the logging status settings of a bucket.
protected abstract  S3BucketLoggingStatus getBucketLoggingStatusImpl(java.lang.String bucketName)
           
 S3BucketVersioningStatus getBucketVersioningStatus(java.lang.String bucketName)
          Return versioning status of bucket, which reports on whether the given bucket has S3 object versioning enabled and whether multi-factor authentication is required to delete versions.
protected abstract  S3BucketVersioningStatus getBucketVersioningStatusImpl(java.lang.String bucketName)
           
 java.util.Date getCurrentTimeWithOffset()
          Returns the current date and time, adjusted according to the time offset between your computer and an AWS server (as set by the RestUtils.getAWSTimeAdjustment() method).
 java.lang.String getDevPayProductToken()
           
 java.lang.String getDevPayUserToken()
           
 int getInternalErrorRetryMax()
           
 java.lang.String getInvokingApplicationDescription()
           
 Jets3tProperties getJetS3tProperties()
           
 S3Object getObject(S3Bucket bucket, java.lang.String objectKey)
          Returns an object representing the details and data of an item in S3, without applying any preconditions.
 S3Object getObject(S3Bucket bucket, 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)
          Returns an object representing the details and data of an item in S3 that meets any given preconditions.
 S3Object getObject(java.lang.String bucketName, java.lang.String objectKey)
          Returns an object representing the details and data of an item in S3, without applying any preconditions.
 S3Object getObject(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)
          Returns an object representing the details and data of an item in S3 that meets any given preconditions.
 AccessControlList getObjectAcl(S3Bucket bucket, java.lang.String objectKey)
          Retrieves the access control settings of an object.
 AccessControlList getObjectAcl(java.lang.String bucketName, java.lang.String objectKey)
          Retrieves the access control settings of an object.
protected abstract  AccessControlList getObjectAclImpl(java.lang.String bucketName, java.lang.String objectKey, java.lang.String versionId)
           
 S3Object getObjectDetails(S3Bucket bucket, java.lang.String objectKey)
          Returns an object representing the details of an item in S3 without the object's data, and without applying any preconditions.
 S3Object getObjectDetails(S3Bucket bucket, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags)
          Returns an object representing the details of an item in S3 that meets any given preconditions.
 S3Object getObjectDetails(java.lang.String bucketName, java.lang.String objectKey)
          Returns an object representing the details of an item in S3 without the object's data, and without applying any preconditions.
 S3Object getObjectDetails(java.lang.String bucketName, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags)
          Returns an object representing the details of an item in S3 that meets any given preconditions.
protected abstract  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 abstract  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)
           
 BaseVersionOrDeleteMarker[] getObjectVersions(java.lang.String bucketName, java.lang.String objectKey)
          Return version information for a specific object.
 S3Bucket getOrCreateBucket(java.lang.String bucketName)
          Returns a bucket in your S3 account, and creates the bucket in the default location specified by the property "s3service.default-bucket-location" if it does not yet exist.
 S3Bucket getOrCreateBucket(java.lang.String bucketName, java.lang.String location)
          Returns a bucket in your S3 account, and creates the bucket in the given S3 location if it does not yet exist.
 S3Object getVersionedObject(java.lang.String versionId, S3Bucket bucket, 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)
          Returns an object representing the details and data of a versioned object in S3 that also meets any given preconditions.
 S3Object getVersionedObject(java.lang.String versionId, java.lang.String bucketName, java.lang.String objectKey)
          Returns an object representing the details and data of an item in S3 with a specific given version, without applying any preconditions.
 S3Object getVersionedObject(java.lang.String versionId, 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)
          Returns an object representing the details and data of a versioned object in S3 that also meets any given preconditions.
 AccessControlList getVersionedObjectAcl(java.lang.String versionId, S3Bucket bucket, java.lang.String objectKey)
          Retrieves the access control settings of a versioned object.
 AccessControlList getVersionedObjectAcl(java.lang.String versionId, java.lang.String bucketName, java.lang.String objectKey)
          Retrieves the access control settings of a versioned object.
 S3Object getVersionedObjectDetails(java.lang.String versionId, S3Bucket bucket, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags)
          Returns an object representing the details of a versioned object in S3 that also meets any given preconditions.
 S3Object getVersionedObjectDetails(java.lang.String versionId, java.lang.String bucketName, java.lang.String objectKey)
          Returns an object representing the details of an item in S3 with a specific given version, without the object's data and without applying any preconditions.
 S3Object getVersionedObjectDetails(java.lang.String versionId, java.lang.String bucketName, java.lang.String objectKey, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags)
          Returns an object representing the details of a versioned object in S3 that also meets any given preconditions.
 boolean isAuthenticatedConnection()
           
abstract  boolean isBucketAccessible(java.lang.String bucketName)
          Indicates whether a bucket exists and is accessible to a service user.
static boolean isBucketNameValidDNSName(java.lang.String bucketName)
          Returns true if the given bucket name can be used as a component of a valid DNS name.
 boolean isHttpsOnly()
          Whether to use secure HTTPS or insecure HTTP for communicating with S3, as set by the JetS3t property: s3service.https-only
 boolean isObjectInBucket(java.lang.String bucketName, java.lang.String objectKey)
          Convenience method to check whether an object exists in a bucket.
 boolean isRequesterPaysBucket(java.lang.String bucketName)
          Return true if the given bucket is configured as a Requester Pays bucket, in which case the requester must supply their own AWS credentials when accessing objects in the bucket, and will be responsible for request and data transfer fees.
protected abstract  boolean isRequesterPaysBucketImpl(java.lang.String bucketName)
           
 boolean isRequesterPaysEnabled()
          Is this service configured to generate Requester Pays requests when uploading data to S3, or retrieving data from the service.
 boolean isShutdown()
           
 S3Bucket[] listAllBuckets()
          Lists the buckets belonging to the service user.
protected abstract  S3Bucket[] listAllBucketsImpl()
           
 S3Object[] listObjects(S3Bucket bucket)
          Lists the objects in a bucket.
 S3Object[] listObjects(S3Bucket bucket, java.lang.String prefix, java.lang.String delimiter)
          Lists the objects in a bucket matching a prefix and delimiter.
 S3Object[] listObjects(S3Bucket bucket, java.lang.String prefix, java.lang.String delimiter, long maxListingLength)
          Lists the objects in a bucket matching a prefix, while instructing S3 to send response messages containing no more than a given number of object results.
 S3Object[] listObjects(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength)
          Lists the objects in a bucket matching a prefix, while instructing S3 to send response messages containing no more than a given number of object results.
 S3ObjectsChunk listObjectsChunked(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey)
          Lists the objects in a bucket matching a prefix, chunking the results into batches of a given size, and returning each chunk separately.
 S3ObjectsChunk listObjectsChunked(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey, boolean completeListing)
          Lists the objects in a bucket matching a prefix and also returns the common prefixes returned by S3.
protected abstract  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 abstract  S3Object[] listObjectsImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength)
          Lists objects in a bucket.
 BaseVersionOrDeleteMarker[] listVersionedObjects(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter)
          Lists versioning information in a versioned bucket where the objects match a given constraints.
 VersionOrDeleteMarkersChunk listVersionedObjectsChunked(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey, java.lang.String priorLastVersionId, boolean completeListing)
          Lists information for a versioned bucket where the items match given constarints.
protected abstract  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 abstract  BaseVersionOrDeleteMarker[] listVersionedObjectsImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, java.lang.String keyMarker, java.lang.String versionMarker, long maxListingLength)
           
 java.util.Map moveObject(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, S3Object destinationObject, boolean replaceMetadata)
          Move an object from your S3 account.
 void putBucketAcl(S3Bucket bucket)
          Applies access control settings to a bucket.
 void putBucketAcl(java.lang.String bucketName, AccessControlList acl)
          Applies access control settings to a bucket.
protected abstract  void putBucketAclImpl(java.lang.String bucketName, AccessControlList acl)
           
 S3Object putObject(S3Bucket bucket, S3Object object)
          Puts an object inside an existing bucket in S3, creating a new object or overwriting an existing one with the same key.
 S3Object putObject(java.lang.String bucketName, S3Object object)
          Puts an object inside an existing bucket in S3, creating a new object or overwriting an existing one with the same key.
 void putObjectAcl(S3Bucket bucket, S3Object object)
          Applies access control settings to an object.
 void putObjectAcl(java.lang.String bucketName, java.lang.String objectKey, AccessControlList acl)
          Applies access control settings to an object.
protected abstract  void putObjectAclImpl(java.lang.String bucketName, java.lang.String objectKey, AccessControlList acl, java.lang.String versionId)
           
protected abstract  S3Object putObjectImpl(java.lang.String bucketName, S3Object object)
           
 void putVersionedObjectAcl(java.lang.String versionId, S3Bucket bucket, S3Object object)
          Applies access control settings to a versioned object.
 void putVersionedObjectAcl(java.lang.String versionId, java.lang.String bucketName, java.lang.String objectKey, AccessControlList acl)
          Applies access control settings to a versioned object.
 java.util.Map renameObject(java.lang.String bucketName, java.lang.String sourceObjectKey, S3Object destinationObject)
          Rename an object in your S3 account.
 void setBucketLoggingStatus(java.lang.String bucketName, S3BucketLoggingStatus status, boolean updateTargetACLifRequired)
          Applies logging settings to a bucket, optionally modifying the ACL permissions for the logging target bucket to ensure log files can be written to it.
protected abstract  void setBucketLoggingStatusImpl(java.lang.String bucketName, S3BucketLoggingStatus status)
           
 void setDevPayProductToken(java.lang.String productToken)
          Set the Product Token value to use for requests to a DevPay S3 account.
 void setDevPayUserToken(java.lang.String userToken)
          Set the User Token value to use for requests to a DevPay S3 account.
 void setRequesterPaysBucket(java.lang.String bucketName, boolean requesterPays)
          Applies request payment configuration settings to a bucket, setting the bucket to be either Requester Pays or Bucket Owner pays.
protected abstract  void setRequesterPaysBucketImpl(java.lang.String bucketName, boolean requesterPays)
           
 void setRequesterPaysEnabled(boolean isRequesterPays)
          Instruct the service whether to generate Requester Pays requests when uploading data to S3, or retrieving data from the service.
 void shutdown()
          Make a best-possible effort to shutdown and clean up any resources used by this service such as HTTP connections, connection pools, threads etc, although there is no guarantee that all such resources will indeed be fully cleaned up.
protected abstract  void shutdownImpl()
           
protected  void sleepOnInternalError(int internalErrorCount)
          Sleeps for a period of time based on the number of S3 Internal Server errors a request has encountered, provided the number of errors does not exceed the value set with the property s3service.internal-error-retry-max.
 void suspendBucketVersioning(java.lang.String bucketName)
          Suspend (disable) the S3 object versioning feature for a bucket.
 void suspendBucketVersioningWithMFA(java.lang.String bucketName, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode)
          Suspend (disable) the S3 object versioning feature for a bucket that requires multi-factor authentication.
protected abstract  void updateBucketVersioningStatusImpl(java.lang.String bucketName, boolean enabled, boolean multiFactorAuthDeleteEnabled, java.lang.String multiFactorSerialNumber, java.lang.String multiFactorAuthCode)
           
 java.util.Map updateObjectMetadata(java.lang.String bucketName, S3Object object)
          Update an object's metadata.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION_NO__JETS3T_TOOLKIT

public static final java.lang.String VERSION_NO__JETS3T_TOOLKIT
The JetS3t suite version number implemented by this service.

See Also:
Constant Field Values

BUCKET_STATUS__MY_BUCKET

public static final int BUCKET_STATUS__MY_BUCKET
See Also:
Constant Field Values

BUCKET_STATUS__DOES_NOT_EXIST

public static final int BUCKET_STATUS__DOES_NOT_EXIST
See Also:
Constant Field Values

BUCKET_STATUS__ALREADY_CLAIMED

public static final int BUCKET_STATUS__ALREADY_CLAIMED
See Also:
Constant Field Values

jets3tProperties

protected Jets3tProperties jets3tProperties

timeOffset

protected long timeOffset
The approximate difference in the current time between your computer and Amazon's S3 server, measured in milliseconds. This value is 0 by default. Use the getCurrentTimeWithOffset() to obtain the current time with this offset factor included, and the RestUtils.getAWSTimeAdjustment() method to calculate an offset value for your computer based on a response from an AWS server.

Constructor Detail

S3Service

protected S3Service(AWSCredentials awsCredentials,
                    java.lang.String invokingApplicationDescription,
                    Jets3tProperties jets3tProperties)
             throws S3ServiceException
Construct an S3Service identified by the given user credentials.

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

S3Service

protected S3Service(AWSCredentials awsCredentials,
                    java.lang.String invokingApplicationDescription)
             throws S3ServiceException
Construct an S3Service identified by the given user credentials.

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

S3Service

protected S3Service(AWSCredentials awsCredentials)
             throws S3ServiceException
Construct an S3Service identified by the given user credentials.

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
Method Detail

shutdown

public void shutdown()
              throws S3ServiceException
Make a best-possible effort to shutdown and clean up any resources used by this service such as HTTP connections, connection pools, threads etc, although there is no guarantee that all such resources will indeed be fully cleaned up. After calling this method the service instance will no longer be usable -- a new instance must be created to do more work.

Throws:
S3ServiceException

isShutdown

public boolean isShutdown()
Returns:
true if the shutdown() method has been used to shut down and clean up this service. If this function returns true this service instance can no longer be used to do work.

setDevPayUserToken

public void setDevPayUserToken(java.lang.String userToken)
Set the User Token value to use for requests to a DevPay S3 account. The user token is not required for DevPay web products for which the user token was created after 15th May 2008.

Parameters:
userToken - the user token value provided by the AWS DevPay activation service.

getDevPayUserToken

public java.lang.String getDevPayUserToken()
Returns:
the user token value to use in requests to a DevPay S3 account, or null if no such token value has been set.

setDevPayProductToken

public void setDevPayProductToken(java.lang.String productToken)
Set the Product Token value to use for requests to a DevPay S3 account.

Parameters:
productToken - the token that identifies your DevPay product.

getDevPayProductToken

public java.lang.String getDevPayProductToken()
Returns:
the product token value to use in requests to a DevPay S3 account, or null if no such token value has been set.

setRequesterPaysEnabled

public void setRequesterPaysEnabled(boolean isRequesterPays)
Instruct the service whether to generate Requester Pays requests when uploading data to S3, or retrieving data from the service. The default value for the Requester Pays Enabled setting is set according to the jets3t.properties setting httpclient.requester-pays-buckets-enabled.

NOTE: Only the REST S3 API supports Requester Pays requests, this setting is ignored by the SOAP implementation SoapS3Service.

Parameters:
isRequesterPays - if true, all subsequent S3 service requests will include the Requester Pays flag.

isRequesterPaysEnabled

public boolean isRequesterPaysEnabled()
Is this service configured to generate Requester Pays requests when uploading data to S3, or retrieving data from the service. The default value for the Requester Pays Enabled setting is set according to the jets3t.properties setting httpclient.requester-pays-buckets-enabled.

NOTE: Only the REST S3 API supports Requester Pays requests, this setting is ignored by the SOAP implementation SoapS3Service.

Returns:
true if S3 service requests will include the Requester Pays flag, false otherwise.

isAuthenticatedConnection

public boolean isAuthenticatedConnection()
Returns:
true if this service has AWSCredentials identifying an S3 user, false if the service is acting as an anonymous user.

isHttpsOnly

public boolean isHttpsOnly()
Whether to use secure HTTPS or insecure HTTP for communicating with S3, as set by the JetS3t property: s3service.https-only

Returns:
true if this service should use only secure HTTPS communication channels to S3. If false, the non-secure HTTP protocol will be used.

getInternalErrorRetryMax

public int getInternalErrorRetryMax()
Returns:
The maximum number of times to retry when S3 Internal Error (500) errors are encountered, as set by the JetS3t property: s3service.internal-error-retry-max

getJetS3tProperties

public Jets3tProperties getJetS3tProperties()
Returns:
the JetS3t properties that will be used by this service.

isBucketNameValidDNSName

public static boolean isBucketNameValidDNSName(java.lang.String bucketName)
Returns true if the given bucket name can be used as a component of a valid DNS name. If so, the bucket can be accessed using requests with the bucket name as part of an S3 sub-domain. If not, the old-style bucket reference URLs must be used, in which case the bucket name must be the first component of the resource path.

Parameters:
bucketName - the name of the bucket to test for DNS compatibility.

generateS3HostnameForBucket

public static java.lang.String generateS3HostnameForBucket(java.lang.String bucketName,
                                                           boolean isDnsBucketNamingDisabled)

sleepOnInternalError

protected void sleepOnInternalError(int internalErrorCount)
                             throws S3ServiceException,
                                    java.lang.InterruptedException
Sleeps for a period of time based on the number of S3 Internal Server errors a request has encountered, provided the number of errors does not exceed the value set with the property s3service.internal-error-retry-max. If the maximum error count is exceeded, this method will throw an S3ServiceException. The millisecond delay grows rapidly according to the formula 50 * (internalErrorCount ^ 2).
Error countDelay in milliseconds
150
2200
3450
4800
51250

Parameters:
internalErrorCount - the number of S3 Internal Server errors encountered by a request.
Throws:
S3ServiceException - thrown if the number of internal errors exceeds the value of internalErrorCount.
java.lang.InterruptedException - thrown if the thread sleep is interrupted.

getAWSCredentials

public AWSCredentials getAWSCredentials()
Returns:
the AWS Credentials identifying the S3 user, may be null if the service is acting anonymously.

getInvokingApplicationDescription

public java.lang.String getInvokingApplicationDescription()
Returns:
a description of the application using this service, suitable for inclusion in the user agent string of REST/HTTP requests.

createSignedUrl

public static java.lang.String createSignedUrl(java.lang.String method,
                                               java.lang.String bucketName,
                                               java.lang.String objectKey,
                                               java.lang.String specialParamName,
                                               java.util.Map headersMap,
                                               AWSCredentials awsCredentials,
                                               long secondsSinceEpoch,
                                               boolean isVirtualHost,
                                               boolean isHttps,
                                               boolean isDnsBucketNamingDisabled)
                                        throws S3ServiceException
Generates a signed URL string that will grant access to an S3 resource (bucket or object) to whoever uses the URL up until the time specified.

Parameters:
method - the HTTP method to sign, such as GET or PUT (note that S3 does not support POST requests).
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
specialParamName - the name of a request parameter to add to the URL generated by this method. 'Special' parameters may include parameters that specify the kind of S3 resource that the URL will refer to, such as 'acl', 'torrent', 'logging', or 'location'.
headersMap - headers to add to the signed URL, may be null. Headers that must match between the signed URL and the actual request include: content-md5, content-type, and any header starting with 'x-amz-'.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
secondsSinceEpoch - the time after which URL's signature will no longer be valid. This time cannot be null. Note: This time is specified in seconds since the epoch, not milliseconds.
isVirtualHost - if this parameter is true, the bucket name is treated as a virtual host name. To use this option, the bucket name must be a valid DNS name that is an alias to an S3 bucket.
isHttps - if true, the signed URL will use the HTTPS protocol. If false, the signed URL will use the HTTP protocol.
isDnsBucketNamingDisabled - if true, the signed URL will not use the DNS-name format for buckets eg. jets3t.s3.amazonaws.com. Unless you have a specific reason to disable DNS bucket naming, leave this value false.
Returns:
a URL signed in such a way as to grant access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createSignedUrl

public static java.lang.String createSignedUrl(java.lang.String method,
                                               java.lang.String bucketName,
                                               java.lang.String objectKey,
                                               java.lang.String specialParamName,
                                               java.util.Map headersMap,
                                               AWSCredentials awsCredentials,
                                               long secondsSinceEpoch,
                                               boolean isVirtualHost)
                                        throws S3ServiceException
Generates a signed URL string that will grant access to an S3 resource (bucket or object) to whoever uses the URL up until the time specified. The URL will use the default JetS3t property settings in the jets3t.properties file to determine whether to generate HTTP or HTTPS links (s3service.https-only), and whether to disable DNS bucket naming (s3service.disable-dns-buckets).

Parameters:
method - the HTTP method to sign, such as GET or PUT (note that S3 does not support POST requests).
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
specialParamName - the name of a request parameter to add to the URL generated by this method. 'Special' parameters may include parameters that specify the kind of S3 resource that the URL will refer to, such as 'acl', 'torrent', 'logging' or 'location'.
headersMap - headers to add to the signed URL, may be null. Headers that must match between the signed URL and the actual request include: content-md5, content-type, and any header starting with 'x-amz-'.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
secondsSinceEpoch - the time after which URL's signature will no longer be valid. This time cannot be null. Note: This time is specified in seconds since the epoch, not milliseconds.
isVirtualHost - if this parameter is true, the bucket name is treated as a virtual host name. To use this option, the bucket name must be a valid DNS name that is an alias to an S3 bucket.
Returns:
a URL signed in such a way as to grant access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createSignedUrl

public static java.lang.String createSignedUrl(java.lang.String method,
                                               java.lang.String bucketName,
                                               java.lang.String objectKey,
                                               java.lang.String specialParamName,
                                               java.util.Map headersMap,
                                               AWSCredentials awsCredentials,
                                               long secondsSinceEpoch)
                                        throws S3ServiceException
Generates a signed URL string that will grant access to an S3 resource (bucket or object) to whoever uses the URL up until the time specified.

Parameters:
method - the HTTP method to sign, such as GET or PUT (note that S3 does not support POST requests).
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
specialParamName - the name of a request parameter to add to the URL generated by this method. 'Special' parameters may include parameters that specify the kind of S3 resource that the URL will refer to, such as 'acl', 'torrent', 'logging' or 'location'.
headersMap - headers to add to the signed URL, may be null. Headers that must match between the signed URL and the actual request include: content-md5, content-type, and any header starting with 'x-amz-'.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
secondsSinceEpoch - the time after which URL's signature will no longer be valid. This time cannot be null. Note: This time is specified in seconds since the epoch, not milliseconds.
Returns:
a URL signed in such a way as to grant access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createSignedGetUrl

public static java.lang.String createSignedGetUrl(java.lang.String bucketName,
                                                  java.lang.String objectKey,
                                                  AWSCredentials awsCredentials,
                                                  java.util.Date expiryTime,
                                                  boolean isVirtualHost)
                                           throws S3ServiceException
Generates a signed GET URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
isVirtualHost - if this parameter is true, the bucket name is treated as a virtual host name. To use this option, the bucket name must be a valid DNS name that is an alias to an S3 bucket.
Returns:
a URL signed in such a way as to grant GET access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createSignedGetUrl

public static java.lang.String createSignedGetUrl(java.lang.String bucketName,
                                                  java.lang.String objectKey,
                                                  AWSCredentials awsCredentials,
                                                  java.util.Date expiryTime)
                                           throws S3ServiceException
Generates a signed GET URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
Returns:
a URL signed in such a way as to grant GET access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createSignedPutUrl

public static java.lang.String createSignedPutUrl(java.lang.String bucketName,
                                                  java.lang.String objectKey,
                                                  java.util.Map headersMap,
                                                  AWSCredentials awsCredentials,
                                                  java.util.Date expiryTime,
                                                  boolean isVirtualHost)
                                           throws S3ServiceException
Generates a signed PUT URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
headersMap - headers to add to the signed URL, may be null. Headers that must match between the signed URL and the actual request include: content-md5, content-type, and any header starting with 'x-amz-'.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
isVirtualHost - if this parameter is true, the bucket name is treated as a virtual host name. To use this option, the bucket name must be a valid DNS name that is an alias to an S3 bucket.
Returns:
a URL signed in such a way as to allow anyone to PUT an object into S3.
Throws:
S3ServiceException

createSignedPutUrl

public static java.lang.String createSignedPutUrl(java.lang.String bucketName,
                                                  java.lang.String objectKey,
                                                  java.util.Map headersMap,
                                                  AWSCredentials awsCredentials,
                                                  java.util.Date expiryTime)
                                           throws S3ServiceException
Generates a signed PUT URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
headersMap - headers to add to the signed URL, may be null. Headers that must match between the signed URL and the actual request include: content-md5, content-type, and any header starting with 'x-amz-'.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
Returns:
a URL signed in such a way as to allow anyone to PUT an object into S3.
Throws:
S3ServiceException

createSignedDeleteUrl

public static java.lang.String createSignedDeleteUrl(java.lang.String bucketName,
                                                     java.lang.String objectKey,
                                                     AWSCredentials awsCredentials,
                                                     java.util.Date expiryTime,
                                                     boolean isVirtualHost)
                                              throws S3ServiceException
Generates a signed DELETE URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
isVirtualHost - if this parameter is true, the bucket name is treated as a virtual host name. To use this option, the bucket name must be a valid DNS name that is an alias to an S3 bucket.
Returns:
a URL signed in such a way as to allow anyone do DELETE an object in S3.
Throws:
S3ServiceException

createSignedDeleteUrl

public static java.lang.String createSignedDeleteUrl(java.lang.String bucketName,
                                                     java.lang.String objectKey,
                                                     AWSCredentials awsCredentials,
                                                     java.util.Date expiryTime)
                                              throws S3ServiceException
Generates a signed DELETE URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
Returns:
a URL signed in such a way as to allow anyone do DELETE an object in S3.
Throws:
S3ServiceException

createSignedHeadUrl

public static java.lang.String createSignedHeadUrl(java.lang.String bucketName,
                                                   java.lang.String objectKey,
                                                   AWSCredentials awsCredentials,
                                                   java.util.Date expiryTime,
                                                   boolean isVirtualHost)
                                            throws S3ServiceException
Generates a signed HEAD URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
isVirtualHost - if this parameter is true, the bucket name is treated as a virtual host name. To use this option, the bucket name must be a valid DNS name that is an alias to an S3 bucket.
Returns:
a URL signed in such a way as to grant HEAD access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createSignedHeadUrl

public static java.lang.String createSignedHeadUrl(java.lang.String bucketName,
                                                   java.lang.String objectKey,
                                                   AWSCredentials awsCredentials,
                                                   java.util.Date expiryTime)
                                            throws S3ServiceException
Generates a signed HEAD URL.

Parameters:
bucketName - the name of the bucket to include in the URL, must be a valid bucket name.
objectKey - the name of the object to include in the URL, if null only the bucket name is used.
awsCredentials - the credentials of someone with sufficient privileges to grant access to the bucket/object
expiryTime - the time after which URL's signature will no longer be valid. This time cannot be null.
Returns:
a URL signed in such a way as to grant HEAD access to an S3 resource to whoever uses it.
Throws:
S3ServiceException

createTorrentUrl

public static java.lang.String createTorrentUrl(java.lang.String bucketName,
                                                java.lang.String objectKey)
Generates a URL string that will return a Torrent file for an object in S3, which file can be downloaded and run in a BitTorrent client.

Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the name of the object.
Returns:
a URL to a Torrent file representing the object.
Throws:
S3ServiceException

generatePostPolicyCondition

public static java.lang.String generatePostPolicyCondition(java.lang.String operation,
                                                           java.lang.String name,
                                                           java.lang.String value)
Generates a policy document condition statement to represent an operation.

Parameters:
operation - the name of the test operation this condition statement will apply.
name - the name of the data item the condition applies to.
value - the test value that will be used by the condition operation.
Returns:
a condition statement that can be included in the policy document belonging to an S3 POST form.

generatePostPolicyCondition_AllowAnyValue

public static java.lang.String generatePostPolicyCondition_AllowAnyValue(java.lang.String name)
Generates a policy document condition statement that will allow the named data item in a POST request to take on any value.

Parameters:
name - the name of the data item that will be allowed to take on any value.
Returns:
a condition statement that can be included in the policy document belonging to an S3 POST form.

generatePostPolicyCondition_Equality

public static java.lang.String generatePostPolicyCondition_Equality(java.lang.String name,
                                                                    java.lang.String value)
Generates a policy document condition statement to represent an equality test.

Parameters:
name - the name of the data item that will be tested.
value - the value that the named data item must match.
Returns:
a condition statement that can be included in the policy document belonging to an S3 POST form.

generatePostPolicyCondition_Equality

public static java.lang.String generatePostPolicyCondition_Equality(java.lang.String name,
                                                                    java.lang.String[] values)
Generates a policy document condition statement to represent an equality test.

Parameters:
name - the name of the data item that will be tested.
values - a list of values, one of which must match the named data item.
Returns:
a condition statement that can be included in the policy document belonging to an S3 POST form.

generatePostPolicyCondition_Equality

public static java.lang.String generatePostPolicyCondition_Equality(java.lang.String name,
                                                                    java.util.List values)
Generates a policy document condition statement to represent an equality test.

Parameters:
name - the name of the data item that will be tested.
values - a list of values, one of which must match the named data item.
Returns:
a condition statement that can be included in the policy document belonging to an S3 POST form.

generatePostPolicyCondition_Range

public static java.lang.String generatePostPolicyCondition_Range(int min,
                                                                 int max)
Generates a policy document condition statement to represent a test that imposes a limit on the minimum and maximum amount of data the user can upload via a POST form.

Parameters:
min - the minimum number of bytes the user must upload. This value should be greater than or equal to zero.
max - the maximum number of bytes the user can upload. This value must be greater than or equal to the min value.
Returns:
a condition statement that can be included in the policy document belonging to an S3 POST form.

buildPostForm

public static java.lang.String buildPostForm(java.lang.String bucketName,
                                             java.lang.String key)
                                      throws S3ServiceException,
                                             java.io.UnsupportedEncodingException
Generates an unauthenticated HTML POST form that can be used to upload files or data to S3 from a standard web browser.

Because the generated form is unauthenticated, it will not contain a policy document and will only allow uploads to be sent to S3 buckets that are publicly writable.

Parameters:
bucketName - the name of the target bucket to which the data will be uploaded.
key - the key name for the object that will store the data. The key name can include the special variable ${filename} which expands to the name of the file the user uploaded in the form.
Returns:
A form document that can be included in a UTF-8 encoded HTML web page to allow uploads to a publicly-writable S3 bucket via a web browser.
Throws:
S3ServiceException
java.io.UnsupportedEncodingException

buildPostForm

public static java.lang.String buildPostForm(java.lang.String bucketName,
                                             java.lang.String key,
                                             AWSCredentials awsCredentials,
                                             java.util.Date expiration,
                                             java.lang.String[] conditions,
                                             java.lang.String[] inputFields,
                                             java.lang.String textInput,
                                             boolean isSecureHttp)
                                      throws S3ServiceException,
                                             java.io.UnsupportedEncodingException
Generates an HTML POST form that can be used to upload files or data to S3 from a standard web browser.

Depending on the parameter values provided, this method will generate an authenticated or unauthenticated form. If the form is unauthenticated, it will not include a policy document and will therefore not have an expiry date or any usage conditions. Unauthenticated forms may only be used to upload data to a publicly writable bucket.

If both the expiration and conditions parameters are non-null, the form will include a policy document and will be authenticated. In this case, you must provide your AWS credentials to sign the authenticated form.

Parameters:
bucketName - the name of the target bucket to which the data will be uploaded.
key - the key name for the object that will store the data. The key name can include the special variable ${filename} which expands to the name of the file the user uploaded in the form.
awsCredentials - your AWS credentials. Credentials are only required if the form includes policy document conditions, otherwise this can be null.
expiration - the expiration date beyond which the form will cease to work. If this parameter is null, the generated form will not include a policy document and will not have an expiry date.
conditions - the policy conditions applied to the form, specified as policy document condition statements. These statements can be generated with the convenience method generatePostPolicyCondition(String, String, String) and its siblings. If this parameter is null, the generated form will not include a policy document and will not apply any usage conditions.
inputFields - optional input field strings that will be added to the form. Each string must be a valid HTML form input field definition, such as <input type="hidden" name="acl" value="public-read">
textInput - an optional input field definition that is used instead of the default file input field <input name=\"file\" type=\"file\">. If this parameter is null, the default file input field will be used to allow file uploads. If this parameter is non-null, the provided string must define an input field named "file" that allows the user to provide input, such as <textarea name="file" cols="60" rows="3"></textarea>
isSecureHttp - if this parameter is true the form will upload data to S3 using HTTPS, otherwise it will use HTTP.
Returns:
A form document that can be included in a UTF-8 encoded HTML web page to allow uploads to S3 via a web browser.
Throws:
S3ServiceException
java.io.UnsupportedEncodingException

buildPostForm

public static java.lang.String buildPostForm(java.lang.String bucketName,
                                             java.lang.String key,
                                             AWSCredentials awsCredentials,
                                             java.util.Date expiration,
                                             java.lang.String[] conditions,
                                             java.lang.String[] inputFields,
                                             java.lang.String textInput,
                                             boolean isSecureHttp,
                                             boolean usePathStyleUrl,
                                             java.lang.String submitButtonName)
                                      throws S3ServiceException,
                                             java.io.UnsupportedEncodingException
Generates an HTML POST form that can be used to upload files or data to S3 from a standard web browser.

Depending on the parameter values provided, this method will generate an authenticated or unauthenticated form. If the form is unauthenticated, it will not include a policy document and will therefore not have an expiry date or any usage conditions. Unauthenticated forms may only be used to upload data to a publicly writable bucket.

If both the expiration and conditions parameters are non-null, the form will include a policy document and will be authenticated. In this case, you must provide your AWS credentials to sign the authenticated form.

Parameters:
bucketName - the name of the target bucket to which the data will be uploaded.
key - the key name for the object that will store the data. The key name can include the special variable ${filename} which expands to the name of the file the user uploaded in the form.
awsCredentials - your AWS credentials. Credentials are only required if the form includes policy document conditions, otherwise this can be null.
expiration - the expiration date beyond which the form will cease to work. If this parameter is null, the generated form will not include a policy document and will not have an expiry date.
conditions - the policy conditions applied to the form, specified as policy document condition statements. These statements can be generated with the convenience method generatePostPolicyCondition(String, String, String) and its siblings. If this parameter is null, the generated form will not include a policy document and will not apply any usage conditions.
inputFields - optional input field strings that will be added to the form. Each string must be a valid HTML form input field definition, such as <input type="hidden" name="acl" value="public-read">
textInput - an optional input field definition that is used instead of the default file input field <input name=\"file\" type=\"file\">. If this parameter is null, the default file input field will be used to allow file uploads. If this parameter is non-null, the provided string must define an input field named "file" that allows the user to provide input, such as <textarea name="file" cols="60" rows="3"></textarea>
isSecureHttp - if this parameter is true the form will upload data to S3 using HTTPS, otherwise it will use HTTP.
usePathStyleUrl - if true the deprecated path style URL will be used to specify the bucket name, for example: http://s3.amazon.com/BUCKET_NAME. If false, the recommended sub-domain style will be used, for example: http://BUCKET_NAME.s3.amazon.com/. The path style can be useful for accessing US-based buckets with SSL, however non-US buckets are inaccessible with this style URL.
submitButtonName - the name to display on the form's submit button.
Returns:
A form document that can be included in a UTF-8 encoded HTML web page to allow uploads to S3 via a web browser.
Throws:
S3ServiceException
java.io.UnsupportedEncodingException

assertAuthenticatedConnection

protected void assertAuthenticatedConnection(java.lang.String action)
                                      throws S3ServiceException
Throws an exception if this service is anonymous (that is, it was created without an AWSCredentials object representing an S3 user account.

Parameters:
action - the action being attempted which this assertion is applied, for debugging purposes.
Throws:
S3ServiceException

assertValidBucket

protected void assertValidBucket(S3Bucket bucket,
                                 java.lang.String action)
                          throws S3ServiceException
Throws an exception if a bucket is null or contains a null/empty name.

Parameters:
bucket -
action - the action being attempted which this assertion is applied, for debugging purposes.
Throws:
S3ServiceException

assertValidObject

protected void assertValidObject(S3Object object,
                                 java.lang.String action)
                          throws S3ServiceException
Throws an exception if an object is null or contains a null/empty key.

Parameters:
object -
action - the action being attempted which this assertion is applied, for debugging purposes.
Throws:
S3ServiceException

assertValidObject

protected void assertValidObject(java.lang.String key,
                                 java.lang.String action)
                          throws S3ServiceException
Throws an exception if an object's key name is null or empty.

Parameters:
key - An object's key name.
action - the action being attempted which this assertion is applied, for debugging purposes.
Throws:
S3ServiceException

listObjects

public S3Object[] listObjects(S3Bucket bucket)
                       throws S3ServiceException
Lists the objects in a bucket.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can only list the objects in a publicly-readable bucket.

Parameters:
bucket - the bucket whose contents will be listed. This must be a valid S3Bucket object that is non-null and contains a name.
Returns:
the set of objects contained in a bucket.
Throws:
S3ServiceException

listObjects

public S3Object[] listObjects(S3Bucket bucket,
                              java.lang.String prefix,
                              java.lang.String delimiter)
                       throws S3ServiceException
Lists the objects in a bucket matching a prefix and delimiter.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can only list the objects in a publicly-readable bucket.

NOTE: If you supply a delimiter value that could cause CommonPrefixes ("subdirectory paths") to be included in the results from S3, use the listObjectsChunked(String, String, String, long, String, boolean) method instead of this one to obtain both object and CommonPrefix values.

Parameters:
bucket - the bucket whose contents will be listed. This must be a valid S3Bucket object that is non-null and contains a name.
prefix - only objects with a key that starts with this prefix will be listed
delimiter - only list objects with key names up to this delimiter, may be null. See note above. Note: If a non-null delimiter is specified, the prefix must include enough text to reach the first occurrence of the delimiter in the bucket's keys, or no results will be returned.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

createBucket

public S3Bucket createBucket(java.lang.String bucketName,
                             java.lang.String location)
                      throws S3ServiceException
Creates a bucket in a specific location, without checking whether the bucket already exists. Caution: Performing this operation unnecessarily when a bucket already exists may cause OperationAborted errors with the message "A conflicting conditional operation is currently in progress against this resource.". To avoid this error, use the getOrCreateBucket(String) in situations where the bucket may already exist.

Warning: Prior to version 0.7.0 this method did check whether a bucket already existed using isBucketAccessible(String). After changes to the way S3 operates, this check started to cause issues so it was removed.

This method cannot be performed by anonymous services.

Parameters:
bucketName - the name of the bucket to create.
location - the location of the S3 data centre in which the bucket will be created. Valid values include S3Bucket.LOCATION_EUROPE, S3Bucket.LOCATION_US_WEST, and the equivalent S3Bucket.LOCATION_US_STANDARD and S3Bucket.LOCATION_US.
Returns:
the created bucket object. Note: the object returned has minimal information about the bucket that was created, including only the bucket's name.
Throws:
S3ServiceException

createBucket

public S3Bucket createBucket(java.lang.String bucketName)
                      throws S3ServiceException
Creates a bucket. The bucket is created in the default location as specified in the properties setting s3service.default-bucket-location. Caution: Performing this operation unnecessarily when a bucket already exists may cause OperationAborted errors with the message "A conflicting conditional operation is currently in progress against this resource.". To avoid this error, use the getOrCreateBucket(String) in situations where the bucket may already exist.

Warning: Prior to version 0.7.0 this method did check whether a bucket already existed using isBucketAccessible(String). After changes to the way S3 operates, this check started to cause issues so it was removed.

This method cannot be performed by anonymous services.

Parameters:
bucketName - the name of the bucket to create.
Returns:
the created bucket object. Note: the object returned has minimal information about the bucket that was created, including only the bucket's name.
Throws:
S3ServiceException

isObjectInBucket

public boolean isObjectInBucket(java.lang.String bucketName,
                                java.lang.String objectKey)
                         throws S3ServiceException
Convenience method to check whether an object exists in a bucket.

Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
Returns:
false if the object is not found in the bucket, true if the object exists (although it may be inaccessible to you).
Throws:
S3ServiceException

getObject

public S3Object getObject(S3Bucket bucket,
                          java.lang.String objectKey)
                   throws S3ServiceException
Returns an object representing the details and data of an item in S3, without applying any preconditions.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

Parameters:
bucket - the bucket containing the object. This must be a valid S3Bucket object that is non-null and contains a name.
objectKey - the key identifying the object.
Returns:
the object with the given key in S3, including the object's data input stream.
Throws:
S3ServiceException

getObject

public S3Object getObject(java.lang.String bucketName,
                          java.lang.String objectKey)
                   throws S3ServiceException
Returns an object representing the details and data of an item in S3, without applying any preconditions.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key in S3, including the object's data input stream.
Throws:
S3ServiceException

getVersionedObject

public S3Object getVersionedObject(java.lang.String versionId,
                                   java.lang.String bucketName,
                                   java.lang.String objectKey)
                            throws S3ServiceException
Returns an object representing the details and data of an item in S3 with a specific given version, without applying any preconditions. Versioned objects are only available from buckets with versioning enabled, see enableBucketVersioning(String).

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

Parameters:
versionId - identifier matching an existing object version that will be retrieved.
bucketName - the name of the versioned bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key in S3, including the object's data input stream.
Throws:
S3ServiceException

getObjectDetails

public S3Object getObjectDetails(S3Bucket bucket,
                                 java.lang.String objectKey)
                          throws S3ServiceException
Returns an object representing the details of an item in S3 without the object's data, and without applying any preconditions.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object's details.

Parameters:
bucket - the bucket containing the object. This must be a valid S3Bucket object that is non-null and contains a name.
objectKey - the key identifying the object.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getObjectDetails

public S3Object getObjectDetails(java.lang.String bucketName,
                                 java.lang.String objectKey)
                          throws S3ServiceException
Returns an object representing the details of an item in S3 without the object's data, and without applying any preconditions.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object's details.

Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getVersionedObjectDetails

public S3Object getVersionedObjectDetails(java.lang.String versionId,
                                          java.lang.String bucketName,
                                          java.lang.String objectKey)
                                   throws S3ServiceException
Returns an object representing the details of an item in S3 with a specific given version, without the object's data and without applying any preconditions. Versioned objects are only available from buckets with versioning enabled, see enableBucketVersioning(String).

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object's details.

Parameters:
bucketName - the name of the versioned bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

listAllBuckets

public S3Bucket[] listAllBuckets()
                          throws S3ServiceException
Lists the buckets belonging to the service user.

This method cannot be performed by anonymous services, and will fail with an exception if the service is not authenticated.

Returns:
the list of buckets owned by the service user.
Throws:
S3ServiceException

getAccountOwner

public S3Owner getAccountOwner()
                        throws S3ServiceException
Returns the owner of an S3 account, using information available in the ListAllBuckets response.

This method cannot be performed by anonymous services, and will fail with an exception if the service is not authenticated.

Returns:
the owner of the S3 account.
Throws:
S3ServiceException

listObjects

public S3Object[] listObjects(S3Bucket bucket,
                              java.lang.String prefix,
                              java.lang.String delimiter,
                              long maxListingLength)
                       throws S3ServiceException
Lists the objects in a bucket matching a prefix, while instructing S3 to send response messages containing no more than a given number of object results.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can list the contents of a publicly-readable bucket.

NOTE: If you supply a delimiter value that could cause CommonPrefixes ("subdirectory paths") to be included in the results from S3, use the listObjectsChunked(String, String, String, long, String, boolean) method instead of this one to obtain both object and CommonPrefix values.

Parameters:
bucket - the bucket whose contents will be listed. This must be a valid S3Bucket object that is non-null and contains a name.
prefix - only objects with a key that starts with this prefix will be listed
delimiter - only list objects with key names up to this delimiter, may be null. See note above.
maxListingLength - the maximum number of objects to include in each result message sent by S3. This value has no effect on the number of objects that will be returned by this method, because it will always return all the objects in the bucket.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

listObjects

public S3Object[] listObjects(java.lang.String bucketName,
                              java.lang.String prefix,
                              java.lang.String delimiter,
                              long maxListingLength)
                       throws S3ServiceException
Lists the objects in a bucket matching a prefix, while instructing S3 to send response messages containing no more than a given number of object results.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can list the contents of a publicly-readable bucket.

NOTE: If you supply a delimiter value that could cause CommonPrefixes ("subdirectory paths") to be included in the results from S3, use the listObjectsChunked(String, String, String, long, String, boolean) method instead of this one to obtain both object and CommonPrefix values.

Parameters:
bucketName - the name of the the bucket whose contents will be listed.
prefix - only objects with a key that starts with this prefix will be listed
delimiter - only list objects with key names up to this delimiter, may be null. See note above.
maxListingLength - the maximum number of objects to include in each result message sent by S3. This value has no effect on the number of objects that will be returned by this method, because it will always return all the objects in the bucket.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

listVersionedObjects

public BaseVersionOrDeleteMarker[] listVersionedObjects(java.lang.String bucketName,
                                                        java.lang.String prefix,
                                                        java.lang.String delimiter)
                                                 throws S3ServiceException
Lists versioning information in a versioned bucket where the objects match a given constraints. The S3 service will also be instructed to send response messages containing no more than a given number of object results.

This operation can only be performed by the bucket owner.

Parameters:
bucketName - the name of the the versioned bucket whose contents will be listed.
prefix - only objects with a key that starts with this prefix will be listed
delimiter - only list objects with key names up to this delimiter, may be null. See note above.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

getObjectVersions

public BaseVersionOrDeleteMarker[] getObjectVersions(java.lang.String bucketName,
                                                     java.lang.String objectKey)
                                              throws S3ServiceException
Return version information for a specific object.

This is a convenience function that applies logic in addition to the LISTVERSIONS S3 operation to simplify retrieval of an object's version history. This method is *not* the most efficient way of retrieving version history in bulk, so if you need version history for multiple objects you should use the listVersionedObjects(String, String, String) or listVersionedObjectsChunked(String, String, String, long, String, String, boolean) methods instead.

Parameters:
bucketName - the name of the versioned bucket containing the object.
objectKey - the key identifying the object.
Returns:
an array of S3Version and S3DeleteMarker objects that describe the version history of the given object.
Throws:
S3ServiceException

listObjectsChunked

public S3ObjectsChunk listObjectsChunked(java.lang.String bucketName,
                                         java.lang.String prefix,
                                         java.lang.String delimiter,
                                         long maxListingLength,
                                         java.lang.String priorLastKey)
                                  throws S3ServiceException
Lists the objects in a bucket matching a prefix, chunking the results into batches of a given size, and returning each chunk separately. It is the responsibility of the caller to building a complete bucket object listing by performing follow-up requests if necessary.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can list the contents of a publicly-readable bucket.

Parameters:
bucketName - the name of the the bucket whose contents will be listed.
prefix - only objects with a key that starts with this prefix will be listed
maxListingLength - the maximum number of objects to include in each result chunk
priorLastKey - the last object key received in a prior call to this method. The next chunk of objects listed will start with the next object in the bucket after this key name. This parameter may be null, in which case the listing will start at the beginning of the bucket's object contents.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

listObjectsChunked

public S3ObjectsChunk listObjectsChunked(java.lang.String bucketName,
                                         java.lang.String prefix,
                                         java.lang.String delimiter,
                                         long maxListingLength,
                                         java.lang.String priorLastKey,
                                         boolean completeListing)
                                  throws S3ServiceException
Lists the objects in a bucket matching a prefix and also returns the common prefixes returned by S3. Depending on the value of the completeListing variable, this method can be set to automatically perform follow-up requests to build a complete object listing, or to return only a partial listing.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can list the contents of a publicly-readable bucket.

Parameters:
bucketName - the name of the the bucket whose contents will be listed.
prefix - only objects with a key that starts with this prefix will be listed
maxListingLength - the maximum number of objects to include in each result chunk
priorLastKey - the last object key received in a prior call to this method. The next chunk of objects listed will start with the next object in the bucket after this key name. This parameter may be null, in which case the listing will start at the beginning of the bucket's object contents.
completeListing - if true, the service class will automatically perform follow-up requests to build a complete bucket object listing.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

listVersionedObjectsChunked

public VersionOrDeleteMarkersChunk listVersionedObjectsChunked(java.lang.String bucketName,
                                                               java.lang.String prefix,
                                                               java.lang.String delimiter,
                                                               long maxListingLength,
                                                               java.lang.String priorLastKey,
                                                               java.lang.String priorLastVersionId,
                                                               boolean completeListing)
                                                        throws S3ServiceException
Lists information for a versioned bucket where the items match given constarints. Depending on the value of the completeListing variable, this method can be set to automatically perform follow-up requests to build a complete object listing, or to return only a partial listing.

The objects returned by this method contain only minimal information such as the object's size, ETag, and LastModified timestamp. To retrieve the objects' metadata you must perform follow-up getObject or getObjectDetails operations.

This method can be performed by anonymous services. Anonymous services can list the contents of a publicly-readable bucket.

Parameters:
bucketName - the name of the versioned bucket whose contents will be listed.
prefix - only objects with a key that starts with this prefix will be listed
maxListingLength - the maximum number of objects to include in each result chunk
priorLastKey - the last object key received in a prior call to this method. The next chunk of items listed will start with the next object in the bucket after this key name. This parameter may be null, in which case the listing will start at the beginning of the bucket's object contents.
priorLastVersionId - the last version ID received in a prior call to this method. The next chunk of items listed will start with the next object version after this version. This parameter can only be used with a non-null priorLastKey.
completeListing - if true, the service class will automatically perform follow-up requests to build a complete bucket object listing.
Returns:
the set of objects contained in a bucket whose keys start with the given prefix.
Throws:
S3ServiceException

createBucket

public S3Bucket createBucket(S3Bucket bucket)
                      throws S3ServiceException
Creates a bucket in S3 based on the provided bucket object. Caution: Performing this operation unnecessarily when a bucket already exists may cause OperationAborted errors with the message "A conflicting conditional operation is currently in progress against this resource.". To avoid this error, use the getOrCreateBucket(String) in situations where the bucket may already exist.

Warning: Prior to version 0.7.0 this method did check whether a bucket already existed using isBucketAccessible(String). After changes to the way S3 operates, this check started to cause issues so it was removed.

This method cannot be performed by anonymous services.

Parameters:
bucket - an object representing the bucket to create which must be valid, and may contain ACL settings.
Returns:
the created bucket object, populated with all metadata made available by the creation operation.
Throws:
S3ServiceException

getBucket

public S3Bucket getBucket(java.lang.String bucketName)
                   throws S3ServiceException
Returns a bucket in your S3 account by listing all your buckets (using listAllBuckets()), and looking for the named bucket in this list.

This method cannot be performed by anonymous services.

Parameters:
bucketName -
Returns:
the bucket in your account, or null if you do not own the named bucket.
Throws:
S3ServiceException

getOrCreateBucket

public S3Bucket getOrCreateBucket(java.lang.String bucketName,
                                  java.lang.String location)
                           throws S3ServiceException
Returns a bucket in your S3 account, and creates the bucket in the given S3 location if it does not yet exist.

Note: This method will not change the location of an existing bucket if you specify a different location from a bucket's current location. To move a bucket between locations you must first delete it in the original location, then re-create it in the new location.

Parameters:
bucketName - the name of the bucket to retrieve or create.
location - the location of the S3 data centre in which the bucket will be created. Valid values include S3Bucket.LOCATION_EUROPE, S3Bucket.LOCATION_US_WEST, and the equivalent S3Bucket.LOCATION_US_STANDARD and S3Bucket.LOCATION_US.
Returns:
the bucket in your account.
Throws:
S3ServiceException

getOrCreateBucket

public S3Bucket getOrCreateBucket(java.lang.String bucketName)
                           throws S3ServiceException
Returns a bucket in your S3 account, and creates the bucket in the default location specified by the property "s3service.default-bucket-location" if it does not yet exist.

Parameters:
bucketName - the name of the bucket to retrieve or create.
Returns:
the bucket in your account.
Throws:
S3ServiceException

deleteBucket

public void deleteBucket(S3Bucket bucket)
                  throws S3ServiceException
Deletes an S3 bucket. Only the owner of a bucket may delete it.

This method cannot be performed by anonymous services.

Parameters:
bucket - the bucket to delete.
Throws:
S3ServiceException

deleteBucket

public void deleteBucket(java.lang.String bucketName)
                  throws S3ServiceException
Deletes an S3 bucket. Only the owner of a bucket may delete it.

This method cannot be performed by anonymous services.

Parameters:
bucketName - the name of the bucket to delete.
Throws:
S3ServiceException

enableBucketVersioning

public void enableBucketVersioning(java.lang.String bucketName)
                            throws S3ServiceException
Enable the S3 object versioning feature for a bucket. Multi-factor authentication will not be required to delete versions.

Parameters:
bucketName - the name of the bucket that will have versioning enabled.
Throws:
S3ServiceException

enableBucketVersioningWithMFA

public void enableBucketVersioningWithMFA(java.lang.String bucketName)
                                   throws S3ServiceException
Enable the S3 object versioning feature and enable the multi-factor authentication (MFA) feature for a bucket which does not yet have MFA enabled.

Parameters:
bucketName - the name of the bucket that will have versioning enabled.
Throws:
S3ServiceException

disableMFAForVersionedBucket

public void disableMFAForVersionedBucket(java.lang.String bucketName,
                                         java.lang.String multiFactorSerialNumber,
                                         java.lang.String multiFactorAuthCode)
                                  throws S3ServiceException
Disable the multi-factor authentication (MFA) feature for a bucket that already has S3 object versioning and MFA enabled.

Parameters:
bucketName - the name of the bucket that will have versioning enabled. versioning status of the bucket.
multiFactorSerialNumber - the serial number for a multi-factor authentication device.
multiFactorAuthCode - a multi-factor authentication code generated by a device.
Throws:
S3ServiceException

suspendBucketVersioning

public void suspendBucketVersioning(java.lang.String bucketName)
                             throws S3ServiceException
Suspend (disable) the S3 object versioning feature for a bucket. The bucket must not have the multi-factor authentication (MFA) feature enabled.

Parameters:
bucketName - the name of the versioned bucket that will have versioning suspended.
Throws:
S3ServiceException

suspendBucketVersioningWithMFA

public void suspendBucketVersioningWithMFA(java.lang.String bucketName,
                                           java.lang.String multiFactorSerialNumber,
                                           java.lang.String multiFactorAuthCode)
                                    throws S3ServiceException
Suspend (disable) the S3 object versioning feature for a bucket that requires multi-factor authentication.

Parameters:
bucketName - the name of the versioned bucket that will have versioning suspended.
multiFactorSerialNumber - the serial number for a multi-factor authentication device.
multiFactorAuthCode - a multi-factor authentication code generated by a device.
Throws:
S3ServiceException

getBucketVersioningStatus

public S3BucketVersioningStatus getBucketVersioningStatus(java.lang.String bucketName)
                                                   throws S3ServiceException
Return versioning status of bucket, which reports on whether the given bucket has S3 object versioning enabled and whether multi-factor authentication is required to delete versions.

Parameters:
bucketName - the name of the bucket.
Throws:
S3ServiceException

putObject

public S3Object putObject(java.lang.String bucketName,
                          S3Object object)
                   throws S3ServiceException
Puts an object inside an existing bucket in S3, creating a new object or overwriting an existing one with the same key.

This method can be performed by anonymous services. Anonymous services can put objects into a publicly-writable bucket.

Parameters:
bucketName - the name of the bucket inside which the object will be put.
object - the object containing all information that will be written to S3. At very least this object must be valid. Beyond that it may contain: an input stream with the object's data content, metadata, and access control settings.

Note: It is very important to set the object's Content-Length to match the size of the data input stream when possible, as this can remove the need to read data into memory to determine its size.

Returns:
the object populated with any metadata information made available by S3.
Throws:
S3ServiceException

copyObject

public java.util.Map copyObject(java.lang.String sourceBucketName,
                                java.lang.String sourceObjectKey,
                                java.lang.String destinationBucketName,
                                S3Object destinationObject,
                                boolean replaceMetadata,
                                java.util.Calendar ifModifiedSince,
                                java.util.Calendar ifUnmodifiedSince,
                                java.lang.String[] ifMatchTags,
                                java.lang.String[] ifNoneMatchTags)
                         throws S3ServiceException
Copy an object within your S3 account. You can copy an object within a single bucket or between buckets, and can optionally update the object's metadata at the same time.

This method cannot be performed by anonymous services. You must have read access to the source object and write access to the destination bucket.

An object can be copied over itself, in which case you can update its metadata without making any other changes.

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.
destinationObject - the object that will be created by the copy operation. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
replaceMetadata - If this parameter is true, the copied object will be assigned the metadata values present in the destinationObject. Otherwise, the copied object will have the same metadata as the original object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
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

copyVersionedObject

public java.util.Map copyVersionedObject(java.lang.String versionId,
                                         java.lang.String sourceBucketName,
                                         java.lang.String sourceObjectKey,
                                         java.lang.String destinationBucketName,
                                         S3Object destinationObject,
                                         boolean replaceMetadata,
                                         java.util.Calendar ifModifiedSince,
                                         java.util.Calendar ifUnmodifiedSince,
                                         java.lang.String[] ifMatchTags,
                                         java.lang.String[] ifNoneMatchTags)
                                  throws S3ServiceException
Copy an object with a specific version within your S3 account. You can copy an object within a single bucket or between buckets, and can optionally update the object's metadata at the same time.

This method cannot be performed by anonymous services. You must have read access to the source object and write access to the destination bucket.

An object can be copied over itself, in which case you can update its metadata without making any other changes.

Parameters:
versionId - identifier matching an existing object version that will be copied.
sourceBucketName - the name of the versioned 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.
destinationObject - the object that will be created by the copy operation. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
replaceMetadata - If this parameter is true, the copied object will be assigned the metadata values present in the destinationObject. Otherwise, the copied object will have the same metadata as the original object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
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

copyObject

public java.util.Map copyObject(java.lang.String sourceBucketName,
                                java.lang.String sourceObjectKey,
                                java.lang.String destinationBucketName,
                                S3Object destinationObject,
                                boolean replaceMetadata)
                         throws S3ServiceException
Copy an object within your S3 account. You can copy an object within a single bucket or between buckets, and can optionally update the object's metadata at the same time.

This method cannot be performed by anonymous services. You must have read access to the source object and write access to the destination bucket.

An object can be copied over itself, in which case you can update its metadata without making any other changes.

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.
destinationObject - the object that will be created by the copy operation. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
replaceMetadata - If this parameter is true, the copied object will be assigned the metadata values present in the destinationObject. Otherwise, the copied object will have the same metadata as the original object.
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

copyVersionedObject

public java.util.Map copyVersionedObject(java.lang.String versionId,
                                         java.lang.String sourceBucketName,
                                         java.lang.String sourceObjectKey,
                                         java.lang.String destinationBucketName,
                                         S3Object destinationObject,
                                         boolean replaceMetadata)
                                  throws S3ServiceException
Copy an object with a specific version within your S3 account. You can copy an object within a single bucket or between buckets, and can optionally update the object's metadata at the same time.

This method cannot be performed by anonymous services. You must have read access to the source object and write access to the destination bucket.

An object can be copied over itself, in which case you can update its metadata without making any other changes.

Parameters:
versionId - identifier matching an existing object version that will be copied.
sourceBucketName - the name of the versioned 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.
destinationObject - the object that will be created by the copy operation. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
replaceMetadata - If this parameter is true, the copied object will be assigned the metadata values present in the destinationObject. Otherwise, the copied object will have the same metadata as the original object.
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

moveObject

public java.util.Map moveObject(java.lang.String sourceBucketName,
                                java.lang.String sourceObjectKey,
                                java.lang.String destinationBucketName,
                                S3Object destinationObject,
                                boolean replaceMetadata)
                         throws S3ServiceException
Move an object from your S3 account. This method works by invoking the copyObject(String, String, String, S3Object, boolean) method to copy the original object, then deletes the original object once the copy has succeeded.

This method cannot be performed by anonymous services. You must have read access to the source object, write access to the destination bucket, and write access to the source bucket.

If the copy operation succeeds but the delete operation fails, this method will not throw an exception but the result map object will contain an item named "DeleteException" with the exception thrown by the delete operation.

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.
destinationObject - the object that will be created by the move operation. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
replaceMetadata - If this parameter is true, the copied object will be assigned the metadata values present in the destinationObject. Otherwise, the copied object will have the same metadata as the original object.
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). If the object was successfully copied but the original could not be deleted, the map will also include an item named "DeleteException" with the exception thrown by the delete operation.
Throws:
S3ServiceException

renameObject

public java.util.Map renameObject(java.lang.String bucketName,
                                  java.lang.String sourceObjectKey,
                                  S3Object destinationObject)
                           throws S3ServiceException
Rename an object in your S3 account. This method works by invoking the moveObject(String, String, String, S3Object, boolean) method to move the original object to a new key name.

The original object's metadata is retained, but to apply an access control setting other than private you must specify an ACL in the destination object.

This method cannot be performed by anonymous services. You must have write access to the source object and write access to the bucket.

Parameters:
bucketName - the name of the bucket containing the original object that will be copied.
sourceObjectKey - the key name of the original object.
destinationObject - the object that will be created by the rename operation. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
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). If the object was successfully copied but the original could not be deleted, the map will also include an item named "DeleteException" with the exception thrown by the delete operation.
Throws:
S3ServiceException

updateObjectMetadata

public java.util.Map updateObjectMetadata(java.lang.String bucketName,
                                          S3Object object)
                                   throws S3ServiceException
Update an object's metadata. This method works by invoking the copyObject(String, String, String, S3Object, boolean) method to copy the original object over itself, applying the new metadata in the process.

Parameters:
bucketName - the name of the bucket containing the object that will be updated.
object - the object that will be updated. If this item includes an AccessControlList setting the copied object will be assigned that ACL, otherwise the copied object will be assigned the default private ACL setting.
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

putObject

public S3Object putObject(S3Bucket bucket,
                          S3Object object)
                   throws S3ServiceException
Puts an object inside an existing bucket in S3, creating a new object or overwriting an existing one with the same key.

This method can be performed by anonymous services. Anonymous services can put objects into a publicly-writable bucket.

Parameters:
bucket - the bucket inside which the object will be put, which must be valid.
object - the object containing all information that will be written to S3. At very least this object must be valid. Beyond that it may contain: an input stream with the object's data content, metadata, and access control settings.

Note: It is very important to set the object's Content-Length to match the size of the data input stream when possible, as this can remove the need to read data into memory to determine its size.

Returns:
the object populated with any metadata information made available by S3.
Throws:
S3ServiceException

deleteObject

public void deleteObject(S3Bucket bucket,
                         java.lang.String objectKey)
                  throws S3ServiceException
Deletes an object from a bucket in S3.

This method can be performed by anonymous services. Anonymous services can delete objects from publicly-writable buckets.

Parameters:
bucket - the bucket containing the object to be deleted.
objectKey - the key representing the object in S3.
Throws:
S3ServiceException

deleteObject

public void deleteObject(java.lang.String bucketName,
                         java.lang.String objectKey)
                  throws S3ServiceException
Deletes an object from a bucket in S3.

This method can be performed by anonymous services. Anonymous services can delete objects from publicly-writable buckets.

Parameters:
bucketName - the name of the bucket containing the object to be deleted.
objectKey - the key representing the object in S3.
Throws:
S3ServiceException

deleteVersionedObjectWithMFA

public void deleteVersionedObjectWithMFA(java.lang.String versionId,
                                         java.lang.String multiFactorSerialNumber,
                                         java.lang.String multiFactorAuthCode,
                                         java.lang.String bucketName,
                                         java.lang.String objectKey)
                                  throws S3ServiceException
Deletes a object version from a bucket in S3. This will delete only the specific version identified and will not affect any other Version or DeleteMarkers related to the object.

This operation can only be performed by the owner of the S3 bucket.

Parameters:
versionId - the identifier of an object version that will be deleted.
multiFactorSerialNumber - the serial number for a multi-factor authentication device.
multiFactorAuthCode - a multi-factor authentication code generated by a device.
bucketName - the name of the versioned bucket containing the object to be deleted.
objectKey - the key representing the object in S3.
Throws:
S3ServiceException

deleteVersionedObject

public void deleteVersionedObject(java.lang.String versionId,
                                  java.lang.String bucketName,
                                  java.lang.String objectKey)
                           throws S3ServiceException
Deletes a object version from a bucket in S3. This will delete only the specific version identified and will not affect any other Version or DeleteMarkers related to the object.

This operation can only be performed by the owner of the S3 bucket.

Parameters:
versionId - the identifier of an object version that will be deleted.
bucketName - the name of the versioned bucket containing the object to be deleted.
objectKey - the key representing the object in S3.
Throws:
S3ServiceException

getObjectDetails

public S3Object getObjectDetails(S3Bucket bucket,
                                 java.lang.String objectKey,
                                 java.util.Calendar ifModifiedSince,
                                 java.util.Calendar ifUnmodifiedSince,
                                 java.lang.String[] ifMatchTags,
                                 java.lang.String[] ifNoneMatchTags)
                          throws S3ServiceException
Returns an object representing the details of an item in S3 that meets any given preconditions. The object is returned without the object's data.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get details of publicly-readable objects.

Parameters:
bucket - the bucket containing the object. This must be a valid S3Bucket object that is non-null and contains a name.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getVersionedObjectDetails

public S3Object getVersionedObjectDetails(java.lang.String versionId,
                                          S3Bucket bucket,
                                          java.lang.String objectKey,
                                          java.util.Calendar ifModifiedSince,
                                          java.util.Calendar ifUnmodifiedSince,
                                          java.lang.String[] ifMatchTags,
                                          java.lang.String[] ifNoneMatchTags)
                                   throws S3ServiceException
Returns an object representing the details of a versioned object in S3 that also meets any given preconditions. The object is returned without the object's data.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get details of publicly-readable objects.

Parameters:
versionId - the identifier of the object version to return.
bucket - the versioned bucket containing the object. This must be a valid S3Bucket object that is non-null and contains a name.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getObjectDetails

public S3Object getObjectDetails(java.lang.String bucketName,
                                 java.lang.String objectKey,
                                 java.util.Calendar ifModifiedSince,
                                 java.util.Calendar ifUnmodifiedSince,
                                 java.lang.String[] ifMatchTags,
                                 java.lang.String[] ifNoneMatchTags)
                          throws S3ServiceException
Returns an object representing the details of an item in S3 that meets any given preconditions. The object is returned without the object's data.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get details of publicly-readable objects.

Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getVersionedObjectDetails

public S3Object getVersionedObjectDetails(java.lang.String versionId,
                                          java.lang.String bucketName,
                                          java.lang.String objectKey,
                                          java.util.Calendar ifModifiedSince,
                                          java.util.Calendar ifUnmodifiedSince,
                                          java.lang.String[] ifMatchTags,
                                          java.lang.String[] ifNoneMatchTags)
                                   throws S3ServiceException
Returns an object representing the details of a versioned object in S3 that also meets any given preconditions. The object is returned without the object's data.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get details of publicly-readable objects.

Parameters:
versionId - the identifier of the object version to return.
bucketName - the name of the versioned bucket containing the object.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getObject

public S3Object getObject(S3Bucket bucket,
                          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)
                   throws S3ServiceException
Returns an object representing the details and data of an item in S3 that meets any given preconditions.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get publicly-readable objects.

Implementation notes

Implementations should use assertValidBucket(org.jets3t.service.model.S3Bucket, java.lang.String) assertion.

Parameters:
bucket - the bucket containing the object. This must be a valid S3Bucket object that is non-null and contains a name.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
byteRangeStart - include only a portion of the object's data - starting at this point, ignored if null.
byteRangeEnd - include only a portion of the object's data - ending at this point, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getVersionedObject

public S3Object getVersionedObject(java.lang.String versionId,
                                   S3Bucket bucket,
                                   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)
                            throws S3ServiceException
Returns an object representing the details and data of a versioned object in S3 that also meets any given preconditions.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get publicly-readable objects.

Implementation notes

Implementations should use assertValidBucket(org.jets3t.service.model.S3Bucket, java.lang.String) assertion.

Parameters:
versionId - the identifier of the object version to return.
bucket - the versioned bucket containing the object. This must be a valid S3Bucket object that is non-null and contains a name.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
byteRangeStart - include only a portion of the object's data - starting at this point, ignored if null.
byteRangeEnd - include only a portion of the object's data - ending at this point, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getObject

public S3Object getObject(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)
                   throws S3ServiceException
Returns an object representing the details and data of an item in S3 that meets any given preconditions.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Implementation notes

Implementations should use assertValidBucket(org.jets3t.service.model.S3Bucket, java.lang.String) assertion.

Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
byteRangeStart - include only a portion of the object's data - starting at this point, ignored if null.
byteRangeEnd - include only a portion of the object's data - ending at this point, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

getVersionedObject

public S3Object getVersionedObject(java.lang.String versionId,
                                   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)
                            throws S3ServiceException
Returns an object representing the details and data of a versioned object in S3 that also meets any given preconditions.

Important: It is the caller's responsibility to close the object's data input stream. The data stream should be consumed and closed as soon as is practical as network connections may be held open until the streams are closed. Excessive unclosed streams can lead to connection starvation.

An exception is thrown if any of the preconditions fail. Preconditions are only applied if they are non-null.

This method can be performed by anonymous services. Anonymous services can get a publicly-readable object.

Implementation notes

Implementations should use assertValidBucket(org.jets3t.service.model.S3Bucket, java.lang.String) assertion.

Parameters:
versionId - the identifier of the object version to return.
bucketName - the name of the versioned bucket containing the object.
objectKey - the key identifying the object.
ifModifiedSince - a precondition specifying a date after which the object must have been modified, ignored if null.
ifUnmodifiedSince - a precondition specifying a date after which the object must not have been modified, ignored if null.
ifMatchTags - a precondition specifying an MD5 hash the object must match, ignored if null.
ifNoneMatchTags - a precondition specifying an MD5 hash the object must not match, ignored if null.
byteRangeStart - include only a portion of the object's data - starting at this point, ignored if null.
byteRangeEnd - include only a portion of the object's data - ending at this point, ignored if null.
Returns:
the object with the given key in S3, including only general details and metadata (not the data input stream)
Throws:
S3ServiceException

putObjectAcl

public void putObjectAcl(S3Bucket bucket,
                         S3Object object)
                  throws S3ServiceException
Applies access control settings to an object. The ACL settings must be included with the object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucket - the bucket containing the object to modify.
object - the object with ACL settings that will be applied.
Throws:
S3ServiceException

putObjectAcl

public void putObjectAcl(java.lang.String bucketName,
                         java.lang.String objectKey,
                         AccessControlList acl)
                  throws S3ServiceException
Applies access control settings to an object. The ACL settings must be included with the object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucketName - the name of the bucket containing the object to modify.
objectKey - the key name of the object with ACL settings that will be applied.
Throws:
S3ServiceException

putVersionedObjectAcl

public void putVersionedObjectAcl(java.lang.String versionId,
                                  java.lang.String bucketName,
                                  java.lang.String objectKey,
                                  AccessControlList acl)
                           throws S3ServiceException
Applies access control settings to a versioned object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
versionId - the identifier of the object version whose ACL will be updated.
bucketName - the name of the versioned bucket containing the object to modify.
objectKey - the key name of the object with ACL settings that will be applied.
Throws:
S3ServiceException

putVersionedObjectAcl

public void putVersionedObjectAcl(java.lang.String versionId,
                                  S3Bucket bucket,
                                  S3Object object)
                           throws S3ServiceException
Applies access control settings to a versioned object. The ACL settings must be included with the object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
versionId - the identifier of the object version whose ACL will be updated.
bucket - the bucket containing the object to modify.
object - the object with ACL settings that will be applied.
Throws:
S3ServiceException

putBucketAcl

public void putBucketAcl(S3Bucket bucket)
                  throws S3ServiceException
Applies access control settings to a bucket. The ACL settings must be included inside the bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of a bucket if the ACL already in place for that bucket (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucket - a bucket with ACL settings to apply.
Throws:
S3ServiceException

putBucketAcl

public void putBucketAcl(java.lang.String bucketName,
                         AccessControlList acl)
                  throws S3ServiceException
Applies access control settings to a bucket. The ACL settings must be included inside the bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of a bucket if the ACL already in place for that bucket (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucketName - a name of the bucket with ACL settings to apply.
Throws:
S3ServiceException

getObjectAcl

public AccessControlList getObjectAcl(S3Bucket bucket,
                                      java.lang.String objectKey)
                               throws S3ServiceException
Retrieves the access control settings of an object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows read access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucket - the bucket whose ACL settings will be retrieved (if objectKey is null) or the bucket containing the object whose ACL settings will be retrieved (if objectKey is non-null).
objectKey - if non-null, the key of the object whose ACL settings will be retrieved. Ignored if null.
Returns:
the ACL settings of the bucket or object.
Throws:
S3ServiceException

getVersionedObjectAcl

public AccessControlList getVersionedObjectAcl(java.lang.String versionId,
                                               S3Bucket bucket,
                                               java.lang.String objectKey)
                                        throws S3ServiceException
Retrieves the access control settings of a versioned object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows read access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
versionId - the identifier of the object version whose ACL will be returned.
bucket - the versioned bucket whose ACL settings will be retrieved (if objectKey is null) or the bucket containing the object whose ACL settings will be retrieved (if objectKey is non-null).
objectKey - if non-null, the key of the object whose ACL settings will be retrieved. Ignored if null.
Returns:
the ACL settings of the bucket or object.
Throws:
S3ServiceException

getObjectAcl

public AccessControlList getObjectAcl(java.lang.String bucketName,
                                      java.lang.String objectKey)
                               throws S3ServiceException
Retrieves the access control settings of an object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucketName - the name of the bucket whose ACL settings will be retrieved (if objectKey is null) or the name of the bucket containing the object whose ACL settings will be retrieved (if objectKey is non-null).
objectKey - if non-null, the key of the object whose ACL settings will be retrieved. Ignored if null.
Returns:
the ACL settings of the bucket or object.
Throws:
S3ServiceException

getVersionedObjectAcl

public AccessControlList getVersionedObjectAcl(java.lang.String versionId,
                                               java.lang.String bucketName,
                                               java.lang.String objectKey)
                                        throws S3ServiceException
Retrieves the access control settings of a versioned object. This method can be performed by anonymous services, but can only succeed if the object's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of an object if the ACL already in place for that object (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
versionId - the identifier of the object version whose ACL will be returned.
bucketName - the name of the versioned bucket containing the object whose ACL settings will be retrieved.
objectKey - if non-null, the key of the object whose ACL settings will be retrieved. Ignored if null.
Returns:
the ACL settings of the bucket or object.
Throws:
S3ServiceException

getBucketAcl

public AccessControlList getBucketAcl(S3Bucket bucket)
                               throws S3ServiceException
Retrieves the access control settings of a bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of a bucket if the ACL already in place for that bucket (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucket - the bucket whose access control settings will be returned. This must be a valid S3Bucket object that is non-null and contains a name.
Returns:
the ACL settings of the bucket.
Throws:
S3ServiceException

getBucketAcl

public AccessControlList getBucketAcl(java.lang.String bucketName)
                               throws S3ServiceException
Retrieves the access control settings of a bucket. This method can be performed by anonymous services, but can only succeed if the bucket's existing ACL already allows write access by the anonymous user. In general, you can only access the ACL of a bucket if the ACL already in place for that bucket (in S3) allows you to do so. See the S3 documentation on ACLs for more details on access to ACLs.

Parameters:
bucketName - the name of the bucket whose access control settings will be returned.
Returns:
the ACL settings of the bucket.
Throws:
S3ServiceException

getBucketLocation

public java.lang.String getBucketLocation(java.lang.String bucketName)
                                   throws S3ServiceException
Retrieves the location of a bucket. Only the owner of a bucket may retrieve its location.

Parameters:
bucketName - the name of the bucket whose location will be returned.
Returns:
a string representing the location of the bucket, such as "EU" for a bucket located in Europe or null for a bucket in the default US location.
Throws:
S3ServiceException

getBucketLoggingStatus

public S3BucketLoggingStatus getBucketLoggingStatus(java.lang.String bucketName)
                                             throws S3ServiceException
Retrieves the logging status settings of a bucket. Only the owner of a bucket may retrieve its logging status.

Parameters:
bucketName - the name of the bucket whose logging status settings will be returned.
Returns:
the Logging Status settings of the bucket.
Throws:
S3ServiceException

setBucketLoggingStatus

public void setBucketLoggingStatus(java.lang.String bucketName,
                                   S3BucketLoggingStatus status,
                                   boolean updateTargetACLifRequired)
                            throws S3ServiceException
Applies logging settings to a bucket, optionally modifying the ACL permissions for the logging target bucket to ensure log files can be written to it. Only the owner of a bucket may change its logging status.

Parameters:
bucketName - the name of the bucket the logging settings will apply to.
status - the logging status settings to apply to the bucket.
updateTargetACLifRequired - if true, when logging is enabled the method will check the target bucket to ensure it has the necessary ACL permissions set to allow logging (that is, WRITE and READ_ACP for the group http://acs.amazonaws.com/groups/s3/LogDelivery). If the target bucket does not have the correct permissions the bucket's ACL will be updated to have the correct permissions. If this parameter is false, no ACL checks or updates will occur.
Throws:
S3ServiceException

isRequesterPaysBucket

public boolean isRequesterPaysBucket(java.lang.String bucketName)
                              throws S3ServiceException
Return true if the given bucket is configured as a Requester Pays bucket, in which case the requester must supply their own AWS credentials when accessing objects in the bucket, and will be responsible for request and data transfer fees.

Parameters:
bucketName - the name of the bucket whose request payment configuration setting will be returned.
Returns:
true if the given bucket is configured to be Requester Pays, false if it is has the default Owner pays configuration.
Throws:
S3ServiceException

setRequesterPaysBucket

public void setRequesterPaysBucket(java.lang.String bucketName,
                                   boolean requesterPays)
                            throws S3ServiceException
Applies request payment configuration settings to a bucket, setting the bucket to be either Requester Pays or Bucket Owner pays. Only the owner of a bucket may change its request payment status.

Parameters:
bucketName - the name of the bucket to which the request payment configuration settings will be applied.
requesterPays - if true, the bucket will be configured to be Requester Pays. If false, the bucket will be configured to be Owner pays (the default configuration setting).
Throws:
S3ServiceException

getCurrentTimeWithOffset

public java.util.Date getCurrentTimeWithOffset()
Returns the current date and time, adjusted according to the time offset between your computer and an AWS server (as set by the RestUtils.getAWSTimeAdjustment() method).

Returns:
the current time, or the current time adjusted to match the AWS time if the RestUtils.getAWSTimeAdjustment() method has been invoked.

isBucketAccessible

public abstract boolean isBucketAccessible(java.lang.String bucketName)
                                    throws S3ServiceException
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 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.

Returns:
true if the bucket exists and is accessible to the service user, false otherwise.
Throws:
S3ServiceException

checkBucketStatus

public abstract int checkBucketStatus(java.lang.String bucketName)
                               throws S3ServiceException
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 getOrCreateBucket(String) method for this purpose instead.

Parameters:
bucketName -
Returns:
BUCKET_STATUS__MY_BUCKET if you already own the bucket, BUCKET_STATUS__DOES_NOT_EXIST if the bucket does not yet exist in S3, or BUCKET_STATUS__ALREADY_CLAIMED if someone else has already created a bucket with the given name.
Throws:
S3ServiceException

getBucketLocationImpl

protected abstract java.lang.String getBucketLocationImpl(java.lang.String bucketName)
                                                   throws S3ServiceException
Throws:
S3ServiceException

getBucketLoggingStatusImpl

protected abstract S3BucketLoggingStatus getBucketLoggingStatusImpl(java.lang.String bucketName)
                                                             throws S3ServiceException
Throws:
S3ServiceException

setBucketLoggingStatusImpl

protected abstract void setBucketLoggingStatusImpl(java.lang.String bucketName,
                                                   S3BucketLoggingStatus status)
                                            throws S3ServiceException
Throws:
S3ServiceException

setRequesterPaysBucketImpl

protected abstract void setRequesterPaysBucketImpl(java.lang.String bucketName,
                                                   boolean requesterPays)
                                            throws S3ServiceException
Throws:
S3ServiceException

isRequesterPaysBucketImpl

protected abstract boolean isRequesterPaysBucketImpl(java.lang.String bucketName)
                                              throws S3ServiceException
Throws:
S3ServiceException

listAllBucketsImpl

protected abstract S3Bucket[] listAllBucketsImpl()
                                          throws S3ServiceException
Returns:
the buckets in an S3 account.
Throws:
S3ServiceException

getAccountOwnerImpl

protected abstract S3Owner getAccountOwnerImpl()
                                        throws S3ServiceException
Returns:
the owner of an S3 account.
Throws:
S3ServiceException

listObjectsImpl

protected abstract S3Object[] listObjectsImpl(java.lang.String bucketName,
                                              java.lang.String prefix,
                                              java.lang.String delimiter,
                                              long maxListingLength)
                                       throws S3ServiceException
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.

Parameters:
bucketName -
prefix -
delimiter -
maxListingLength -
Returns:
the objects in a bucket.
Throws:
S3ServiceException

listVersionedObjectsImpl

protected abstract 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
Throws:
S3ServiceException

listObjectsChunkedImpl

protected abstract S3ObjectsChunk listObjectsChunkedImpl(java.lang.String bucketName,
                                                         java.lang.String prefix,
                                                         java.lang.String delimiter,
                                                         long maxListingLength,
                                                         java.lang.String priorLastKey,
                                                         boolean completeListing)
                                                  throws S3ServiceException
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.

Parameters:
bucketName -
prefix -
delimiter -
maxListingLength -
priorLastKey -
completeListing -
Throws:
S3ServiceException

listVersionedObjectsChunkedImpl

protected abstract 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
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.

Parameters:
bucketName -
prefix -
delimiter -
maxListingLength -
priorLastKey -
completeListing -
Throws:
S3ServiceException

createBucketImpl

protected abstract S3Bucket createBucketImpl(java.lang.String bucketName,
                                             java.lang.String location,
                                             AccessControlList acl)
                                      throws S3ServiceException
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.

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

deleteBucketImpl

protected abstract void deleteBucketImpl(java.lang.String bucketName)
                                  throws S3ServiceException
Throws:
S3ServiceException

updateBucketVersioningStatusImpl

protected abstract void updateBucketVersioningStatusImpl(java.lang.String bucketName,
                                                         boolean enabled,
                                                         boolean multiFactorAuthDeleteEnabled,
                                                         java.lang.String multiFactorSerialNumber,
                                                         java.lang.String multiFactorAuthCode)
                                                  throws S3ServiceException
Throws:
S3ServiceException

getBucketVersioningStatusImpl

protected abstract S3BucketVersioningStatus getBucketVersioningStatusImpl(java.lang.String bucketName)
                                                                   throws S3ServiceException
Throws:
S3ServiceException

putObjectImpl

protected abstract S3Object putObjectImpl(java.lang.String bucketName,
                                          S3Object object)
                                   throws S3ServiceException
Throws:
S3ServiceException

copyObjectImpl

protected abstract 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
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.

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

deleteObjectImpl

protected abstract void deleteObjectImpl(java.lang.String bucketName,
                                         java.lang.String objectKey,
                                         java.lang.String versionId,
                                         java.lang.String multiFactorSerialNumber,
                                         java.lang.String multiFactorAuthCode)
                                  throws S3ServiceException
Throws:
S3ServiceException

getObjectDetailsImpl

protected abstract 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
Throws:
S3ServiceException

getObjectImpl

protected abstract 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
Throws:
S3ServiceException

putBucketAclImpl

protected abstract void putBucketAclImpl(java.lang.String bucketName,
                                         AccessControlList acl)
                                  throws S3ServiceException
Throws:
S3ServiceException

putObjectAclImpl

protected abstract void putObjectAclImpl(java.lang.String bucketName,
                                         java.lang.String objectKey,
                                         AccessControlList acl,
                                         java.lang.String versionId)
                                  throws S3ServiceException
Throws:
S3ServiceException

getObjectAclImpl

protected abstract AccessControlList getObjectAclImpl(java.lang.String bucketName,
                                                      java.lang.String objectKey,
                                                      java.lang.String versionId)
                                               throws S3ServiceException
Throws:
S3ServiceException

getBucketAclImpl

protected abstract AccessControlList getBucketAclImpl(java.lang.String bucketName)
                                               throws S3ServiceException
Throws:
S3ServiceException

shutdownImpl

protected abstract void shutdownImpl()
                              throws S3ServiceException
Throws:
S3ServiceException