Package io.wcm.handler.media

Class MediaArgs

java.lang.Object
io.wcm.handler.media.MediaArgs
All Implemented Interfaces:
Cloneable
@ProviderType public final class MediaArgs extends Object implements Cloneable
Holds parameters to influence the media resolving process.

  • Constructor Details

    • MediaArgs

      public MediaArgs()
      Default constructor

    • MediaArgs

      public MediaArgs(@NotNull @NotNull MediaFormat @NotNull ... mediaFormats)
      Create media arguments with media formats.
      Parameters:
      mediaFormats - Media formats

    • MediaArgs

      public MediaArgs(@NotNull @NotNull String @NotNull ... mediaFormatNames)
      Create media arguments with media format names.
      Parameters:
      mediaFormatNames - Media format names

  • Method Details

    • getMediaFormats

      public MediaFormat @Nullable [] getMediaFormats()
      Returns list of media formats to resolve to.
      Returns:
      Media formats

    • mediaFormats

      @NotNull public @NotNull MediaArgs mediaFormats(@Nullable @Nullable MediaFormat @Nullable ... values)
      Sets list of media formats to resolve to.
      Parameters:
      values - Media formats
      Returns:
      this

    • mandatoryMediaFormats

      @NotNull public @NotNull MediaArgs mandatoryMediaFormats(@NotNull @NotNull MediaFormat @Nullable ... values)
      Sets list of media formats to resolve to.
      Parameters:
      values - Media formats
      Returns:
      this

    • mediaFormat

      @NotNull public @NotNull MediaArgs mediaFormat(MediaFormat value)
      Sets a single media format to resolve to.
      Parameters:
      value - Media format
      Returns:
      this

    • mediaFormatsMandatory

      @NotNull public @NotNull MediaArgs mediaFormatsMandatory(boolean value)
      The "mandatory" flag of all media format options is set to to the given value.
      Parameters:
      value - Resolving of all media formats is mandatory.
      Returns:
      this

    • getMediaFormatNames

      public String @Nullable [] getMediaFormatNames()
      Returns list of media formats to resolve to. See getMediaFormatNames() for details.
      Returns:
      Media format names

    • mediaFormatNames

      @NotNull public @NotNull MediaArgs mediaFormatNames(@NotNull @NotNull String @Nullable ... names)
      Sets list of media formats to resolve to.
      Parameters:
      names - Media format names.
      Returns:
      this

    • mandatoryMediaFormatNames

      @NotNull public @NotNull MediaArgs mandatoryMediaFormatNames(@NotNull @NotNull String @Nullable ... names)
      Sets list of media formats to resolve to.
      Parameters:
      names - Media format names.
      Returns:
      this

    • mediaFormatName

      @NotNull public @NotNull MediaArgs mediaFormatName(String name)
      Sets a single media format to resolve to.
      Parameters:
      name - Media format name
      Returns:
      this

    • getMediaFormatOptions

      public MediaArgs.MediaFormatOption @Nullable [] getMediaFormatOptions()
      Gets list of media formats to resolve to.
      Returns:
      Media formats with mandatory flag

    • mediaFormatOptions

      @NotNull public @NotNull MediaArgs mediaFormatOptions(@NotNull @NotNull MediaArgs.MediaFormatOption @Nullable ... values)
      Sets list of media formats to resolve to.
      Parameters:
      values - Media formats with mandatory flag
      Returns:
      this

    • isAutoCrop

      public boolean isAutoCrop()
      Check if auto-cropping mode is enabled.
      Returns:
      Enables "auto-cropping" mode. If no matching rendition is found it is tried to generate one by automatically cropping another one.

    • autoCrop

      @NotNull public @NotNull MediaArgs autoCrop(boolean value)
      Enable or disable auto-cropping mode.
      Parameters:
      value - Enables "auto-cropping" mode. If no matching rendition is found it is tried to generate one by automatically cropping another one.
      Returns:
      this

    • getFileExtensions

      public String @Nullable [] getFileExtensions()
      Get accepted file extensions.
      Returns:
      Accepted file extensions

    • fileExtensions

      @NotNull public @NotNull MediaArgs fileExtensions(@NotNull @NotNull String @Nullable ... values)
      Set accepted file extensions.
      Parameters:
      values - Accepted file extensions
      Returns:
      this

    • fileExtension

      @NotNull public @NotNull MediaArgs fileExtension(@Nullable @Nullable String value)
      Set accepted file extension.
      Parameters:
      value - Accepted file extension
      Returns:
      this

    • getEnforceOutputFileExtension

      @Nullable public @Nullable String getEnforceOutputFileExtension()
      Enforces image file type for renditions.

      By default, renditions are rendered with the same file type as the original rendition (except if the original renditions uses a file type not directly supported in browser, e.g. a TIFF image). With this parameter, it is possible to enforce generating renditions with this file type.

      Supported file types: JPEG, PNG

      Returns:
      File extension to be used for returned renditions

    • enforceOutputFileExtension

      @NotNull public @NotNull MediaArgs enforceOutputFileExtension(@Nullable @Nullable String value)
      Enforces image file type for renditions.

      By default, renditions are rendered with the same file type as the original rendition (except if the original renditions uses a file type not directly supported in browser, e.g. a TIFF image). With this parameter, it is possible to enforce generating renditions with this file type.

      Supported file types: JPEG, PNG

      Parameters:
      value - File extension to be used for returned renditions
      Returns:
      this

    • getUrlMode

      @Nullable public @Nullable io.wcm.handler.url.UrlMode getUrlMode()
      Get URL mode.
      Returns:
      URL mode

    • urlMode

      @NotNull public @NotNull MediaArgs urlMode(@Nullable @Nullable io.wcm.handler.url.UrlMode value)
      Set URL mode.
      Parameters:
      value - URS mode
      Returns:
      this

    • getFixedWidth

      public long getFixedWidth()
      Use fixed width instead of width from media format or original image
      Returns:
      Fixed width

    • fixedWidth

      @NotNull public @NotNull MediaArgs fixedWidth(long value)
      Use fixed width instead of width from media format or original image
      Parameters:
      value - Fixed width
      Returns:
      this

    • getFixedHeight

      public long getFixedHeight()
      Use fixed height instead of width from media format or original image
      Returns:
      Fixed height

    • fixedHeight

      @NotNull public @NotNull MediaArgs fixedHeight(long value)
      Use fixed height instead of width from media format or original image
      Parameters:
      value - Fixed height
      Returns:
      this

    • fixedDimension

      @NotNull public @NotNull MediaArgs fixedDimension(long widthValue, long heightValue)
      Use fixed dimensions instead of width from media format or original image
      Parameters:
      widthValue - Fixed width
      heightValue - Fixed height
      Returns:
      this

    • isDownload

      public boolean isDownload()
      Check if only download media formats are accepted.
      Returns:
      Accept only media formats that have the download flag set.

    • download

      @NotNull public @NotNull MediaArgs download(boolean value)
      Set whether to accept only download media formats.
      Parameters:
      value - Accept only media formats that have the download flag set.
      Returns:
      this

    • isContentDispositionAttachment

      public boolean isContentDispositionAttachment()
      Check if Content-Disposition header should be set to attachment.
      Returns:
      Whether to set a "Content-Disposition" header to "attachment" for forcing a "Save as" dialog on the client

    • contentDispositionAttachment

      @NotNull public @NotNull MediaArgs contentDispositionAttachment(boolean value)
      Set whether Content-Disposition header should be set to attachment.
      Parameters:
      value - Whether to set a "Content-Disposition" header to "attachment" for forcing a "Save as" dialog on the client
      Returns:
      this

    • getAltText

      @Nullable public @Nullable String getAltText()
      Get custom alternative text.
      Returns:
      The custom alternative text that is to be used instead of the one defined in the the asset metadata.

    • altText

      @NotNull public @NotNull MediaArgs altText(@Nullable @Nullable String value)
      Allows to specify a custom alternative text that is to be used instead of the one defined in the the asset metadata.
      Parameters:
      value - Custom alternative text. If null or empty, the default alt text from media library is used.
      Returns:
      this

    • isForceAltValueFromAsset

      public boolean isForceAltValueFromAsset()
      Check if alt text should be forced from DAM asset description.
      Returns:
      Whether to force to read alt. text from DAM asset description.

    • forceAltValueFromAsset

      @NotNull public @NotNull MediaArgs forceAltValueFromAsset(boolean value)
      Set whether to force alt text from DAM asset description.
      Parameters:
      value - Whether to force to read alt. text from DAM asset description. If not set, the asset description is used as fallback value of no custom alt. text is defined.
      Returns:
      this

    • isDecorative

      public boolean isDecorative()
      Check if image is marked as decorative.
      Returns:
      Marks this image as "decorative". Alt. text is then explicitly set to an empty string.

    • decorative

      @NotNull public @NotNull MediaArgs decorative(boolean value)
      Set whether image is decorative.
      Parameters:
      value - Marks this image as "decorative". Alt. text is then explicitly set to an empty string.
      Returns:
      this

    • isDummyImage

      public boolean isDummyImage()
      Check if dummy image is enabled.
      Returns:
      If set to true, media handler never returns a dummy image. Otherwise this can happen in edit mode.

    • dummyImage

      @NotNull public @NotNull MediaArgs dummyImage(boolean value)
      Set whether dummy image is enabled.
      Parameters:
      value - If set to false, media handler never returns a dummy image. Otherwise this can happen in edit mode.
      Returns:
      this

    • getDummyImageUrl

      @Nullable public @Nullable String getDummyImageUrl()
      Get URL of custom dummy image.
      Returns:
      Url of custom dummy image. If null default dummy image is used.

    • dummyImageUrl

      @NotNull public @NotNull MediaArgs dummyImageUrl(@Nullable @Nullable String value)
      Set URL of custom dummy image.
      Parameters:
      value - Url of custom dummy image. If null default dummy image is used.
      Returns:
      this

    • getIncludeAssetAemRenditions

      @Nullable public @Nullable Set<AemRenditionType> getIncludeAssetAemRenditions()
      Get which types of AEM-generated renditions are included.
      Returns:
      Defines which types of AEM-generated renditions (with cq5dam. prefix) are taken into account when trying to resolve the media request.

    • includeAssetAemRenditions

      @NotNull public @NotNull MediaArgs includeAssetAemRenditions(@Nullable @Nullable Set<AemRenditionType> value)
      Set which types of AEM-generated renditions are included.
      Parameters:
      value - Defines which types of AEM-generated renditions (with cq5dam. prefix) are taken into account when trying to resolve the media request.
      Returns:
      this

    • isIncludeAssetThumbnails

      @Deprecated(since="2.0.0") @Nullable public @Nullable Boolean isIncludeAssetThumbnails()
      Deprecated.
      Use includeAssetAemRenditions(Set) instead.
      Returns:
      If set to true, thumbnail generated by AEM (with cq5dam.thumbnail. prefix) are taken into account as well when trying to resolve the media request. Defaults to false.

    • includeAssetThumbnails

      @Deprecated(since="2.0.0") @NotNull public @NotNull MediaArgs includeAssetThumbnails(boolean value)
      Deprecated.
      Use includeAssetAemRenditions(Set) instead.
      Parameters:
      value - If set to true, thumbnail generated by AEM (with cq5dam.thumbnail. prefix) are taken into account as well when trying to resolve the media request.
      Returns:
      this

    • isIncludeAssetWebRenditions

      @Deprecated(since="2.0.0") @Nullable public @Nullable Boolean isIncludeAssetWebRenditions()
      Deprecated.
      Use includeAssetAemRenditions(Set) instead.
      Returns:
      If set to true, web renditions generated by AEM (with cq5dam.web. prefix) are taken into account as well when trying to resolve the media request. If null, the default setting applies from the media handler configuration.

    • includeAssetWebRenditions

      @Deprecated(since="2.0.0") @NotNull public @NotNull MediaArgs includeAssetWebRenditions(boolean value)
      Deprecated.
      Use includeAssetAemRenditions(Set) instead.
      Parameters:
      value - If set to true, web renditions generated by AEM (with cq5dam.web. prefix) are taken into account as well when trying to resolve the media request.
      Returns:
      this

    • getImageSizes

      @Nullable public @Nullable MediaArgs.ImageSizes getImageSizes()
      Get image sizes for responsive image handling.
      Returns:
      Image sizes for responsive image handling

    • imageSizes

      @NotNull public @NotNull MediaArgs imageSizes(@Nullable @Nullable MediaArgs.ImageSizes value)
      Set image sizes for responsive image handling.
      Parameters:
      value - Image sizes for responsive image handling
      Returns:
      this

    • getPictureSources

      public MediaArgs.PictureSource @Nullable [] getPictureSources()
      Get picture sources for responsive image handling.
      Returns:
      Picture sources for responsive image handling

    • pictureSources

      @NotNull public @NotNull MediaArgs pictureSources(@NotNull @NotNull MediaArgs.PictureSource @Nullable ... value)
      Set picture sources for responsive image handling.
      Parameters:
      value - Picture sources for responsive image handling
      Returns:
      this

    • isDynamicMediaDisabled

      public boolean isDynamicMediaDisabled()
      Check if dynamic media support is disabled.
      Returns:
      If set to true, dynamic media support is disabled even when enabled on the instance.

    • dynamicMediaDisabled

      @NotNull public @NotNull MediaArgs dynamicMediaDisabled(boolean value)
      Set whether dynamic media support is disabled.
      Parameters:
      value - If set to true, dynamic media support is disabled even when enabled on the instance.
      Returns:
      this

    • isWebOptimizedImageDeliveryDisabled

      public boolean isWebOptimizedImageDeliveryDisabled()
      Check if web-optimized image delivery is disabled.
      Returns:
      If set to true, web-optimized image delivery is disabled even when enabled on the instance.

    • webOptimizedImageDeliveryDisabled

      @NotNull public @NotNull MediaArgs webOptimizedImageDeliveryDisabled(boolean value)
      Set whether web-optimized image delivery is disabled.
      Parameters:
      value - If set to true, web-optimized image delivery is disabled even when enabled on the instance.
      Returns:
      this

    • getImageQualityPercentage

      @Nullable public @Nullable Double getImageQualityPercentage()
      Get image quality percentage.
      Returns:
      Image quality in percent (0..1) for images with lossy compression (e.g. JPEG).

    • imageQualityPercentage

      @NotNull public @NotNull MediaArgs imageQualityPercentage(@Nullable @Nullable Double value)
      Set image quality percentage.
      Parameters:
      value - Image quality in percent (0..1) for images with lossy compression (e.g. JPEG).
      Returns:
      this

    • getDragDropSupport

      @NotNull public @NotNull DragDropSupport getDragDropSupport()
      Drag&Drop support for media builder.
      Returns:
      Drag&Drop support

    • dragDropSupport

      @NotNull public @NotNull MediaArgs dragDropSupport(@NotNull @NotNull DragDropSupport value)
      Drag&Drop support for media builder.
      Parameters:
      value - Drag&Drop support
      Returns:
      this

    • getIPERatioCustomize

      public IPERatioCustomize getIPERatioCustomize()
      Get IPE ratio customization setting.
      Returns:
      Whether to set customized list of IPE cropping ratios.

    • ipeRatioCustomize

      @NotNull public @NotNull MediaArgs ipeRatioCustomize(@Nullable @Nullable IPERatioCustomize value)
      Set IPE ratio customization setting.
      Parameters:
      value - Whether to set customized list of IPE cropping ratios.
      Returns:
      this

    • getVideoManifestFormat

      @Nullable public @Nullable String getVideoManifestFormat()
      Get the preferred video manifest format.
      Returns:
      Preferred video manifest format

    • videoManifestFormat

      @NotNull public @NotNull MediaArgs videoManifestFormat(@Nullable @Nullable String value)
      Set the preferred video manifest format.
      Parameters:
      value - Preferred video manifest format as file extension string (e.g. MediaFileType.M3U8.getExtension() for HLS, MediaFileType.MPD.getExtension() for DASH)
      Returns:
      this

    • isHostedVideoPlayer

      public boolean isHostedVideoPlayer()
      Check if hosted video player is enabled.
      Returns:
      Whether to use Adobe's hosted video player instead of a streaming manifest, affecting both URL generation and markup (iframe vs. HTML5 video element).

    • hostedVideoPlayer

      @NotNull public @NotNull MediaArgs hostedVideoPlayer(boolean value)
      Set whether to use hosted video player.
      Parameters:
      value - Whether to use Adobe's hosted video player instead of a streaming manifest, affecting both URL generation and markup (iframe vs. HTML5 video element).
      Returns:
      this

    • properties

      @NotNull public @NotNull MediaArgs properties(@NotNull @NotNull Map<String,Object> map)
      Custom properties that my be used by application-specific markup builders or processors.
      Parameters:
      map - Property map. Is merged with properties already set.
      Returns:
      this

    • property

      @NotNull public @NotNull MediaArgs property(@NotNull @NotNull String key, @Nullable @Nullable Object value)
      Custom properties that my be used by application-specific markup builders or processors.
      Parameters:
      key - Property key
      value - Property value
      Returns:
      this

    • getProperties

      @NotNull public @NotNull org.apache.sling.api.resource.ValueMap getProperties()
      Custom properties that my be used by application-specific markup builders or processors.
      Returns:
      Value map

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • clone

      public MediaArgs clone()
      Custom clone-method for MediaArgs
      Overrides:
      clone in class Object
      Returns:
      the cloned MediaArgs