Amazon S3

/**
 * Amazon Simple Storage Service (S3) client interface
 */
public interface AmazonS3 {
    String ENDPOINT_PREFIX = "s3";
    
    // Object operations
    PutObjectResult putObject(PutObjectRequest putObjectRequest);
    PutObjectResult putObject(String bucketName, String key, String content);
    PutObjectResult putObject(String bucketName, String key, File file);
    PutObjectResult putObject(String bucketName, String key, InputStream input, ObjectMetadata metadata);
    
    S3Object getObject(GetObjectRequest getObjectRequest);
    S3Object getObject(String bucketName, String key);
    
    ObjectMetadata getObjectMetadata(GetObjectMetadataRequest getObjectMetadataRequest);
    ObjectMetadata getObjectMetadata(String bucketName, String key);
    
    void deleteObject(DeleteObjectRequest deleteObjectRequest);
    void deleteObject(String bucketName, String key);
    
    DeleteObjectsResult deleteObjects(DeleteObjectsRequest deleteObjectsRequest);
    
    CopyObjectResult copyObject(CopyObjectRequest copyObjectRequest);
    CopyObjectResult copyObject(String sourceBucketName, String sourceKey, 
                               String destinationBucketName, String destinationKey);
    
    // Bucket operations
    Bucket createBucket(CreateBucketRequest createBucketRequest);
    Bucket createBucket(String bucketName);
    
    void deleteBucket(DeleteBucketRequest deleteBucketRequest);
    void deleteBucket(String bucketName);
    
    List<Bucket> listBuckets();
    
    boolean doesBucketExist(String bucketName);
    boolean doesObjectExist(String bucketName, String objectName);
    
    // Listing operations
    ObjectListing listObjects(ListObjectsRequest listObjectsRequest);
    ObjectListing listObjects(String bucketName);
    ObjectListing listObjects(String bucketName, String prefix);
    
    ListObjectsV2Result listObjectsV2(ListObjectsV2Request listObjectsV2Request);
    
    // Lifecycle management
    void shutdown();
}

/**
 * Builder for creating Amazon S3 clients
 */
public final class AmazonS3ClientBuilder extends AwsClientBuilder<AmazonS3ClientBuilder, AmazonS3> {
    /**
     * Creates a builder with default configuration
     * @return New S3 client builder
     */
    public static AmazonS3ClientBuilder standard();
    
    /**
     * Creates a default S3 client with standard configuration
     * @return Configured S3 client using default credential chain and region
     */
    public static AmazonS3 defaultClient();
    
    /**
     * Enables path-style access for S3 (deprecated, use virtual-hosted style)
     * @param pathStyleAccessEnabled Whether to use path-style access
     * @return Builder instance for method chaining
     */
    public AmazonS3ClientBuilder withPathStyleAccessEnabled(Boolean pathStyleAccessEnabled);
    
    /**
     * Enables chunked encoding for uploads
     * @param chunkedEncodingDisabled Whether to disable chunked encoding
     * @return Builder instance for method chaining
     */
    public AmazonS3ClientBuilder withChunkedEncodingDisabled(Boolean chunkedEncodingDisabled);
    
    /**
     * Enables payload signing for all requests
     * @param payloadSigningEnabled Whether to enable payload signing
     * @return Builder instance for method chaining
     */
    public AmazonS3ClientBuilder withPayloadSigningEnabled(Boolean payloadSigningEnabled);
}

import com.amazonaws.services.s3.AmazonS3;
import com.amazonaws.services.s3.AmazonS3ClientBuilder;
import com.amazonaws.regions.Regions;

// Default S3 client
AmazonS3 s3Client = AmazonS3ClientBuilder.defaultClient();

// Custom S3 client configuration
AmazonS3 customS3Client = AmazonS3ClientBuilder.standard()
    .withRegion(Regions.US_WEST_2)
    .withPathStyleAccessEnabled(false)  // Use virtual-hosted style (recommended)
    .withPayloadSigningEnabled(true)    // Enable payload signing for security
    .build();

// Remember to shutdown when done
s3Client.shutdown();

/**
 * Request for putting an object to S3
 */
public class PutObjectRequest extends AmazonWebServiceRequest {
    /**
     * Creates a request to put object with content string
     * @param bucketName Name of the bucket
     * @param key Object key
     * @param content String content to upload
     */
    public PutObjectRequest(String bucketName, String key, String content);
    
    /**
     * Creates a request to put object with input stream
     * @param bucketName Name of the bucket
     * @param key Object key
     * @param input Input stream containing object data
     * @param metadata Object metadata
     */
    public PutObjectRequest(String bucketName, String key, InputStream input, ObjectMetadata metadata);
    
    /**
     * Creates a request to put object from file
     * @param bucketName Name of the bucket
     * @param key Object key
     * @param file File to upload
     */
    public PutObjectRequest(String bucketName, String key, File file);
    
    // Getters and setters
    public String getBucketName();
    public String getKey();
    public ObjectMetadata getMetadata();
    public InputStream getInputStream();
    public File getFile();
    
    // Server-side encryption
    public PutObjectRequest withSSESpecification(SSESpecification sseSpec);
    public PutObjectRequest withStorageClass(StorageClass storageClass);
    public PutObjectRequest withCannedAcl(CannedAccessControlList cannedAcl);
}

/**
 * Result of putting an object to S3
 */
public class PutObjectResult {
    /**
     * Gets the ETag of the uploaded object
     * @return ETag value
     */
    public String getETag();
    
    /**
     * Gets the version ID if versioning is enabled
     * @return Version ID or null
     */
    public String getVersionId();
    
    /**
     * Gets server-side encryption information
     * @return Encryption details
     */
    public String getSSEAlgorithm();
    public String getSSECustomerAlgorithm();
    public String getSSECustomerKeyMd5();
}

import com.amazonaws.services.s3.model.*;
import java.io.*;

// Upload string content
PutObjectResult result1 = s3Client.putObject("my-bucket", "hello.txt", "Hello, World!");

// Upload from file
File localFile = new File("/path/to/local/file.pdf");
PutObjectResult result2 = s3Client.putObject("my-bucket", "documents/file.pdf", localFile);

// Upload with metadata and encryption
ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("application/json");
metadata.setContentLength(1024);
metadata.addUserMetadata("purpose", "testing");

PutObjectRequest request = new PutObjectRequest("my-bucket", "data.json", inputStream, metadata)
    .withStorageClass(StorageClass.StandardIA)
    .withCannedAcl(CannedAccessControlList.PublicRead);
PutObjectResult result3 = s3Client.putObject(request);

System.out.println("ETag: " + result3.getETag());
System.out.println("Version: " + result3.getVersionId());

/**
 * Request for getting an object from S3
 */
public class GetObjectRequest extends AmazonWebServiceRequest {
    /**
     * Creates a request to get an object
     * @param bucketName Name of the bucket
     * @param key Object key
     */
    public GetObjectRequest(String bucketName, String key);
    
    /**
     * Creates a request to get a specific version of an object
     * @param bucketName Name of the bucket
     * @param key Object key
     * @param versionId Version ID of the object
     */
    public GetObjectRequest(String bucketName, String key, String versionId);
    
    // Range requests
    public GetObjectRequest withRange(long start, long end);
    public GetObjectRequest withRange(long start);
    
    // Conditional requests
    public GetObjectRequest withMatchingETagConstraint(String eTag);
    public GetObjectRequest withNonmatchingETagConstraint(String eTag);
    public GetObjectRequest withModifiedSinceConstraint(Date date);
    public GetObjectRequest withUnmodifiedSinceConstraint(Date date);
}

/**
 * S3 object containing content and metadata
 */
public class S3Object implements Closeable {
    /**
     * Gets the bucket name containing this object
     * @return Bucket name
     */
    public String getBucketName();
    
    /**
     * Gets the key (name) of this object
     * @return Object key
     */
    public String getKey();
    
    /**
     * Gets the object metadata
     * @return Object metadata
     */
    public ObjectMetadata getObjectMetadata();
    
    /**
     * Gets the object content as an input stream
     * IMPORTANT: Must be closed after use to avoid resource leaks
     * @return Input stream containing object data
     */
    public S3ObjectInputStream getObjectContent();
    
    /**
     * Closes the object content stream
     */
    public void close() throws IOException;
}

import com.amazonaws.services.s3.model.*;
import java.io.*;

// Simple object retrieval
S3Object object = s3Client.getObject("my-bucket", "hello.txt");
try (S3ObjectInputStream content = object.getObjectContent()) {
    // Read content
    String text = new BufferedReader(new InputStreamReader(content))
        .lines().collect(Collectors.joining("\n"));
    System.out.println(text);
} // Auto-closes the stream

// Get object with range (partial content)
GetObjectRequest rangeRequest = new GetObjectRequest("my-bucket", "large-file.zip")
    .withRange(0, 1023); // First 1024 bytes
S3Object partialObject = s3Client.getObject(rangeRequest);

// Get object with conditional request
GetObjectRequest conditionalRequest = new GetObjectRequest("my-bucket", "data.json")
    .withModifiedSinceConstraint(new Date(System.currentTimeMillis() - 86400000)); // If modified in last day
try {
    S3Object conditionalObject = s3Client.getObject(conditionalRequest);
    // Process object...
} catch (AmazonS3Exception e) {
    if (e.getStatusCode() == 304) {
        System.out.println("Object not modified");
    }
}

/**
 * Request for creating a bucket
 */
public class CreateBucketRequest extends AmazonWebServiceRequest {
    /**
     * Creates a request to create a bucket in the default region
     * @param bucketName Name of the bucket to create
     */
    public CreateBucketRequest(String bucketName);
    
    /**
     * Creates a request to create a bucket in a specific region
     * @param bucketName Name of the bucket to create
     * @param region AWS region for the bucket
     */
    public CreateBucketRequest(String bucketName, Region region);
    
    /**
     * Creates a request to create a bucket with specific configuration
     * @param bucketName Name of the bucket to create
     * @param bucketConfiguration Bucket configuration
     */
    public CreateBucketRequest(String bucketName, CreateBucketConfiguration bucketConfiguration);
    
    public String getBucketName();
    public Region getRegion();
    public CreateBucketConfiguration getBucketConfiguration();
    
    // Access control
    public CreateBucketRequest withCannedAcl(CannedAccessControlList cannedAcl);
}

/**
 * Represents an S3 bucket
 */
public class Bucket {
    /**
     * Gets the bucket name
     * @return Bucket name
     */
    public String getName();
    
    /**
     * Gets the bucket owner
     * @return Bucket owner information
     */
    public Owner getOwner();
    
    /**
     * Gets the bucket creation date
     * @return Creation date
     */
    public Date getCreationDate();
}

import com.amazonaws.services.s3.model.*;
import com.amazonaws.regions.Regions;

// Create bucket in default region
Bucket bucket1 = s3Client.createBucket("my-unique-bucket-name");

// Create bucket in specific region
Bucket bucket2 = s3Client.createBucket(
    new CreateBucketRequest("my-eu-bucket", Region.EU_West_1)
);

// Create private bucket with specific ACL
CreateBucketRequest request = new CreateBucketRequest("my-private-bucket")
    .withCannedAcl(CannedAccessControlList.Private);
Bucket privateBucket = s3Client.createBucket(request);

// List all buckets
List<Bucket> buckets = s3Client.listBuckets();
for (Bucket bucket : buckets) {
    System.out.println("Bucket: " + bucket.getName() + 
                      ", Created: " + bucket.getCreationDate());
}

// Check if bucket exists
boolean exists = s3Client.doesBucketExist("my-bucket");
if (exists) {
    System.out.println("Bucket exists");
}

// Delete empty bucket
s3Client.deleteBucket("bucket-to-delete");

/**
 * Request for listing objects in a bucket
 */
public class ListObjectsRequest extends AmazonWebServiceRequest {
    /**
     * Creates a request to list objects in a bucket
     * @param bucketName Name of the bucket
     */
    public ListObjectsRequest(String bucketName);
    
    // Filtering options
    public ListObjectsRequest withPrefix(String prefix);
    public ListObjectsRequest withDelimiter(String delimiter);
    public ListObjectsRequest withMarker(String marker);
    public ListObjectsRequest withMaxKeys(Integer maxKeys);
    
    public String getBucketName();
    public String getPrefix();
    public String getDelimiter();
    public String getMarker();
    public Integer getMaxKeys();
}

/**
 * Result of listing objects in a bucket
 */
public class ObjectListing {
    /**
     * Gets the list of object summaries
     * @return List of objects in the bucket
     */
    public List<S3ObjectSummary> getObjectSummaries();
    
    /**
     * Gets common prefixes (for delimiter-based listing)
     * @return List of common prefixes
     */
    public List<String> getCommonPrefixes();
    
    /**
     * Checks if the listing is truncated (more objects available)
     * @return true if more objects are available
     */
    public boolean isTruncated();
    
    /**
     * Gets the marker for the next page of results
     * @return Next marker for pagination
     */
    public String getNextMarker();
    
    public String getBucketName();
    public String getPrefix();
    public String getDelimiter();
    public int getMaxKeys();
}

/**
 * Summary information about an S3 object
 */
public class S3ObjectSummary {
    public String getBucketName();
    public String getKey();
    public String getETag();
    public long getSize();
    public Date getLastModified();
    public String getStorageClass();
    public Owner getOwner();
}

import com.amazonaws.services.s3.model.*;

// List all objects in bucket
ObjectListing listing = s3Client.listObjects("my-bucket");
for (S3ObjectSummary object : listing.getObjectSummaries()) {
    System.out.println("Object: " + object.getKey() + 
                      ", Size: " + object.getSize() + 
                      ", Modified: " + object.getLastModified());
}

// List objects with prefix (folder-like structure)
ObjectListing photosListing = s3Client.listObjects("my-bucket", "photos/");

// List objects with pagination
ListObjectsRequest request = new ListObjectsRequest("my-bucket")
    .withPrefix("logs/")
    .withMaxKeys(100);

do {
    ObjectListing page = s3Client.listObjects(request);
    for (S3ObjectSummary object : page.getObjectSummaries()) {
        System.out.println("Log file: " + object.getKey());
    }
    request.setMarker(page.getNextMarker());
} while (listing.isTruncated());

// List with delimiter for folder simulation
ListObjectsRequest folderRequest = new ListObjectsRequest("my-bucket")
    .withPrefix("documents/")
    .withDelimiter("/");
ObjectListing folderListing = s3Client.listObjects(folderRequest);

// Process "folders" (common prefixes)
for (String folder : folderListing.getCommonPrefixes()) {
    System.out.println("Folder: " + folder);
}

/**
 * Object metadata containing content information and user-defined metadata
 */
public class ObjectMetadata {
    public void setContentType(String contentType);
    public String getContentType();
    public void setContentLength(long contentLength);
    public long getContentLength();
    public void setContentEncoding(String contentEncoding);
    public String getContentEncoding();
    public void setContentDisposition(String contentDisposition);
    public String getContentDisposition();
    public void setCacheControl(String cacheControl);
    public String getCacheControl();
    
    // User metadata
    public void addUserMetadata(String key, String value);
    public Map<String, String> getUserMetadata();
    
    // System metadata
    public String getETag();
    public Date getLastModified();
    public String getVersionId();
    public String getStorageClass();
}

/**
 * Storage classes for S3 objects
 */
public enum StorageClass {
    Standard,
    ReducedRedundancy,
    StandardIA,        // Standard Infrequent Access
    OneZoneIA,         // One Zone Infrequent Access
    Glacier,
    DeepArchive,
    IntelligentTiering
}

/**
 * Predefined access control lists
 */
public enum CannedAccessControlList {
    Private,
    PublicRead,
    PublicReadWrite,
    AuthenticatedRead,
    LogDeliveryWrite,
    BucketOwnerRead,
    BucketOwnerFullControl,
    AwsExecRead
}

/**
 * Owner information for S3 resources
 */
public class Owner {
    public String getId();
    public String getDisplayName();
}