Package com.broadleafcommerce.asset.service

Interface StorageService

All Known Implementing Classes:
DefaultStorageService
public interface StorageService

This interface exposes methods required to perform basic tasks involving processing of uploaded files. It is responsible for validation and pre-processing of files (such as unzipping and URL creation), but interacts with and relies on the StorageProvider to abstract away the details of file storage/management.

This service is also responsible for creating the Folders and Asset for the files it processes.

Author:
Chad Harchar (charchar), Samarth Dhruva (samarthd)

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addAttributesToAsset(Asset asset, ResourceWithMetadata resource)
    Add attributes to the asset based on the resource.
    void
    addAttributesToAsset(Asset asset, File file)
    Add attributes to the asset based on the file.
    default void
    addAttributesToAsset(Asset asset, org.springframework.core.io.Resource resource)
    Add attributes to the asset based on the resource.
    void
    removeFile(String filename)
    Deprecated, for removal: This API element is subject to removal in a future version. 
    void
    removeFile(String filename, com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
    Remove the provided file from the storage provider.
    void
    unzipAndUploadResourcesAsync(File sourceZipFile, String fileUploadStateId, Asset assetRequest, com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo, boolean optimizeImg)
    Deprecated.
    Use unzipAndUploadResourcesAsync(File, String, Asset, ContextInfo, boolean, boolean)
    void
    unzipAndUploadResourcesAsync(File sourceZipFile, String fileUploadStateId, Asset assetRequest, com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo, boolean optimizeImg, boolean ignoreFolderName)
    Asynchronously upload the individual contents of a zip file to the storage provider, and create all necessary Folders and Assets in the data store for them.
    Asset
    uploadResource(org.springframework.web.multipart.MultipartFile file, Asset assetRequest, com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo, boolean optimizeImg)
    Uploads a single file, creating an Asset for it (optionally using details specified in assetRequest if present).
    void
    validateZipResource(org.springframework.web.multipart.MultipartFile file)
    A simple method intended to be used to pre-validate a MultipartFile received in an API request when expecting a zip file.

  • Method Details

    • uploadResource

      Asset uploadResource(org.springframework.web.multipart.MultipartFile file, @Nullable Asset assetRequest, @Nullable com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo, boolean optimizeImg)
      Uploads a single file, creating an Asset for it (optionally using details specified in assetRequest if present).

      Validation includes:

      • File size is within the size limits of `spring.servlet.multipart.max-file-size`
      • File is of a supported mime type from `broadleaf.asset.storage.whitelisted-mime-type-formats`
      • File path and name does not already exist on a asset within the system
      Parameters:
      file - the file to be uploaded to the system.
      assetRequest - (optional) asset from which to derive certain attributes when creating the final Asset for the file. Currently, Asset.tags and Asset.locale are used.
      contextInfo - context information around sandboxing and multitenant state
      optimizeImg - optimizes the image if true
      Returns:
      the created asset after the associated resource has been uploaded
      Throws:
      StorageException - if there was an error processing the resource
      org.springframework.web.multipart.MaxUploadSizeExceededException - if the file is too large
      FileUploadBadRequestException - if a URL already belongs to an asset
      ImageOptimizationException - Throw when the optimization fails. This could be because a stream to read the image could not be opened, the thread performing the optimization was interrupted, or some other reason.

    • unzipAndUploadResourcesAsync

      @Deprecated void unzipAndUploadResourcesAsync(File sourceZipFile, String fileUploadStateId, @Nullable Asset assetRequest, @Nullable com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo, boolean optimizeImg)
      Deprecated.
      Use unzipAndUploadResourcesAsync(File, String, Asset, ContextInfo, boolean, boolean)
      Asynchronously upload the individual contents of a zip file to the storage provider, and create all necessary Folders and Assets in the data store for them. This method updates the FileUploadState with id fileUploadStateId with the status of upload.

      Certain validations are done in a way that, if not satisfied, cause the entire contents of the zip to fail to upload. These include:

      Parameters:
      sourceZipFile - a temporary zip file whose contents should be unzipped and uploaded to the storage provider. This file itself will be deleted following this operation. If the file passes validation and InternalAssetProperties.isStoreZipFileOnProvider() is true, then a copy of the zip file will be uploaded to the provider.
      fileUploadStateId - the context ID of the base FileUploadState for this operation. The results of this upload attempt will be updated on this entity.
      assetRequest - (optional) asset from which to derive certain attributes when creating the final Assets for the files. Currently, Asset.tags, Asset.locale, and Asset.folderId are used. If supplied, Asset.folderId is used as the root folder under which all other folders/assets will be created.
      contextInfo - request context information around sandbox and multitenant state
      optimizeImg - whether or not to optimize the images

    • unzipAndUploadResourcesAsync

      void unzipAndUploadResourcesAsync(File sourceZipFile, String fileUploadStateId, @Nullable Asset assetRequest, @Nullable com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo, boolean optimizeImg, boolean ignoreFolderName)
      Asynchronously upload the individual contents of a zip file to the storage provider, and create all necessary Folders and Assets in the data store for them. This method updates the FileUploadState with id fileUploadStateId with the status of upload.

      Certain validations are done in a way that, if not satisfied, cause the entire contents of the zip to fail to upload. These include:

      Parameters:
      sourceZipFile - a temporary zip file whose contents should be unzipped and uploaded to the storage provider. This file itself will be deleted following this operation. If the file passes validation and InternalAssetProperties.isStoreZipFileOnProvider() is true, then a copy of the zip file will be uploaded to the provider.
      fileUploadStateId - the context ID of the base FileUploadState for this operation. The results of this upload attempt will be updated on this entity.
      assetRequest - (optional) asset from which to derive certain attributes when creating the final Assets for the files. Currently, Asset.tags, Asset.locale, and Asset.folderId are used. If supplied, Asset.folderId is used as the root folder under which all other folders/assets will be created.
      contextInfo - request context information around sandbox and multitenant state
      optimizeImg - whether or not to optimize the images
      ignoreFolderName - whether or not to include the parent folder path in the URI resolution of the files within the zip

    • validateZipResource

      void validateZipResource(org.springframework.web.multipart.MultipartFile file)
      A simple method intended to be used to pre-validate a MultipartFile received in an API request when expecting a zip file.

      While methods like unzipAndUploadResourcesAsync(File, String, Asset, ContextInfo, boolean) do perform certain validations, this method is intended to allow immediate rejection of invalid requests before getting too far in the flow.

      Default validations:

      Parameters:
      file - the file to validate
      Throws:
      org.springframework.web.multipart.MaxUploadSizeExceededException - if the file is exceeds the maximum upload size allowed.
      FileUploadBadRequestException - if the file is not an `application/zip`

    • removeFile

      @Deprecated(since="1.7.6", forRemoval=true) void removeFile(String filename)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Remove the provided file from the storage provider.
      Parameters:
      filename - the name of the file to delete on the storage provider
      Throws:
      StorageException - if an error is encountered

    • removeFile

      void removeFile(String filename, @Nullable com.broadleafcommerce.data.tracking.core.context.ContextInfo contextInfo)
      Remove the provided file from the storage provider.
      Parameters:
      filename - the name of the file to delete on the storage provider
      contextInfo - context of the request: information around sandbox and multitenant state
      Throws:
      StorageException - if an error is encountered

    • addAttributesToAsset

      void addAttributesToAsset(Asset asset, File file)
      Add attributes to the asset based on the file.
      Parameters:
      asset - the asset to add attributes to
      file - the file to use to add attributes to the asset

    • addAttributesToAsset

      default void addAttributesToAsset(Asset asset, org.springframework.core.io.Resource resource)
      Add attributes to the asset based on the resource.
      Parameters:
      asset - the asset to add attributes to
      resource - the Resource to use to add attributes to the asset

    • addAttributesToAsset

      void addAttributesToAsset(Asset asset, ResourceWithMetadata resource)
      Add attributes to the asset based on the resource.
      Parameters:
      asset - the asset to add attributes to
      resource - the ResourceWithMetadata to use to add attributes to the asset