Class RestStorageService
- All Implemented Interfaces:
AWSRequestAuthorizer
- Direct Known Subclasses:
GoogleStorageService
,S3Service
This class uses properties obtained through Jets3tProperties
. For more information on
these properties please refer to
JetS3t Configuration
- Author:
- James Murty, Google Developers
-
Field Summary
Fields inherited from class org.jets3t.service.StorageService
BUCKET_STATUS__ALREADY_CLAIMED, BUCKET_STATUS__DOES_NOT_EXIST, BUCKET_STATUS__MY_BUCKET
-
Constructor Summary
ConstructorsConstructorDescriptionRestStorageService
(ProviderCredentials credentials) Constructs the service and initialises the properties.RestStorageService
(ProviderCredentials credentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider) Constructs the service and initialises the properties.RestStorageService
(ProviderCredentials credentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties) Constructs the service and initialises the properties.RestStorageService
(ProviderCredentials credentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties, org.apache.commons.httpclient.HostConfiguration hostConfig) Constructs the service and initialises the properties. -
Method Summary
Modifier and TypeMethodDescriptionvoid
authorizeHttpRequest
(org.apache.commons.httpclient.HttpMethod httpMethod) Authorizes an HTTP request by signing it.int
checkBucketStatus
(String bucketName) Find out the status of a bucket with the given name.void
deleteObjectWithSignedUrl
(String signedDeleteUrl) Deletes an object using a pre-signed DELETE URL generated for that object.org.apache.commons.httpclient.auth.CredentialsProvider
org.apache.commons.httpclient.HttpClient
org.apache.commons.httpclient.HttpConnectionManager
getObjectAclWithSignedUrl
(String signedAclUrl) Gets an object's ACL details using a pre-signed GET URL generated for that object.getObjectDetailsWithSignedUrl
(String signedHeadUrl) Gets an object's details using a pre-signed HEAD URL generated for that object.getObjectWithSignedUrl
(String signedGetUrl) Gets an object using a pre-signed GET URL generated for that object.boolean
isBucketAccessible
(String bucketName) Indicates whether a bucket exists and is accessible to a service user.void
putObjectAclWithSignedUrl
(String signedAclUrl, AccessControlList acl) Sets an object's ACL details using a pre-signed PUT URL generated for that object.putObjectWithSignedUrl
(String signedPutUrl, S3Object object) Puts an object using a pre-signed PUT URL generated for that object.void
setCredentialsProvider
(org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider) Sets the credentials provider this service will use to authenticate itself.void
setHttpClient
(org.apache.commons.httpclient.HttpClient httpClient) Replaces the service's default HTTP client.void
setHttpConnectionManager
(org.apache.commons.httpclient.HttpConnectionManager httpConnectionManager) Replaces the service's default HTTP connection manager.Methods inherited from class org.jets3t.service.StorageService
copyObject, copyObject, createBucket, createBucket, deleteBucket, deleteBucket, deleteObject, getAccountOwner, getBucket, getBucketAcl, getCurrentTimeWithOffset, getEndpoint, getInternalErrorRetryMax, getInvokingApplicationDescription, getJetS3tProperties, getObject, getObject, getObjectAcl, getObjectDetails, getObjectDetails, getOrCreateBucket, getProviderCredentials, getResourceParameterNames, getRestHeaderPrefix, getRestMetadataPrefix, isAuthenticatedConnection, isHttpsOnly, isObjectInBucket, isShutdown, listAllBuckets, listObjects, listObjects, listObjects, listObjectsChunked, listObjectsChunked, moveObject, putBucketAcl, putBucketAcl, putObject, putObjectAcl, putObjectAcl, renameMetadataKeys, renameObject, shutdown, updateObjectMetadata
-
Constructor Details
-
RestStorageService
Constructs the service and initialises the properties.- Parameters:
credentials
- the user credentials to use when communicating with S3, may be null in which case the communication is done as an anonymous user.
-
RestStorageService
public RestStorageService(ProviderCredentials credentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider) Constructs the service and initialises the properties.- Parameters:
credentials
- 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
orMy App Name/1.0
credentialsProvider
- an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.
-
RestStorageService
public RestStorageService(ProviderCredentials credentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties) Constructs the service and initialises the properties.- Parameters:
credentials
- 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
orMy App Name/1.0
credentialsProvider
- an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.jets3tProperties
- JetS3t properties that will be applied within this service.
-
RestStorageService
public RestStorageService(ProviderCredentials credentials, String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties, org.apache.commons.httpclient.HostConfiguration hostConfig) Constructs the service and initialises the properties.- Parameters:
credentials
- 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
orMy App Name/1.0
credentialsProvider
- an implementation of the HttpClient CredentialsProvider interface, to provide a means for prompting for credentials when necessary.jets3tProperties
- JetS3t properties that will be applied within this service.hostConfig
- Custom HTTP host configuration; e.g to register a custom Protocol Socket Factory
-
-
Method Details
-
getHttpConnectionManager
public org.apache.commons.httpclient.HttpConnectionManager getHttpConnectionManager()- Returns:
- the manager of HTTP connections for this service.
-
setHttpConnectionManager
public void setHttpConnectionManager(org.apache.commons.httpclient.HttpConnectionManager httpConnectionManager) Replaces the service's default HTTP connection manager. This method should only be used by advanced users.- Parameters:
httpConnectionManager
- the connection manager that will replace the default manager created by the class constructor.
-
getHttpClient
public org.apache.commons.httpclient.HttpClient getHttpClient()- Returns:
- the HTTP client for this service.
-
setHttpClient
public void setHttpClient(org.apache.commons.httpclient.HttpClient httpClient) Replaces the service's default HTTP client. This method should only be used by advanced users.- Parameters:
httpClient
- the client that will replace the default client created by the class constructor.
-
getCredentialsProvider
public org.apache.commons.httpclient.auth.CredentialsProvider getCredentialsProvider()- Returns:
- the credentials provider this service will use to authenticate itself, or null if no provider is set.
-
setCredentialsProvider
public void setCredentialsProvider(org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider) Sets the credentials provider this service will use to authenticate itself. Changing the credentials provider with this method will have no effect until theinitHttpConnection(org.apache.commons.httpclient.HostConfiguration)
method is called.- Parameters:
credentialsProvider
-
-
authorizeHttpRequest
public void authorizeHttpRequest(org.apache.commons.httpclient.HttpMethod httpMethod) throws Exception Authorizes an HTTP request by signing it. The signature is based on the target URL, and the signed authorization string is added to theHttpMethod
object as an Authorization header.- Specified by:
authorizeHttpRequest
in interfaceAWSRequestAuthorizer
- Parameters:
httpMethod
- the request object- Throws:
ServiceException
Exception
-
isBucketAccessible
Description copied from class:StorageService
Indicates whether a bucket exists and is accessible to a service user.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
StorageService.getOrCreateBucket(String)
method instead.This method can be performed by anonymous services.
Implementation notes
This method can be implemented by attempting to list the objects in a bucket. If the listing is successful return true, if the listing failed for any reason return false.
- Specified by:
isBucketAccessible
in classStorageService
- Parameters:
bucketName
- the bucket to check.- Returns:
- true if the bucket exists and is accessible to the service user, false otherwise.
- Throws:
ServiceException
-
checkBucketStatus
Description copied from class:StorageService
Find out the status of a bucket with the given name.Caveats:
- If someone else owns the bucket but has made it public, this method will
mistakenly return
StorageService.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
StorageService.getOrCreateBucket(String)
method for this purpose instead.
- Specified by:
checkBucketStatus
in classStorageService
- Returns:
StorageService.BUCKET_STATUS__MY_BUCKET
if you already own the bucket,StorageService.BUCKET_STATUS__DOES_NOT_EXIST
if the bucket does not yet exist, orStorageService.BUCKET_STATUS__ALREADY_CLAIMED
if someone else has already created a bucket with the given name.- Throws:
ServiceException
- If someone else owns the bucket but has made it public, this method will
mistakenly return
-
putObjectWithSignedUrl
public S3Object putObjectWithSignedUrl(String signedPutUrl, S3Object object) throws ServiceException Puts an object using a pre-signed PUT URL generated for that object. This method is an implementation of the interfaceSignedUrlHandler
.This operation does not required any S3 functionality as it merely uploads the object by performing a standard HTTP PUT using the signed URL.
- Parameters:
signedPutUrl
- a signed PUT URL generated withS3Service.createSignedPutUrl(String, String, java.util.Map, org.jets3t.service.security.ProviderCredentials, java.util.Date)
.object
- the object to upload, which must correspond to the object for which the URL was signed. The object must have the correct content length set, and to apply a non-standard ACL policy only the REST canned ACLs can be used (egAccessControlList.REST_CANNED_PUBLIC_READ_WRITE
).- Returns:
- the S3Object put to S3. The S3Object returned will represent the object created in S3.
- Throws:
ServiceException
-
deleteObjectWithSignedUrl
Deletes an object using a pre-signed DELETE URL generated for that object. This method is an implementation of the interfaceSignedUrlHandler
.This operation does not required any S3 functionality as it merely deletes the object by performing a standard HTTP DELETE using the signed URL.
- Parameters:
signedDeleteUrl
- a signed DELETE URL generated withS3Service.createSignedDeleteUrl(java.lang.String, java.lang.String, java.util.Date, boolean)
.- Throws:
ServiceException
-
getObjectWithSignedUrl
Gets an object using a pre-signed GET URL generated for that object. This method is an implementation of the interfaceSignedUrlHandler
.This operation does not required any S3 functionality as it merely uploads the object by performing a standard HTTP GET using the signed URL.
- Parameters:
signedGetUrl
- a signed GET URL generated withS3Service.createSignedGetUrl(String, String, org.jets3t.service.security.ProviderCredentials, java.util.Date)
.- Returns:
- the S3Object in S3 including all metadata and the object's data input stream.
- Throws:
ServiceException
-
getObjectDetailsWithSignedUrl
Gets an object's details using a pre-signed HEAD URL generated for that object. This method is an implementation of the interfaceSignedUrlHandler
.This operation does not required any S3 functionality as it merely uploads the object by performing a standard HTTP HEAD using the signed URL.
- Parameters:
signedHeadUrl
- a signed HEAD URL generated withS3Service.createSignedHeadUrl(String, String, org.jets3t.service.security.ProviderCredentials, java.util.Date)
.- Returns:
- the S3Object in S3 including all metadata, but without the object's data input stream.
- Throws:
ServiceException
-
getObjectAclWithSignedUrl
Gets an object's ACL details using a pre-signed GET URL generated for that object. This method is an implementation of the interfaceSignedUrlHandler
.- Parameters:
signedAclUrl
- a signed URL generated withS3Service.createSignedUrl(String, String, String, String, java.util.Map, org.jets3t.service.security.ProviderCredentials, long, boolean)
.- Returns:
- the AccessControlList settings of the object in S3.
- Throws:
ServiceException
-
putObjectAclWithSignedUrl
public void putObjectAclWithSignedUrl(String signedAclUrl, AccessControlList acl) throws ServiceException Sets an object's ACL details using a pre-signed PUT URL generated for that object. This method is an implementation of the interfaceSignedUrlHandler
.- Parameters:
signedAclUrl
- a signed URL generated withS3Service.createSignedUrl(String, String, String, String, java.util.Map, org.jets3t.service.security.ProviderCredentials, long, boolean)
.acl
- the ACL settings to apply to the object represented by the signed URL.- Throws:
ServiceException
-