org.jets3t.service.model
Class S3Object

java.lang.Object
  extended by org.jets3t.service.model.BaseS3Object
      extended by org.jets3t.service.model.S3Object
All Implemented Interfaces:
Serializable, Cloneable

public class S3Object
extends BaseS3Object
implements Cloneable

An S3 object.

Author:
James Murty
See Also:
Serialized Form

Field Summary
static String METADATA_HEADER_CONTENT_DISPOSITION
           
static String METADATA_HEADER_CONTENT_ENCODING
           
static String METADATA_HEADER_CONTENT_LANGUAGE
           
static String METADATA_HEADER_CONTENT_LENGTH
           
static String METADATA_HEADER_CONTENT_MD5
           
static String METADATA_HEADER_CONTENT_TYPE
           
static String METADATA_HEADER_DATE
           
static String METADATA_HEADER_ETAG
           
static String METADATA_HEADER_HASH_MD5
           
static String METADATA_HEADER_LAST_MODIFIED_DATE
           
static String METADATA_HEADER_ORIGINAL_HASH_MD5
           
static String METADATA_HEADER_OWNER
           
static String STORAGE_CLASS_REDUCED_REDUNDANCY
           
static String STORAGE_CLASS_STANDARD
           
 
Constructor Summary
S3Object()
          Create an object without any associated information whatsoever.
S3Object(File file)
          Create an object representing a file.
S3Object(S3Bucket bucket, File file)
          Create an object representing a file.
S3Object(S3Bucket bucket, String key)
          Create an object without any associated data.
S3Object(S3Bucket bucket, String key, String dataString)
          Create an object representing text data.
S3Object(String key)
          Create an object without any associated data, and no associated bucket.
S3Object(String key, String dataString)
          Create an object representing text data.
 
Method Summary
 void addAllMetadata(Map metadata)
          Add all the metadata information to the object from the provided map.
 void addMetadata(String name, String value)
          Add metadata information to the object.
 Object clone()
           
 void closeDataInputStream()
          Closes the object's data input stream if it exists.
 AccessControlList getAcl()
           
 String getBucketName()
           
 String getContentDisposition()
           
 String getContentEncoding()
           
 String getContentLanguage()
           
 long getContentLength()
           
 String getContentType()
           
 File getDataInputFile()
           
 InputStream getDataInputStream()
          Returns an input stream containing this object's data, or null if there is no data associated with the object.
 String getETag()
           
 String getKey()
           
 Date getLastModifiedDate()
           
 String getMd5HashAsBase64()
           
 String getMd5HashAsHex()
           
 Map getModifiableMetadata()
          Returns only those object metadata items that can be modified in S3.
 S3Owner getOwner()
           
 String getStorageClass()
           
 String getVersionId()
           
 boolean isMetadataComplete()
           
 void setAcl(AccessControlList acl)
          Set the object's ACL.
 void setBucketName(String bucketName)
          Set the name of the bucket this object belongs to or will be placed into.
 void setContentDisposition(String contentDisposition)
          Set the content disposition of the object.
 void setContentEncoding(String contentEncoding)
          Set the content encoding of this object.
 void setContentLanguage(String contentLanguage)
          Set the content language of the object.
 void setContentLength(long size)
          Set this object's content length.
 void setContentType(String contentType)
          Set the content type of the object.
 void setDataInputFile(File dataInputFile)
          Sets the file containing the data content to associate with this object.
 void setDataInputStream(InputStream dataInputStream)
          Sets an input stream containing the data content to associate with this object.
 void setETag(String etag)
          Set the ETag value of the object based on information returned from S3.
 void setKey(String key)
          Set the key of this object.
 void setLastModifiedDate(Date lastModifiedDate)
          Set this object's last modified date based on information returned from S3.
 void setMd5Hash(byte[] md5Hash)
          Set the MD5 hash value of this object's data.
 void setMetadataComplete(boolean isMetadataComplete)
          S3 Object metadata are only complete when it is populated with all values following a HEAD or GET request.
 void setOwner(S3Owner owner)
          Set this object's owner object based on information returned from S3.
 void setStorageClass(String storageClass)
          Set the storage class for this object.
 String toString()
           
 boolean verifyData(byte[] downloadedData)
          Calculates the MD5 hash value of the given data object, and compares it against this object's hash (as stored in the Content-MD5 header for uploads, or the ETag header for downloads).
 boolean verifyData(File downloadedFile)
          Calculates the MD5 hash value of the given data object, and compares it against this object's hash (as stored in the Content-MD5 header for uploads, or the ETag header for downloads).
 boolean verifyData(InputStream downloadedDataStream)
          Calculates the MD5 hash value of the given data object, and compares it against this object's hash (as stored in the Content-MD5 header for uploads, or the ETag header for downloads).
 
Methods inherited from class org.jets3t.service.model.BaseS3Object
addMetadata, addMetadata, containsMetadata, getMetadata, getMetadataMap, removeMetadata, replaceAllMetadata
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

METADATA_HEADER_LAST_MODIFIED_DATE

public static final String METADATA_HEADER_LAST_MODIFIED_DATE
See Also:
Constant Field Values

METADATA_HEADER_DATE

public static final String METADATA_HEADER_DATE
See Also:
Constant Field Values

METADATA_HEADER_OWNER

public static final String METADATA_HEADER_OWNER
See Also:
Constant Field Values

METADATA_HEADER_ETAG

public static final String METADATA_HEADER_ETAG
See Also:
Constant Field Values

METADATA_HEADER_HASH_MD5

public static final String METADATA_HEADER_HASH_MD5
See Also:
Constant Field Values

METADATA_HEADER_ORIGINAL_HASH_MD5

public static final String METADATA_HEADER_ORIGINAL_HASH_MD5
See Also:
Constant Field Values

METADATA_HEADER_CONTENT_MD5

public static final String METADATA_HEADER_CONTENT_MD5
See Also:
Constant Field Values

METADATA_HEADER_CONTENT_LENGTH

public static final String METADATA_HEADER_CONTENT_LENGTH
See Also:
Constant Field Values

METADATA_HEADER_CONTENT_TYPE

public static final String METADATA_HEADER_CONTENT_TYPE
See Also:
Constant Field Values

METADATA_HEADER_CONTENT_ENCODING

public static final String METADATA_HEADER_CONTENT_ENCODING
See Also:
Constant Field Values

METADATA_HEADER_CONTENT_DISPOSITION

public static final String METADATA_HEADER_CONTENT_DISPOSITION
See Also:
Constant Field Values

METADATA_HEADER_CONTENT_LANGUAGE

public static final String METADATA_HEADER_CONTENT_LANGUAGE
See Also:
Constant Field Values

STORAGE_CLASS_STANDARD

public static final String STORAGE_CLASS_STANDARD
See Also:
Constant Field Values

STORAGE_CLASS_REDUCED_REDUNDANCY

public static final String STORAGE_CLASS_REDUCED_REDUNDANCY
See Also:
Constant Field Values
Constructor Detail

S3Object

public S3Object(S3Bucket bucket,
                File file)
         throws NoSuchAlgorithmException,
                IOException
Create an object representing a file. The object is initialised with the file's name as its key, the file's content as its data, a content type based on the file's extension (see Mimetypes), and a content length matching the file's size. The file's MD5 hash value is also calculated and provided to S3, so the service can verify that no data are corrupted in transit.

NOTE: The automatic calculation of a file's MD5 hash digest as performed by this constructor could take some time for large files, or for many small ones.

Parameters:
bucket - the bucket the object belongs to, or will be placed in.
file - the file the object will represent. This file must exist and be readable.
Throws:
IOException - when an i/o error occurred reading the file
NoSuchAlgorithmException - when this JRE doesn't support the MD5 hash algorithm

S3Object

public S3Object(File file)
         throws NoSuchAlgorithmException,
                IOException
Create an object representing a file. The object is initialised with the file's name as its key, the file's content as its data, a content type based on the file's extension (see Mimetypes), and a content length matching the file's size. The file's MD5 hash value is also calculated and provided to S3, so the service can verify that no data are corrupted in transit.

NOTE: The automatic calculation of a file's MD5 hash digest as performed by this constructor could take some time for large files, or for many small ones.

Parameters:
file - the file the object will represent. This file must exist and be readable.
Throws:
IOException - when an i/o error occurred reading the file
NoSuchAlgorithmException - when this JRE doesn't support the MD5 hash algorithm

S3Object

public S3Object(S3Bucket bucket,
                String key,
                String dataString)
         throws NoSuchAlgorithmException,
                IOException
Create an object representing text data. The object is initialized with the given key, the given string as its data content (encoded as UTF-8), a content type of text/plain; charset=utf-8, and a content length matching the string's length. The given string's MD5 hash value is also calculated and provided to S3, so the service can verify that no data are corrupted in transit.

NOTE: The automatic calculation of the MD5 hash digest as performed by this constructor could take some time for large strings, or for many small ones.

Parameters:
bucket - the bucket the object belongs to, or will be placed in.
key - the key name for the object.
dataString - the text data the object will contain. Text data will be encoded as UTF-8. This string cannot be null.
Throws:
IOException
NoSuchAlgorithmException - when this JRE doesn't support the MD5 hash algorithm

S3Object

public S3Object(String key,
                String dataString)
         throws NoSuchAlgorithmException,
                IOException
Create an object representing text data. The object is initialized with the given key, the given string as its data content (encoded as UTF-8), a content type of text/plain; charset=utf-8, and a content length matching the string's length. The given string's MD5 hash value is also calculated and provided to S3, so the service can verify that no data are corrupted in transit.

NOTE: The automatic calculation of the MD5 hash digest as performed by this constructor could take some time for large strings, or for many small ones.

Parameters:
key - the key name for the object.
dataString - the text data the object will contain. Text data will be encoded as UTF-8. This string cannot be null.
Throws:
IOException
NoSuchAlgorithmException - when this JRE doesn't support the MD5 hash algorithm

S3Object

public S3Object(String key)
Create an object without any associated data, and no associated bucket.

Parameters:
key - the key name for the object.

S3Object

public S3Object(S3Bucket bucket,
                String key)
Create an object without any associated data.

Parameters:
bucket - the bucket the object belongs to, or will be placed in.
key - the key name for the object.

S3Object

public S3Object()
Create an object without any associated information whatsoever.

Method Detail

toString

public String toString()
Overrides:
toString in class Object

getDataInputStream

public InputStream getDataInputStream()
                               throws S3ServiceException
Returns an input stream containing this object's data, or null if there is no data associated with the object.

If you are downloading data from S3, you should consider verifying the integrity of the data you read from this stream using one of the verifyData(InputStream) methods.

Throws:
S3ServiceException

setDataInputStream

public void setDataInputStream(InputStream dataInputStream)
Sets an input stream containing the data content to associate with this object.

Note: If the data content comes from a file, use the alternate method setDataInputFile(File) which allows objects to lazily open files and avoid any Operating System limits on the number of files that may be opened simultaneously.

Note 2: This method does not calculate an MD5 hash of the input data, which means S3 will not be able to recognize if data are corrupted in transit. To allow S3 to verify data you upload, you should set the MD5 hash value of your data using setMd5Hash(byte[]).

This method will set the object's file data reference to null.

Parameters:
dataInputStream - an input stream containing the object's data.

setDataInputFile

public void setDataInputFile(File dataInputFile)
Sets the file containing the data content to associate with this object. This file will be automatically opened as an input stream only when absolutely necessary, that is when getDataInputStream() is called.

Note 2: This method does not calculate an MD5 hash of the input data, which means S3 will not be able to recognize if data are corrupted in transit. To allow S3 to verify data you upload, you should set the MD5 hash value of your data using setMd5Hash(byte[]).

This method will set the object's input stream data reference to null.

Parameters:
dataInputFile - a file containing the object's data.

getDataInputFile

public File getDataInputFile()
Returns:
Return the file that contains this object's data, if such a file has been provided. Null otherwise.

closeDataInputStream

public void closeDataInputStream()
                          throws IOException
Closes the object's data input stream if it exists.

Throws:
IOException

getETag

public String getETag()
Returns:
the ETag value of the object as returned by S3 when an object is created. The ETag value does not include quote (") characters. This value will be null if the object's ETag value is not known, such as when an object has not yet been uploaded to S3.

setETag

public void setETag(String etag)
Set the ETag value of the object based on information returned from S3. This method should only by used by code that reads S3 responses.

Parameters:
etag - the ETag value as provided by S3.

getMd5HashAsHex

public String getMd5HashAsHex()
Returns:
the hex-encoded MD5 hash of an object's data contents as stored in the jets3t-specific metadata item md5-hash, or null if the hash value is not available.

getMd5HashAsBase64

public String getMd5HashAsBase64()
Returns:
the Base64-encoded MD5 hash of an object's data contents as stored in the metadata item Content-MD5, or as derived from an ETag or md5-hash hex-encoded version of the hash. Returns null if the hash value is not available.

setMd5Hash

public void setMd5Hash(byte[] md5Hash)
Set the MD5 hash value of this object's data. The hash value is stored as metadata under Content-MD5 (Base64-encoded) and the jets3t-specific md5-hash (Hex-encoded).

Parameters:
md5Hash - the MD5 hash value of the object's data.

getLastModifiedDate

public Date getLastModifiedDate()
Returns:
the last modified date of this object, as provided by S3. If the last modified date is not available (e.g. if the object has only just been created) the object's creation date is returned instead. If both last modified and creation dates are unavailable, null is returned.

setLastModifiedDate

public void setLastModifiedDate(Date lastModifiedDate)
Set this object's last modified date based on information returned from S3. This method should only by used internally by code that reads the last modified date from an S3 response; it must not be set prior to uploading data to S3.

Parameters:
lastModifiedDate -

getOwner

public S3Owner getOwner()
Returns:
this object's owner, or null if the owner is not available.

setOwner

public void setOwner(S3Owner owner)
Set this object's owner object based on information returned from S3. This method should only by used by code that reads S3 responses.

Parameters:
owner -

getContentLength

public long getContentLength()
Returns:
the content length, or size, of this object's data, or 0 if it is unknown.

setContentLength

public void setContentLength(long size)
Set this object's content length. The content length is set internally by JetS3t for objects that are retrieved from S3. For objects that are uploaded into S3, JetS3t automatically calculates the content length if the data is provided to the String- or File-based S3Object constructor. If you manually provide data to this object via the setDataInputStream(InputStream) or setDataInputFile(File) methods, you must also set the content length value.

Parameters:
size -

getStorageClass

public String getStorageClass()
Returns:
the storage class of the object.

setStorageClass

public void setStorageClass(String storageClass)
Set the storage class for this object.

Parameters:
storageClass -

getContentType

public String getContentType()
Returns:
the content type of the object

setContentType

public void setContentType(String contentType)
Set the content type of the object. JetS3t can help you determine the content type when the associated data is a File (see Mimetypes). You should set the content type for associated String or InputStream data.

Parameters:
contentType -

getContentLanguage

public String getContentLanguage()
Returns:
the content language of this object, or null if it is unknown.

setContentLanguage

public void setContentLanguage(String contentLanguage)
Set the content language of the object.

Parameters:
contentLanguage -

getContentDisposition

public String getContentDisposition()
Returns:
the content disposition of this object, or null if it is unknown.

setContentDisposition

public void setContentDisposition(String contentDisposition)
Set the content disposition of the object.

Parameters:
contentDisposition -

getContentEncoding

public String getContentEncoding()
Returns:
the content encoding of this object, or null if it is unknown.

setContentEncoding

public void setContentEncoding(String contentEncoding)
Set the content encoding of this object.

Parameters:
contentEncoding -

getBucketName

public String getBucketName()
Returns:
the name of the bucket this object belongs to or will be placed into, or null if none is set.

setBucketName

public void setBucketName(String bucketName)
Set the name of the bucket this object belongs to or will be placed into.

Parameters:
bucketName - the name for the bucket.

getAcl

public AccessControlList getAcl()
Returns:
the object's ACL, or null if it is unknown.

setAcl

public void setAcl(AccessControlList acl)
Set the object's ACL. If a pre-canned REST ACL is used, the plain-text representation of the canned ACL is also added as a metadata header x-amz-acl.

Parameters:
acl -

getKey

public String getKey()
Returns:
the key of this object.

setKey

public void setKey(String key)
Set the key of this object.

Parameters:
key - the key for this object.

isMetadataComplete

public boolean isMetadataComplete()
Returns:
true if the object's metadata are considered complete, such as when the object's metadata has been retrieved from S3 by a HEAD request. If this value is not true, the metadata information in this object should not be considered authoritative.

setMetadataComplete

public void setMetadataComplete(boolean isMetadataComplete)
S3 Object metadata are only complete when it is populated with all values following a HEAD or GET request. This method should only by used by code that reads S3 responses.

Parameters:
isMetadataComplete -

addMetadata

public void addMetadata(String name,
                        String value)
Add metadata information to the object. If date metadata items (as recognized by name) are added and the value is not a date the value is parsed as an RFC 822 or ISO 8601 string.

Overrides:
addMetadata in class BaseS3Object
Parameters:
name -
value -

addAllMetadata

public void addAllMetadata(Map metadata)
Add all the metadata information to the object from the provided map.

Overrides:
addAllMetadata in class BaseS3Object
Parameters:
metadata -

getModifiableMetadata

public Map getModifiableMetadata()
Returns only those object metadata items that can be modified in S3. This list excludes those that are set by the S3 service, and those that are specific to a particular HTTP request/response session (such as request identifiers).

Returns:
the limited set of metadata items that S3 allows users to control.

getVersionId

public String getVersionId()

clone

public Object clone()
Overrides:
clone in class Object

verifyData

public boolean verifyData(File downloadedFile)
                   throws NoSuchAlgorithmException,
                          FileNotFoundException,
                          IOException
Calculates the MD5 hash value of the given data object, and compares it against this object's hash (as stored in the Content-MD5 header for uploads, or the ETag header for downloads).

Parameters:
downloadedFile -
Returns:
true if the calculated MD5 hash value of the file matches this object's hash value, false otherwise.
Throws:
NoSuchAlgorithmException
FileNotFoundException
IOException

verifyData

public boolean verifyData(byte[] downloadedData)
                   throws NoSuchAlgorithmException,
                          FileNotFoundException,
                          IOException
Calculates the MD5 hash value of the given data object, and compares it against this object's hash (as stored in the Content-MD5 header for uploads, or the ETag header for downloads).

Parameters:
downloadedData -
Returns:
true if the calculated MD5 hash value of the bytes matches this object's hash value, false otherwise.
Throws:
NoSuchAlgorithmException
FileNotFoundException
IOException

verifyData

public boolean verifyData(InputStream downloadedDataStream)
                   throws NoSuchAlgorithmException,
                          FileNotFoundException,
                          IOException
Calculates the MD5 hash value of the given data object, and compares it against this object's hash (as stored in the Content-MD5 header for uploads, or the ETag header for downloads).

Parameters:
downloadedDataStream - the input stream of a downloaded S3Object.
Returns:
true if the calculated MD5 hash value of the input stream matches this object's hash value, false otherwise.
Throws:
NoSuchAlgorithmException
FileNotFoundException
IOException