Class ListVersionsRequest
- All Implemented Interfaces:
ReadLimitInfo
,Serializable
,Cloneable
Returned version summaries are ordered first by key and then by version. Keys are sorted lexicographically (i.e. alphabetically from a-Z) and versions are sorted from the most recent to the least recent. Versions with data and versions with delete markers are included in the results.
Buckets can contain a virtually unlimited number of keys, and the complete
results of a list query can be extremely large. To manage large result sets,
Amazon S3 uses pagination to split them into multiple responses.
Always check the ObjectListing.isTruncated()
method to see
if the returned listing is complete, or if callers need to make additional
calls to get more results. Alternatively, use the
AmazonS3Client.listNextBatchOfVersions(VersionListing)
method as an
easy way to get the next page of object listings.
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
null
version ID is a valid version ID and is not the same
as not having a version ID.
Calling setDelimiter(String)
sets the delimiter, allowing groups of keys that share the
delimiter-terminated prefix to be included
in the returned listing. This allows applications to organize and browse
their keys hierarchically, similar to how a file system organizes files
into directories. These common prefixes can be retrieved
through the VersionListing.getCommonPrefixes()
method.
For example, consider a bucket that contains the following keys:
- "foo/bar/baz"
- "foo/bar/bash"
- "foo/bar/bang"
- "foo/boo"
listVersions
with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, an VersionListing
is returned that contains one key
("foo/boo") and one entry in the common prefixes list ("foo/bar/").
To see deeper into the virtual hierarchy, make another
call to listVersions
setting the prefix parameter to any interesting
common prefix to list the individual keys under that prefix.
The total number of keys in a bucket doesn't substantially affect list performance, nor does the presence or absence of additional request parameters.
For more information about enabling versioning for a bucket, see
AmazonS3.setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)
.
- See Also:
-
Field Summary
Fields inherited from class com.amazonaws.AmazonWebServiceRequest
NOOP
-
Constructor Summary
ConstructorsConstructorDescriptionConstructs a newListVersionsRequest
object.ListVersionsRequest
(String bucketName, String prefix, String keyMarker, String versionIdMarker, String delimiter, Integer maxResults) Constructs a newListVersionsRequest
object and initializes all required and optional fields. -
Method Summary
Modifier and TypeMethodDescriptionGets the name of the Amazon S3 bucket whose versions are to be listed.Gets the optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list.Gets the optionalencodingType
parameter indicating the encoding method to be applied on the response.Gets the optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.Gets the optionalmaxResults
parameter indicating the maximum number of results to include in the response.Gets the optional prefix parameter restricting the response to keys that begin with the specified prefix.Gets the optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.void
setBucketName
(String bucketName) Sets the name of the Amazon S3 bucket whose versions are to be listed.void
setDelimiter
(String delimiter) Sets the optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list.void
setEncodingType
(String encodingType) Sets the optionalencodingType
parameter indicating the encoding method to be applied on the response.void
setKeyMarker
(String keyMarker) Sets the optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.void
setMaxResults
(Integer maxResults) Sets the optionalmaxResults
parameter indicating the maximum number of results to include in the response.void
Sets the optional prefix parameter restricting the response to keys that begin with the specified prefix.void
setVersionIdMarker
(String versionIdMarker) Sets the optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.withBucketName
(String bucketName) Sets the name of the Amazon S3 bucket whose versions are to be listed.withDelimiter
(String delimiter) Sets the optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list.withEncodingType
(String encodingType) Sets the optionalencodingType
parameter indicating the encoding method to be applied on the response.withKeyMarker
(String keyMarker) Sets the optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.withMaxResults
(Integer maxResults) Sets the optionalmaxResults
parameter indicating the maximum number of results to include in the response.withPrefix
(String prefix) Sets the optional prefix parameter restricting the response to keys that begin with the specified prefix.withVersionIdMarker
(String versionIdMarker) Sets the optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.Methods inherited from class com.amazonaws.AmazonWebServiceRequest
clone, copyBaseTo, getCloneRoot, getCloneSource, getCustomQueryParameters, getCustomRequestHeaders, getGeneralProgressListener, getReadLimit, getRequestClientOptions, getRequestCredentials, getRequestCredentialsProvider, getRequestMetricCollector, getSdkClientExecutionTimeout, getSdkRequestTimeout, putCustomQueryParameter, putCustomRequestHeader, setGeneralProgressListener, setRequestCredentials, setRequestCredentialsProvider, setRequestMetricCollector, setSdkClientExecutionTimeout, setSdkRequestTimeout, withGeneralProgressListener, withRequestMetricCollector, withSdkClientExecutionTimeout, withSdkRequestTimeout
-
Constructor Details
-
ListVersionsRequest
public ListVersionsRequest()Constructs a newListVersionsRequest
object. The caller must populate the fields before the request is executed.- See Also:
-
ListVersionsRequest
public ListVersionsRequest(String bucketName, String prefix, String keyMarker, String versionIdMarker, String delimiter, Integer maxResults) Constructs a newListVersionsRequest
object and initializes all required and optional fields.- Parameters:
bucketName
- The name of the bucket whose versions are to be listed.prefix
- The prefix restricting what keys will be listed.keyMarker
- The key marker indicating where results should begin.versionIdMarker
- The version ID marker indicating where results should begin.delimiter
- The delimiter for condensing common prefixes in returned results.maxResults
- The maximum number of results to return.- See Also:
-
-
Method Details
-
getBucketName
Gets the name of the Amazon S3 bucket whose versions are to be listed.- Returns:
- The name of the Amazon S3 bucket whose versions are to be listed.
- See Also:
-
setBucketName
Sets the name of the Amazon S3 bucket whose versions are to be listed.- Parameters:
bucketName
- The name of the Amazon S3 bucket whose versions are to be listed.- See Also:
-
withBucketName
Sets the name of the Amazon S3 bucket whose versions are to be listed. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
bucketName
- The name of the Amazon S3 bucket whose versions are to be listed.- Returns:
- This
ListVersionsRequest
, enabling additional method calls to be chained together. - See Also:
-
getPrefix
Gets the optional prefix parameter restricting the response to keys that begin with the specified prefix. Use prefixes to separate a bucket into different sets of keys, similar to how a file system organizes files into directories.- Returns:
- The optional prefix parameter restricting the response to keys that begin with the specified prefix.
- See Also:
-
setPrefix
Sets the optional prefix parameter restricting the response to keys that begin with the specified prefix.- Parameters:
prefix
- The optional prefix parameter restricting the response to keys that begin with the specified prefix.- See Also:
-
withPrefix
Sets the optional prefix parameter restricting the response to keys that begin with the specified prefix. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
prefix
- The optional prefix parameter restricting the response to keys that begin with the specified prefix.- Returns:
- This
ListVersionsRequest
, enabling additional method calls to be chained together. - See Also:
-
getKeyMarker
Gets the optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first lexicographically (i.e. alphabetically) and then from most recent version to least recent version.If a
keyMarker
is used without a version ID marker, results begin immediately after that key's last version. When akeyMarker
is used with a version ID marker, results begin immediately after the version with the specified key and version ID.- Returns:
- The optional
keyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results. - See Also:
-
setKeyMarker
Sets the optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.- Parameters:
keyMarker
- The optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.- See Also:
-
withKeyMarker
Sets the optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
keyMarker
- The optionalkeyMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.- Returns:
- This
ListVersionsRequest
, enabling additional method calls to be chained together. - See Also:
-
getVersionIdMarker
Gets the optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results. Results are always ordered first lexicographically (i.e. alphabetically) and then from most recent version to least recent version.A key marker must be specified when specifying a
versionIdMarker
. Results begin immediately after the version with the specified key and version ID.- Returns:
- The optional
versionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results. - See Also:
-
setVersionIdMarker
Sets the optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.- Parameters:
versionIdMarker
- The optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.- See Also:
-
withVersionIdMarker
Sets the optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
versionIdMarker
- The optionalversionIdMarker
parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.- Returns:
- This
ListVersionsRequest
, enabling additional method calls to be chained together. - See Also:
-
getDelimiter
Gets the optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list. These combined keys are not returned elsewhere in the response.The most commonly used delimiter is "/", which simulates a hierarchical organization similar to a file system directory structure.
- Returns:
- The optional delimiter parameter that causes keys that contain
the same string between the prefix and the first occurrence of
the delimiter to be combined into a single result element in the
VersionListing.getCommonPrefixes()
list. - See Also:
-
setDelimiter
Sets the optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list.- Parameters:
delimiter
- The optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list.- See Also:
-
withDelimiter
Sets the optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
delimiter
- The optional delimiter parameter that causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be combined into a single result element in theVersionListing.getCommonPrefixes()
list.- Returns:
- This
ListVersionsRequest
, enabling additional method calls to be chained together. - See Also:
-
getMaxResults
Gets the optionalmaxResults
parameter indicating the maximum number of results to include in the response. Amazon S3 might return fewer than this, but will never return more. Even ifmaxResults
is not specified, Amazon S3 will limit the number of results in the response.- Returns:
- The optional
maxResults
parameter indicating the maximum number of results - See Also:
-
setMaxResults
Sets the optionalmaxResults
parameter indicating the maximum number of results to include in the response.- Parameters:
maxResults
- The optionalmaxResults
parameter indicating the maximum number of results to include in the response.- See Also:
-
withMaxResults
Sets the optionalmaxResults
parameter indicating the maximum number of results to include in the response. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
maxResults
- The optionalmaxResults
parameter indicating the maximum number of results to include in the response.- Returns:
- This
ListVersionsRequest
, enabling additional method calls to be chained together. - See Also:
-
getEncodingType
Gets the optionalencodingType
parameter indicating the encoding method to be applied on the response.- Returns:
- The encoding method to be applied on the response.
-
setEncodingType
Sets the optionalencodingType
parameter indicating the encoding method to be applied on the response. An object key can contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.- Parameters:
encodingType
- The encoding method to be applied on the response. Valid values: null (not encoded) or "url".
-
withEncodingType
Sets the optionalencodingType
parameter indicating the encoding method to be applied on the response. An object key can contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response. Returns thisListVersionsRequest
, enabling additional method calls to be chained together.- Parameters:
encodingType
- The encoding method to be applied on the response. Valid values: null (not encoded) or "url".
-