S3 for Kotlin

Usage

S34K defines the base API for a generalized abstraction layer over S3 API clients and SDKs treating the target S3 store as a remote filesystem.

This project and repository simply defines a standard API and does not provide any functionality on its own.

Usage of this API is done through specific implementations (such as S34K-Minio).

Adding to project:

    implementation("org.veupathdb.lib.s3:s34k:0.11.0")

Examples

Getting an S3Client instance

fun main() {
  val client = S3Api.newClient(S3Config(
    url       = "my-s3-host",
    accessKey = System.getenv("S3_ACCESS_KEY"),
    secretKey = System.getenv("S3_SECRET_KEY"),
  ))
}

Upserting a bucket

fun main() {
  val client = S3Api.newClient(...)

  // Simple call
  val bucket1 = client.buckets.createIfNotExists("my-bucket-1")

  // Customized call
  val bucket2 = client.buckets.createIfNotExists {
    bucketName = "my-bucket-2"
    headers.add("x-my-custom-header", "some value")
    tags.add("some-tag", "some tag value")
  }
}

Uploading a file

fun main() {
  val client = S3Api.newClient(...)
  val bucket = client.getBucket("my-bucket")

  // Simple call
  bucket.objects.upload("my/object/key", File("/path/to/some/local/file"))

  // Customized call
  bucket.objects.upload {
    path      = "my/object/key2"
    localFile = File("/path/to/some/file")
    partSize  = 26_214_400 // 25MiB
    tags.add(
      "foo"  to "bar",
      "fizz" to "buzz",
    )
  }
}

Operations

The following operations are currently supported as of v0.4.0

Bucket

Bucket operations are accessible through the buckets property on the S3Client type.

Bucket Operations:

• Create

• Delete

• Delete recursive

• Exists Test

• List buckets

Bucket tag operations are accessible through the tags property on the S3Bucket type.

Bucket Tag Operations:

• Delete tags (all)

• Delete tags (targeted)

• Get tags

• Put tags

Object

Object operations are accessible through the objects property on the S3Bucket type.

Object Operations:

• Bucket contains object

• Count objects in bucket

• Count 'directories' in bucket

• Delete Object

• Delete Objects (targeted)

• Download

• Exists test

• List all objects

• List prefixed objects

• Open (stream over contents)

• Put Object

• Remove 'directory'

• Stat

• Touch object

• Upload object

Object tag operations are accessible through the tags property on the S3Object type.

Object Tag Operations:

• Delete Tags (all)

• Delete Tags (targeted)

• Get Tags

• Put Tags