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

java.lang.Object
  extended by org.jets3t.service.StorageService
      extended by org.jets3t.service.impl.rest.httpclient.RestStorageService
          extended by org.jets3t.service.impl.rest.httpclient.GoogleStorageService
All Implemented Interfaces:
AWSRequestAuthorizer

public class GoogleStorageService
extends RestStorageService

REST/HTTP implementation of Google Storage Service based on the HttpClient library.

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


Nested Class Summary
 
Nested classes/interfaces inherited from class org.jets3t.service.impl.rest.httpclient.RestStorageService
RestStorageService.HTTP_METHOD
 
Field Summary
 
Fields inherited from class org.jets3t.service.impl.rest.httpclient.RestStorageService
connectionManager, credentialsProvider, defaultStorageClass, httpClient
 
Fields inherited from class org.jets3t.service.StorageService
BUCKET_STATUS__ALREADY_CLAIMED, BUCKET_STATUS__DOES_NOT_EXIST, BUCKET_STATUS__MY_BUCKET, credentials, jets3tProperties, timeOffset
 
Constructor Summary
GoogleStorageService(ProviderCredentials credentials)
          Constructs the service and initialises the properties.
GoogleStorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
          Constructs the service and initialises the properties.
GoogleStorageService(ProviderCredentials credentials, java.lang.String invokingApplicationDescription, org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider, Jets3tProperties jets3tProperties)
          Constructs the service and initialises the properties.
GoogleStorageService(ProviderCredentials credentials, java.lang.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
 GSBucket createBucket(java.lang.String bucketName)
          Creates a bucket.
 GSAccessControlList getBucketAcl(java.lang.String bucketName)
          Retrieves the access control settings of a bucket.
protected  boolean getDisableDnsBuckets()
           
protected  boolean getEnableStorageClasses()
           
 java.lang.String getEndpoint()
           
protected  int getHttpPort()
           
protected  boolean getHttpsOnly()
           
protected  int getHttpsPort()
           
 GSObject 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.
 GSObject 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.
 GSObject 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.
 java.util.List<java.lang.String> getResourceParameterNames()
           
 java.lang.String getRestHeaderPrefix()
           
 java.lang.String getRestMetadataPrefix()
           
protected  java.lang.String getSignatureIdentifier()
           
protected  java.lang.String getVirtualPath()
           
protected  boolean isTargettingGoogleStorageService()
           
 GSBucket[] listAllBuckets()
          Lists the buckets belonging to the service user.
 GSObject[] listObjects(java.lang.String bucketName)
          Lists the objects in a bucket.
 GSObject[] listObjects(java.lang.String bucketName, java.lang.String prefix, java.lang.String delimiter)
          Lists the objects in a bucket matching a prefix and delimiter.
 void putBucketAcl(GSBucket bucket)
          Applies access control settings to a bucket.
 void putBucketAcl(java.lang.String bucketName, GSAccessControlList acl)
          Applies access control settings to a bucket.
 GSObject putObject(java.lang.String bucketName, GSObject object)
           
 
Methods inherited from class org.jets3t.service.impl.rest.httpclient.RestStorageService
addMetadataToHeaders, addRequestHeadersToConnection, addRequestParametersToUrlPath, authorizeHttpRequest, checkBucketStatus, copyObjectImpl, createBucketImpl, createObjectImpl, deleteBucketImpl, deleteObjectImpl, deleteObjectWithSignedUrl, getAccountOwnerImpl, getBucketAclImpl, getCredentialsProvider, getHttpClient, getHttpConnectionManager, getObjectAclImpl, getObjectAclImpl, getObjectAclWithSignedUrl, getObjectDetailsImpl, getObjectDetailsWithSignedUrl, getObjectImpl, getObjectWithSignedUrl, initHttpConnection, isBucketAccessible, isXmlContentType, listAllBucketsImpl, listObjectsChunkedImpl, listObjectsImpl, listObjectsInternal, performRequest, performRestDelete, performRestGet, performRestHead, performRestPost, performRestPostWithXmlBuilder, performRestPut, performRestPutWithXmlBuilder, prepareCannedAcl, prepareStorageClass, putAclImpl, putBucketAclImpl, putObjectAclImpl, putObjectAclWithSignedUrl, putObjectImpl, putObjectWithRequestEntityImpl, putObjectWithSignedUrl, setCredentialsProvider, setHttpClient, setHttpConnectionManager, setupConnection, shutdownImpl, verifyExpectedAndActualETagValues
 
Methods inherited from class org.jets3t.service.StorageService
assertAuthenticatedConnection, assertValidBucket, assertValidObject, assertValidObject, copyObject, copyObject, createBucket, deleteBucket, deleteBucket, deleteObject, getAccountOwner, getBucket, getCurrentTimeWithOffset, getInternalErrorRetryMax, getInvokingApplicationDescription, getJetS3tProperties, getObjectAcl, getObjectDetails, getOrCreateBucket, getProviderCredentials, getXmlResponseSaxParser, isAuthenticatedConnection, isHttpsOnly, isObjectInBucket, isShutdown, listObjects, listObjectsChunked, listObjectsChunked, moveObject, newBucket, newObject, putBucketAcl, putBucketAcl, putObject, putObjectAcl, putObjectAcl, renameMetadataKeys, renameObject, shutdown, sleepOnInternalError, updateObjectMetadata
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials)
                     throws ServiceException
Constructs the service and initialises the properties.

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

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials,
                            java.lang.String invokingApplicationDescription,
                            org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider)
                     throws ServiceException
Constructs the service and initialises the properties.

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

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials,
                            java.lang.String invokingApplicationDescription,
                            org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                            Jets3tProperties jets3tProperties)
                     throws ServiceException
Constructs the service and initialises the properties.

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

GoogleStorageService

public GoogleStorageService(ProviderCredentials credentials,
                            java.lang.String invokingApplicationDescription,
                            org.apache.commons.httpclient.auth.CredentialsProvider credentialsProvider,
                            Jets3tProperties jets3tProperties,
                            org.apache.commons.httpclient.HostConfiguration hostConfig)
                     throws ServiceException
Constructs the service and initialises the properties.

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

isTargettingGoogleStorageService

protected boolean isTargettingGoogleStorageService()
Specified by:
isTargettingGoogleStorageService in class RestStorageService

getEndpoint

public java.lang.String getEndpoint()
Specified by:
getEndpoint in class StorageService
Returns:
the endpoint to be used to connect to Google Storage.

getVirtualPath

protected java.lang.String getVirtualPath()
Specified by:
getVirtualPath in class StorageService
Returns:
the virtual path inside the service.

getSignatureIdentifier

protected java.lang.String getSignatureIdentifier()
Specified by:
getSignatureIdentifier in class StorageService
Returns:
the identifier for the signature algorithm.

getRestHeaderPrefix

public java.lang.String getRestHeaderPrefix()
Specified by:
getRestHeaderPrefix in class StorageService
Returns:
header prefix for general Google Storage headers: x-goog-.

getRestMetadataPrefix

public java.lang.String getRestMetadataPrefix()
Specified by:
getRestMetadataPrefix in class StorageService
Returns:
header prefix for Google Storage metadata headers: x-goog-meta-.

getResourceParameterNames

public java.util.List<java.lang.String> getResourceParameterNames()
Specified by:
getResourceParameterNames in class StorageService
Returns:
GET parameter names that represent specific resources in the target service, as opposed to representing REST operation "plumbing". For example the "acl" parameter might be used to represent a resource's access control list settings.

getHttpPort

protected int getHttpPort()
Specified by:
getHttpPort in class StorageService
Returns:
the port number to be used for insecure connections over HTTP.

getHttpsPort

protected int getHttpsPort()
Specified by:
getHttpsPort in class StorageService
Returns:
the port number to be used for secure connections over HTTPS.

getHttpsOnly

protected boolean getHttpsOnly()
Specified by:
getHttpsOnly in class StorageService
Returns:
If true, all communication with GS will be via encrypted HTTPS connections, otherwise communications will be sent unencrypted via HTTP

getDisableDnsBuckets

protected boolean getDisableDnsBuckets()
Specified by:
getDisableDnsBuckets in class StorageService
Returns:
If true, JetS3t will specify bucket names in the request path of the HTTP message instead of the Host header.

getEnableStorageClasses

protected boolean getEnableStorageClasses()
Specified by:
getEnableStorageClasses in class StorageService
Returns:
If true, JetS3t will enable support for Storage Classes.

listAllBuckets

public GSBucket[] listAllBuckets()
                          throws ServiceException
Description copied from class: StorageService
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.

Overrides:
listAllBuckets in class StorageService
Returns:
the list of buckets owned by the service user.
Throws:
ServiceException

listObjects

public GSObject[] listObjects(java.lang.String bucketName)
                       throws ServiceException
Description copied from class: StorageService
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.

Overrides:
listObjects in class StorageService
Parameters:
bucketName - the name of the bucket whose contents will be listed.
Returns:
the set of objects contained in a bucket.
Throws:
ServiceException

listObjects

public GSObject[] listObjects(java.lang.String bucketName,
                              java.lang.String prefix,
                              java.lang.String delimiter)
                       throws ServiceException
Description copied from class: StorageService
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 virtual path "subdirectories" to be included in the results from the service, use the StorageService.listObjectsChunked(String, String, String, long, String, boolean) method instead of this one to obtain both object and path values.

Overrides:
listObjects in class StorageService
Parameters:
bucketName - the name of 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. 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:
ServiceException

createBucket

public GSBucket createBucket(java.lang.String bucketName)
                      throws ServiceException
Description copied from class: StorageService
Creates a bucket. 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 StorageService.getOrCreateBucket(String) in situations where the bucket may already exist. This method cannot be performed by anonymous services.

Overrides:
createBucket in class StorageService
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:
ServiceException

getBucketAcl

public GSAccessControlList getBucketAcl(java.lang.String bucketName)
                                 throws ServiceException
Description copied from class: StorageService
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 allows you to do so.

Overrides:
getBucketAcl in class StorageService
Parameters:
bucketName - the name of the bucket whose access control settings will be returned.
Returns:
the ACL settings of the bucket.
Throws:
ServiceException

putBucketAcl

public void putBucketAcl(java.lang.String bucketName,
                         GSAccessControlList acl)
                  throws ServiceException
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.

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

putBucketAcl

public void putBucketAcl(GSBucket bucket)
                  throws ServiceException
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.

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

getObject

public GSObject getObject(java.lang.String bucketName,
                          java.lang.String objectKey)
                   throws ServiceException
Description copied from class: StorageService
Returns an object representing the details and data of an item in a service, 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.

Overrides:
getObject in class StorageService
Parameters:
bucketName - the name of the bucket containing the object.
objectKey - the key identifying the object.
Returns:
the object with the given key, including the object's data input stream.
Throws:
ServiceException

putObject

public GSObject putObject(java.lang.String bucketName,
                          GSObject object)
                   throws ServiceException
Throws:
ServiceException

getObject

public GSObject 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
Description copied from class: StorageService
Returns an object representing the details and data of an item 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 StorageService.assertValidBucket(org.jets3t.service.model.StorageBucket, java.lang.String) assertion.

Overrides:
getObject in class StorageService
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, including only general details and metadata (not the data input stream)
Throws:
ServiceException

getObjectDetails

public GSObject getObjectDetails(java.lang.String bucketName,
                                 java.lang.String objectKey)
                          throws ServiceException
Description copied from class: StorageService
Returns an object representing the details of an item in 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.

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