Apache Sling Thumbnails

Clone this repo:
  1. 04a87b5 [maven-release-plugin] prepare for next development iteration by Dan Klco · 6 weeks ago master
  2. 47ba3e9 [maven-release-plugin] prepare release org.apache.sling.thumbnails-1.0.2 by Dan Klco · 6 weeks ago org.apache.sling.thumbnails-1.0.2
  3. d317b42 SLING-12109 - Removing dependency on Guava by Dan Klco · 6 weeks ago
  4. 22d0396 SLING-12111 - Updating to latest release of thumbnailator by Dan Klco · 6 weeks ago
  5. d279958 SLING-12110 - Updating to latest sling parent and fixing POM issues detected by Dan Klco · 6 weeks ago

Apache Sling

Build Status Test Status Coverage Sonarcloud Status JavaDoc Maven Central License

Apache Sling Thumbnails

Generate and transform thumbnails from file-like Resources.


This library registers two servlets for generating thumbnails.

Dynamic Transform Servlet

Generates and transforms thumbnails “on the fly” based on a request path, format and transformation JSON payload. Available for POST requests at the path /bin/sling/thumbnails/transform with the parameters resource (required) and format (optional), for example, given the following image at /content/image/test.png"

Image credit Markos Mant from Unsplash

Sending a request like:

URL: http://localhost:8080/bin/sling/thumbnails/transform?resource=/content/image/test.png&format=jpeg


        "handlerType": "sling/thumbnails/transformers/crop",
        "properties": {
            "width": 300,
            "height": 300
        "handlerType": "sling/thumbnails/transformers/colorize",
        "properties": {
            "red": 112,
            "green": 66,
            "blue": 20,
            "alpha": 0.4

Will result in the following thumbnail:


Saving Thumbnails

The Dynamic Transform Servlet can save the generated thumbnail for any Persistable resource type. To do so add the URL parameter renditionName, e.g.:


Once saved, the rendition can be access directly using the configured Rendition Path for the Resource Type or using the Transform Servlet. Note that the rendition will only be available on the resource the servlet is executed on.

Transform Servlet

The second servlet uses Sling Context Aware Configurations to generate thumbnails based on pre-defined transformation pipelines. Note that the RenderedResource model is useful for retrieving the available transformation pipelines and existing renditions for a particular resource.

Each available transformation can then be accessed in the form:


This for a request like:


The servlet would:

  1. Get the resource /content/images/test.png
  2. Apply the transformation my-transformation (found in any CA Config)
  3. Convert the result to a JPEG

CA Config Structure

The structure for the transformations under the CA Config root (e.g. /conf/global/) should include files/transformations, as such:

/conf/global: {
  "jcr:primaryType": "sling:Folder",
  "files": {
    "jcr:primaryType": "sling:Folder",
    "transformations": {
      "jcr:primaryType": "sling:Folder",
      "transformation": {
        "jcr:primaryType": "nt:unstructured",
        "name": "transformation",
        "sling:resourceType": "sling/thumbnails/transformation",
        "handlers": {
          "jcr:primaryType": "nt:unstructured",
          "resize": {
            "jcr:primaryType": "nt:unstructured",
            "height": 200,
            "width": 200,
            "sling:resourceType": "sling/thumbnails/transformers/resize"


The Transform Servlet supports persisting renditions and using the persisted renditions instead of rendering the image on the fly. To persist renditions, you must configure the persistableTypes in the Thumbnail Support Configuration

The persistableTypes node type must also be in the supportedTypes list. The rendition will be persisted at the provided path as an nt:file node with the name provided when requesting the rendition.


This library can be installed on Sling 11+ but does require the following libraries:

  • org.apache.commons:commons-compress:1.20
  • org.apache.commons:commons-math3:3.6.1
  • org.apache.servicemix.bundles:org.apache.servicemix.bundles.poi:4.1.2_2
  • org.apache.servicemix.bundles:org.apache.servicemix.bundles.xmlbeans:3.1.0_2

Add a service user sling-thumbnails with the following permissions:

  • jcr:write,jcr:nodeTypeManagement,jcr:versionManagement on /content
  • jcr:read on /

Add a service user mapping: org.apache.sling.thumbnails:sling-commons-thumbnails=sling-thumbnails

Note that this library generates Sling Feature Models which can be used to install it easily with the Sling Feature Launcher:

  • org.apache.sling:org.apache.sling.thumbnails:slingosgifeature:base:{RELEASE_VERSION}
  • org.apache.sling:org.apache.sling.thumbnails:slingosgifeature:default:{RELEASE_VERSION}
  • org.apache.sling:org.apache.sling.thumbnails:slingosgifeature:dependencies:{RELEASE_VERSION}


This module requires configuring the following pid:

PID = org.apache.sling.thumbnails.internal.ThumbnailSupportImpl
  errorResourcePath = /static/sling-cms/thumbnails/file.png
  errorSuffix = /sling-cms-thumbnail.png
  persistedTypes = []
  supportedTypes = [nt:file=jcr:content/jcr:mimeType]

The the values should be set as follows:

  • errorResourcePath - the path to a resource to transform if an error occurs instead of returning the default error page
  • errorSuffix - the transformation to call on the error resource if an error occurs instead of returning the default error page
  • persistedTypes - The types which support persistence of renditions in the format resourceType=rendition-path
  • supportedTypes - The types which support thumbnail generation and transformation in the format resourceType=metdata-path

Note: the supportedTypes (and by extension persistedTypes) must be adaptable to from a Resource to an java.io.InputStream.

Generally, this configuration should be provided by the application including this functionality. See ThumbnailSupportConfig for more on the configuration values.

Primary Concepts

There are two main concepts in this library:

  • ThumbnailProviders - implement the interface ThumbnailProvider and are responsible for generating a thumbnail from a defined file node
  • TransformationHandler - implement the class TransformationHandler and are responsible for executing a single transformation as part of a thumbnail transformation pipeline

Default Thumbnail Providers and Transformation Handlers are provided with this library and both interfaces are available for extension.

Thumbnail Providers

Thumbnail Providers implement the ThumbnailProvider interface and are responsible for generating a thumbnail from a file resource. Each handler is expected to indicate whether or not it can handle the provided resource / mime type and will be evaluated in order of their Service Ranking with the TikaFallbackProvider having a service ranking of Integer.MIN_VALUE

The following are the included Thumbnail Providers:

Image Thumbnail Provider

Directly uses the image as the thumbnail

Implementation: org.apache.sling.thumbnails.internal.providers.ImageThumbnailProvider

Supported Type(s): All image types, except SVG

PDF Thumbnail Provider

Generates a PDF thumbnail using PDFBox

Implementation: org.apache.sling.thumbnails.internal.providers.PDFThumbnailProvider

Supported Type(s): PDF documents

Slide Show Thumbnail Provider

Generates a thumbnail from PPTX / PPT documents using POI

Implementation: org.apache.sling.thumbnails.internal.providers.SlideShowThumbnailProvider

Supported Type(s): PPTX / PPT documents

Tika Fallback Thumbnail Provider

Generates a thumbnail using Apache Tika

Implementation: org.apache.sling.thumbnails.internal.providers.TikaFallbackProvider

Supported Type(s): Any remaining document type

Transformation Handlers

Transformation Handlers implement the TransformationHandler interface and are responsible for invoking tranformation effects on thumbnails. Each Transformation Handler is identified by a Handler Type which should correspond to a Sling Resource Type. Only one Transformation Handler is expected to be registered per resource type.

Most of the transformnation handlers use the Thumbnailator library under the hood to perform the transformations.

The following are the included Transformation Handlers:

Colorize Hander

Adds a color tint to an image.

Implementation: org.apache.sling.thumbnails.internal.transformers.ColorizeHandler

Handler Type: sling/thumbnails/transformers/colorize


  • red - the red color value (0-255)
  • green - the green color value (0-255)
  • blue - the blue color value (0-255)
  • alpha - the level of transparency, with lower being more transparent (0.0 - 1.0)

Crop Handler

Crops an image to the size specified. Note the width and height must be specified.

Implementation: org.apache.sling.thumbnails.internal.transformers.ColorizeHandler

Handler Type: sling/thumbnails/transformers/colorize


  • height - the height to constrain the crop (1+)
  • width - the width to constrain the crop (1+)
  • position - one of:
    • CENTER
    • TOP_LEFT

Greyscale Handler

Converts an image to greyscale. Note this will remove transparency.

Implementation: org.apache.sling.thumbnails.internal.transformers.GreyscaleHandler

Handler Type: sling/thumbnails/transformers/greyscale



Resize Handler

Resizes an image to the size specified. If only one dimension is specified the image will be sized to the other

Implementation: org.apache.sling.thumbnails.internal.transformers.ResizeHandler

Handler Type: sling/thumbnails/transformers/resize


  • height - the height to constrain the crop (1+)
  • width - the width to constrain the crop (1+)
  • keepAspectRatio - boolean, if false, the exact width and height will be used which will not preserve the aspect ratio of the original image.

Rotate Handler

Rotates an image.

Implementation: org.apache.sling.thumbnails.internal.transformers.RotateHandler

Handler Type: sling/thumbnails/transformers/rotate


  • degrees - the number of degrees to rotate the image (any number)

Scale Handler

Sets the scaling factor for the width and height of the image. If the scaling factor for the width and height are not equal, then the image will not preserve the aspect ratio of the original image.

Note: either both or the width+height must be set.

Implementation: org.apache.sling.thumbnails.internal.transformers.ScaleHandler

Handler Type: sling/thumbnails/transformers/scale


  • both - scale the thumbnail by the same factor for width and height (0+ - 1.0+)
  • width - scale the thumbnail width (0+ - 1.0+)
  • height - scale the thumbnail height (0+ - 1.0+)

Transparency Handler

Makes an image transparent

Implementation: org.apache.sling.thumbnails.internal.transformers.TransparencyHandler

Handler Type: sling/thumbnails/transformers/transparency


  • alpha - the level of transparency, with lower being more transparent (0.0 - 1.0)