How to list objects in a bucket by using Android SDK - Object Storage Service

This topic describes how to list objects in a bucket, such as all objects in the bucket, a specific number of objects, and objects whose names contain a specific prefix.

Usage notes

Before you run the sample code in this topic, you must create an OSSClient instance by using methods such as using a custom domain name or Security Token Service (STS). For more information, see Initialization.

List a specific number of objects

The following sample code provides an example on how to list 20 objects in a bucket named examplebucket:

// Specify the bucket name, for example, examplebucket.
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// Specify the maximum number of objects to return. If you do not set this parameter, the default value is 100. The value of maxkeys cannot be greater than 1,000.
request.setMaxKeys(20);

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", objectSummary.getKey());
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        // Request exception.
        if (clientException != null) {
            // Client exception, such as a network error.
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // Server exception.
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

List objects whose names contain a specific prefix

The following sample code provides an example on how to list the objects whose names contain the file prefix in a bucket named examplebucket:

// Specify the bucket name, for example, examplebucket.
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// Specify the prefix.
// The prefix is used for fuzzy matching. The query returns objects whose names start with the specified prefix. For example, if you set the prefix to "a", all objects whose names start with "a", such as abc.txt and abcd.jpg, are returned.
request.setPrefix("file");

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", objectSummary.getKey());
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        // Request exception.
        if (clientException != null) {
            // Client exception, such as a network error.
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // Server exception.
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

List objects whose names are alphabetically after the value of marker

The following sample code provides an example on how to list the objects whose names are alphabetically after the object named exampleobject.txt in a bucket named examplebucket:

// Specify the bucket name, for example, examplebucket.
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// Specify the marker. The list operation starts from the first object that is alphabetically after the marker.
// If the specified marker does not exist in the bucket, the list operation starts from the object that is alphabetically after the marker value.
request.setMarker("exampleobject.txt");

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", objectSummary.getKey());
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        // Request exception.
        if (clientException != null) {
            // Client exception, such as a network error.
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // Server exception.
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

List all objects in a bucket by page

The following sample code provides an example on how to list all objects in a bucket named examplebucket by page. Up to 20 objects can be listed on each page.

private String marker = null;
private boolean isCompleted = false;

// List all objects by page.
public void getAllObject() {
    do {
        OSSAsyncTask task = getObjectList();
        // Block the thread and wait for the request to complete to get NextMarker. To request the next page, set the marker to the NextMarker value from the previous response. You do not need to set a marker for the first page.
        // In this example, a loop is used to list data by page. You must block the thread and wait for the request to complete to get NextMarker before you can request the next page. Determine whether to block the thread based on your scenario.
        task.waitUntilFinished();
    } while (!isCompleted);
}

// List one page of objects.
public OSSAsyncTask getObjectList() {
    // Specify the bucket name.
    ListObjectsRequest request = new ListObjectsRequest("examplebucket");
    // Specify the maximum number of objects to return per page. If you do not set this parameter, the default value is 100. The value of maxkeys cannot be greater than 1,000.
    request.setMaxKeys(20);
    request.setMarker(marker);

    OSSAsyncTask task = oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
        @Override
        public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
            for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
                Log.i("ListObjects", objectSummary.getKey());
            }
            // This is the last page.
            if (!result.isTruncated()) {
                isCompleted = true;
                return;
            }
            // The marker for the next list operation.
            marker = result.getNextMarker();
        }

        @Override
        public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
            isCompleted = true;
            // Request exception.
            if (clientException != null) {
                // Client exception, such as a network error.
                clientException.printStackTrace();
            }
            if (serviceException != null) {
                // Server exception.
                Log.e("ErrorCode", serviceException.getErrorCode());
                Log.e("RequestId", serviceException.getRequestId());
                Log.e("HostId", serviceException.getHostId());
                Log.e("RawMessage", serviceException.getRawMessage());
            }
        }
    });
    return task;
}

List objects whose names contain a specific prefix by page

The following sample code provides an example on how to list the objects whose names contain the file prefix in a bucket named examplebucket by page. Up to 20 objects can be listed on each page.

private String marker = null;
private boolean isCompleted = false;

// List all objects by page.
public void getAllObject() {
    do {
        OSSAsyncTask task = getObjectList();
        // Block the thread and wait for the request to complete to get NextMarker. To request the next page, set the marker to the NextMarker value from the previous response. You do not need to set a marker for the first page.
        // In this example, a loop is used to list data by page. You must block the thread and wait for the request to complete to get NextMarker before you can request the next page. Determine whether to block the thread based on your scenario.
        task.waitUntilFinished();
    } while (!isCompleted);
}

// List one page of objects.
public OSSAsyncTask getObjectList() {
    // Specify the bucket name.
    ListObjectsRequest request = new ListObjectsRequest("examplebucket");
    // Specify the maximum number of objects to return per page. If you do not set this parameter, the default value is 100. The value of maxkeys cannot be greater than 1,000.
    request.setMaxKeys(20);
    // Specify the prefix.
    // The prefix is used for fuzzy matching. The query returns objects whose names start with the specified prefix. For example, if you set the prefix to "a", all objects whose names start with "a", such as abc.txt and abcd.jpg, are returned.
    request.setPrefix("file");
    request.setMarker(marker);

    OSSAsyncTask task = oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
        @Override
        public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
            for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
                Log.i("ListObjects", objectSummary.getKey());
            }
            // This is the last page.
            if (!result.isTruncated()) {
                isCompleted = true;
                return;
            }
            // The marker for the next list operation.
            marker = result.getNextMarker();
        }

        @Override
        public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
            isCompleted = true;
            // Request exception.
            if (clientException != null) {
                // Client exception, such as a network error.
                clientException.printStackTrace();
            }
            if (serviceException != null) {
                // Server exception.
                Log.e("ErrorCode", serviceException.getErrorCode());
                Log.e("RequestId", serviceException.getRequestId());
                Log.e("HostId", serviceException.getHostId());
                Log.e("RawMessage", serviceException.getRawMessage());
            }
        }
    });
    return task;
}

List the objects whose names contain special characters

If the name of an object contains one of the following special characters, you must encode the object name before you transmit the object. Only URL encoding is supported in OSS.

Single quotation marks (')
Double quotations marks (")
Ampersands (&)
Angle brackets (<>)
Chinese

The following sample code provides an example on how to list the objects whose names contain special characters in a bucket named examplebucket:

// Specify the bucket name, for example, examplebucket.
ListObjectsRequest request = new ListObjectsRequest("examplebucket");
// Specify the encoding type for object names.
request.setEncodingType("url");

oss.asyncListObjects(request, new OSSCompletedCallback<ListObjectsRequest, ListObjectsResult>() {
    @Override
    public void onSuccess(ListObjectsRequest request, ListObjectsResult result) {
        for (OSSObjectSummary objectSummary : result.getObjectSummaries()) {
            Log.i("ListObjects", URLDecoder.decode(objectSummary.getKey(), "UTF-8"));
        }
    }

    @Override
    public void onFailure(ListObjectsRequest request, ClientException clientException, ServiceException serviceException) {
        // Request exception.
        if (clientException != null) {
            // Client exception, such as a network error.
            clientException.printStackTrace();
        }
        if (serviceException != null) {
            // Server exception.
            Log.e("ErrorCode", serviceException.getErrorCode());
            Log.e("RequestId", serviceException.getRequestId());
            Log.e("HostId", serviceException.getHostId());
            Log.e("RawMessage", serviceException.getRawMessage());
        }
    }
});

References

For more information about the API operations that you can call to list objects, see GetBucket (ListObjects) and ListObjectsV2(GetBucketV2).
For more information about how to initialize an OSSClient instance, see Initialization.