public class ListObjectsRequest extends AmazonWebServiceRequest implements Serializable, ExpectedBucketOwnerRequest
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 the
AmazonS3Client.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 the ObjectListing.getCommonPrefixes()
method.
For example, consider a bucket that contains the following keys:
listObjects
with
a prefix value of "foo/" and a delimiter value of "/"
on this bucket, an ObjectListing
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 listObjects
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.
NOOP
Constructor and Description |
---|
ListObjectsRequest()
Constructs a new
ListObjectsRequest object. |
ListObjectsRequest(String bucketName,
String prefix,
String marker,
String delimiter,
Integer maxKeys)
Constructs a new
ListObjectsRequest object and
initializes all required and optional object fields. |
Modifier and Type | Method and Description |
---|---|
String |
getBucketName()
The name of the bucket containing the objects.
|
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
ObjectListing.getCommonPrefixes() list. |
String |
getEncodingType()
Gets the optional
encodingType parameter indicating the
encoding method to be applied on the response. |
String |
getExpectedBucketOwner()
Returns he account id of the expected bucket owner.
|
String |
getMarker()
Gets the optional marker parameter indicating where in the bucket to begin
listing.
|
Integer |
getMaxKeys()
Gets the optional
maxKeys 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.
|
boolean |
isRequesterPays()
Returns true if the user has enabled Requester Pays option when
conducting this operation from Requester Pays Bucket; else false.
|
void |
setBucketName(String bucketName)
The name of the bucket containing the objects.
|
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
ObjectListing.getCommonPrefixes() list. |
void |
setEncodingType(String encodingType)
Sets the optional
encodingType parameter indicating the
encoding method to be applied on the response. |
void |
setExpectedBucketOwner(String expectedBucketOwner)
Set the account id of the expected bucket owner.
|
void |
setMarker(String marker)
Sets the optional marker parameter indicating where in the bucket to begin
listing.
|
void |
setMaxKeys(Integer maxKeys)
Sets the optional
maxKeys 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.
|
void |
setRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket.
|
ListObjectsRequest |
withBucketName(String bucketName)
The name of the bucket containing the objects.
|
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. |
ListObjectsRequest |
withEncodingType(String encodingType)
Sets the optional
encodingType parameter indicating the
encoding method to be applied on the response. |
ListObjectsRequest |
withExpectedBucketOwner(String expectedBucketOwner)
Set the account id of the expected bucket owner.
|
ListObjectsRequest |
withMarker(String marker)
Sets the optional marker parameter indicating where in the bucket to begin
listing.
|
ListObjectsRequest |
withMaxKeys(Integer maxKeys)
Sets the optional
maxKeys 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.
|
ListObjectsRequest |
withRequesterPays(boolean isRequesterPays)
Used for conducting this operation from a Requester Pays Bucket.
|
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 ListObjectsRequest()
ListObjectsRequest
object.
The caller must populate
the object fields before the request is ready to be executed.public ListObjectsRequest(String bucketName, String prefix, String marker, String delimiter, Integer maxKeys)
ListObjectsRequest
object and
initializes all required and optional object 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 Amazon Web Services 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 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.ListObjectsRequest()
public String getExpectedBucketOwner()
ExpectedBucketOwnerRequest
403 (Access Denied)
error.getExpectedBucketOwner
in interface ExpectedBucketOwnerRequest
public ListObjectsRequest withExpectedBucketOwner(String expectedBucketOwner)
ExpectedBucketOwnerRequest
403 (Access Denied)
error.withExpectedBucketOwner
in interface ExpectedBucketOwnerRequest
public void setExpectedBucketOwner(String expectedBucketOwner)
ExpectedBucketOwnerRequest
403 (Access Denied)
error.setExpectedBucketOwner
in interface ExpectedBucketOwnerRequest
public String getBucketName()
The name of the bucket containing the objects.
When using this action 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 action with an access point through the Amazon Web Services 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 S3 User Guide.
When using this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon S3 User Guide.
When using this action 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 action with an access point through the Amazon Web Services 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 S3 User Guide.
When using this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon S3 User Guide.
setBucketName(String)
,
withBucketName(String)
public void setBucketName(String bucketName)
The name of the bucket containing the objects.
When using this action 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 action with an access point through the Amazon Web Services 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 S3 User Guide.
When using this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon S3 User Guide.
bucketName
- The name of the bucket containing the objects.
When using this action 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 action with an access point through the Amazon Web Services 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 S3 User Guide.
When using this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon S3 User Guide.
getBucketName()
,
withBucketName(String)
public ListObjectsRequest withBucketName(String bucketName)
The name of the bucket containing the objects.
When using this action 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 action with an access point through the Amazon Web Services 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 S3 User Guide.
When using this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon S3 User Guide.
bucketName
- The name of the bucket containing the objects.
When using this action 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 action with an access point through the Amazon Web Services 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 S3 User Guide.
When using this action with Amazon S3 on Outposts, you must direct requests to the S3 on Outposts hostname. The S3 on Outposts hostname takes the form AccessPointName-AccountId.outpostID.s3-outposts.Region.amazonaws.com. When using this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts bucket ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see Using S3 on Outposts in the Amazon S3 User Guide.
ListObjectsRequest
, enabling additional method
calls to be chained together.getBucketName()
,
setBucketName(String)
public String getPrefix()
setPrefix(String)
public void setPrefix(String prefix)
prefix
- The optional prefix parameter, restricting the response to keys
that begin with the specified prefix.getPrefix()
public ListObjectsRequest withPrefix(String prefix)
ListObjectsRequest
, enabling additional method
calls to be chained together.prefix
- The optional prefix parameter restricting the response to keys
that begin with the specified prefix.ListObjectsRequest
, enabling additional method
calls to be chained together.getPrefix()
,
setPrefix(String)
public String getMarker()
setMarker(String)
,
withMarker(String)
public void setMarker(String marker)
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.getMarker()
,
withMarker(String)
public ListObjectsRequest withMarker(String marker)
ListObjectsRequest
, enabling additional method
calls to be chained together.
The list will only include keys that occur lexicographically
after the marker.marker
- The optional parameter indicating where in the bucket to begin
listing. The list will only include keys that occur
lexicographically after the marker.ListObjectsRequest
, enabling additional method
calls to be chained together.getMarker()
,
setMarker(String)
public String getDelimiter()
ObjectListing.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.ObjectListing.getCommonPrefixes()
list.setDelimiter(String)
,
withDelimiter(String)
public void setDelimiter(String delimiter)
ObjectListing.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 ObjectListing.getCommonPrefixes()
list.getDelimiter()
,
withDelimiter(String)
public ListObjectsRequest withDelimiter(String delimiter)
ObjectListing.getCommonPrefixes()
list.
Returns this ListObjectsRequest
, 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 rolled up into a single result element in
the ObjectListing.getCommonPrefixes()
list.ListObjectsRequest
, enabling additional method
calls to be chained together.getDelimiter()
,
setDelimiter(String)
public Integer getMaxKeys()
maxKeys
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.setMaxKeys(Integer)
,
withMaxKeys(Integer)
public void setMaxKeys(Integer maxKeys)
maxKeys
parameter indicating the maximum number of keys to
include in the response.maxKeys
- The optional parameter indicating the maximum number of keys
to include in the response.getMaxKeys()
,
withMaxKeys(Integer)
public ListObjectsRequest withMaxKeys(Integer maxKeys)
maxKeys
parameter indicating the maximum number of keys to
include in the response.
Returns this ListObjectsRequest
, enabling additional method
calls to be chained together.maxKeys
- The optional parameter indicating the maximum number of keys
to include in the response.ListObjectsRequest
, enabling additional method
calls to be chained together.getMaxKeys()
,
setMaxKeys(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 ListObjectsRequest 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 ListObjectsRequest
, 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".public boolean isRequesterPays()
If a bucket is enabled for Requester Pays, then any attempt to upload or download an object from it without Requester Pays enabled will result in a 403 error and the bucket owner will be charged for the request.
Enabling Requester Pays disables the ability to have anonymous access to this bucket
public void setRequesterPays(boolean isRequesterPays)
If a bucket is enabled for Requester Pays, then any attempt to upload or download an object from it without Requester Pays enabled will result in a 403 error and the bucket owner will be charged for the request.
Enabling Requester Pays disables the ability to have anonymous access to this bucket.
isRequesterPays
- Enable Requester Pays option for the operation.public ListObjectsRequest withRequesterPays(boolean isRequesterPays)
If a bucket is enabled for Requester Pays, then any attempt to upload or download an object from it without Requester Pays enabled will result in a 403 error and the bucket owner will be charged for the request.
Enabling Requester Pays disables the ability to have anonymous access to this bucket.
isRequesterPays
- Enable Requester Pays option for the operation.Copyright © 2022. All rights reserved.