Package io.wcm.handler.media

Class MediaArgs

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

    • Constructor Detail

      • MediaArgs

        public MediaArgs()
        Default constructor

      • MediaArgs

        public MediaArgs​(@NotNull
                 @NotNull MediaFormat @NotNull ... mediaFormats)
        Parameters:
        mediaFormats - Media formats

      • MediaArgs

        public MediaArgs​(@NotNull
                 @NotNull java.lang.String @NotNull ... mediaFormatNames)
        Parameters:
        mediaFormatNames - Media format names

    • Method Detail

      • 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 java.lang.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 java.lang.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 java.lang.String @Nullable ... names)
        Sets list of media formats to resolve to.
        Parameters:
        names - Media format names.
        Returns:
        this

      • mediaFormatName

        @NotNull
public @NotNull MediaArgs mediaFormatName​(java.lang.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()
        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)
        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 java.lang.String @Nullable [] getFileExtensions()
        Returns:
        Accepted file extensions

      • fileExtensions

        @NotNull
public @NotNull MediaArgs fileExtensions​(@NotNull
                                         @NotNull java.lang.String @Nullable ... values)
        Parameters:
        values - Accepted file extensions
        Returns:
        this

      • fileExtension

        @NotNull
public @NotNull MediaArgs fileExtension​(@Nullable
                                        @Nullable java.lang.String value)
        Parameters:
        value - Accepted file extension
        Returns:
        this

      • getEnforceOutputFileExtension

        @Nullable
public @Nullable java.lang.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 java.lang.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()
        Returns:
        URL mode

      • urlMode

        @NotNull
public @NotNull MediaArgs urlMode​(@Nullable
                                  @Nullable io.wcm.handler.url.UrlMode value)
        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()
        Returns:
        Accept only media formats that have the download flag set.

      • download

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

      • isContentDispositionAttachment

        public boolean isContentDispositionAttachment()
        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)
        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 java.lang.String getAltText()
        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 java.lang.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()
        Returns:
        Whether to force to read alt. text from DAM asset description.

      • forceAltValueFromAsset

        @NotNull
public @NotNull MediaArgs forceAltValueFromAsset​(boolean value)
        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()
        Returns:
        Marks this image as "decorative". Alt. text is then explicitly set to an empty string.

      • decorative

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

      • isDummyImage

        public boolean isDummyImage()
        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)
        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 java.lang.String getDummyImageUrl()
        Returns:
        Url of custom dummy image. If null default dummy image is used.

      • dummyImageUrl

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

      • getIncludeAssetAemRenditions

        @Nullable
public @Nullable java.util.Set<AemRenditionType> getIncludeAssetAemRenditions()
        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 java.util.Set<AemRenditionType> value)
        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 java.lang.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 java.lang.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()
        Returns:
        Image sizes for responsive image handling

      • imageSizes

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

      • getPictureSources

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

      • pictureSources

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

      • isDynamicMediaDisabled

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

      • dynamicMediaDisabled

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

      • isWebOptimizedImageDeliveryDisabled

        public boolean isWebOptimizedImageDeliveryDisabled()
        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)
        Parameters:
        value - If set to true, web-optimized image delivery is disabled even when enabled on the instance.
        Returns:
        this

      • getImageQualityPercentage

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

      • imageQualityPercentage

        @NotNull
public @NotNull MediaArgs imageQualityPercentage​(@Nullable
                                                 @Nullable java.lang.Double value)
        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()
        Returns:
        Whether to set customized list of IPE cropping ratios.

      • ipeRatioCustomize

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

      • properties

        @NotNull
public @NotNull MediaArgs properties​(@NotNull
                                     @NotNull java.util.Map<java.lang.String,​java.lang.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 java.lang.String key,
                                   @Nullable
                                   @Nullable java.lang.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 java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • clone

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