Provides options for returning a list of summary information about the versions in a specified bucket.
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 {@link ObjectListing#isTruncated()} method to seeif the returned listing is complete, or if callers need to make additional calls to get more results. Alternatively, use the {@link AmazonS3Client#listNextBatchOfVersions(VersionListing)} method as aneasy 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 {@link 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 {@link ListVersionsRequest#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 {@link VersionListing#getCommonPrefixes()} method.
For example, consider a bucket that contains the following keys:
- "foo/bar/baz"
- "foo/bar/bash"
- "foo/bar/bang"
- "foo/boo"
If calling
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 {@link AmazonS3#setBucketVersioningConfiguration(SetBucketVersioningConfigurationRequest)}.