Overview | Package | Class | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.amazonaws.services.s3.model
Class ListVersionsRequest

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

    public class ListVersionsRequest

extends AmazonWebServiceRequest

Request for a list of summary information about the versions in a specified bucket.

The 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 most recent to least recent. Both versions with data and delete markers are included in the results.

Since buckets can contain a virtually unlimited number of versions, 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. Callers should always check the `VersionListing.isTruncated()` method to determine if the returned listing is complete, or if callers need to make additional calls to get more results. The key and version ID marker parameters allow callers to specify where to start the version listing. Alternatively callers can use `AmazonS3.listNextBatchOfVersions(VersionListing)` as an easy way to get the next page of results.

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.

The delimiter parameter allows groups of keys that share a prefix terminated by a special delimiter to be rolled-up by that common prefix in the returned listing. This allows applications to organize and browse their keys hierarchically, much like how you would organize your files into directories in a file system. These common prefixes can be retrieved through the `VersionListing.getCommonPrefixes()` method.

For example, consider a bucket that contains the keys:

- "foo/bar/baz"
- "foo/bar/bash"
- "foo/bar/bang"
- "foo/boo"

If you call listVersions with prefix="foo/" and delimiter="/" on this bucket, you will get an S3VersionListing back that contains:

- all the versions for one key ("foo/boo")
- one entry in the common prefixes list ("foo/bar/")

If you want to see deeper into the virtual hierarchy, you can make another call to listVersions setting the prefix parameter to any interesting common prefix to list the individual versions under that prefix.

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

Constructor Summary
`ListVersionsRequest()` Constructs an empty 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.

Method Summary
`String` | `getBucketName()` Returns the name of the Amazon S3 bucket whose versions are to be listed.
`String` | `getDelimiter()` 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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list.
`String` | `getKeyMarker()` Returns the optional keyMarker parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.
`Integer` | `getMaxResults()` Returns the optional parameter indicating the maximum number of results to include in the response.
`String` | `getPrefix()` Returns the optional prefix parameter restricting the response to keys which begin with the specified prefix.
`String` | `getVersionIdMarker()` Returns 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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list.
`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 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 which 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, and returns this ListVersionsRequest object so that method calls can be chained together.
`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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list, and returns this ListVersionsRequest object so that method calls may be chained together.
`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, and returns this ListVersionsRequest object so that method calls may be chained together.
`ListVersionsRequest` | `withMaxResults(Integer maxResults)` Sets the optional parameter indicating the maximum number of results to include in the response, and returns this ListVersionsRequest object so that method calls may be chained together.
`ListVersionsRequest` | `withPrefix(String prefix)` Sets the optional prefix parameter restricting the response to keys which begin with the specified prefix, and returns this ListVersionsRequest object so that method calls may be chained together.
`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, and returns this ListVersionsRequest object so that method calls may 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

### ListVersionsRequest

    public ListVersionsRequest()

  Constructs an empty ListVersionsRequest object. The caller must populate the fields before the request is ready to be executed.

### ListVersionsRequest

    public 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.

  Parameters:
    `bucketName` - The name of the bucket whose versions are to be listed. See `getBucketName()`.
    `prefix` - The prefix restricting what keys will be listed. See `getPrefix()`.
    `keyMarker` - The key marker indicating where results should begin. See `getKeyMarker()`.
    `versionIdMarker` - The version ID marker indicating where results should begin. See `getVersionIdMarker()`.
    `delimiter` - The delimiter for condensing common prefixes in returned results. See `getDelimiter()`.
    `maxResults` - The maximum number of results to return. See `getMaxResults()`.

Method Detail

### getBucketName

    public String getBucketName()

  Returns 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.

### setBucketName

    public void setBucketName(String bucketName)

  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.

### withBucketName

    public ListVersionsRequest withBucketName(String bucketName)

  Sets the name of the Amazon S3 bucket whose versions are to be listed, and returns this ListVersionsRequest object so that method calls can be chained together.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose versions are to be listed.
  Returns:
    This ListVersionsRequest object so that method calls can be chained together.

### getPrefix

    public String getPrefix()

  Returns the optional prefix parameter restricting the response to keys which begin with the specified prefix. You can use prefixes to separate a bucket into different sets of keys in a way similar to how a file system uses folders.

  Returns:
    the optional prefix parameter restricting the response to keys which begin with the specified prefix.

### setPrefix

    public void setPrefix(String prefix)

  Sets the optional prefix parameter restricting the response to keys which begin with the specified prefix.

  Parameters:
    `prefix` - the optional prefix parameter restricting the response to keys which begin with the specified prefix.

### withPrefix

    public ListVersionsRequest withPrefix(String prefix)

  Sets the optional prefix parameter restricting the response to keys which begin with the specified prefix, and returns this ListVersionsRequest object so that method calls may be chained together.

  Parameters:
    `prefix` - the optional prefix parameter restricting the response to keys which begin with the specified prefix.
  Returns:
    This ListVersionsRequest object so that method calls may be chained together.

### getKeyMarker

    public String getKeyMarker()

  Returns the optional 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 versionIdMarker, results begin immediately after that key's last version. When a keyMarker is used with a versionIdMarker, 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.

### setKeyMarker

    public 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.

  Parameters:
    `keyMarker` - the optional keyMarker parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.

### withKeyMarker

    public 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, and returns this ListVersionsRequest object so that method calls may be chained together.

  Parameters:
    `keyMarker` - the optional keyMarker parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.
  Returns:
    This ListVersionsRequest object so that method calls may be chained together.

### getVersionIdMarker

    public String getVersionIdMarker()

  Returns the optional 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 keyMarker 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.

### setVersionIdMarker

    public 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.

  Parameters:
    `versionIdMarker` - the optional versionIdMarker parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.

### withVersionIdMarker

    public 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, and returns this ListVersionsRequest object so that method calls may be chained together.

  Parameters:
    `versionIdMarker` - the optional versionIdMarker parameter indicating where in the sorted list of all versions in the specified bucket to begin returning results.
  Returns:
    This ListVersionsRequest object so that method calls may be chained together.

### getDelimiter

    public String getDelimiter()

  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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list. These rolled-up 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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list.

### setDelimiter

    public 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 rolled up into a single result element in the `VersionListing.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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list.

### withDelimiter

    public 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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list, and returns this ListVersionsRequest object so that method calls may 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 rolled up into a single result element in the `VersionListing.getCommonPrefixes()` list.
  Returns:
    This ListVersionsRequest object so that method calls may be chained together.

### getMaxResults

    public Integer getMaxResults()

  Returns the optional parameter indicating the maximum number of results to include in the response. Amazon S3 might return fewer than this, but will not return more. Even if maxResults is not specified, Amazon S3 will limit the number of results in the response.

  Returns:
    the optional parameter indicating the maximum number of results to include in the response.

### setMaxResults

    public void setMaxResults(Integer maxResults)

  Sets the optional parameter indicating the maximum number of results to include in the response.

  Parameters:
    `maxResults` - the optional parameter indicating the maximum number of results to include in the response.

### withMaxResults

    public ListVersionsRequest withMaxResults(Integer maxResults)

  Sets the optional parameter indicating the maximum number of results to include in the response, and returns this ListVersionsRequest object so that method calls may be chained together.

  Parameters:
    `maxResults` - the optional parameter indicating the maximum number of results to include in the response.
  Returns:
    This ListVersionsRequest object so that method calls may be chained together.

Overview | Package | Class | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010 Amazon Web Services, Inc. All Rights Reserved.