Class ListObjectsRequest
- java.lang.Object
-
- com.amazonaws.AmazonWebServiceRequest
-
- com.amazonaws.services.s3.model.ListObjectsRequest
-
- All Implemented Interfaces:
ReadLimitInfo
,Serializable
,Cloneable
public class ListObjectsRequest extends AmazonWebServiceRequest implements Serializable
Contains options to return a list of summary information about the objects in the specified bucket. Depending on the request parameters, additional information is returned, such as common prefixes if a delimiter was specified. List results are always returned in lexicographic (alphabetical) order.
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 theAmazonS3Client.listNextBatchOfObjects(ObjectListing)
method as an easy way to get the next page of object listings.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 theObjectListing.getCommonPrefixes()
method.For example, consider a bucket that contains the following keys:
- "foo/bar/baz"
- "foo/bar/bash"
- "foo/bar/bang"
- "foo/boo"
listObjects
with a prefix value of "foo/" and a delimiter value of "/" on this bucket, anObjectListing
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 tolistObjects
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.
- See Also:
- Serialized Form
-
-
Field Summary
-
Fields inherited from class com.amazonaws.AmazonWebServiceRequest
NOOP
-
-
Constructor Summary
Constructors Constructor Description ListObjectsRequest()
Constructs a newListObjectsRequest
object.ListObjectsRequest(String bucketName, String prefix, String marker, String delimiter, Integer maxKeys)
Constructs a newListObjectsRequest
object and initializes all required and optional object fields.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description String
getBucketName()
Gets the name of the Amazon S3 bucket whose objects 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 theObjectListing.getCommonPrefixes()
list.String
getEncodingType()
Gets the optionalencodingType
parameter indicating the encoding method to be applied on the response.String
getMarker()
Gets the optional marker parameter indicating where in the bucket to begin listing.Integer
getMaxKeys()
Gets the optionalmaxKeys
parameter indicating the maximum number of keys to include in the response.String
getPrefix()
Gets the optional prefix parameter and restricts the response to keys that 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 combined into a single result element in theObjectListing.getCommonPrefixes()
list.void
setEncodingType(String encodingType)
Sets the optionalencodingType
parameter indicating the encoding method to be applied on the response.void
setMarker(String marker)
Sets the optional marker parameter indicating where in the bucket to begin listing.void
setMaxKeys(Integer maxKeys)
Sets the optionalmaxKeys
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 that begin with the specified prefix.ListObjectsRequest
withBucketName(String bucketName)
Sets the name of the Amazon S3 bucket whose objects are to be listed.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 theObjectListing.getCommonPrefixes()
list.ListObjectsRequest
withEncodingType(String encodingType)
Sets the optionalencodingType
parameter indicating the encoding method to be applied on the response.ListObjectsRequest
withMarker(String marker)
Sets the optional marker parameter indicating where in the bucket to begin listing.ListObjectsRequest
withMaxKeys(Integer maxKeys)
Sets the optionalmaxKeys
parameter indicating the maximum number of keys to include in the response.ListObjectsRequest
withPrefix(String prefix)
Sets the optional prefix parameter restricting the response to keys that begin with the specified prefix.-
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 Detail
-
ListObjectsRequest
public ListObjectsRequest()
Constructs a newListObjectsRequest
object. The caller must populate the object fields before the request is ready to be executed.
-
ListObjectsRequest
public ListObjectsRequest(String bucketName, String prefix, String marker, String delimiter, Integer maxKeys)
Constructs a newListObjectsRequest
object and initializes all required and optional object 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 listing results should begin.delimiter
- The delimiter for condensing common prefixes in the returned listing results.maxKeys
- The maximum number of results to return.- See Also:
ListObjectsRequest()
-
-
Method Detail
-
getBucketName
public String getBucketName()
Gets 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.
- See Also:
setBucketName(String)
,withBucketName(String)
-
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.- See Also:
getBucketName()
,withBucketName(String)
-
withBucketName
public ListObjectsRequest withBucketName(String bucketName)
Sets the name of the Amazon S3 bucket whose objects are to be listed. Returns thisListObjectsRequest
, enabling additional method calls to be chained together.- Parameters:
bucketName
- The name of the Amazon S3 bucket whose objects are to be listed.- Returns:
- This
ListObjectsRequest
, enabling additional method calls to be chained together. - See Also:
getBucketName()
,setBucketName(String)
-
getPrefix
public String getPrefix()
Gets the optional prefix parameter and restricts 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(String)
-
setPrefix
public void setPrefix(String prefix)
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:
getPrefix()
-
withPrefix
public ListObjectsRequest withPrefix(String prefix)
Sets the optional prefix parameter restricting the response to keys that begin with the specified prefix. Returns thisListObjectsRequest
, 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
ListObjectsRequest
, enabling additional method calls to be chained together. - See Also:
getPrefix()
,setPrefix(String)
-
getMarker
public String getMarker()
Gets the optional marker parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.- Returns:
- The optional marker parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.
- See Also:
setMarker(String)
,withMarker(String)
-
setMarker
public void setMarker(String marker)
Sets the optional marker 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 marker parameter indicating where in the bucket to begin listing. The list will only include keys that occur lexicographically after the marker.- See Also:
getMarker()
,withMarker(String)
-
withMarker
public ListObjectsRequest withMarker(String marker)
Sets the optional marker parameter indicating where in the bucket to begin listing. Returns thisListObjectsRequest
, enabling additional method calls to be chained together. 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.- Returns:
- This
ListObjectsRequest
, enabling additional method calls to be chained together. - See Also:
getMarker()
,setMarker(String)
-
getDelimiter
public 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 theObjectListing.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
ObjectListing.getCommonPrefixes()
list. - See Also:
setDelimiter(String)
,withDelimiter(String)
-
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 combined into a single result element in theObjectListing.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 theObjectListing.getCommonPrefixes()
list.- See Also:
getDelimiter()
,withDelimiter(String)
-
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 theObjectListing.getCommonPrefixes()
list. Returns thisListObjectsRequest
, 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 rolled up into a single result element in theObjectListing.getCommonPrefixes()
list.- Returns:
- This
ListObjectsRequest
, enabling additional method calls to be chained together. - See Also:
getDelimiter()
,setDelimiter(String)
-
getMaxKeys
public Integer getMaxKeys()
Gets the optionalmaxKeys
parameter indicating the maximum number of keys to include in the response. Amazon S3 might return fewer keys than specified, but will never return more. Even if the optional parameter 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.
- See Also:
setMaxKeys(Integer)
,withMaxKeys(Integer)
-
setMaxKeys
public void setMaxKeys(Integer maxKeys)
Sets the optionalmaxKeys
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.- See Also:
getMaxKeys()
,withMaxKeys(Integer)
-
withMaxKeys
public ListObjectsRequest withMaxKeys(Integer maxKeys)
Sets the optionalmaxKeys
parameter indicating the maximum number of keys to include in the response. Returns thisListObjectsRequest
, enabling additional method calls to be chained together.- Parameters:
maxKeys
- The optional parameter indicating the maximum number of keys to include in the response.- Returns:
- This
ListObjectsRequest
, enabling additional method calls to be chained together. - See Also:
getMaxKeys()
,setMaxKeys(Integer)
-
getEncodingType
public String 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
public void setEncodingType(String encodingType)
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
public ListObjectsRequest withEncodingType(String encodingType)
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 thisListObjectsRequest
, 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".
-
-