Package com.broadleafcommerce.asset.storage.provider.service

Interface StorageProvider

All Known Implementing Classes:
FilesystemStorageProvider, GoogleCloudStorageProvider
public interface StorageProvider

This interface exposes methods required for interacting with a asset storage provider, that is, to store, retrieve, and delete digital content. In other words, this service is responsible for supporting internal assets that Broadleaf has access and responsibility to store. It should be implemented for each type of storage provider to be used. By default, there should only be a single implementation of this service used, meaning that there should only be one storage provider used by the Asset service.

Note this service's use is restricted by a MIME type whitelist (see isWhitelistedMimeType(String)). This means that implementors can restrict what kinds of files can be supported. This method is linked to a system property of the form broadleaf.asset.internal.storageProvider.mimeTypeWhitelist.

This service can handle creating new resources from either an InputStream (addResourceFromStream(InputStream, String), addResourcesFromStreams(Map)) or by moving files from a temporary workspace (moveResourceFromDirectory(File) moveResourcesFromDirectory(Iterable)). Also note that, in the case of failures while processing multiple resources in either the add or delete methods, the default implementation will try to process as many resources as possible before returning a composite exception with all files that failed and their causes (see BulkStorageException).

Author:
Nathan Moore (nathanmoore), Samarth Dhruva (samarthd)
See Also:

  • Method Details

    • isWhitelistedMimeType

      boolean isWhitelistedMimeType(@NonNull String mimeType)
      Determines whether the given MIME type string is supported by this provider. Files with MIME types not supported, cannot be stored using this provider. The whitelist can be configured using a system property of the form broadleaf.asset.internal.storageProvider.mimeTypeWhitelist.

      If the whitelist is empty, then all types are considered whitelisted.

      Parameters:
      mimeType - the mime type to check against the provider's whitelist
      Returns:
      whether the given MIME type string is supported by this provider.
      See Also:

    • readResource

      @Deprecated(since="2.0.1", forRemoval=true) @NonNull default Optional<File> readResource(@NonNull String path)
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favor of readStreamableResourceWithMetadata(String)
      Retrieves the resource in the configured storage provider at the given path string if it exists.
      Parameters:
      path - fully qualified path to the resource's location in the storage provider
      Returns:
      Either the resource wrapped in an Optional if it exists or else Optional.EMPTY.

    • readStreamableResource

      default Optional<org.springframework.core.io.Resource> readStreamableResource(String path)
      Retrieves the resource in the configured storage provider at the given path string if it exists.
      Parameters:
      path - fully qualified path to the resource's location in the storage provider
      Returns:
      Either the resource wrapped in an Optional if it exists or else Optional.empty().

    • readStreamableResourceWithMetadata

      Optional<ResourceWithMetadata> readStreamableResourceWithMetadata(String path)
      Retrieves the resource in the configured storage provider at the given path string if it exists.
      Parameters:
      path - fully qualified path to the resource's location in the storage provider
      Returns:
      Either the resource wrapped in an Optional if it exists or else Optional.empty().

    • readResources

      @Deprecated(since="2.0.1", forRemoval=true) @NonNull default Iterable<File> readResources(@NonNull Iterable<String> paths)
      Deprecated, for removal: This API element is subject to removal in a future version.
      in favor of readStreamableResources(Iterable)
      Retrieves the resources in the configured storage provider at the given path strings if they exist.
      Parameters:
      paths - fully qualified path to the resources' locations in the storage provider
      Returns:
      Iterable of resources that were found

    • readStreamableResources

      default Iterable<org.springframework.core.io.Resource> readStreamableResources(Iterable<String> paths)
      Retrieves the resources in the configured storage provider at the given path strings if they exist.
      Parameters:
      paths - fully qualified path to the resources' locations in the storage provider
      Returns:
      Iterable of resources that were found

    • readStreamableResourcesWithMetadata

      default Iterable<ResourceWithMetadata> readStreamableResourcesWithMetadata(Iterable<String> paths)
      Retrieves the resources in the configured storage provider at the given path strings if they exist.
      Parameters:
      paths - fully qualified path to the resources' locations in the storage provider
      Returns:
      Iterable of resources that were found

    • addResourceFromStream

      @NonNull String addResourceFromStream(@NonNull InputStream resource, @NonNull String fileName)
      Adds a new resource to the configured storage provider using the provided InputStream and filename. Then, it returns the fully qualified path of the newly stored resource.
      Parameters:
      resource - resource to add to the configured storage provider
      fileName - the name of the resource, potentially including path segments.
      Returns:
      the fully qualified path to the added resource
      Throws:
      StorageException - if there is an issue processing the resource

    • addResourcesFromStreams

      @NonNull BulkAddResourcesResponse addResourcesFromStreams(@NonNull Map<String,InputStream> fileNamesToResources)

      Adds new resources to the configured storage provider using the provided Map of InputStreams and filenames. Then, it returns a BulkAddResourcesResponse containing the information about which files succeeded and which files failed.

      Parameters:
      fileNamesToResources - a map of filenames to resources that should be copied to the storage provider. The filenames can include path segments.
      Returns:
      a BulkAddResourcesResponse containing the details of which files did and didn't succeed

    • addResourcesFromFiles

      @NonNull BulkAddResourcesResponse addResourcesFromFiles(@NonNull Map<String,File> fileNamesToResources)
      Adds new resources to the configured storage provider using the provided Map of Files and filenames. Then, it returns a BulkAddResourcesResponse containing the information about which files succeeded and which files failed.
      Parameters:
      fileNamesToResources - a map of filenames to resources that should be copied to the storage provider. The filenames can include path segments.
      Returns:
      a BulkAddResourcesResponse containing the details of which files did and didn't succeed

    • deleteResource

      void deleteResource(@NonNull String path)
      Deletes the resource in the configured storage provider at the given path string if it exists.
      Parameters:
      path - fully qualified path to the resource's location in the storage provider
      Throws:
      StorageException - if there was an error in deleting the resource

    • deleteResources

      void deleteResources(@NonNull Iterable<String> paths)
      Deletes the resources in the configured storage provider at the given path strings if they exist. This method will attempt to remove all the resources it can successfully before throwing a BulkStorageException containing all the failures and their causes.
      Parameters:
      paths - fully qualified paths to the resources' locations in the storage provider
      Throws:
      BulkStorageException - if there were errors in deleting some resources

    • moveResourceFromDirectory

      @NonNull default String moveResourceFromDirectory(@NonNull File resource)
      Moves a given resource from a directory to the configured storage provider and returns the path as a string to the resource within that provider.
      Parameters:
      resource - resource to move to the configured storage provider
      Returns:
      the path to the added file

    • moveResourceFromDirectoryAndGetPath

      @NonNull default Path moveResourceFromDirectoryAndGetPath(@NonNull File resource)
      Moves a given resource from a directory to the configured storage provider and returns the path to the resource within that provider.
      Parameters:
      resource - resource to move to the configured storage provider
      Returns:
      the path to the added file

    • moveResourcesFromDirectory

      @NonNull default Iterable<String> moveResourcesFromDirectory(@NonNull Iterable<File> resources)
      Moves all the given resources from a directory to the configured storage provider and returns the paths to the resources within that provider as strings.
      Parameters:
      resources - Iterable of resources to move to the configured storage provider
      Returns:
      the Iterable of added file paths

    • moveResourcesFromDirectoryAndGetPaths

      @NonNull default Iterable<Path> moveResourcesFromDirectoryAndGetPaths(@NonNull Iterable<File> resources)
      Moves all the given resources from a directory to the configured storage provider and returns the paths to the resources within that provider.
      Parameters:
      resources - Iterable of resources to move to the configured storage
      Returns:
      the Iterable of added file paths