public abstract class StorageService
extends java.lang.Object
This class must be extended by implementation classes that perform the communication with a specific service using a specific interface, such as REST or SOAP.
Implementations of StorageService
must be thread-safe as they will probably be used by
the multi-threaded service class ThreadedStorageService
.
This class uses properties obtained through Jets3tProperties
. For more information on
these properties please refer to
JetS3t Configuration
Modifier and Type | Field and Description |
---|---|
static int |
BUCKET_STATUS__ALREADY_CLAIMED
Status code returned by
checkBucketStatus(String) for a bucket
that exists but is not owned by the service user (i.e. |
static int |
BUCKET_STATUS__DOES_NOT_EXIST
Status code returned by
checkBucketStatus(String) for a bucket
that does not exist. |
static int |
BUCKET_STATUS__MY_BUCKET
Status code returned by
checkBucketStatus(String) for a bucket
that exists and is owned by the service user. |
protected long |
timeOffset
The approximate difference in the current time between your computer and
a target service, measured in milliseconds.
|
Modifier | Constructor and Description |
---|---|
protected |
StorageService(ProviderCredentials credentials)
Construct a
StorageService identified by the given user credentials. |
protected |
StorageService(ProviderCredentials credentials,
java.lang.String invokingApplicationDescription)
Construct a
StorageService identified by the given user credentials. |
protected |
StorageService(ProviderCredentials credentials,
java.lang.String invokingApplicationDescription,
Jets3tProperties jets3tProperties)
Construct a
StorageService identified by the given user credentials. |
Modifier and Type | Method and Description |
---|---|
protected void |
assertAuthenticatedConnection(java.lang.String action)
Throws an exception if this service is anonymous (that is, it was created without
an
ProviderCredentials object representing a user account. |
protected void |
assertValidBucket(StorageBucket bucket,
java.lang.String action)
Throws an exception if a bucket is null or contains a null/empty name.
|
protected void |
assertValidObject(StorageObject 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.
|
abstract int |
checkBucketStatus(java.lang.String bucketName)
Find out the status of a bucket with the given name.
|
java.util.Map<java.lang.String,java.lang.Object> |
copyObject(java.lang.String sourceBucketName,
java.lang.String sourceObjectKey,
java.lang.String destinationBucketName,
StorageObject destinationObject,
boolean replaceMetadata)
Copy an object.
|
java.util.Map<java.lang.String,java.lang.Object> |
copyObject(java.lang.String sourceBucketName,
java.lang.String sourceObjectKey,
java.lang.String destinationBucketName,
StorageObject destinationObject,
boolean replaceMetadata,
java.util.Calendar ifModifiedSince,
java.util.Calendar ifUnmodifiedSince,
java.lang.String[] ifMatchTags,
java.lang.String[] ifNoneMatchTags)
Copy an object.
|
protected abstract java.util.Map<java.lang.String,java.lang.Object> |
copyObjectImpl(java.lang.String sourceBucketName,
java.lang.String sourceObjectKey,
java.lang.String destinationBucketName,
java.lang.String destinationObjectKey,
AccessControlList acl,
java.util.Map<java.lang.String,java.lang.Object> destinationMetadata,
java.util.Calendar ifModifiedSince,
java.util.Calendar ifUnmodifiedSince,
java.lang.String[] ifMatchTags,
java.lang.String[] ifNoneMatchTags,
java.lang.String versionId,
java.lang.String destinationObjectStorageClass,
java.lang.String destinationObjectServerSideEncryptionAlgorithm)
Copy an object within your account.
|
StorageBucket |
createBucket(StorageBucket bucket)
Create a bucket with the Access Control List settings of the bucket object (if any).
|
StorageBucket |
createBucket(java.lang.String bucketName)
Creates a bucket.
|
protected StorageBucket |
createBucketImpl(java.lang.String bucketName,
java.lang.String location,
AccessControlList acl)
Creates a bucket.
|
protected abstract StorageBucket |
createBucketImpl(java.lang.String bucketName,
java.lang.String location,
AccessControlList acl,
java.util.Map<java.lang.String,java.lang.Object> headers)
Creates a bucket.
|
void |
deleteBucket(StorageBucket bucket)
Deletes a bucket.
|
void |
deleteBucket(java.lang.String bucketName)
Deletes a bucket.
|
protected abstract void |
deleteBucketImpl(java.lang.String bucketName) |
void |
deleteObject(java.lang.String bucketName,
java.lang.String objectKey)
Deletes an object from a bucket.
|
protected abstract void |
deleteObjectImpl(java.lang.String bucketName,
java.lang.String objectKey,
java.lang.String versionId,
java.lang.String multiFactorSerialNumber,
java.lang.String multiFactorAuthCode) |
StorageOwner |
getAccountOwner()
Returns the owner of an account, using information available in the
bucket listing response.
|
protected abstract StorageOwner |
getAccountOwnerImpl() |
StorageBucket |
getBucket(java.lang.String bucketName)
Returns a bucket in your account by listing all your buckets
(using
listAllBuckets() ), and looking for the named bucket in
this list. |
AccessControlList |
getBucketAcl(java.lang.String bucketName)
Retrieves the access control settings of a bucket.
|
protected abstract AccessControlList |
getBucketAclImpl(java.lang.String bucketName) |
java.util.Date |
getCurrentTimeWithOffset()
Returns the current date and time, adjusted according to the time
offset between your computer and a service endpoint, as set by
RestUtils.calculateTimeAdjustmentOffset(org.apache.http.HttpResponse) . |
protected abstract boolean |
getDisableDnsBuckets() |
protected abstract boolean |
getEnableServerSideEncryption() |
protected abstract boolean |
getEnableStorageClasses() |
abstract java.lang.String |
getEndpoint() |
protected abstract int |
getHttpPort() |
protected abstract boolean |
getHttpsOnly() |
protected abstract int |
getHttpsPort() |
int |
getInternalErrorRetryMax() |
java.lang.String |
getInvokingApplicationDescription() |
Jets3tProperties |
getJetS3tProperties() |
StorageObject |
getObject(java.lang.String bucketName,
java.lang.String objectKey)
Returns an object representing the details and data of an item in a service,
without applying any preconditions.
|
StorageObject |
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 that meets any given preconditions.
|
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) |
StorageObject |
getObjectDetails(java.lang.String bucketName,
java.lang.String objectKey)
Returns an object representing the details of an item in without the object's data, and
without applying any preconditions.
|
StorageObject |
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 that meets any given preconditions.
|
protected abstract StorageObject |
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 StorageObject |
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) |
StorageBucket |
getOrCreateBucket(java.lang.String bucketName)
Returns a bucket in your account, and creates the bucket if
it does not yet exist.
|
ProviderCredentials |
getProviderCredentials() |
abstract java.util.List<java.lang.String> |
getResourceParameterNames() |
abstract java.lang.String |
getRestHeaderPrefix() |
abstract java.lang.String |
getRestMetadataPrefix() |
protected abstract java.lang.String |
getSignatureIdentifier() |
protected abstract java.lang.String |
getVirtualPath() |
protected abstract XmlResponsesSaxParser |
getXmlResponseSaxParser() |
protected void |
initializeDefaults() |
boolean |
isAuthenticatedConnection() |
abstract boolean |
isBucketAccessible(java.lang.String bucketName)
Indicates whether a bucket exists and is accessible to a service user.
|
boolean |
isHttpsOnly()
Whether to use secure HTTPS or insecure HTTP for communicating with a service,
as configured in the
Jets3tProperties . |
boolean |
isObjectInBucket(java.lang.String bucketName,
java.lang.String objectKey)
Convenience method to check whether an object exists in a bucket.
|
boolean |
isShutdown() |
StorageBucket[] |
listAllBuckets()
Lists the buckets belonging to the service user.
|
protected StorageBucket[] |
listAllBucketsImpl() |
protected abstract StorageBucket[] |
listAllBucketsImpl(java.util.Map<java.lang.String,java.lang.Object> headers) |
StorageObject[] |
listObjects(java.lang.String bucketName)
Lists the objects in a bucket.
|
StorageObject[] |
listObjects(java.lang.String bucketName,
java.lang.String prefix,
java.lang.String delimiter)
Lists the objects in a bucket matching a prefix and delimiter.
|
StorageObject[] |
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 the service
to send response messages containing no more than a given number of object
results.
|
StorageObjectsChunk |
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.
|
StorageObjectsChunk |
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.
|
protected abstract StorageObjectsChunk |
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 StorageObject[] |
listObjectsImpl(java.lang.String bucketName,
java.lang.String prefix,
java.lang.String delimiter,
long maxListingLength)
Lists objects in a bucket.
|
java.util.Map<java.lang.String,java.lang.Object> |
moveObject(java.lang.String sourceBucketName,
java.lang.String sourceObjectKey,
java.lang.String destinationBucketName,
StorageObject destinationObject,
boolean replaceMetadata)
Move an object.
|
protected abstract StorageBucket |
newBucket() |
protected abstract StorageObject |
newObject() |
void |
putBucketAcl(StorageBucket 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) |
StorageObject |
putObject(java.lang.String bucketName,
StorageObject object)
Puts an object inside an existing bucket, creating a new object or overwriting
an existing one with the same key.
|
void |
putObjectAcl(java.lang.String bucketName,
StorageObject 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 StorageObject |
putObjectImpl(java.lang.String bucketName,
StorageObject object) |
java.util.Map<java.lang.String,java.lang.Object> |
renameMetadataKeys(java.util.Map<java.lang.String,java.lang.Object> metadata)
Renames metadata property names to be suitable for use as HTTP Headers.
|
java.util.Map<java.lang.String,java.lang.Object> |
renameObject(java.lang.String bucketName,
java.lang.String sourceObjectKey,
StorageObject destinationObject)
Rename an object.
|
void |
setProviderCredentials(ProviderCredentials credentials) |
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,
ServiceException ex)
Sleeps for a period of time based on the number of Internal Server errors a request has
encountered, provided the number of errors does not exceed the value set with the
property
storage-service.internal-error-retry-max . |
java.util.Map<java.lang.String,java.lang.Object> |
updateObjectMetadata(java.lang.String bucketName,
StorageObject object)
Update an object's metadata.
|
public static final int BUCKET_STATUS__MY_BUCKET
checkBucketStatus(String)
for a bucket
that exists and is owned by the service user.public static final int BUCKET_STATUS__DOES_NOT_EXIST
checkBucketStatus(String)
for a bucket
that does not exist.public static final int BUCKET_STATUS__ALREADY_CLAIMED
checkBucketStatus(String)
for a bucket
that exists but is not owned by the service user (i.e. another user has
already created this bucket in the service's namespace).protected long timeOffset
getCurrentTimeWithOffset()
to obtain the current time with this offset factor included, and the
RestUtils.calculateTimeAdjustmentOffset(org.apache.http.HttpResponse)
method to calculate an offset value for your computer based on a response
from an AWS server.protected StorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription, Jets3tProperties jets3tProperties)
StorageService
identified by the given user credentials.credentials
- the user credentials, 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.protected StorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription)
StorageService
identified by the given user credentials.credentials
- the user credentials, 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
protected StorageService(ProviderCredentials credentials)
StorageService
identified by the given user credentials.credentials
- the user credentials, may be null in which case the communication is done as an anonymous user.protected void initializeDefaults()
public void shutdown() throws ServiceException
ServiceException
public boolean isShutdown()
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.public boolean isAuthenticatedConnection()
ProviderCredentials
identifying a user, false
if the service is acting as an anonymous user.public boolean isHttpsOnly()
Jets3tProperties
.public int getInternalErrorRetryMax()
Jets3tProperties
.public Jets3tProperties getJetS3tProperties()
protected abstract XmlResponsesSaxParser getXmlResponseSaxParser() throws ServiceException
ServiceException
protected abstract StorageBucket newBucket()
StorageBucket
implementation.protected abstract StorageObject newObject()
StorageObject
implementation.protected void sleepOnInternalError(int internalErrorCount, ServiceException ex) throws ServiceException, java.lang.InterruptedException
storage-service.internal-error-retry-max
. If the maximum error count is
exceeded, this method will throw the provided ServiceException
.
The millisecond delay grows rapidly according to the formula
50 * (internalErrorCount ^ 2)
.
Error count | Delay in milliseconds |
---|---|
1 | 50 |
2 | 200 |
3 | 450 |
4 | 800 |
5 | 1250 |
internalErrorCount
- the number of Internal Server errors encountered by a request.ServiceException
- thrown if the number of internal errors exceeds the value of internalErrorCount.java.lang.InterruptedException
- thrown if the thread sleep is interrupted.public ProviderCredentials getProviderCredentials()
public void setProviderCredentials(ProviderCredentials credentials)
public java.lang.String getInvokingApplicationDescription()
protected void assertAuthenticatedConnection(java.lang.String action) throws ServiceException
ProviderCredentials
object representing a user account.action
- the action being attempted which this assertion is applied, for debugging purposes.ServiceException
protected void assertValidBucket(StorageBucket bucket, java.lang.String action) throws ServiceException
bucket
- action
- the action being attempted which this assertion is applied, for debugging purposes.ServiceException
protected void assertValidObject(StorageObject object, java.lang.String action) throws ServiceException
object
- action
- the action being attempted which this assertion is applied, for debugging purposes.ServiceException
protected void assertValidObject(java.lang.String key, java.lang.String action) throws ServiceException
key
- An object's key name.action
- the action being attempted which this assertion is applied, for debugging purposes.ServiceException
public StorageObject[] listObjects(java.lang.String bucketName) throws ServiceException
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.
bucketName
- the name of the bucket whose contents will be listed.ServiceException
public StorageObject[] listObjects(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter) throws ServiceException
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 virtual path
"subdirectories" to be included in the results from the service, use the
listObjectsChunked(String, String, String, long, String, boolean)
method instead of this one to obtain both object and path values.
bucketName
- the name of the bucket whose contents will be listed.prefix
- only objects with a key that starts with this prefix will be listeddelimiter
- 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.ServiceException
public StorageBucket createBucket(java.lang.String bucketName) throws ServiceException
getOrCreateBucket(String)
in situations where the bucket may already exist.
This method cannot be performed by anonymous services.bucketName
- the name of the bucket to create.ServiceException
public StorageBucket createBucket(StorageBucket bucket) throws ServiceException
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.
This method cannot be performed by anonymous services.
bucket
- the bucket to create, including optional ACL settings.ServiceException
public boolean isObjectInBucket(java.lang.String bucketName, java.lang.String objectKey) throws ServiceException
bucketName
- the name of the bucket containing the object.objectKey
- the key identifying the object.ServiceException
public StorageObject getObject(java.lang.String bucketName, java.lang.String objectKey) throws ServiceException
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.
bucketName
- the name of the bucket containing the object.objectKey
- the key identifying the object.ServiceException
public StorageObject getObjectDetails(java.lang.String bucketName, java.lang.String objectKey) throws ServiceException
This method can be performed by anonymous services. Anonymous services can get a publicly-readable object's details.
bucketName
- the name of the bucket containing the object.objectKey
- the key identifying the object.ServiceException
public StorageBucket[] listAllBuckets() throws ServiceException
This method cannot be performed by anonymous services, and will fail with an exception if the service is not authenticated.
ServiceException
public StorageOwner getAccountOwner() throws ServiceException
This method cannot be performed by anonymous services, and will fail with an exception if the service is not authenticated.
ServiceException
public StorageObject[] listObjects(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength) throws ServiceException
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 virtual path
"subdirectories" to be included in the results from the service, use the
listObjectsChunked(String, String, String, long, String, boolean)
method instead of this one to obtain both object and path values.
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 listeddelimiter
- 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. 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.ServiceException
public StorageObjectsChunk listObjectsChunked(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey) throws ServiceException
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.
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, may be null.delimiter
- only list objects with key names up to this delimiter, may be null.maxListingLength
- the maximum number of objects to include in each result chunkpriorLastKey
- 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.ServiceException
public StorageObjectsChunk listObjectsChunked(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey, boolean completeListing) throws ServiceException
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.
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, may be null.delimiter
- only objects with a key that starts with this prefix will be listed, may be null.maxListingLength
- the maximum number of objects to include in each result chunkpriorLastKey
- 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.ServiceException
public StorageBucket getBucket(java.lang.String bucketName) throws ServiceException
listAllBuckets()
), and looking for the named bucket in
this list.
This method cannot be performed by anonymous services.
bucketName
- ServiceException
public StorageBucket getOrCreateBucket(java.lang.String bucketName) throws ServiceException
bucketName
- the name of the bucket to retrieve or create.ServiceException
public void deleteBucket(StorageBucket bucket) throws ServiceException
This method cannot be performed by anonymous services.
bucket
- the bucket to delete.ServiceException
public void deleteBucket(java.lang.String bucketName) throws ServiceException
This method cannot be performed by anonymous services.
bucketName
- the name of the bucket to delete.ServiceException
public StorageObject putObject(java.lang.String bucketName, StorageObject object) throws ServiceException
This method can be performed by anonymous services. Anonymous services can put objects into a publicly-writable bucket.
bucketName
- the name of the bucket inside which the object will be put.object
- the object containing all information that will be written to the service.
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.
ServiceException
public java.util.Map<java.lang.String,java.lang.Object> copyObject(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, StorageObject destinationObject, boolean replaceMetadata, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags) throws ServiceException
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.
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.ServiceException
public java.util.Map<java.lang.String,java.lang.Object> copyObject(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, StorageObject destinationObject, boolean replaceMetadata) throws ServiceException
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.
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.ServiceException
public java.util.Map<java.lang.String,java.lang.Object> moveObject(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, StorageObject destinationObject, boolean replaceMetadata) throws ServiceException
copyObject(String, String, String, StorageObject, 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.
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.ServiceException
public java.util.Map<java.lang.String,java.lang.Object> renameObject(java.lang.String bucketName, java.lang.String sourceObjectKey, StorageObject destinationObject) throws ServiceException
moveObject(String, String, String, StorageObject, 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.
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.ServiceException
public java.util.Map<java.lang.String,java.lang.Object> updateObjectMetadata(java.lang.String bucketName, StorageObject object) throws ServiceException
copyObject(String, String, String, StorageObject, boolean)
method to
copy the original object over itself, applying the new metadata in the
process.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.ServiceException
public void deleteObject(java.lang.String bucketName, java.lang.String objectKey) throws ServiceException
This method can be performed by anonymous services. Anonymous services can delete objects from publicly-writable buckets.
bucketName
- the name of the bucket containing the object to be deleted.objectKey
- the key representing the objectServiceException
public StorageObject 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 ServiceException
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.
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.ServiceException
public StorageObject 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 ServiceException
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.StorageBucket, java.lang.String)
assertion.
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.ServiceException
public void putObjectAcl(java.lang.String bucketName, StorageObject object) throws ServiceException
bucketName
- the name of the bucket containing the object to modify.object
- the object with ACL settings that will be applied.ServiceException
public void putObjectAcl(java.lang.String bucketName, java.lang.String objectKey, AccessControlList acl) throws ServiceException
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.acl
- the ACL to apply.ServiceException
public AccessControlList getObjectAcl(java.lang.String bucketName, java.lang.String objectKey) throws ServiceException
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.ServiceException
public void putBucketAcl(java.lang.String bucketName, AccessControlList acl) throws ServiceException
bucketName
- a name of the bucket with ACL settings to apply.acl
- the ACL to apply.ServiceException
public void putBucketAcl(StorageBucket bucket) throws ServiceException
bucket
- a bucket with ACL settings to apply.ServiceException
public AccessControlList getBucketAcl(java.lang.String bucketName) throws ServiceException
bucketName
- the name of the bucket whose access control settings will be returned.ServiceException
public java.util.Date getCurrentTimeWithOffset()
RestUtils.calculateTimeAdjustmentOffset(org.apache.http.HttpResponse)
.RestUtils.calculateTimeAdjustmentOffset(org.apache.http.HttpResponse)
method has been invoked.public java.util.Map<java.lang.String,java.lang.Object> renameMetadataKeys(java.util.Map<java.lang.String,java.lang.Object> metadata)
RestUtils.HTTP_HEADER_METADATA_NAMES
metadata
- public abstract boolean isBucketAccessible(java.lang.String bucketName) throws ServiceException
Caution: 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.
bucketName
- the bucket to check.ServiceException
public abstract int checkBucketStatus(java.lang.String bucketName) throws ServiceException
Caveats:
BUCKET_STATUS__MY_BUCKET
.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, the service 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.
bucketName
- BUCKET_STATUS__MY_BUCKET
if you already own the bucket,
BUCKET_STATUS__DOES_NOT_EXIST
if the bucket does not yet exist, or
BUCKET_STATUS__ALREADY_CLAIMED
if someone else has
already created a bucket with the given name.ServiceException
protected StorageBucket[] listAllBucketsImpl() throws ServiceException
ServiceException
protected abstract StorageBucket[] listAllBucketsImpl(java.util.Map<java.lang.String,java.lang.Object> headers) throws ServiceException
headers
- Additional metadata to send with requestServiceException
protected abstract StorageOwner getAccountOwnerImpl() throws ServiceException
ServiceException
protected abstract StorageObject[] listObjectsImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength) throws ServiceException
The implementation of this method is expected to return all the objects
in a bucket, not a subset. This may require repeating the list operation if the
first one doesn't include all the available objects, such as when the number of objects
is greater than maxListingLength
.
bucketName
- prefix
- only objects with a key that starts with this prefix will be listed, may be null.delimiter
- only list objects with key names up to this delimiter, may be null.maxListingLength
- ServiceException
protected abstract StorageObjectsChunk listObjectsChunkedImpl(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter, long maxListingLength, java.lang.String priorLastKey, boolean completeListing) throws ServiceException
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.
bucketName
- prefix
- only objects with a key that starts with this prefix will be listed, may be null.delimiter
- only list objects with key names up to this delimiter, may be null.maxListingLength
- priorLastKey
- completeListing
- ServiceException
protected StorageBucket createBucketImpl(java.lang.String bucketName, java.lang.String location, AccessControlList acl) throws ServiceException
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.
bucketName
- the name of the bucket to create.location
- the geographical location where the bucket will be stored (if applicable for the target
service). A null string value will cause the bucket to be stored in the default location.acl
- an access control object representing the initial acl values for the bucket.
May be null, in which case the default permissions are applied.ServiceException
protected abstract StorageBucket createBucketImpl(java.lang.String bucketName, java.lang.String location, AccessControlList acl, java.util.Map<java.lang.String,java.lang.Object> headers) throws ServiceException
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.
bucketName
- the name of the bucket to create.location
- the geographical location where the bucket will be stored (if applicable for the target
service). A null string value will cause the bucket to be stored in the default location.acl
- an access control object representing the initial acl values for the bucket.
May be null, in which case the default permissions are applied.headers
- Additional metadata to add to requestServiceException
protected abstract void deleteBucketImpl(java.lang.String bucketName) throws ServiceException
ServiceException
protected abstract StorageObject putObjectImpl(java.lang.String bucketName, StorageObject object) throws ServiceException
ServiceException
protected abstract java.util.Map<java.lang.String,java.lang.Object> copyObjectImpl(java.lang.String sourceBucketName, java.lang.String sourceObjectKey, java.lang.String destinationBucketName, java.lang.String destinationObjectKey, AccessControlList acl, java.util.Map<java.lang.String,java.lang.Object> destinationMetadata, java.util.Calendar ifModifiedSince, java.util.Calendar ifUnmodifiedSince, java.lang.String[] ifMatchTags, java.lang.String[] ifNoneMatchTags, java.lang.String versionId, java.lang.String destinationObjectStorageClass, java.lang.String destinationObjectServerSideEncryptionAlgorithm) throws ServiceException
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.ServiceException
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 ServiceException
ServiceException
protected abstract StorageObject 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 ServiceException
ServiceException
protected abstract StorageObject 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 ServiceException
ServiceException
protected abstract void putBucketAclImpl(java.lang.String bucketName, AccessControlList acl) throws ServiceException
ServiceException
protected abstract void putObjectAclImpl(java.lang.String bucketName, java.lang.String objectKey, AccessControlList acl, java.lang.String versionId) throws ServiceException
ServiceException
protected abstract AccessControlList getObjectAclImpl(java.lang.String bucketName, java.lang.String objectKey, java.lang.String versionId) throws ServiceException
ServiceException
protected abstract AccessControlList getBucketAclImpl(java.lang.String bucketName) throws ServiceException
ServiceException
protected abstract void shutdownImpl() throws ServiceException
ServiceException
public abstract java.lang.String getEndpoint()
protected abstract java.lang.String getVirtualPath()
protected abstract java.lang.String getSignatureIdentifier()
public abstract java.lang.String getRestHeaderPrefix()
public abstract java.util.List<java.lang.String> getResourceParameterNames()
public abstract java.lang.String getRestMetadataPrefix()
protected abstract int getHttpPort()
protected abstract int getHttpsPort()
protected abstract boolean getHttpsOnly()
protected abstract boolean getDisableDnsBuckets()
protected abstract boolean getEnableStorageClasses()
protected abstract boolean getEnableServerSideEncryption()