public class ListVersionsRequest extends AmazonWebServiceRequest implements Serializable
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:
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)
.
NOOP
Constructor and Description |
---|
ListVersionsRequest()
Constructs a new
ListVersionsRequest object. |
ListVersionsRequest(String bucketName,
String prefix,
String keyMarker,
String versionIdMarker,
String delimiter,
Integer maxResults)
Constructs a new
ListVersionsRequest object and initializes all required
and optional fields. |
Modifier and Type | Method and Description |
---|---|
String |
getBucketName()
Gets the name of the Amazon S3 bucket whose versions are to be listed.
|
String |
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 the
VersionListing.getCommonPrefixes() list. |
String |
getEncodingType()
Gets the optional
encodingType parameter indicating the
encoding method to be applied on the response. |
String |
getKeyMarker()
Gets the optional
keyMarker
parameter indicating where in the sorted
list of all versions in the specified bucket to begin returning results. |
Integer |
getMaxResults()
Gets the optional
maxResults parameter indicating the maximum number of results
to include in the response. |
String |
getPrefix()
Gets the optional prefix parameter restricting the response to keys
that begin with the specified prefix.
|
String |
getVersionIdMarker()
Gets the optional
versionIdMarker 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 the
VersionListing.getCommonPrefixes() list. |
void |
setEncodingType(String encodingType)
Sets the optional
encodingType parameter indicating the
encoding method to be applied on the response. |
void |
setKeyMarker(String keyMarker)
Sets the optional
keyMarker parameter indicating where in the sorted list
of all versions in the specified bucket to begin returning results. |
void |
setMaxResults(Integer maxResults)
Sets the optional
maxResults parameter indicating the maximum number of results to
include in the response. |
void |
setPrefix(String prefix)
Sets the optional prefix parameter restricting the response to keys that
begin with the specified prefix.
|
void |
setVersionIdMarker(String versionIdMarker)
Sets the optional
versionIdMarker parameter indicating where in the
sorted list of all versions in the specified bucket to begin returning
results. |
ListVersionsRequest |
withBucketName(String bucketName)
Sets the name of the Amazon S3 bucket whose versions are to be listed.
|
ListVersionsRequest |
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 the
VersionListing.getCommonPrefixes() list. |
ListVersionsRequest |
withEncodingType(String encodingType)
Sets the optional
encodingType parameter indicating the
encoding method to be applied on the response. |
ListVersionsRequest |
withKeyMarker(String keyMarker)
Sets the optional
keyMarker parameter indicating where in the sorted list
of all versions in the specified bucket to begin returning results. |
ListVersionsRequest |
withMaxResults(Integer maxResults)
Sets the optional
maxResults parameter indicating the maximum number of results to
include in the response. |
ListVersionsRequest |
withPrefix(String prefix)
Sets the optional prefix parameter restricting the response to keys that
begin with the specified prefix.
|
ListVersionsRequest |
withVersionIdMarker(String versionIdMarker)
Sets the optional
versionIdMarker parameter indicating where in the
sorted list of all versions in the specified bucket to begin returning
results. |
addHandlerContext, clone, copyBaseTo, getCloneRoot, getCloneSource, getCustomQueryParameters, getCustomRequestHeaders, getGeneralProgressListener, getHandlerContext, getReadLimit, getRequestClientOptions, getRequestCredentials, getRequestCredentialsProvider, getRequestMetricCollector, getSdkClientExecutionTimeout, getSdkRequestTimeout, putCustomQueryParameter, putCustomRequestHeader, setGeneralProgressListener, setRequestCredentials, setRequestCredentialsProvider, setRequestMetricCollector, setSdkClientExecutionTimeout, setSdkRequestTimeout, withGeneralProgressListener, withRequestCredentialsProvider, withRequestMetricCollector, withSdkClientExecutionTimeout, withSdkRequestTimeout
public ListVersionsRequest()
ListVersionsRequest
object.
The caller must populate
the fields before the request is executed.public ListVersionsRequest(String bucketName, String prefix, String keyMarker, String versionIdMarker, String delimiter, Integer maxResults)
ListVersionsRequest
object and initializes all required
and optional fields.
When using this API with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com.
When using this operation using an access point through the AWS SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer Guide.
bucketName
- The name of the bucket, or access point ARN, 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.ListVersionsRequest()
public String getBucketName()
setBucketName(String)
,
withBucketName(String)
public void setBucketName(String bucketName)
When using this API with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com.
When using this operation using an access point through the AWS SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer Guide.
bucketName
- The name of the Amazon S3 bucket, or access point ARN, whose versions are to be
listed.getBucketName()
,
withBucketName(String)
public ListVersionsRequest withBucketName(String bucketName)
ListVersionsRequest
, enabling additional method
calls to be chained together.
When using this API with an access point, you must direct requests to the access point hostname. The access point hostname takes the form AccessPointName-AccountId.s3-accesspoint.Region.amazonaws.com.
When using this operation using an access point through the AWS SDKs, you provide the access point ARN in place of the bucket name. For more information about access point ARNs, see Using Access Points in the Amazon Simple Storage Service Developer Guide.
bucketName
- The name of the Amazon S3 bucket, or access point ARN, whose versions are to be
listed.ListVersionsRequest
, enabling additional method
calls to be chained together.getBucketName()
,
setBucketName(String)
public String getPrefix()
setPrefix(String)
,
withPrefix(String)
public void setPrefix(String prefix)
prefix
- The optional prefix parameter restricting the response to keys
that begin with the specified prefix.getPrefix()
,
withPrefix(String)
public ListVersionsRequest withPrefix(String prefix)
ListVersionsRequest
, enabling additional method
calls to be chained together.prefix
- The optional prefix parameter restricting the response to keys
that begin with the specified prefix.ListVersionsRequest
, enabling additional method
calls to be chained together.getPrefix()
,
setPrefix(String)
public String getKeyMarker()
keyMarker
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 a keyMarker
is used with a version ID marker,
results begin immediately after the version with the specified key and
version ID.
keyMarker
parameter indicating where in the sorted
list of all versions in the specified bucket to begin returning
results.setKeyMarker(String)
,
withKeyMarker(String)
public void setKeyMarker(String keyMarker)
keyMarker
parameter indicating where in the sorted list
of all versions in the specified bucket to begin returning results.keyMarker
- The optional keyMarker
parameter indicating where in the
sorted list of all versions in the specified bucket to begin
returning results.getKeyMarker()
,
withKeyMarker(String)
public ListVersionsRequest withKeyMarker(String keyMarker)
keyMarker
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.keyMarker
- The optional keyMarker
parameter indicating where in the
sorted list of all versions in the specified bucket to begin
returning results.ListVersionsRequest
, enabling additional method
calls to be chained together.getKeyMarker()
,
setKeyMarker(String)
public String getVersionIdMarker()
versionIdMarker
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.
versionIdMarker
parameter indicating where in the
sorted list of all versions in the specified bucket to begin
returning results.setVersionIdMarker(String)
,
withVersionIdMarker(String)
public void setVersionIdMarker(String versionIdMarker)
versionIdMarker
parameter indicating where in the
sorted list of all versions in the specified bucket to begin returning
results.versionIdMarker
- The optional versionIdMarker
parameter indicating where in the
sorted list of all versions in the specified bucket to begin
returning results.getVersionIdMarker()
,
withVersionIdMarker(String)
public ListVersionsRequest withVersionIdMarker(String versionIdMarker)
versionIdMarker
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.versionIdMarker
- The optional versionIdMarker
parameter indicating where in the
sorted list of all versions in the specified bucket to begin
returning results.ListVersionsRequest
, enabling additional method
calls to be chained together.getVersionIdMarker()
,
setVersionIdMarker(String)
public String getDelimiter()
VersionListing.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.
VersionListing.getCommonPrefixes()
list.setDelimiter(String)
,
withDelimiter(String)
public void setDelimiter(String delimiter)
VersionListing.getCommonPrefixes()
list.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
the VersionListing.getCommonPrefixes()
list.getDelimiter()
,
withDelimiter(String)
public ListVersionsRequest withDelimiter(String delimiter)
VersionListing.getCommonPrefixes()
list.
Returns this ListVersionsRequest
, enabling additional method
calls to be chained together.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
the VersionListing.getCommonPrefixes()
list.ListVersionsRequest
, enabling additional method
calls to be chained together.getDelimiter()
,
setDelimiter(String)
public Integer getMaxResults()
maxResults
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 if maxResults
is not specified,
Amazon S3 will
limit the number of results in the response.maxResults
parameter indicating the maximum number of resultssetMaxResults(Integer)
,
withMaxResults(Integer)
public void setMaxResults(Integer maxResults)
maxResults
parameter indicating the maximum number of results to
include in the response.maxResults
- The optional maxResults
parameter indicating the maximum number of
results to include in the response.getMaxResults()
,
withMaxResults(Integer)
public ListVersionsRequest withMaxResults(Integer maxResults)
maxResults
parameter indicating the maximum number of results to
include in the response.
Returns this ListVersionsRequest
, enabling additional method
calls to be chained together.maxResults
- The optional maxResults
parameter indicating the maximum number of
results to include in the response.ListVersionsRequest
, enabling additional method
calls to be chained together.getMaxResults()
,
setMaxResults(Integer)
public String getEncodingType()
encodingType
parameter indicating the
encoding method to be applied on the response.public void setEncodingType(String encodingType)
encodingType
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.encodingType
- The encoding method to be applied on the response. Valid
values: null (not encoded) or "url".public ListVersionsRequest withEncodingType(String encodingType)
encodingType
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 this ListVersionsRequest
, enabling additional method calls
to be chained together.encodingType
- The encoding method to be applied on the response. Valid
values: null (not encoded) or "url".Copyright © 2020. All rights reserved.