Package 

Interface ObjectContainer

  • All Implemented Interfaces:
    
public interface ObjectContainer

    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.

    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

    • Constructor Detail

    • Method Detail

      • withObject

         abstract <R extends Any> R withObject(String path, Function1<S3Object, R> action)

        Executes the given action on the target object.

        Parameters:
        path - Path/key to the target object.
        action - Action that will be called on the S3Object handle on the target object.

      • contains

         abstract Boolean contains(String path)

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

        Parameters:
        path - Path to the object to test for.

      • contains

         abstract Boolean contains(String path, Function1<ObjectExistsParams, Unit> action)

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

        Parameters:
        action - Action used to configure the backing S3 operation.

      • contains

         abstract Boolean contains(String path, ObjectExistsParams params)

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

        Parameters:
        params - Parameters for the backing S3 operation.

      • countAll

         abstract UInt countAll(String pathPrefix)

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

        If no path prefix is provided, all paths in this object container will be counted regardless of nested directory depth.

        If a path prefix is provided, only paths in this object container whose path name begins with pathPrefix will be counted.

        Parameters:
        pathPrefix - Optional filtering prefix.

      • countAll

         abstract UInt countAll(Function1<String, Boolean> filter)

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

        The given predicate function will be given each path individually, only those paths on which the predicate returns true will be counted.

        Parameters:
        filter - Predicate that will be used to determine which paths to count and which not to.

      • countSubDirs

         abstract UInt countSubDirs(String parent)

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

        Examples

        For these examples our object container is a bucket named "my-bucket".

        Given contents of "my-bucket":

        /foo/bar.txt
/bazz.txt
/fizz/buzz/flamingo.txt
/fizz/buzz/grapes.png

        If we run the command:

        container.countSubDirs()

        The result will be 2, as at the root of the container the direct subdirectories are my-bucket/foo/ and my-bucket/fizz/.

        If we run the command:

        container.countSubDirs("foo")

        The result will be 0 as the path my-bucket/foo/ contains no direct subdirectories.

        If we run the command:

        container.countSubDirs("fizz")

        The result will be 1 as the path my-bucket/fizz/ contains the direct subdirectory ./buzz/

        Parameters:
        parent - Name of the parent directory under which the subdirectories will be listed.

      • open

         abstract StreamObject open(String path)

        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.

        If the target path does not exist, or is a directory, null will be returned.

        Parameters:
        path - Path to the target object.

      • open

         abstract StreamObject open(String path, Function1<ObjectOpenParams, Unit> action)

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

        If the target path does not exist, or is a directory, null will be returned.

        Parameters:
        action - Action used to configure the backing S3 operation.

      • open

         abstract StreamObject open(String path, ObjectOpenParams params)

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

        If the target path does not exist, or is a directory, null will be returned.

        Parameters:
        params - Parameters for the backing S3 operation.

      • download

         abstract FileObject download(String path, File localFile)

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

        Parameters:
        path - Path to the target object to download.
        localFile - Target local file into which the object's content will be downloaded.

      • download

         abstract FileObject download(String path, Function1<ObjectDownloadParams, Unit> action)

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

        Parameters:
        action - Action used to configure the backing S3 operation.

      • download

         abstract FileObject download(String path, ObjectDownloadParams params)

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

        Parameters:
        params - Parameters for the backing S3 operation.

      • stat

         abstract ObjectMeta stat(String path)

        Fetches metadata for the object at the target path.

        If the target object does not exist, null will be returned.

        Parameters:
        path - Path to the target object whose metadata should be returned.

      • stat

         abstract ObjectMeta stat(String path, Function1<ObjectStatParams, Unit> action)

        Fetches metadata for the object at the target path.

        If the target object does not exist, null will be returned.

        Parameters:
        path - Path to the target object whose metadata should be returned.
        action - Action used to configure the backing S3 operation.

      • stat

         abstract ObjectMeta stat(String path, ObjectStatParams params)

        Fetches metadata for the object at the target path.

        If the target object does not exist, null will be returned.

        Parameters:
        path - Path to the target object whose metadata should be returned.
        params - Parameters for the backing S3 operation.

      • listAll

         abstract ObjectList listAll()

        Fetches a list of all the objects in this container.

      • listAll

         abstract ObjectList listAll(Function1<ObjectListAllParams, Unit> action)

        Fetches a list of all the objects in this container.

        Parameters:
        action - Action used to configure the backing S3 operation.

      • listAll

         abstract ObjectList listAll(ObjectListAllParams params)

        Fetches a list of all the objects in this container.

        Parameters:
        params - Parameters for the backing S3 operation.

      • touch

         abstract S3Object touch(String path)

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

        Unlike the other object put methods, if an object already exists at the given path it will not be overwritten, in that case this method will do nothing.

        Parameters:
        path - Path/key for the empty object to create.

      • touch

         abstract S3Object touch(String path, Function1<ObjectTouchParams, Unit> action)

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

        Unlike the other object put methods, if an object already exists at the given path it will not be overwritten, in that case this method will do nothing.

        Parameters:
        action - Action used to configure the backing S3 operation.

      • touch

         abstract S3Object touch(String path, ObjectTouchParams params)

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

        Unlike the other object put methods, if an object already exists at the given path it will not be overwritten, in that case this method will do nothing.

        Parameters:
        params - Parameters for the backing S3 operation.

      • set

         S3Object set(String path, InputStream stream)

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

        This method is a Kotlin syntax extra that is an alias for put.

        Parameters:
        path - Path to the new object to create.
        stream - Stream whose contents will be written to the object in the store at the given path.

      • set

         S3Object set(String path, File file)

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

        This method is a Kotlin syntax extra that is an alias for upload.

        Parameters:
        path - Path to the object to create/overwrite in this container.
        file - Local file to upload.

      • put

         abstract S3Object put(String path, InputStream stream)

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

        Parameters:
        path - Path to the new object to create.
        stream - Stream whose contents will be written to the object in the store at the given path.

      • put

         abstract S3Object put(String path, Function1<StreamingObjectPutParams, Unit> action)

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

        Parameters:
        action - Action used to configure the backing S3 operation.

      • put

         abstract S3Object put(String path, StreamingObjectPutParams params)

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

        Parameters:
        params - Parameters for the backing S3 operation.

      • upload

         abstract S3Object upload(String path, File file)

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

        Parameters:
        path - Path to the object to create/overwrite in this container.
        file - Local file to upload.

      • upload

         abstract S3Object upload(String path, Function1<FileUploadParams, Unit> action)

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

        Parameters:
        action - Action used to configure the backing S3 operation.

      • upload

         abstract S3Object upload(String path, FileUploadParams params)

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

        Parameters:
        params - Parameters for the backing S3 operation.

      • delete

         abstract Unit delete(String path)

        Deletes the object at the target path from this container.

        Parameters:
        path - Path to the target object to delete.

      • delete

         abstract Unit delete(String path, Function1<DeleteParams, Unit> action)

        Deletes the object at the target path from this container.

        Parameters:
        action - Action used to configure the backing S3 operation.

      • delete

         abstract Unit delete(String path, DeleteParams params)

        Deletes the object at the target path from this container.

        Parameters:
        params - Parameters for the backing S3 operation.

      • deleteAll

         abstract Unit deleteAll(String paths)

        Deletes all the given target objects from this container.

        If the target paths set is empty, this method does nothing.

        Parameters:
        paths - Target paths to delete.

      • deleteAll

         abstract Unit deleteAll(Iterable<String> paths)

        Deletes all the given target objects from this container.

        If the target paths set is empty, this method does nothing.

        Parameters:
        paths - Target paths to delete.

      • deleteAll

         abstract Unit deleteAll(Function1<MultiObjectDeleteParams, Unit> action)

        Deletes all the given target objects from this container.

        If the target paths set is empty, this method does nothing.

        Parameters:
        action - Action used to configure the backing S3 operation.

      • deleteAll

         abstract Unit deleteAll(MultiObjectDeleteParams params)

        Deletes all the given target objects from this container.

        If the target paths set is empty, this method does nothing.

        Parameters:
        params - Parameters for the backing S3 operation.

      • rmdir

         abstract Unit rmdir(String path)

        Recursively removes all contents in the target directory.

        Example

        Given the container state:

        foo/bar/bazz.txt
foo/bar/fizz.txt
foo/buzz.txt
food/world.png

        The operation:

        container.rmdir("foo")

        Will result in the state:

        food/world.png
        Parameters:
        path - Path to the target directory that will be removed.

      • rmdir

         abstract Unit rmdir(String path, Function1<DirectoryDeleteParams, Unit> action)

        Recursively removes all contents in the target directory.

        Example

        Given the container state:

        foo/bar/bazz.txt
foo/bar/fizz.txt
foo/buzz.txt
food/world.png

        The operation:

        container.rmdir("foo")

        Will result in the state:

        food/world.png
        Parameters:
        action - Action used to configure the backing S3 operation.

      • rmdir

         abstract Unit rmdir(String path, DirectoryDeleteParams params)

        Recursively removes all contents in the target directory.

        Example

        Given the container state:

        foo/bar/bazz.txt
foo/bar/fizz.txt
foo/buzz.txt
food/world.png

        The operation:

        container.rmdir("foo")

        Will result in the state:

        food/world.png
        Parameters:
        params - Parameters for the backing S3 operation.