Interface TemplateStorage

All Superinterfaces:
AutoCloseable, Named
public interface TemplateStorage extends AutoCloseable, Named
Provides an interface to execute all types of operations on templates stored on any file system. A template storage is bound to that file system and can not interoperate with different file systems.

All operations which are executable from a template storage are based on the assumption that you either can access files using an output/input stream or via the local file system. Once a template storage was closed via the provided close method it is not safe anymore to access data through it. These operations might succeed as expected but will most likely fail. It is safe to access a template storage from multiple threads concurrently, but there are no checks made if the template storage is still in use when the storage is getting closed, meaning that other threads which are still accessing the storage might die due to an exception.

Since:
4.0

  • Method Details

    • deployDirectory

      default boolean deployDirectory(@NonNull @NonNull ServiceTemplate target, @NonNull @NonNull Path directory)
      Deploys all files in the given directory to the associated target in this template storage for the given template.
      Parameters:
      target - the template to deploy the directory to.
      directory - the directory to deploy to the storage.
      Returns:
      true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given directory or service template is null.

    • deployDirectory

      boolean deployDirectory(@NonNull @NonNull ServiceTemplate target, @NonNull @NonNull Path directory, @Nullable @Nullable Predicate<Path> filter)
      Deploys all files in the given directory to the associated target in this template storage for the given template. All files in the directory will be passed to the given filter, if present. If the filter returns false for a path the file or directory will not be deployed into the storage.
      Parameters:
      target - the template to deploy the directory to.
      directory - the directory to deploy to the storage.
      filter - an optional filter which can be used to filter out files which shouldn't get deployed.
      Returns:
      true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given directory or service template is null.

    • deploy

      boolean deploy(@NonNull @NonNull ServiceTemplate target, @NonNull @NonNull InputStream inputStream)
      Deploys all files in the given input stream to the given target template. The given input stream is expected to be backed by a zip file, each entry of that zip file will be deployed. If anything else than a stream of a zip file is given to this method it will either not deploy anything or fail with an exception.
      Parameters:
      target - the template to deploy the data inside the zip file to.
      inputStream - the stream to the zip file which should be deployed.
      Returns:
      true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given input stream or target template is null.

    • pull

      boolean pull(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull Path directory)
      Pulls the template data which is stored in this template storage to the given directory. If any file stored in the template in this storage is already present in the target directory it will be overridden.
      Parameters:
      template - the template to pull the files of.
      directory - the target directory to pull the files into.
      Returns:
      true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or target directory is null.

    • zipTemplate

      @Nullable @Nullable InputStream zipTemplate(@NonNull @NonNull ServiceTemplate template) throws IOException
      Pulls the data of the given template into a temporary directory and zip it. The returned input stream is a stream which can read from the created zip file but is not necessarily a zip input stream. If you specifically want a zip input stream consider using openZipInputStream(ServiceTemplate) instead.

      When the returned input stream is closed the created temporary zip file will be deleted automatically.

      Parameters:
      template - the template to download and zip.
      Returns:
      a stream which reads from the pulled and zipped template file, null if the template doesn't exist.
      Throws:
      IOException - if an I/O error occurred while zipping the template data.
      NullPointerException - if the given template is null.

    • openZipInputStream

      @Nullable default @Nullable ZipInputStream openZipInputStream(@NonNull @NonNull ServiceTemplate template) throws IOException
      Pulls the data of the given template into a temporary directory and zip it. When the returned input stream is closed the created temporary zip file will be deleted automatically.
      Parameters:
      template - the template to download and zip.
      Returns:
      a stream which reads from the pulled and zipped template file, null if the template doesn't exist.
      Throws:
      IOException - if an I/O error occurred while zipping the template data.
      NullPointerException - if the given template is null.

    • delete

      boolean delete(@NonNull @NonNull ServiceTemplate template)
      Deletes the given template completely from this template storage.
      Parameters:
      template - the template to delete.
      Returns:
      true if the given template was deleted successfully, false otherwise.
      Throws:
      NullPointerException - if the given template is null.

    • create

      boolean create(@NonNull @NonNull ServiceTemplate template)
      Creates the given template in this template storage if it doesn't exist already.
      Parameters:
      template - the template to create.
      Returns:
      true if the template was created successfully, false otherwise.
      Throws:
      NullPointerException - if the given template is null.

    • contains

      boolean contains(@NonNull @NonNull ServiceTemplate template)
      Checks if this template storage contains any data associated with the given template.
      Parameters:
      template - the template to check for.
      Returns:
      true if this storage contains the given template, false otherwise.
      Throws:
      NullPointerException - if the given template is null.

    • appendOutputStream

      @Nullable @Nullable OutputStream appendOutputStream(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path) throws IOException
      Creates a new output stream which appends to the file at the given path in the given template in this storage. If the file at the given path doesn't exist already it will be created automatically. After all the content was written to the given output stream it must be closed in order to persist your changes in this storage.
      Parameters:
      template - the template in which the file to append to is located.
      path - the path to the file in the given template to open the append-stream for.
      Returns:
      an output stream which appends to the given file in the given template.
      Throws:
      IOException - if an I/O error occurred.
      NullPointerException - if the given template or file path is null.

    • newOutputStream

      @Nullable @Nullable OutputStream newOutputStream(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path) throws IOException
      Creates a new output stream which overrides the content of the file at the given path in the given template in this storage. If the file at the given path doesn't exist already it will be created automatically. After all the content was written to the given output stream it must be closed in order to persist your changes in this storage.
      Parameters:
      template - the template in which the file to write to is located.
      path - the path to the file in the given template to open the stream for.
      Returns:
      an output stream which overrides to the given file in the given template.
      Throws:
      IOException - if an I/O error occurred.
      NullPointerException - if the given template or file path is null.

    • createFile

      boolean createFile(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Creates a new, empty file at the given path in the given template in this storage if the file didn't exist already.
      Parameters:
      template - the template to create the file in.
      path - the path to the file in the given template.
      Returns:
      true if the file was created successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • createDirectory

      boolean createDirectory(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Creates a new, empty directory at the given path in the given template in this storage if the directory didn't exist already.
      Parameters:
      template - the template to create the directory in.
      path - the path to the directory in the given template.
      Returns:
      true if the directory was created successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • hasFile

      boolean hasFile(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Checks if a file or directory exists at the given path in the given template in this template storage.
      Parameters:
      template - the template to check for the file existence in.
      path - the path to the file in the template to check for.
      Returns:
      true if a file or directory exists at the given path, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • deleteFile

      boolean deleteFile(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Deletes the given file at the given path in the given template in this storage. This method is only able to delete files, directories cannot be deleted using this method.
      Parameters:
      template - the template in which the file to delete is located in.
      path - the path to the file in the template to delete.
      Returns:
      true if the file at the given path was deleted successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • newInputStream

      @Nullable @Nullable InputStream newInputStream(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path) throws IOException
      Opens a new input stream to read the content of the file at the given path in the given template in this storage. This method returns null if either the file doesn't exist or is a directory.
      Parameters:
      template - the template in which the file to read is located in.
      path - the path to the file in the template to read.
      Returns:
      a new input stream to read the content of the file at the given path, null if the file isn't readable.
      Throws:
      IOException - if an I/O error occurred.
      NullPointerException - if the given template or template path is null.

    • fileInfo

      @Nullable @Nullable FileInfo fileInfo(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Retrieves information about the specified file or directory at the given path in the given template in this storage.
      Parameters:
      template - the template in which the file or directory to get the info of is located in.
      path - the path to the file or directory to get the info of.
      Returns:
      an information about the file or directory at the given path.
      Throws:
      NullPointerException - if the given template or path is null.

    • listFiles

      @NonNull @NonNull Collection<FileInfo> listFiles(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String dir, boolean deep)
      Lists all files in the given directory and computes a file information of them. Optionally all files in subdirectories are listed as well if the deep option is set to true.
      Parameters:
      template - the template in which the directory to list the files of is located.
      dir - the directory to list the files and optionally the directories in.
      deep - whether the content of subdirectories in the given directory should be included.
      Returns:
      all files which are located in the given directory.
      Throws:
      NullPointerException - if the given template or directory is null.

    • templates

      @NonNull @NonNull Collection<ServiceTemplate> templates()
      Gets a list of all templates that exist in this storage. Modifications to the collection won't have any effect.

      The templates in the returned collection will not have the following options configured correctly as they are not stored in the template storage directly:

      1. priority
      2. alwaysCopyToStaticServices
      Returns:
      all templates which are located in this storage.

    • close

      void close() throws IOException
      Closes this storage and releases all resources which are associated with it (if any). Calls which are made to this storage after it has been closed might either not have any effect or will result in an exception.
      Specified by:
      close in interface AutoCloseable
      Throws:
      IOException - if an I/O error occurred while closing the underlying resources of this storage.

    • deployDirectoryAsync

      @NonNull default @NonNull CompletableFuture<Boolean> deployDirectoryAsync(@NonNull @NonNull ServiceTemplate target, @NonNull @NonNull Path directory)
      Deploys all files in the given directory to the associated target in this template storage for the given template.
      Parameters:
      target - the template to deploy the directory to.
      directory - the directory to deploy to the storage.
      Returns:
      a task completed with true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given directory or service template is null.

    • deployDirectoryAsync

      @NonNull @NonNull CompletableFuture<Boolean> deployDirectoryAsync(@NonNull @NonNull ServiceTemplate target, @NonNull @NonNull Path directory, @Nullable @Nullable Predicate<Path> filter)
      Deploys all files in the given directory to the associated target in this template storage for the given template. All files in the directory will be passed to the given filter, if present. If the filter returns false for a path the file or directory will not be deployed into the storage.
      Parameters:
      target - the template to deploy the directory to.
      directory - the directory to deploy to the storage.
      filter - an optional filter which can be used to filter out files which shouldn't get deployed.
      Returns:
      a task completed with true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given directory or service template is null.

    • deployAsync

      @NonNull @NonNull CompletableFuture<Boolean> deployAsync(@NonNull @NonNull ServiceTemplate target, @NonNull @NonNull InputStream inputStream)
      Deploys all files in the given input stream to the given target template. The given input stream is expected to be backed by a zip file, each entry of that zip file will be deployed. If anything else than a stream of a zip file is given to this method it will either not deploy anything or fail with an exception.
      Parameters:
      target - the template to deploy the data inside the zip file to.
      inputStream - the stream to the zip file which should be deployed.
      Returns:
      a task completed with true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given input stream or target template is null.

    • pullAsync

      @NonNull @NonNull CompletableFuture<Boolean> pullAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull Path directory)
      Pulls the template data which is stored in this template storage to the given directory. If any file stored in the template in this storage is already present in the target directory it will be overridden.
      Parameters:
      template - the template to pull the files of.
      directory - the target directory to pull the files into.
      Returns:
      a task completed with true if the operation completed successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or target directory is null.

    • zipTemplateAsync

      @NonNull @NonNull CompletableFuture<InputStream> zipTemplateAsync(@NonNull @NonNull ServiceTemplate template)
      Pulls the data of the given template into a temporary directory and zip it. The returned input stream is a stream which can read from the created zip file but is not necessarily a zip input stream. If you specifically want a zip input stream consider using openZipInputStreamAsync(ServiceTemplate) instead.

      When the returned input stream is closed the created temporary zip file will be deleted automatically.

      Parameters:
      template - the template to download and zip.
      Returns:
      a task completed with a stream which reads from the pulled and zipped template file.
      Throws:
      NullPointerException - if the given template is null.

    • openZipInputStreamAsync

      @NonNull @NonNull CompletableFuture<ZipInputStream> openZipInputStreamAsync(@NonNull @NonNull ServiceTemplate template)
      Pulls the data of the given template into a temporary directory and zip it. When the returned input stream is closed the created temporary zip file will be deleted automatically.
      Parameters:
      template - the template to download and zip.
      Returns:
      a task completed with a stream which reads from the pulled and zipped template file.
      Throws:
      NullPointerException - if the given template is null.

    • deleteAsync

      @NonNull @NonNull CompletableFuture<Boolean> deleteAsync(@NonNull @NonNull ServiceTemplate template)
      Deletes the given template completely from this template storage.
      Parameters:
      template - the template to delete.
      Returns:
      a task completed with true if the given template was deleted successfully, false otherwise.
      Throws:
      NullPointerException - if the given template is null.

    • createAsync

      @NonNull @NonNull CompletableFuture<Boolean> createAsync(@NonNull @NonNull ServiceTemplate template)
      Creates the given template in this template storage if it doesn't exist already.
      Parameters:
      template - the template to create.
      Returns:
      a task completed with true if the template was created successfully, false otherwise.
      Throws:
      NullPointerException - if the given template is null.

    • containsAsync

      @NonNull @NonNull CompletableFuture<Boolean> containsAsync(@NonNull @NonNull ServiceTemplate template)
      Checks if this template storage contains any data associated with the given template.
      Parameters:
      template - the template to check for.
      Returns:
      a task completed true if this storage contains the given template, false otherwise.
      Throws:
      NullPointerException - if the given template is null.

    • appendOutputStreamAsync

      @NonNull @NonNull CompletableFuture<OutputStream> appendOutputStreamAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Creates a new output stream which appends to the file at the given path in the given template in this storage. If the file at the given path doesn't exist already it will be created automatically. After all the content was written to the given output stream it must be closed in order to persist your changes in this storage.
      Parameters:
      template - the template in which the file to append to is located.
      path - the path to the file in the given template to open the append-stream for.
      Returns:
      a task completed with an output stream which appends to the given file in the given template.
      Throws:
      NullPointerException - if the given template or file path is null.

    • newOutputStreamAsync

      @NonNull @NonNull CompletableFuture<OutputStream> newOutputStreamAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Creates a new output stream which overrides the content of the file at the given path in the given template in this storage. If the file at the given path doesn't exist already it will be created automatically. After all the content was written to the given output stream it must be closed in order to persist your changes in this storage.
      Parameters:
      template - the template in which the file to write to is located.
      path - the path to the file in the given template to open the stream for.
      Returns:
      a task completed with an output stream which overrides to the given file in the given template.
      Throws:
      NullPointerException - if the given template or file path is null.

    • createFileAsync

      @NonNull @NonNull CompletableFuture<Boolean> createFileAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Creates a new, empty file at the given path in the given template in this storage if the file didn't exist already.
      Parameters:
      template - the template to create the file in.
      path - the path to the file in the given template.
      Returns:
      a task completed with true if the file was created successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • createDirectoryAsync

      @NonNull @NonNull CompletableFuture<Boolean> createDirectoryAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Creates a new, empty directory at the given path in the given template in this storage if the directory didn't exist already.
      Parameters:
      template - the template to create the directory in.
      path - the path to the directory in the given template.
      Returns:
      a task completed with true if the directory was created successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • hasFileAsync

      @NonNull @NonNull CompletableFuture<Boolean> hasFileAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Checks if a file or directory exists at the given path in the given template in this template storage.
      Parameters:
      template - the template to check for the file existence in.
      path - the path to the file in the template to check for.
      Returns:
      a task completed with true if a file or directory exists at the given path, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • deleteFileAsync

      @NonNull @NonNull CompletableFuture<Boolean> deleteFileAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Deletes the given file at the given path in the given template in this storage. This method is only able to delete files, directories cannot be deleted using this method.
      Parameters:
      template - the template in which the file to delete is located in.
      path - the path to the file in the template to delete.
      Returns:
      a task completed with true if the file at the given path was deleted successfully, false otherwise.
      Throws:
      NullPointerException - if the given template or path is null.

    • newInputStreamAsync

      @NonNull @NonNull CompletableFuture<InputStream> newInputStreamAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Opens a new input stream to read the content of the file at the given path in the given template in this storage. This method returns null if either the file doesn't exist or is a directory.
      Parameters:
      template - the template in which the file to read is located in.
      path - the path to the file in the template to read.
      Returns:
      a task completed with a new input stream to read the content of the file at the given path.
      Throws:
      NullPointerException - if the given template or template path is null.

    • fileInfoAsync

      @NonNull @NonNull CompletableFuture<FileInfo> fileInfoAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String path)
      Retrieves information about the specified file or directory at the given path in the given template in this storage.
      Parameters:
      template - the template in which the file or directory to get the info of is located in.
      path - the path to the file or directory to get the info of.
      Returns:
      a task completed with an information about the file or directory at the given path.
      Throws:
      NullPointerException - if the given template or path is null.

    • listFilesAsync

      @NonNull @NonNull CompletableFuture<Collection<FileInfo>> listFilesAsync(@NonNull @NonNull ServiceTemplate template, @NonNull @NonNull String dir, boolean deep)
      Lists all files in the given directory and computes a file information of them. Optionally all files in subdirectories are listed as well if the deep option is set to true.
      Parameters:
      template - the template in which the directory to list the files of is located.
      dir - the directory to list the files and optionally the directories in.
      deep - whether the content of subdirectories in the given directory should be included.
      Returns:
      a task completed with all files which are located in the given directory.
      Throws:
      NullPointerException - if the given template or directory is null.

    • templatesAsync

      @NonNull @NonNull CompletableFuture<Collection<ServiceTemplate>> templatesAsync()
      Gets a list of all templates that exist in this storage. Modifications to the collection won't have any effect.

      The templates in the returned collection will not have the following options configured correctly as they are not stored in the template storage directly:

      1. priority
      2. alwaysCopyToStaticServices
      Returns:
      a task completed with all templates which are located in this storage.

    • closeAsync

      @NonNull @NonNull CompletableFuture<Void> closeAsync()
      Closes this storage and releases all resources which are associated with it (if any). Calls which are made to this storage after it has been closed might either not have any effect or will result in an exception.
      Returns:
      a task completed when the template storage was closed.