Class StorageObject
- java.lang.Object
-
- org.jets3t.service.model.BaseStorageItem
-
- org.jets3t.service.model.StorageObject
-
- All Implemented Interfaces:
Cloneable
public class StorageObject extends BaseStorageItem implements Cloneable
A generic storage object.- Author:
- James Murty
-
-
Field Summary
Fields Modifier and Type Field Description static String
METADATA_HEADER_HASH_MD5
static String
METADATA_HEADER_ORIGINAL_HASH_MD5
-
Fields inherited from class org.jets3t.service.model.BaseStorageItem
METADATA_HEADER_CONTENT_DISPOSITION, METADATA_HEADER_CONTENT_ENCODING, METADATA_HEADER_CONTENT_LANGUAGE, METADATA_HEADER_CONTENT_LENGTH, METADATA_HEADER_CONTENT_MD5, METADATA_HEADER_CONTENT_TYPE, METADATA_HEADER_CREATION_DATE, METADATA_HEADER_DATE, METADATA_HEADER_ETAG, METADATA_HEADER_LAST_MODIFIED_DATE
-
-
Constructor Summary
Constructors Constructor Description StorageObject()
Create an object without any associated information whatsoever.StorageObject(File file)
Create an object representing a file.StorageObject(String key)
Create an object without any associated data.StorageObject(String key, byte[] data)
Create an object representing binary data.StorageObject(String key, String dataString)
Create an object representing text data.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addAllMetadata(Map<String,Object> 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<String,Object>
getModifiableMetadata()
Returns only those object metadata items that can be modified in a service.String
getStorageClass()
boolean
isDirectoryPlaceholder()
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 the service.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 the service.void
setMd5Hash(byte[] md5Hash)
Set the MD5 hash value of this object's data.void
setMetadataComplete(boolean isMetadataComplete)
Object metadata are only complete when it is populated with all values following a HEAD or GET request.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.BaseStorageItem
addMetadata, addMetadata, containsMetadata, getMetadata, getMetadataMap, getName, getOwner, removeMetadata, replaceAllMetadata, setName, setOwner
-
-
-
-
Field Detail
-
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
-
-
Constructor Detail
-
StorageObject
public StorageObject(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 (seeMimetypes
), and a content length matching the file's size. The file's MD5 hash value is also calculated and provided to the destination service, 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 fileNoSuchAlgorithmException
- when this JRE doesn't support the MD5 hash algorithm
-
StorageObject
public StorageObject(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 oftext/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 the target service, 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
-
StorageObject
public StorageObject(String key, byte[] data) throws NoSuchAlgorithmException, IOException
Create an object representing binary data. The object is initialized with the given key, the bytes as its data content, a content type ofapplication/octet-stream
, and a content length matching the byte array's length. The MD5 hash value of the byte data is also calculated and provided to the target service, so the service can verify that no data are corrupted in transit.- Parameters:
key
- the key name for the object.data
- the byte data the object will contain, cannot be null.- Throws:
IOException
NoSuchAlgorithmException
- when this JRE doesn't support the MD5 hash algorithm
-
StorageObject
public StorageObject(String key)
Create an object without any associated data.- Parameters:
key
- the key name for the object.
-
StorageObject
public StorageObject()
Create an object without any associated information whatsoever.
-
-
Method Detail
-
clone
public Object clone()
-
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.
-
getDataInputStream
public InputStream getDataInputStream() throws ServiceException
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 a service, you should consider verifying the integrity of the data you read from this stream using one of the
verifyData(InputStream)
methods.- Returns:
- input stream containing the object's service-side data, or null if no data.
- Throws:
ServiceException
-
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 the target service will not be able to recognize if data are corrupted in transit. To allow the target service 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 whengetDataInputStream()
is called.Note 2: This method does not calculate an MD5 hash of the input data, which means the target service will not be able to recognize if data are corrupted in transit. To allow the target service 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 the service 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 the service.
-
setETag
public void setETag(String etag)
Set the ETag value of the object based on information returned from the service. This method should only by used by code that reads service responses.- Parameters:
etag
- the ETag value as provided by the service.
-
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 anETag
ormd5-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 underContent-MD5
(Base64-encoded) and the JetS3t-specificmd5-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 the service. 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 the service. This method should only by used internally by code that reads the last modified date from a service response; it must not be set prior to uploading data to the service.- Parameters:
lastModifiedDate
-
-
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 a service. For objects that are uploaded, JetS3t automatically calculates the content length if the data is provided to the String- or File-based object constructor. If you manually provide data to this object via thesetDataInputStream(InputStream)
orsetDataInputFile(File)
methods, you must also set the content length value.- Parameters:
size
-
-
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 (seeMimetypes
). 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
-
-
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.
-
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.- Parameters:
acl
-
-
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
-
-
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 the service 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)
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 service 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 classBaseStorageItem
- Parameters:
name
-value
-
-
addAllMetadata
public void addAllMetadata(Map<String,Object> metadata)
Add all the metadata information to the object from the provided map.- Overrides:
addAllMetadata
in classBaseStorageItem
- Parameters:
metadata
-
-
getModifiableMetadata
public Map<String,Object> getModifiableMetadata()
Returns only those object metadata items that can be modified in a service. This list excludes those that are set by the the 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 users can control.
-
isDirectoryPlaceholder
public boolean isDirectoryPlaceholder()
-
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 object.- Returns:
- true if the calculated MD5 hash value of the input stream matches this object's hash value, false otherwise.
- Throws:
NoSuchAlgorithmException
FileNotFoundException
IOException
-
-