AWS Java SDK S3 List Objects Examples (in Bucket and Folder)

Details: Written by Nam Ha Minh; Last Updated on 03 January 2022 | Print Email

In this AWS Java SDK tutorial, you will learn how to list objects in a bucket on Amazon S3 server programmatically. In details, I’ll share about:

How to list objects in a bucket
How to list objects in a specific “folder” of a bucket
How to filter the result using prefix, max keys and delimiter

Notes: to follow this article, you must already setup AWS SDK for Java. If not, refer to this guide.

1. Understand Objects in Amazon S3

In Amazon S3, everything within a bucket is object. No concept of file or folder, even though you see “Folder” on S3 management console. A key uniquely identifies an object within a bucket.

Consider the key of an object as follows:

product-images/123/main-image.png

Here, the words product-images and 123 are just parts of the object’s key - they are not separate folders as you usually see on a file system. That’s the important difference you must know when working with S3’s objects.

2. List objects in a bucket

The following code example illustrates a command line Java program that lists objects in a given bucket on Amazon S3 server, using AWS SDK for Java:

package net.codejava.aws;

import java.util.List;
import java.util.ListIterator;

import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.ListObjectsRequest;
import software.amazon.awssdk.services.s3.model.ListObjectsResponse;
import software.amazon.awssdk.services.s3.model.S3Object;

public class ListObjectsExample1 {
	public static void main(String[] args) {
		String bucketName = "nam-public-images";
		
		S3Client client = S3Client.builder().build();

		ListObjectsRequest request = ListObjectsRequest.builder().bucket(bucketName).build();
		
		ListObjectsResponse response = client.listObjects(request);
		List<S3Object> objects = response.contents();
		
		ListIterator<S3Object> listIterator = objects.listIterator();
		
		while (listIterator.hasNext()) {
			S3Object object = listIterator.next();
			System.out.println(object.key() + " - " + object.size());
		}
	}
}

I think the code example is straightforward and self-explanatory. You need to build a ListObjectsRequest object, pass the bucket name, call listObjects() method of the S3Client object, and get the response as a ListObjectsResponse object.

And then you can get a List of S3Object from the response, use an iterator to iterate over each object in the result, and get the details of an object such as key and size. The output of the program above would look like this:

brand-logos/1/Canon.png - 4010
brand-logos/10/Samsung.png - 7594
brand-logos/11/Olympus.png - 13392
category-images/1/electronics.png - 117245
category-images/10/digital cameras.png - 29225
category-images/11/flashes.png - 23178
product-images/1/canon eos m50.png - 437094
product-images/1/extras/EOS M50 LCD.png - 196919
product-images/1/extras/EOS M50 flash opened.png - 473993
product-images/1/extras/EOS M50 incline.png - 399941
product-images/1/extras/EOS M50 straight.png - 351950

It lists up to 1,000 objects in the given bucket.

3. List objects in a specific “folder” of a bucket

In case you want to list only objects whose keys starting with a given string, use the prefix() method when building a ListObjectsRequest. The following code snippets illustrates listing objects in the “folder” named “product-images” of a given bucket:

String bucketName = "nam-public-images";
String folderName = "product-images";

S3Client client = S3Client.builder().build();

ListObjectsRequest request = ListObjectsRequest.builder()
						.bucket(bucketName)
						.prefix(folderName).build();

ListObjectsResponse response = client.listObjects(request);
List<S3Object> objects = response.contents();

ListIterator<S3Object> listIterator = objects.listIterator();

while (listIterator.hasNext()) {
	S3Object object = listIterator.next();
	System.out.println(object.key() + " - " + object.size());
}

The result contains only objects whose keys starting with the specified prefix “product-images”.

4. Limit result using max keys and delimiter

You can use the maxKeys() method to limit the maximum number of objects returned in the response. Here’s an example:

ListObjectsRequest request = ListObjectsRequest.builder()
						.bucket(bucketName)
						.prefix(folderName)
						.maxKeys(100)
						.build();

This tell Amazon S3 to send maximum 100 objects in the response.

In case you want to exclude objects whose keys contain a given string, use the delimiter() method. For example:

ListObjectsRequest request = ListObjectsRequest.builder()
						.bucket(bucketName)
						.prefix(“product-images”)
						.delimiter("extras")
						.build();

This tell Amazon S3 to get only objects whose keys starting with the prefix “product-images”, and do not contain the word “extras”.

For handling exception, you can catch these runtime exceptions which may be thrown by the listObjects() method: NoSuchBucketException, AwsServiceException, SdkClientException and S3Exception.

So that’s I have shared with you some Java code examples for listing objects in a bucket on Amazon S3 server. You also learned how to list objects in a “folder” and filter the result using max keys and delimiter.

To see the coding in action, I recommend you watch the following video:

About the Author:

Nam Ha Minh is certified Java programmer (SCJP and SCWCD). He began programming with Java back in the days of Java 1.4 and has been passionate about it ever since. You can connect with him on Facebook and watch his Java videos on YouTube.