Thumbnail Service

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Thumbnail Service3.0Digital Asset Management

Table of Contents

• 1 Requirement MoSCoW List


• 2 Thumbnail Service API


• 3 Thumbnail Content Model


• 4 Transformation Options


• 5 Changes to Transformation Service


• 6 Supporting Image Thumnails


• 7 Other APIs

Requirement MoSCoW List

Requirement	Priority
Thumbnail Content Model	Must
Thumbnail Java APIs	Must
Support for Multiple Thumbnails	Must
Automatic Updates To Thumbnails	Must
Asynchronous Thumbnail Creation/Update	Must
Extend script and template APIs	Must
Thumbnail REST API	Must
Image Thumbnailing (image to image)	Must
Document Preview Thumbnailing (document to swf/txt)	Must
Document Image Thumbnailing (document to image)	Should
Support for Adhoc Thumbnail Generation (Real-Time Thumbnailing)	Should
Extend FileFolder API	Should
Migration From Current Thumbnail Implementation	Could
Web Client UI	Could
Video Image Thumbnailing (video to image)	Could

Thumbnail Service API

These interfaces and classes make up the fundamental thumbnail service API.

Package:     com.alfresco.cmr.thumbnail

Interface:   ThumbnailService

Description: Thumbnail service API to create, update and retrieve thumbnails.

Methods:

/**
 * Creates a new thumbnail for the given node and content property.
 * 
 * The passed create options specify the details of the thumbnail, including the 
 * mimetpye, size and location of the thumbnail.
 * 
 * Once created the source node will have the 'tn:thumbnailed' aspect applied and an
 * association to the thumbnail node (or type 'tn:thumbnail') will be created.
 * 
 * The returned node reference is to the 'tn:thumbnail' content node that contains
 * the thumnail content in the standard 'cm:content' property.
 * 
 * @see org.alfresco.service.cmr.thumnail.GenerateOptions
 * 
 * @param  node                 the source content node
 * @param  contentProperty      the content property
 * @param  createOptions        the create options
 * @return NodeRef              node reference to the newly created thumbnail 
 */
NodeRef createThumbnail(NodeRef node, QName contentProperty, CreateOptions createOptions);

/**
 * Updates the content of a thumbnail.
 * 
 * The original creation options are used when updating the thumbnail.  The content of 
 * the associated thumbnailed node is used to update.
 * 
 * An error is raised if the original content no longer exists.
 * 
 * @param thumbnail             the thumbnail node
 */
void updateThumbnail(NodeRef thumbnail);

/**
 * Gets the thumbnail for a given content property with a given name.
 * 
 * Returns null if no thumbnail with that name for that content property is found.
 * 
 * @param node              node reference
 * @param contentProperty   content property name
 * @param thumbnailName     thumbnail name
 * @return NodeRef          the thumbnail node reference, null if not found
 */
NodeRef getThumbnailByName(NodeRef node, QName contentProperty, String thumbnailName);

/**
  * Gets a list of thumbnail nodes for a given content property that match the provided mimetype and
  * transformation options.
  * 
  * Both mimetype and transformation options are optional parameters.  If only one or other is specified the
  * only the other is considered during.  If neither are provided all thumbnails for that content property 
  * are returned.
  * 
  * If no matches are found then an empty list is returned.
  * 
  * @param node                  node reference
  * @param contentProperty       content property name
  * @param mimetype              mimetype
  * @param options               transformation options
  * @return List<NodeRef>        list of matching thumbnail node references, empty if no matches found
  */
List<NodeRef> getThumbnails(NodeRef node, QName contentProperty, String mimetype, TransformationOptions options);

Package:     com.alfresco.cmr.thumbnail

Type:        CreateOptions

Description: Provides the thumbnail create options to the thumbnail service

Methods:

/**
 * Accessors methods for the destination mimetype
 */
void setDestinationMimetype(String mimetype);
String getDestinationMimetype();

/**
 * Accessors methods for the transformation options used to create the thumbnail
 */
public void setTransformationOptions(TransformationOptions options) { ...
public TransformationOptions getTransformationOptions() { ...

/**
 * Accessors methods for the name of the created thumbnail
 * 
 * Providing a name for the thumbanil is optional.  If not set a unique name is 
 * generated for the thumbnail.
 */
public void setThumbnailName(String thumbnailName) { ...
public String getThumbnailName() { ...

/**
 * Accessors methods for the thumbnail association details.
 *
 * If not set the thumbnail is created as a child of the source node using the thumbnailed
 * association.
 */
public void setParentAssociationDetails(ParentAssociationDetails assocDetails) { ...
public ParentAssociationDetails getParentAssociationDetails() { ...

Thumbnail Content Model

The thumbnail content model is an extension to the standard content model.

Aspects:

<aspect name='cm:thumbnailed'>
         <title>Thumbnailed</title>
         <properties>             
            <property name='cm:automaticUpdate'>
               <title>Automatic Update</title>
               <type>d:boolean</type>
               <mandatory>true</mandatory>
               <default>true</default>
            </property> 
         </properties>
         <associations>
             <child-association name='cm:thumbnails'>
                 <source>
                 <mandatory>false</mandatory>
                 <many>true</many>
                 </source>
                 <target>
                 <class>cm:thumbnail</class>
                 <mandatory>false</mandatory>
                 <many>true</many>
                 </target>
             </child-association>
         </associations>
      </aspect>

Types:

  <type name='cm:thumbnail'>
      <title>Thumbnail</title>
   <parent>cm:content</parent>
   <archive>true</archive>
   <properties>     
      <property name='cm:thumbnailName'>
          <title>Thumbnail Name</title>
       <type>d:text</type>
       <mandatory>false</mandatory>
      </property>     
      <property name='cm:contentPropertyName'>
          <title>Thumbnailed Content Property Name</title>
       <type>d:qname</type>
       <mandatory>true</mandatory>
      </property>            
   </properties>
 </type>

Transformation Options

Package:     com.alfresco.cmr.repository

Type:        TransformationOptions

Description: Contains the basic parameters and context that is passed to a transformation

Properties:

• sourceNodeRef - the node reference of the source node in the transformation
  
• sourceContentProperty - the content property of the source node that is being transformed
  
• targetNodeRef - the node reference of the target node in the transformation
  
• targetContentProperty - the content property of the target node that the transformation is destined to
  

Methods:

/**
 * Save the transformation options to the given node by applying the appropriate aspect
 * and setting the meta data from the transformation options
 * 
 * @param nodeRef       the node reference
 * @param nodeService   the node service
 */
public void saveToNode(NodeRef nodeRef, NodeService nodeService)
{
   // The base implementation does nothing, override in derived classes
   ...

/**
 * Populate the transformation options from the meta data present on the appropraite
 * aspect on the passed node.
 * 
 * @param nodeRef       the node reference
 * @param nodeService   the node service
 */
 public void populateFromNode(NodeRef nodeRef, NodeService nodeService)
 {
   // The base implementation does nothing, override in derived classes
   ...

Note:

• Transformation options can be created from Maps and converted to Maps in order to maintain backward compatibility.
  

Changes to Transformation Service

ContentService

Deprecate the existing transform method that takes a map of options.  This method will continue to work as expected since the map will be converted to a best fit TransformOptions instance and ContentService.transform(ContentReader, ContentWriter, TransformOptions) called.

@Deprecated
public void transform(ContentReader reader, ContentWriter writer, Map<String, Object> options)
   throws NoTransformerException, ContentIOException;

Add the following methods which allow TransformOptions to be passed.  When retrieveing a transformer the TransformOptions will now be considered along with the mimetype.

/**
 * Tranforms the content with the provided transformation options.
 */
public void transform(ContentReader reader, ContentWriter writer, TransformationOptions options)
   throws NoTransformerException, ContentIOException;

/**
 * Get the transformer that can satisfy the request to transform from the source mimetype to the destination mimetype 
 * with the provided transformation options.
 */
public ContentTransformer getTransformer(String sourceMimetype, String targetMimetype, TransformationOptions options);

/**
 * Indicates whether the provided content can be transformed to the destination mimetype (specified on the content writer) with
 * the provided transformation options.
 */
public boolean isTransformable(ContentReader reader, ContentWriter writer, TransformationOptions options);

ContentTransformer

Remove the getReliability method.  Backwards compatibility can be maintained by keeping the existing abstract base class implementation for content transformers and creating a new one which can be migrated to.  The old one will implement the new isTransformable interface method by using the exiting getReliability implementation and the new abstract base will delegate the implementation of isTransformable to the implemented class and not have an implementation of getReliability.

/** Removed */
//public double getReliability(String sourceMimetype, String targetMimetype);

Deprecate the following transform method, providing an implementation in the new abstract base class that converts the map into transformation options.

@Deprecated
public void transform(
            ContentReader reader,
            ContentWriter writer,
            Map<String, Object> options) throws ContentIOException;

Add the following methods.  Implementaions will be provided in the existing abstract base class to ensure exisiting transformers are compatible, but migration to the new abstract implementation is expected.

/**
 * Indicates whether the provided source mimetype can be transformed into the target mimetype with 
 * the options specified by this content transformer.
 * 
 * @param  sourceMimetype           the source mimetype
 * @param  destinationMimetype      the destination mimetype
 * @param  options                  the transformation options
 * @return boolean                  true if this content transformer can satify the mimetypes and options specified, false otherwise
 */
public boolean isTransformable(String sourceMimeType, String targetMimetype, TransformationOptions options);

/**
 * Indicates whether given the provided transformation parmaters this transformer can prvide an explict
 * transformation.
 * 
 * An explict transformation indicates that the transformation happens directly and not as a result of 
 * another transformation process.  Explict transformation always take presidence over normal transformations.
 * 
 * @param sourceMimetype    the source mimetype
 * @param targetMimetype    the target mimetype
 * @param options           the transformation options
 * @return boolean          true if it is an explicit transformation, flase otherwise         
 */
public boolean isExplicitTransformation(String sourceMimetype, String targetMimetype, TransformationOptions options);

/**
 * Transforms the content provided by the reader and source mimetype
 * to the writer and target mimetype with the provided transformation options.
 * 

 * The transformation viability can be determined by an up front call
 * to {@link #isTransformable(String, String, TransformationOptions)}.
 * <p>
 * The source and target mimetypes must be available on the
 * {@link org.alfresco.service.cmr.repository.ContentAccessor#getMimetype()} methods of
 * both the reader and the writer.
 * <p>
 * Both reader and writer will be closed after the transformation completes.
 * <p>
 * The provided options can be null.
 * 
 * @param  reader               the source of the content
 * @param  contentWriter        the destination of the transformed content    
 * @param  options              transformation options, these can be null
 * @throws ContentIOException   if an IO exception occurs
 */
public void transform(ContentReader reader, ContentWriter contentWriter, TransformationOptions options) 
   throws ContentIOException;

ContentTransformerRegistry

Update to consider the options of the transformer when retrieving and storing it in the registry.

Remove the transformer cache since it becomes overly complicated with the introduction of options as a caching parameter.

<pre>
/* DELETED */
public void resetCache()

Explicit transformations are now managed by the content transformers directly.

<pre>
/* DELETED */
//public void addExplicitTransformer(TransformationKey key, ContentTransformer transformer)

Add transformation options as a parameter when retrieving transformers.

<pre>
/* Updated to include transformation options */
public ContentTransformer getTransformer(String sourceMimetype, String targetMimetype, TransformationOptions options)

Deprecate the transformation key object as it is no longer needed.

<pre>
@Deprecated
public static class TransformationKey
{ ...

Supporting Image Thumnails

Support for image thumbanails will be achieved by extending the current imageMagick content transformation implementation to take a number of ImageTransformationOptions, a number of which specify the manner in which the source image should be resized during the transformation.

Package:     org.alfresco.repo.content.transform.magick

Interface:   ImageTransformationOptions

Description: Image transformation options.

Properties:

• commandOptions - Command string that can be directly applied to the image transformation engine.  Provided for backward compatibility.
  
• resizeOptions - object containg deatils of resize options available during the transformation
  

Note:

• Implementations of saveToNode and populateFromNode provided to map the various image transformation options to and from the ImageTransformationOptions aspect (see below for definition of aspect)
  

Package:     org.alfresco.repo.content.transform.magick

Interface:   ImageResizeOptions

Description: Contains the various image resize options.

Properties:

• width - the width of the resized image
  
• height - the height of the resized image
  
• maintainAspectRatio - indicates whether the aspect ratio of the image should be preserved
  
• percentResize - indicates whether the width and height values should be interpreted as percentage changes of the origional dimensions
  
• resizeToThumbail - indicates whether the transformed image will be used as a thumbnail or not
  

imageTransformationOptions Aspect

<pre>
<aspect name='cm:imageTransformationOptions'>

  <title>Image Transformation Options</title>
  <properties>
     <property name='cm:commandOptions'>
        <title>Command Options</title>
        <type>d:text</type>
        <mandatory>false</mandatory>
        <default>-1</default>
     </property>
     <property name='cm:resize'>
        <title>Resize The Image</title>
        <type>d:boolean</type>
        <default>false</default>
     </property>
     <property name='cm:resizeWidth'>
        <title>Resize Width</title>
        <type>d:int</type>
        <mandatory>false</mandatory>
        <default>-1</default>
      </property>
      <property name='cm:resizeHeight'>
         <title>Resize Height</title>
         <type>d:int</type>
         <mandatory>false</mandatory>
      </property>
      <property name='cm:resizeMaintainAspectRatio'>
         <title>Resize Maintain Aspect Ratio</title>
         <type>d:boolean</type>
         <default>true</default>            
      </property>
      <property name='cm:resizePercent'>
         <title>Resize Percent</title>
         <type>d:boolean</type>
         <default>false</default>            
      </property>
      <property name='cm:resizeToThumbnail'>
         <title>Resize To Thumbnail</title>
         <type>d:boolean</type>
         <default>false</default>            
      </property>
  </properties>

</aspect>

Other APIs

• Thumbnail REST API
  
• Thumbnail JavaScript API