Skip to content

Getting Started

This is an implementation of an Amazon AWS S3 FileSystem provider using JSR-203 (a.k.a. NIO2) for Java 8.

Amazon Simple Storage Service provides a fully redundant data storage infrastructure for storing and retrieving any amount of data, at any time.

NIO2 is the new file management API, introduced in Java version 7.

This project provides a complete API implementation, for managing files and folders directly in Amazon S3.

Compatibility

We aim to support only the latest LTS versions. At the moment this includes:

  • JDK 8
  • JDK 11
  • JDK 17
  • JDK 21

Please note that although we support JDK 8 we have plans to drop it in one of our next major release.

Documentation

You can check out our documentation here.

Installation

<dependency>
    <groupId>org.carlspring.cloud.aws</groupId>
    <artifactId>s3fs-nio</artifactId>
    <version>2.0.0-SNAPSHOT</version>
</dependency>

implementation("org.carlspring.cloud.aws:s3fs-nio:2.0.0-SNAPSHOT")

implementation 'org.carlspring.cloud.aws:s3fs-nio:2.0.0-SNAPSHOT'

libraryDependencies += "org.carlspring.cloud.aws" % "s3fs-nio" % "2.0.0-SNAPSHOT"

Quick start

Amazon S3 Setup

  1. Open S3 Console and add a bucket
  2. Open IAM and go to Add User
  3. Set Access Type to Programmatic Access or you will get 403 Forbidden errors.
  4. Select Attach an existing policies directly
  5. Select AmazonS3FullAccess policy and Create user (if you prefer more fine-grained access click here)
  6. Copy Access key ID and Secret access key - you will need them later!

Example

Create/load a properties file in your project which defines the following properties:

s3fs.bucket.name=/your-bucket-name-for-test
# http://docs.aws.amazon.com/general/latest/gr/rande.html 
s3fs.access.key=access-key-for-test
s3fs.secret.key=secret-key-for-test
# check software.amazon.awssdk.regions.Region for quick list
s3fs.region=eu-central-1
s3fs.protocol=https

These properties can also be exported as environment variables. A complete list is available in the Configuration Options

FileSystems.newFileSystem(URI.create("s3:///"),
                          new HashMap<>(),
                          Thread.currentThread().getContextClassLoader());

See also