https://github.com/veupathdb/lib-s34k

S3 for Kotlin
https://github.com/veupathdb/lib-s34k

aws kotlin library s3

Last synced: about 1 month ago
JSON representation

S3 for Kotlin

• Host: GitHub
• URL: https://github.com/veupathdb/lib-s34k
• Owner: VEuPathDB
• Created: 2022-04-13T22:31:40.000Z (about 4 years ago)
• Default Branch: main
• Last Pushed: 2024-02-05T19:39:21.000Z (over 2 years ago)
• Last Synced: 2025-08-06T09:50:43.343Z (11 months ago)
• Topics: aws, kotlin, library, s3
• Language: Kotlin
• Homepage:
• Size: 3.59 MB
• Stars: 0
• Watchers: 20
• Forks: 0
• Open Issues: 8
• Metadata Files:
  • Readme: readme.adoc

Awesome Lists containing this project

README

          
= S3 for Kotlin

:source-highlighter: highlightjs

image:https://img.shields.io/badge/jvm-1.8-blue[title="Compatible with JVM 1.8"]

image:https://img.shields.io/github/v/release/veupathdb/lib-s34k[title="Version"]

image:https://img.shields.io/badge/docs-javadoc-brightgreen[link="https://veupathdb.github.io/lib-s34k/javadoc"]

image:https://img.shields.io/badge/docs-dokka-brightgreen[link="https://veupathdb.github.io/lib-s34k/dokka"]

////

TODO: Region should only be optional at the client level and in params, buckets

      and objects have a region attached always.

TODO: should the tags field on BucketPutParams be moved to BPTagPutParams? Yes

TODO: Object put retention

TODO: Object put legal hold

TODO: Object put user meta

TODO: object put SSE

TODO: Version IDs

TODO: ObjectWriteOperation `tags` field should be moved down to subtypes as tags

      are not always set.

TODO: Bucket.exists method?

TODO: enable/disable legal hold

TODO: retention periods

TODO: get all tags params

TODO: param configuration functions (such as `callback(action: () -> Unit)` that

      create a more dsl like vibe

////

== 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

https://github.com/VEuPathDB/lib-s34k-minio[S34K-Minio]).

.*Adding to project*:

[source, kotlin]

----

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

----

=== Examples

.Getting an `S3Client` instance

[source, kotlin]

----

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

[source, kotlin]

----

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

[source, kotlin]

----

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