com.amazonaws.services.s3.model
Class GetObjectRequest

java.lang.Object
  com.amazonaws.AmazonWebServiceRequest
      com.amazonaws.services.s3.model.GetObjectRequest

public class GetObjectRequest
extends AmazonWebServiceRequest

Options for downloading an S3 object.

All GetObjectRequests must specify a bucket name and key. Beyond that, requests can also specify:

• The range of bytes within the object to download
• Constraints controlling if the object will be downloaded or not

Constructor Summary

GetObjectRequest(String bucketName, String key)
Constructs a new GetObjectRequest with all the required parameters.

GetObjectRequest(String bucketName, String key, String versionId)
Constructs a new GetObjectRequest with all the required parameters.

Method Summary

String	getBucketName() Returns the name of the bucket containing the object to be downloaded.
String	getKey() Returns the key under which the object to be downloaded is stored.
List<String>	getMatchingETagConstraints() Returns the optional list of ETag constraints that, when present, must include a match for the object's current ETag in order for this request to be executed.
Date	getModifiedSinceConstraint() Returns the optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.
List<String>	getNonmatchingETagConstraints() Returns the optional list of ETag constraints that, when present, must not include a match for the object's current ETag in order for this request to be executed.
long[]	getRange() Returns the optional byte range (inclusive) within the desired object that will be downloaded by this request.
Date	getUnmodifiedSinceConstraint() Returns the optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date.
String	getVersionId() Returns the optional version ID specifying which version of the object to download.
void	setBucketName(String bucketName) Sets the name of the bucket containing the object to be downloaded.
void	setKey(String key) Sets the key under which the object to be downloaded is stored.
void	setMatchingETagConstraints(List<String> eTagList) Sets the optional list of ETag constraints that, when present, must include a match for the object's current ETag in order for this request to be executed.
void	setModifiedSinceConstraint(Date date) Sets the optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.
void	setNonmatchingETagConstraints(List<String> eTagList) Sets the optional list of ETag constraints that, when present, must not include a match for the object's current ETag in order for this request to be executed.
void	setRange(long start, long end) Sets the optional byte range (inclusive) within the desired object that will be downloaded by this request.
void	setUnmodifiedSinceConstraint(Date date) Sets the optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date.
void	setVersionId(String versionId) Sets the optional version ID specifying which version of the object to download.
GetObjectRequest	withBucketName(String bucketName) Sets the name of the bucket containing the object to be downloaded, and returns this object so that additional method calls can be chained together.
GetObjectRequest	withKey(String key) Sets the key under which the object to be downloaded is stored, and returns this object so that additional method calls can be chained together.
GetObjectRequest	withMatchingETagConstraint(String eTag) Adds an single ETag constraint to this request, and returns this object so that additional method calls can be chained together.
GetObjectRequest	withModifiedSinceConstraint(Date date) Sets the optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.
GetObjectRequest	withNonmatchingETagConstraint(String eTag) Adds a single ETag constraint to this request, and returns this object so that additional method calls can be chained together.
GetObjectRequest	withRange(long start, long end) Sets the optional byte range (inclusive) within the desired object that will be downloaded by this request, and this returns this request object so that additional method calls can be chained together.
GetObjectRequest	withUnmodifiedSinceConstraint(Date date) Sets the optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date, and returns this object so that additional method calls can be chained together.
GetObjectRequest	withVersionId(String versionId) Sets the optional version ID specifying which version of the object to download, and returns this object so that additional method calls can be chained together.

Methods inherited from class com.amazonaws.AmazonWebServiceRequest

copyPrivateRequestParameters

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GetObjectRequest

public GetObjectRequest(String bucketName,
                        String key)

Constructs a new GetObjectRequest with all the required parameters.

Parameters:

bucketName - The name of the bucket containing the desired object.

key - The key in the specified bucket under which the object is stored.

GetObjectRequest

public GetObjectRequest(String bucketName,
                        String key,
                        String versionId)

Constructs a new GetObjectRequest with all the required parameters.

Parameters:

bucketName - The name of the bucket containing the desired object.

key - The key in the specified bucket under which the object is stored.

versionId - The Amazon S3 version ID specifying a specific version of the object to download.

Method Detail

getBucketName

public String getBucketName()

Returns the name of the bucket containing the object to be downloaded.

Returns:

The name of the bucket containing the object to be downloaded.

setBucketName

public void setBucketName(String bucketName)

Sets the name of the bucket containing the object to be downloaded.

Parameters:

bucketName - The name of the bucket containing the object to be downloaded.

withBucketName

public GetObjectRequest withBucketName(String bucketName)

Sets the name of the bucket containing the object to be downloaded, and returns this object so that additional method calls can be chained together.

Parameters:

bucketName - The name of the bucket containing the object to be downloaded.

Returns:

This updated GetObjectRequest, so that additional method calls can be chained together.

getKey

public String getKey()

Returns the key under which the object to be downloaded is stored.

Returns:

The key under which the object to be downloaded is stored.

setKey

public void setKey(String key)

Sets the key under which the object to be downloaded is stored.

Parameters:

key - The key under which the object to be downloaded is stored.

withKey

public GetObjectRequest withKey(String key)

Sets the key under which the object to be downloaded is stored, and returns this object so that additional method calls can be chained together.

Parameters:

key - The key under which the object to be downloaded is stored.

Returns:

This updated GetObjectRequest, so that additional method calls can be chained together.

getVersionId

public String getVersionId()

Returns the optional version ID specifying which version of the object to download. If not specified, the most recent version will be downloaded.

Objects created before versioning was enabled or when versioning is suspended will be given the default/null version ID (see Constants.NULL_VERSION_ID). Note that the Constants.NULL_VERSION_ID is a valid version ID and is not the same as not having a version ID.

See AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest) for more information about enabling versioning for a bucket.

Returns:

The optional version ID specifying which version of the object to download. If not specified, the most recent version will be downloaded.

setVersionId

public void setVersionId(String versionId)

Sets the optional version ID specifying which version of the object to download. If not specified, the most recent version will be downloaded.

Objects created before versioning was enabled or when versioning is suspended will be given the default/null version ID (see Constants.NULL_VERSION_ID). Note that the Constants.NULL_VERSION_ID is a valid version ID and is not the same as not having a version ID.

See AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest) for more information about enabling versioning for a bucket.

Parameters:

versionId - The optional version ID specifying which version of the object to download.

withVersionId

public GetObjectRequest withVersionId(String versionId)

Sets the optional version ID specifying which version of the object to download, and returns this object so that additional method calls can be chained together. If not specified, the most recent version will be downloaded.

Objects created before versioning was enabled or when versioning is suspended will be given the default/null version ID (see Constants.NULL_VERSION_ID). Note that the Constants.NULL_VERSION_ID is a valid version ID and is not the same as not having a version ID.

See AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest) for more information about enabling versioning for a bucket.

Parameters:

versionId - The optional version ID specifying which version of the object to download.

getRange

public long[] getRange()

Returns the optional byte range (inclusive) within the desired object that will be downloaded by this request. The range is returned as a two element array containing the start and end index of the byte range. If no byte range has been specified (and therefore, the entire object will be downloaded by this request), null is returned.

Returns:

A two element array indicating the start index and end index (inclusive) within the object being downloaded by this request, or null if no range has been specified, and the whole object is to be downloaded.

setRange

public void setRange(long start,
                     long end)

Sets the optional byte range (inclusive) within the desired object that will be downloaded by this request. The first byte in an object has position 0, so, for example, the first ten bytes of an object can be downloaded by specifying a range of 0 to 9.

If no byte range is specified, this request will download the entire object from S3.

Parameters:

start - The start of the byte range to download (inclusive).

end - The end of the byte range to download (inclusive).

withRange

public GetObjectRequest withRange(long start,
                                  long end)

Sets the optional byte range (inclusive) within the desired object that will be downloaded by this request, and this returns this request object so that additional method calls can be chained together. The first byte in an object has position 0, so, for example, the first ten bytes of an object can be downloaded by specifying a range of 0 to 9.

If no byte range is specified, this request will download the entire object from S3.

Parameters:

start - The start of the byte range to download (inclusive).

end - The end of the byte range to download (inclusive).

Returns:

This updated object, after setting the byte range for this request, so that additional method calls can be chained together.

getMatchingETagConstraints

public List<String> getMatchingETagConstraints()

Returns the optional list of ETag constraints that, when present, must include a match for the object's current ETag in order for this request to be executed. Only one ETag in the list needs to match for this request to be executed by Amazon S3.

Returns:

The optional list of ETag constraints that, when present, must include a match for the object's current ETag in order for this request to be executed.

setMatchingETagConstraints

public void setMatchingETagConstraints(List<String> eTagList)

Sets the optional list of ETag constraints that, when present, must include a match for the object's current ETag in order for this request to be executed. If none of the specified ETags match the object's current ETag, the this request will not be executed. Only one ETag in the list needs to match for the request to be executed by Amazon S3.

Parameters:

eTagList - The optional list of ETag constraints that must include a match for the object's current ETag in order for this request to be executed.

withMatchingETagConstraint

public GetObjectRequest withMatchingETagConstraint(String eTag)

Adds an single ETag constraint to this request, and returns this object so that additional method calls can be chained together. Multiple ETag constraints can be added to a request, but one must match the object's current ETag in order for this request to be executed. If none of the ETag constraints added to this request match the object's current ETag, this request will not be executed by Amazon S3.

Parameters:

eTag - The matching ETag constraint to add to this request.

Returns:

This GetObjectRequest, so that additional method calls can be chained together.

getNonmatchingETagConstraints

public List<String> getNonmatchingETagConstraints()

Returns the optional list of ETag constraints that, when present, must not include a match for the object's current ETag in order for this request to be executed. If any entry in the non-matching ETag constraint list matches the object's current ETag, this request will not be executed by Amazon S3.

Returns:

The optional list of ETag constraints that, when present, must not include a match for the object's current ETag in order for this request to be executed.

setNonmatchingETagConstraints

public void setNonmatchingETagConstraints(List<String> eTagList)

Sets the optional list of ETag constraints that, when present, must not include a match for the object's current ETag in order for this request to be executed. If any entry in the non-matching ETag constraint list matches the object's current ETag, this request will not be executed by Amazon S3.

Parameters:

eTagList - The list of ETag constraints that, when present, must not include a match for the object's current ETag in order for this request to be executed.

withNonmatchingETagConstraint

public GetObjectRequest withNonmatchingETagConstraint(String eTag)

Adds a single ETag constraint to this request, and returns this object so that additional method calls can be chained together. Multiple ETag constraints can be added to a request, but all ETag constraints must not match the object's current ETag in order for this request to be executed. If any entry in the non-matching ETag constraint list matches the object's current ETag, this request will not be executed by Amazon S3.

Parameters:

eTag - The non-matching ETag constraint to add to this request.

Returns:

This GetObjectRequest, so that additional method calls can be chained together.

getUnmodifiedSinceConstraint

public Date getUnmodifiedSinceConstraint()

Returns the optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date.

Returns:

The optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date.

setUnmodifiedSinceConstraint

public void setUnmodifiedSinceConstraint(Date date)

Sets the optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date.

Note that Amazon S3 will ignore any dates occurring in the future.

Parameters:

date - The unmodified since constraint that restricts this request to executing only if the object has not been modified since this date.

withUnmodifiedSinceConstraint

public GetObjectRequest withUnmodifiedSinceConstraint(Date date)

Sets the optional unmodified since constraint that restricts this request to executing only if the object has not been modified since the specified date, and returns this object so that additional method calls can be chained together.

Note that Amazon S3 will ignore any dates occurring in the future.

Parameters:

date - The unmodified since constraint that restricts this request to executing only if the object has not been modified since this date.

Returns:

This GetObjectRequest, so that additional method calls can be chained together.

getModifiedSinceConstraint

public Date getModifiedSinceConstraint()

Returns the optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.

Returns:

The optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.

setModifiedSinceConstraint

public void setModifiedSinceConstraint(Date date)

Sets the optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.

Note that Amazon S3 will ignore any dates occurring in the future.

Parameters:

date - The modified since constraint that restricts this request to executing only if the object has been modified since the specified date.

withModifiedSinceConstraint

public GetObjectRequest withModifiedSinceConstraint(Date date)

Sets the optional modified since constraint that restricts this request to executing only if the object has been modified since the specified date.

Note that Amazon S3 will ignore any dates occurring in the future.

Parameters:

date - The modified since constraint that restricts this request to executing only if the object has been modified since the specified date.

Returns:

This GetObjectRequest, so that additional method calls can be chained together.