s34k/org.veupathdb.lib.s3.s34k.objects/ObjectContainer

ObjectContainer

S3 Object Container

Represents a segment of an S3 store that may contain objects. This could either be a bucket or a 'directory'.

All paths for all methods defined in this type are treated as relative to the root of the container. In the case of a bucket, all paths are absolute paths to the bucket root. In the case of a 'directory', all paths are relative to the directory prefix. The exception to this is paths starting with a leading '/' character which will be treated as absolute paths in all cases.

Managing Object Tags

This interface does not define any methods for managing object tags. To work with object tags use one of the object access methods contained in this type, such as withObject or get which will give access to an S3Object instance without opening a stream over that object's contents.

Example:

container.withObject("my/object") {
  tags.put("something", "something else")
}

container["my/object"].tags.put("something", "something else")

TODO: Handle delete markers TODO: Version IDs TODO: Governance Mode

Author

Elizabeth Paige Harper https://github.com/Foxcapades

Since

v0.3.0

Functions

contains

abstract operator fun contains(path: String): Boolean

Tests whether this object container contains an object at the given path.

abstract fun contains(path: String, action: ObjectExistsParams.() -> Unit): Boolean

abstract fun contains(path: String, params: ObjectExistsParams): Boolean

Tests whether this object container contains an object at the configured target path.

countAll

abstract fun countAll(filter: (String) -> Boolean): UInt

Returns a count of all the objects in this object container, filtered by the given predicate function.

abstract fun countAll(pathPrefix: String? = null): UInt

Returns a count of all the objects in this object container, optionally filtered by a given path prefix.

countSubDirs

abstract fun countSubDirs(parent: String? = null): UInt

Returns a count of first level subdirectories directly under the given parent directory name.

delete

abstract fun delete(path: String)

abstract fun delete(path: String, action: DeleteParams.() -> Unit)

abstract fun delete(path: String, params: DeleteParams)

Deletes the object at the target path from this container.

deleteAll

abstract fun deleteAll(vararg paths: String)

abstract fun deleteAll(action: MultiObjectDeleteParams.() -> Unit)

abstract fun deleteAll(paths: Iterable<String>)

abstract fun deleteAll(params: MultiObjectDeleteParams)

Deletes all the given target objects from this container.

download

abstract fun download(path: String, localFile: File): FileObject

Fetches the object at the target path and downloads it into the specified local file.

abstract fun download(path: String, action: ObjectDownloadParams.() -> Unit): FileObject

abstract fun download(path: String, params: ObjectDownloadParams): FileObject

Fetches the object at the configured path and downloads it into the target local file.

get

abstract operator fun get(path: String): S3Object?

abstract fun get(path: String, action: ObjectGetParams.() -> Unit): S3Object?

abstract fun get(path: String, params: ObjectGetParams): S3Object?

list

abstract fun list(action: ObjectListParams.() -> Unit): ObjectList

abstract fun list(prefix: String? = null): ObjectList

abstract fun list(params: ObjectListParams): ObjectList

listAll

abstract fun listAll(): ObjectList

abstract fun listAll(action: ObjectListAllParams.() -> Unit): ObjectList

abstract fun listAll(params: ObjectListAllParams): ObjectList

Fetches a list of all the objects in this container.

listSubPaths

abstract fun listSubPaths(action: SubPathListParams.() -> Unit): SubPathListing

abstract fun listSubPaths(params: SubPathListParams): SubPathListing

abstract fun listSubPaths(prefix: String, delimiter: String = "/"): SubPathListing

open

abstract fun open(path: String): StreamObject?

Fetches the object at the target path and returns a handle on it which can be used to stream out the target object's contents.

abstract fun open(path: String, action: ObjectOpenParams.() -> Unit): StreamObject?

abstract fun open(path: String, params: ObjectOpenParams): StreamObject?

Fetches the configured target object and returns a handle on it which can be used to stream out the target object's contents.

put

abstract fun put(path: String, stream: InputStream): S3Object

Creates or overwrites an object at the specified path with its contents uploaded from the given stream.

abstract fun put(path: String, action: StreamingObjectPutParams.() -> Unit): S3Object

abstract fun put(path: String, params: StreamingObjectPutParams): S3Object

Creates or overwrites an object at the configured path with its contents uploaded from the configured stream.

rmdir

abstract fun rmdir(path: String)

abstract fun rmdir(path: String, action: DirectoryDeleteParams.() -> Unit)

abstract fun rmdir(path: String, params: DirectoryDeleteParams)

Recursively removes all contents in the target directory.

set

open operator fun set(path: String, file: File): S3Object

Uploads the specified file to this container at the given path, overwriting any object presently at that path.

open operator fun set(path: String, stream: InputStream): S3Object

Creates or overwrites an object at the specified path with its contents uploaded from the given stream.

stat

abstract fun stat(path: String): ObjectMeta?

abstract fun stat(path: String, action: ObjectStatParams.() -> Unit): ObjectMeta?

abstract fun stat(path: String, params: ObjectStatParams): ObjectMeta?

Fetches metadata for the object at the target path.

touch

abstract fun touch(path: String): S3Object

abstract fun touch(path: String, action: ObjectTouchParams.() -> Unit): S3Object

abstract fun touch(path: String, params: ObjectTouchParams): S3Object

Creates an empty object at the specified path if one does not already exist.

upload

abstract fun upload(path: String, file: File): S3Object

Uploads the specified file to this container at the given path, overwriting any object presently at that path.

abstract fun upload(path: String, action: FileUploadParams.() -> Unit): S3Object

abstract fun upload(path: String, params: FileUploadParams): S3Object

Uploads the configured file to this container at the configured path, overwriting any object presently at that path.

withObject

abstract fun <R> withObject(path: String, action: S3Object.() -> R): R

Executes the given action on the target object.