LocalS3
LocalS3 is an Amazon S3 mock service for testing and local development. LocalS3 is based on Netty and without heavy dependencies, it starts up quickly and handles requests efficiently.
Supported Amazon S3 APIs
- AbortMultipartUpload
- CopyObject
- CreateBucket
- CreateMultipartUpload
- CompleteMultipartUpload
- DeleteBucket
- DeleteBucketEncryption
- DeleteBucketPolicy
- DeleteBucketReplication
- DeleteBucketTagging
- DeleteObject
- DeleteObjects
- DeleteObjectTagging
- GetObject
- GetObjectTagging
- GetBucketAcl
- GetBucketEncryption
- GetBucketPolicy
- GetBucketReplication
- GetBucketVersioning
- GetBucketTagging
- GetBucketLocation
- HeadBucket
- HeadObject
- ListBuckets
- ListObjects
- ListObjectsV2
- ListObjectVersions
- ListParts
- PutBucketAcl
- PutBucketEncryption
- PutBucketPolicy
- PutBucketReplication
- PutBucketVersioning
- PutBucketTagging
- PutObject
- PutObjectTagging
- UploadPart
Features
- Support S3 object versioning.
- In memory and persistence mode.
Usages
Programming with LocalS3
Developers could integrate LocalS3 into their own Java applications or testing frameworks via Java APIs.
Dependency
<dependency>
<groupId>io.github.robothy</groupId>
<artifactId>local-s3-rest</artifactId>
</dependency>
Run LocalS3 in In-Memory mode
By default, LocalS3 runs in In-Memory mode; all data and metadata retain in the memory.
LocalS3 localS3 = LocalS3.builder()
.port(19090)
.build();
localS3.start();
Call the stop method to shut down the service gracefully.
localS3.shutdown();
Run LocalS3 in Persistence mode
When LocalS3 runs in persistence mode, a data path is required. LocalS3 loads data from and stores all data into the specified path.
LocalS3 localS3 = LocalS3.builder()
.port(19090)
.mode(LocalS3Mode.PERSISTENCE)
.dataDirectory("C://local-s3")
.build();
localS3.start();
Run LocalS3 in In-Memory mode with initial data.
LocalS3 loads initial data from the specified path. Changes on such LocalS3 instance only modify the data in memory, not persist to the disk.
LocalS3 localS3 = LocalS3.builder()
.port(-1) // assign a random port
.dataDirectory("/data")
.build();
localS3.start();
LocalS3 for Junit5
LocalS3 for Junit5 provides a Java annotation @LocalS3
helps you easily launch S3 services for your tests.
Dependency
<dependency>
<groupId>io.github.robothy</groupId>
<artifactId>local-s3-jupiter</artifactId>
<scope>test</scope>
</dependency>
When you annotate it on test classes or test methods, the LocalS3 extension automatically inject instances for AmazonS3 parameters of test methods.
@LocalS3
class AppTest {
@Test
void test(AmazonS3 s3) {
s3.createBucket("my-bucket");
}
}
@LocalS3
on test classes and test methods
Difference between If @LocalS3
is on a test class, the Junit5 extension will create a shared service for all test methods in the class
and shut it down in the "after all" callback.
If @LocalS3
is on a test method, the extension creates an exclusive service for the method and shut down the
service in the "after each" callback.
Run LocalS3 in Docker
You can run LocalS3 in Docker since it's image is published to DockerHub.
docker run --name s3 -d -v C:\\local-s3:/data -p 8080:80 luofuxiang/local-s3
LocalS3 test container
LocalS3 provides a testcontainers implementation. You can run LocalS3 in your tests with testcontainers API.
Dependency
<dependency>
<groupId>io.github.robothy</groupId>
<artifactId>local-s3-testcontainers</artifactId>
</dependency>
Start LocalS3 with testcontainers
@Testcontainers
public class AppTest {
@Container
public LocalS3Container container = new LocalS3Container("latest")
.withMode(LocalS3Container.Mode.IN_MEMORY)
.withRandomHttpPort();
@Test
void test() {
assertTrue(container.isRunning());
int port = container.getPort();
AmazonS3 s3 = AmazonS3ClientBuilder.standard()
.enablePathStyleAccess()
.withClientConfiguration(new ClientConfiguration().withSocketTimeout(1000).withConnectionTimeout(1000))
.withEndpointConfiguration(new AwsClientBuilder.EndpointConfiguration(
"http://localhost:" + port, "local"
)).build();
s3.createBucket("my-bucket");
}
}