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 ListObjectsRequest

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

    public class ListObjectsRequest

extends AmazonWebServiceRequest

Returns a list of summary information about the objects in the specified bucket, along with additional information depending on the request parameters (such as common prefixes if a delimiter was specified). List results are always returned in lexicographic (alphabetical) order.

Since buckets can contain a virtually unlimited number of keys, 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 `ObjectListing.isTruncated()` method to see if the returned listing is complete, or if callers need to make additional calls to get more results. The marker parameter allows callers to specify where to start the object listing. Alternatively, callers can use the `AmazonS3Client.listNextBatchOfObjects(ObjectListing)` method as an easy way to get the next page of object listings.

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 `ObjectListing.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 listObjects with prefix="foo/" and delimiter="/" on this bucket, you will get an S3ObjectListing back that contains one key ("foo/boo") and 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 listObjects setting the prefix parameter to any interesting common prefix to list the individual keys under that prefix.

List performance is not substantially affected by the total number of keys in your bucket, nor by the presence or absence of any additional query parameters.

Constructor Summary
`ListObjectsRequest()` Constructs an empty ListObjectsRequest object.
`ListObjectsRequest(String bucketName, String prefix, String marker, String delimiter, Integer maxKeys)` Constructs a new ListObjectsRequest object and initializes all required and optional fields.

Method Summary
`String` | `getBucketName()` Returns the name of the Amazon S3 bucket whose objects 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 `ObjectListing.getCommonPrefixes()` list.
`String` | `getMarker()` Returns the optional parameter indicating where in the bucket to begin listing.
`Integer` | `getMaxKeys()` Returns the optional parameter indicating the maximum number of keys to include in the response.
`String` | `getPrefix()` Returns the optional prefix parameter restricting the response to keys which begin with the specified prefix.
`void` | `setBucketName(String bucketName)` Sets the name of the Amazon S3 bucket whose objects 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 `ObjectListing.getCommonPrefixes()` list.
`void` | `setMarker(String marker)` Sets the optional parameter indicating where in the bucket to begin listing.
`void` | `setMaxKeys(Integer maxKeys)` Sets the optional parameter indicating the maximum number of keys 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.
`ListObjectsRequest` | `withBucketName(String bucketName)` Sets the name of the Amazon S3 bucket whose objects are to be listed, and returns this ListObjectsRequest object so that method calls can be chained together.
`ListObjectsRequest` | `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 `ObjectListing.getCommonPrefixes()` list, and returns this ListObjectsRequest object so that method calls may be chained together.
`ListObjectsRequest` | `withMarker(String marker)` Sets the optional parameter indicating where in the bucket to begin listing.
`ListObjectsRequest` | `withMaxKeys(Integer maxKeys)` Sets the optional parameter indicating the maximum number of keys to include in the response, and returns this ListObjectsRequest object so that method calls may be chained together.
`ListObjectsRequest` | `withPrefix(String prefix)` Sets the optional prefix parameter restricting the response to keys which begin with the specified prefix, and returns this ListObjectsRequest 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

### ListObjectsRequest

    public ListObjectsRequest()

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

### ListObjectsRequest

    public ListObjectsRequest(String bucketName,
                              String prefix,
                              String marker,
                              String delimiter,
                              Integer maxKeys)

  Constructs a new ListObjectsRequest object and initializes all required and optional fields.

  Parameters:
    `bucketName` - The name of the bucket whose objects are to be listed.
    `prefix` - The prefix restricting what keys will be listed.
    `marker` - The key marker indicating where results should begin.
    `delimiter` - The delimiter for condensing common prefixes in returned results.
    `maxKeys` - The maximum number of results to return.

Method Detail

### getBucketName

    public String getBucketName()

  Returns the name of the Amazon S3 bucket whose objects are to be listed.

  Returns:
    The name of the Amazon S3 bucket whose objects are to be listed.

### setBucketName

    public void setBucketName(String bucketName)

  Sets the name of the Amazon S3 bucket whose objects are to be listed.

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose objects are to be listed.

### withBucketName

    public ListObjectsRequest withBucketName(String bucketName)

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

  Parameters:
    `bucketName` - The name of the Amazon S3 bucket whose objects are to be listed.
  Returns:
    This ListObjectsRequest 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 ListObjectsRequest withPrefix(String prefix)

  Sets the optional prefix parameter restricting the response to keys which begin with the specified prefix, and returns this ListObjectsRequest 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 ListObjectsRequest object so that method calls may be chained together.

### getMarker

    public String getMarker()

  Returns the optional parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.

  Returns:
    the optional parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.

### setMarker

    public void setMarker(String marker)

  Sets the optional parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.

  Parameters:
    `marker` - the optional parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.

### withMarker

    public ListObjectsRequest withMarker(String marker)

  Sets the optional parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker, and returns this ListObjectsRequest object so that method calls may be chained together.

  Parameters:
    `marker` - the optional parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.
  Returns:
    This ListObjectsRequest 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 `ObjectListing.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 `ObjectListing.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 `ObjectListing.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 `ObjectListing.getCommonPrefixes()` list.

### withDelimiter

    public ListObjectsRequest 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 `ObjectListing.getCommonPrefixes()` list, and returns this ListObjectsRequest 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 `ObjectListing.getCommonPrefixes()` list.
  Returns:
    This ListObjectsRequest object so that method calls may be chained together.

### getMaxKeys

    public Integer getMaxKeys()

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

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

### setMaxKeys

    public void setMaxKeys(Integer maxKeys)

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

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

### withMaxKeys

    public ListObjectsRequest withMaxKeys(Integer maxKeys)

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

  Parameters:
    `maxKeys` - the optional parameter indicating the maximum number of keys to include in the response.
  Returns:
    This ListObjectsRequest 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.