com.ibm.cloud.objectstorage.services.s3.model

Class ListObjectsRequest

java.lang.Object

com.ibm.cloud.objectstorage.AmazonWebServiceRequest

com.ibm.cloud.objectstorage.services.s3.model.ListObjectsRequest

All Implemented Interfaces:

HandlerContextAware, ReadLimitInfo, WormMirrorDestinationProvider, Serializable, Cloneable

public class ListObjectsRequest
extends AmazonWebServiceRequest
implements WormMirrorDestinationProvider, 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 the AmazonS3Client.listNextBatchOfObjects(ObjectListing) method as an easy way to get the next page of object listings.

Calling ListObjectsRequest.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:

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

If calling 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.

See Also:

Serialized Form

Field Summary

Fields inherited from class com.ibm.cloud.objectstorage.AmazonWebServiceRequest

NOOP

Constructor Summary

Constructors

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.

Method Summary

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	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.
String	getWormMirrorDestination() Returns the optional mirror-destination value for WORM mirroring
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	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	setWormMirrorDestination(String wormMirrorDestination) Sets the optional mirror-destination value for WORM mirroring
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	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	withWormMirrorDestination(String wormMirrorDestination) Sets the optional mirror-destination value for WORM mirroring and returns the updated ListObjectsRequest so that additional method calls may be chained together.

Methods inherited from class com.ibm.cloud.objectstorage.AmazonWebServiceRequest

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

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ListObjectsRequest

public ListObjectsRequest()

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

See Also:

ListObjectsRequest(String, String, String, String, Integer)

ListObjectsRequest

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

Constructs a new ListObjectsRequest object and initializes all required and optional object fields. 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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

Parameters:

bucketName - The name of the bucket, or access point ARN, whose objects are to be listed.

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

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()

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

Returns:

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

See Also:

ListObjectsRequest.setBucketName(String), ListObjectsRequest.withBucketName(String)

setBucketName

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

Parameters:

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

See Also:

ListObjectsRequest.getBucketName(), ListObjectsRequest.withBucketName(String)

withBucketName

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

Parameters:

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 you use 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 you use this action using S3 on Outposts through the Amazon Web Services SDKs, you provide the Outposts access point ARN in place of the bucket name. For more information about S3 on Outposts ARNs, see What is S3 on Outposts in the Amazon S3 User Guide.

Returns:

This ListObjectsRequest, enabling additional method calls to be chained together.

See Also:

ListObjectsRequest.getBucketName(), ListObjectsRequest.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:

ListObjectsRequest.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:

ListObjectsRequest.getPrefix()

withPrefix

public ListObjectsRequest withPrefix(String prefix)

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

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:

ListObjectsRequest.getPrefix(), ListObjectsRequest.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:

ListObjectsRequest.setMarker(String), ListObjectsRequest.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:

ListObjectsRequest.getMarker(), ListObjectsRequest.withMarker(String)

withMarker

public ListObjectsRequest withMarker(String marker)

Sets the optional marker parameter indicating where in the bucket to begin listing. Returns this ListObjectsRequest, 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:

ListObjectsRequest.getMarker(), ListObjectsRequest.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 the 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.

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:

ListObjectsRequest.setDelimiter(String), ListObjectsRequest.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 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 combined into a single result element in the ObjectListing.getCommonPrefixes() list.

See Also:

ListObjectsRequest.getDelimiter(), ListObjectsRequest.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 the ObjectListing.getCommonPrefixes() list. Returns this ListObjectsRequest, 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 the ObjectListing.getCommonPrefixes() list.

Returns:

This ListObjectsRequest, enabling additional method calls to be chained together.

See Also:

ListObjectsRequest.getDelimiter(), ListObjectsRequest.setDelimiter(String)

getMaxKeys

public Integer getMaxKeys()

Gets the optional 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.

Returns:

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

See Also:

ListObjectsRequest.setMaxKeys(Integer), ListObjectsRequest.withMaxKeys(Integer)

setMaxKeys

public void setMaxKeys(Integer maxKeys)

Sets the optional maxKeys 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:

ListObjectsRequest.getMaxKeys(), ListObjectsRequest.withMaxKeys(Integer)

withMaxKeys

public ListObjectsRequest withMaxKeys(Integer maxKeys)

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

ListObjectsRequest.getMaxKeys(), ListObjectsRequest.setMaxKeys(Integer)

getEncodingType

public String getEncodingType()

Gets the optional encodingType 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 optional 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.

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

Parameters:

encodingType - The encoding method to be applied on the response. Valid values: null (not encoded) or "url".

getWormMirrorDestination

public String getWormMirrorDestination()

Returns the optional mirror-destination value for WORM mirroring

Specified by:

getWormMirrorDestination in interface WormMirrorDestinationProvider

Returns:

The optional mirror-destination value

setWormMirrorDestination

public void setWormMirrorDestination(String wormMirrorDestination)

Sets the optional mirror-destination value for WORM mirroring

Specified by:

setWormMirrorDestination in interface WormMirrorDestinationProvider

Parameters:

wormMirrorDestination - The optional mirror-destination value for WORM mirroring

withWormMirrorDestination

public ListObjectsRequest withWormMirrorDestination(String wormMirrorDestination)

Sets the optional mirror-destination value for WORM mirroring and returns the updated ListObjectsRequest so that additional method calls may be chained together.

Parameters:

wormMirrorDestination - The optional mirror-destination value for WORM mirroring

Returns:

This ListObjectsRequest, enabling additional method calls to be chained together.