List files in the storage space

Updated at：2025-11-03

The BOS SDK allows users to list objects in the following two ways:

Simple listing
Advanced listing via parameters

In addition, users can also simulate folders while listing files. For the complete sample code, please refer to File Listing Demo

Simple listing

To quickly and easily list the needed files, users can use the listObjects method, which returns a ListObjectsResponse object containing the results of the listObject request. Users can retrieve details of all objects using the getContents method in the ListObjectsResponse.

                Java
                
            

                public void listObjects(BosClient client, String bucketName) {
 // Obtain all object information under the specified bucket
    ListObjectsResponse listing = client.listObjects(bucketName);
 // Traverse all objects
    for (BosObjectSummary objectSummary : listing.getContents()) {
        System.out.println("ObjectKey: " + objectSummary.getKey());
    }
}
            

Note:

By default, if the number of objects in the bucket exceeds 1,000, only 1,000 objects will be returned. In this case, the IsTruncated value in the returned result will be set to True, and NextMarker will be provided as the starting point for the next retrieval.

To retrieve more objects, the marker parameter can be used to enable batch reading.

Advanced listing via parameters

In addition to simple listing, users can achieve various flexible queries by adjusting the parameters of ListObjectsRequest. The available parameters for ListObjectsRequest include:

Parameters	Function	Usage method
Prefix	Restrict the returned object keys to those starting with a specific prefix	setPrefix(String prefix)
Delimiter	A character used to group object names. Only objects containing the specified prefix and appearing for the first time are included. Objects between the delimiter characters are treated as a single group element: CommonPrefixes.	setDelimiter(String delimiter)
Marker	Set the result to start returning from the first object in alphabetical order after the marker	setMarker(String marker)
MaxKeys	Set the maximum number of objects to return, with a default and upper limit of 1,000. Specifying a value greater than 1,000 will default to 1,000.	setMaxKeys(int maxKeys)

Note:

If there is an object named with the prefix, querying only by prefix will return all keys, including the object with the prefix.

If there is an object named with the prefix, querying with both a prefix and a delimiter will result in Null for all returned keys, and the key names will not include the prefix.

The following are several examples to illustrate the method of listing via parameters:

Specify the maximum number of returned items

                Java
                
            

                //Specify the maximum number of returned items as 500
ListObjectsRequest listObjectsRequest = new ListObjectsRequest("bucketName");
listObjectsRequest.withMaxKeys(500);
ListObjectsResponse listObjectsResponse = client.listObjects(listObjectsRequest);
for(BosObjectSummary objectSummary :listObjectsResponse.getContents()) {
    System.out.println("ObjectKey:" + objectSummary.getKey());
}
            

Return objects with a specified prefix

                Java
                
            

                //Specify to return objects with the prefix “test"
ListObjectsRequest listObjectsRequest = new ListObjectsRequest("bucketName");
listObjectsRequest.withPrefix("test");
ListObjectsResponse listObjectsResponse = client.listObjects(listObjectsRequest);
for(BosObjectSummary objectSummary :listObjectsResponse.getContents()) {
    System.out.println("ObjectKey:" + objectSummary.getKey());
}
            

Return from after a specified object

                Java
                
            

                //Users can define to exclude a certain object and start returning from after it
ListObjectsRequest listObjectsRequest = new ListObjectsRequest("bucketName");
listObjectsRequest.withMarker("object");
ListObjectsResponse listObjectsResponse = client.listObjects(listObjectsRequest);
for(BosObjectSummary objectSummary :listObjectsResponse.getContents()) {
    System.out.println("ObjectKey:" + objectSummary.getKey());
}
            

Pagination to get all objects

                Java
                
            

                //Users can set a maximum of 500 records per page
ListObjectsRequest listObjectsRequest = new ListObjectsRequest("bucketName");
listObjectsRequest.withMaxKeys(500);
ListObjectsResponse listObjectsResponse;
boolean isTruncated = true;
while (isTruncated) {
    listObjectsResponse = client.listObjects(listObjectsRequest);
    isTruncated = listObjectsResponse.isTruncated();
    if (listObjectsResponse.getNextMarker() != null) {
        listObjectsRequest.withMarker(listObjectsResponse.getNextMarker());
    }
}
            

Results of paginated restoration of all objects after a specific object

                Java
                
            

                //Users can set a maximum of 500 records per page and start getting from after a specific object
ListObjectsRequest listObjectsRequest = new ListObjectsRequest("bucketName");
listObjectsRequest.withMaxKeys(500);
listObjectsRequest.withMarker("object");
ListObjectsResponse listObjectsResponse;
boolean isTruncated = true;
while (isTruncated) {
    listObjectsResponse = client.listObjects(listObjectsRequest);
    isTruncated = listObjectsResponse.isTruncated();
    if (listObjectsResponse.getNextMarker() != null) {
        listObjectsRequest.withMarker(listObjectsResponse.getNextMarker());
    }
}
            

Results of paginated restoration of all objects after a specific object

                Java
                
            

                //Users can set pagination to get objects with a specified prefix, with a maximum of 500 records per page
ListObjectsRequest listObjectsRequest = new ListObjectsRequest("bucketName");
listObjectsRequest.withMaxKeys(500);
listObjectsRequest.withPrefix("object");
ListObjectsResponse listObjectsResponse;
boolean isTruncated = true;
while (isTruncated) {
    listObjectsResponse = client.listObjects(listObjectsRequest);
    isTruncated = listObjectsResponse.isTruncated();
    if (listObjectsResponse.getNextMarker() != null) {
        listObjectsRequest.withMarker(listObjectsResponse.getNextMarker());
    }
}
            

The parameters available for calling in the resolution class returned by the listObject method are as follows:

Parameters	Description
name	Bucket name
prefix	The matched objects from prefix to the first Delimiter character are returned as a group of elements
marker	Starting point of this query
maxKeys	Maximum number of requests returned
isTruncated	Indicate whether all queries are returned; false - all results are returned this time; true - not all results are returned this time
contents	A container for the returned objects
+key	Object name
+lastModified	Last modification time of the object
+eTag	The HTTP protocol entity tag of object.
+storageClass	Storage class of object
+size	The size of the object content (in bytes)
+owner	User information of the bucket corresponding to the object
++id	User ID of bucket owner
++displayName	Name of bucket owner

Simulate folder function

In BOS storage, there is no concept of folders. All elements are stored as objects. However, when using data, BOS users often need to manage files in folders. Therefore, BOS provides the ability to create simulated folders, which essentially involves creating an object with a size of 0. This object can be uploaded and downloaded, but the console will display objects ending with “/” as folders.

By combining the delimiter and prefix parameters, users can simulate folder functionalities. The combined effect of delimiter and prefix is as follows:

If prefix is set to a folder name, files starting with the prefix can be listed, including all files and subfolders (directory) recursively listed under the folder. File names are displayed in contents. If delimiter is set to /, the return values only list the files and subfolders (directory) under the folder. The names of subfolders (directory) under the folder are returned in the CommonPrefixes. The files and folders recursively listed under the subfolders are not displayed.

The following are several application methods:

List all files in the bucket

When users need to get all files under a bucket, they can refer to [Pagination to Get All Objects](#Advanced listing via parameters)

Recursively list all files in a directory

You can obtain all files in the a directory by setting the Prefix parameter:

                Java
                
            

                // Construct a ListObjectsRequest request
ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
    
 // Recursively list all files under the fun directory
listObjectsRequest.setPrefix("fun/");
    
ListObjectsResponse listing = client.listObjects(listObjectsRequest);
    
 // Traverse all objects
System.out.println("Objects:");
for (BosObjectSummary objectSummary : listing.getContents()) {
    System.out.println(objectSummary.getKey());
	}
}
            

Output:

Plain Text

1Objects:
2fun/
3fun/movie/001.avi
4fun/movie/007.avi
5fun/test.jpg

View files and subdirectories in a directory

With the combination of Prefix and Delimiter, it can list files and subdirectories under the directory:

                Java
                
            

                // Construct a ListObjectsRequest request
ListObjectsRequest listObjectsRequest = new ListObjectsRequest(bucketName);
    
 // "/" is the delimiter for folders
listObjectsRequest.setDelimiter("/");
    
 //List all files and folders under the “fun” directory
listObjectsRequest.setPrefix("fun/");
    
ListObjectsResponse listing = client.listObjects(listObjectsRequest);
    
 // Traverse all objects
System.out.println("Objects:");
for (BosObjectSummary objectSummary : listing.getContents()) {
    System.out.println(objectSummary.getKey());
}
    
 // Traverse all CommonPrefix
System.out.println("\nCommonPrefixs:");
for (String commonPrefix : listing.getCommonPrefixes()) {
    System.out.println(commonPrefix);
}
            

Output:

Plain Text

1Objects:
2fun/
3fun/test.jpg
4
5CommonPrefixs:
6fun/movie/

In the returned results, the list in ObjectSummaries shows the files under the fun directory. The list in CommonPrefixs shows all subfolders under the fun directory. It can be seen that the two files fun/movie/001.avi and fun/movie/007.avi are not listed because they belong to the movie directory under the fun folder.

List storage properties of objects in a bucket

After users complete the upload, if they need to view the storage class properties of all objects in a specified bucket, it can be achieved through the following code:

                Java
                
            

                public void listObjectsStorageClass(){
    ListObjectsResponse listObjectResponse = client.listObjects("bucketName");
    List<BosObjectSummary> objectList = listObjectResponse.getContents();
    for(int i=0; i<objectList.length(); i++) {
        System.out.println(objectList[i].getStorageClass());
    }
}
            

Restore archived storage class files

Object Tag