# Hello Amazon S3 directory buckets
Hello Amazon S3 directory buckets
The following code example shows how to get started using Amazon S3 directory buckets.
------
#### [ Java ]
**SDK for Java 2.x**
There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/s3/src/main/java/com/example/s3/directorybucket#code-examples).
```
package com.example.s3.directorybucket;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.Bucket;
import software.amazon.awssdk.services.s3.model.BucketInfo;
import software.amazon.awssdk.services.s3.model.BucketType;
import software.amazon.awssdk.services.s3.model.CreateBucketConfiguration;
import software.amazon.awssdk.services.s3.model.CreateBucketRequest;
import software.amazon.awssdk.services.s3.model.CreateBucketResponse;
import software.amazon.awssdk.services.s3.model.DataRedundancy;
import software.amazon.awssdk.services.s3.model.DeleteBucketRequest;
import software.amazon.awssdk.services.s3.model.ListDirectoryBucketsRequest;
import software.amazon.awssdk.services.s3.model.ListDirectoryBucketsResponse;
import software.amazon.awssdk.services.s3.model.LocationInfo;
import software.amazon.awssdk.services.s3.model.LocationType;
import software.amazon.awssdk.services.s3.model.S3Exception;
import java.util.List;
import java.util.stream.Collectors;
import static com.example.s3.util.S3DirectoryBucketUtils.createS3Client;
/**
* Before running this example:
*
* The SDK must be able to authenticate AWS requests on your behalf. If you have
* not configured
* authentication for SDKs and tools, see
* https://docs.aws.amazon.com/sdkref/latest/guide/access.html in the AWS SDKs
* and Tools Reference Guide.
*
* You must have a runtime environment configured with the Java SDK.
* See
* https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html in
* the Developer Guide if this is not set up.
*
* To use S3 directory buckets, configure a gateway VPC endpoint. This is the
* recommended method to enable directory bucket traffic without
* requiring an internet gateway or NAT device. For more information on
* configuring VPC gateway endpoints, visit
* https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-networking.html#s3-express-networking-vpc-gateway.
*
* Directory buckets are available in specific AWS Regions and Zones. For
* details on Regions and Zones supporting directory buckets, see
* https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-networking.html#s3-express-endpoints.
*/
public class HelloS3DirectoryBuckets {
private static final Logger logger = LoggerFactory.getLogger(HelloS3DirectoryBuckets.class);
public static void main(String[] args) {
String bucketName = "test-bucket-" + System.currentTimeMillis() + "--usw2-az1--x-s3";
Region region = Region.US_WEST_2;
String zone = "usw2-az1";
S3Client s3Client = createS3Client(region);
try {
// Create the directory bucket
createDirectoryBucket(s3Client, bucketName, zone);
logger.info("Created bucket: {}", bucketName);
// List all directory buckets
List bucketNames = listDirectoryBuckets(s3Client);
bucketNames.forEach(name -> logger.info("Bucket Name: {}", name));
} catch (S3Exception e) {
logger.error("An error occurred during S3 operations: {} - Error code: {}",
e.awsErrorDetails().errorMessage(), e.awsErrorDetails().errorCode(), e);
} finally {
try {
// Delete the created bucket
deleteDirectoryBucket(s3Client, bucketName);
logger.info("Deleted bucket: {}", bucketName);
} catch (S3Exception e) {
logger.error("Failed to delete the bucket due to S3 error: {} - Error code: {}",
e.awsErrorDetails().errorMessage(), e.awsErrorDetails().errorCode(), e);
} catch (RuntimeException e) {
logger.error("Failed to delete the bucket due to unexpected error: {}", e.getMessage(), e);
} finally {
s3Client.close();
}
}
}
/**
* Creates a new S3 directory bucket in a specified Zone (For example, a
* specified Availability Zone in this code example).
*
* @param s3Client The S3 client used to create the bucket
* @param bucketName The name of the bucket to be created
* @param zone The region where the bucket will be created
* @throws S3Exception if there's an error creating the bucket
*/
public static void createDirectoryBucket(S3Client s3Client, String bucketName, String zone) throws S3Exception {
logger.info("Creating bucket: {}", bucketName);
CreateBucketConfiguration bucketConfiguration = CreateBucketConfiguration.builder()
.location(LocationInfo.builder()
.type(LocationType.AVAILABILITY_ZONE)
.name(zone).build())
.bucket(BucketInfo.builder()
.type(BucketType.DIRECTORY)
.dataRedundancy(DataRedundancy.SINGLE_AVAILABILITY_ZONE)
.build())
.build();
try {
CreateBucketRequest bucketRequest = CreateBucketRequest.builder()
.bucket(bucketName)
.createBucketConfiguration(bucketConfiguration).build();
CreateBucketResponse response = s3Client.createBucket(bucketRequest);
logger.info("Bucket created successfully with location: {}", response.location());
} catch (S3Exception e) {
logger.error("Error creating bucket: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
/**
* Lists all S3 directory buckets.
*
* @param s3Client The S3 client used to interact with S3
* @return A list of bucket names
*/
public static List listDirectoryBuckets(S3Client s3Client) {
logger.info("Listing all directory buckets");
try {
// Create a ListBucketsRequest
ListDirectoryBucketsRequest listBucketsRequest = ListDirectoryBucketsRequest.builder().build();
// Retrieve the list of buckets
ListDirectoryBucketsResponse response = s3Client.listDirectoryBuckets(listBucketsRequest);
// Extract bucket names
List bucketNames = response.buckets().stream()
.map(Bucket::name)
.collect(Collectors.toList());
return bucketNames;
} catch (S3Exception e) {
logger.error("Failed to list buckets: {} - Error code: {}", e.awsErrorDetails().errorMessage(),
e.awsErrorDetails().errorCode(), e);
throw e;
}
}
/**
* Deletes the specified S3 directory bucket.
*
* @param s3Client The S3 client used to interact with S3
* @param bucketName The name of the bucket to delete
*/
public static void deleteDirectoryBucket(S3Client s3Client, String bucketName) {
try {
DeleteBucketRequest deleteBucketRequest = DeleteBucketRequest.builder()
.bucket(bucketName)
.build();
s3Client.deleteBucket(deleteBucketRequest);
} catch (S3Exception e) {
logger.error("Failed to delete bucket: " + bucketName + " - Error code: " + e.awsErrorDetails().errorCode(),
e);
throw e;
}
}
}
```
+ For API details, see the following topics in *AWS SDK for Java 2.x API Reference*.
+ [CreateBucket](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/CreateBucket)
+ [ListDirectoryBuckets](https://docs.aws.amazon.com/goto/SdkForJavaV2/s3-2006-03-01/ListDirectoryBuckets)
------
For a complete list of AWS SDK developer guides and code examples, see [Developing with Amazon S3 using the AWS SDKs](sdk-general-information-section.md). This topic also includes information about getting started and details about previous SDK versions.