Skip to content

Latest commit

 

History

History
161 lines (122 loc) · 3.7 KB

readme.adoc

File metadata and controls

161 lines (122 loc) · 3.7 KB

S3 for Kotlin

jvm 1 lib s34k docs javadoc brightgreen docs dokka brightgreen

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