Added Javadoc to various RenditionService parameter constants.

git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@19230 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/repo/rendition/executer/AbstractRenderingEngine.java

@@ -117,17 +117,57 @@ public abstract class AbstractRenderingEngine extends ActionExecuterAbstractBase
 
     /* Parameter names common to all Rendering Actions */
     //TODO javadoc these
+    /**
+     * This optional {@link String} parameter specifies the location of a
+     * classpath resource which can be used as a placeholder while a rendition
+     * is being generated. For example, this might be a simple icon to indicate
+     * a rendition is not yet available. This is intended to be used in
+     * conjunction with asynchronous generation of renditions.
+     */
     public static final String PARAM_PLACEHOLDER_RESOURCE_PATH = "placeHolderResourcePath";
+
+    /**
+     * This optional {@link QName} parameter specifies which property the
+     * Rendering Engine uses to read content from the source node in order to
+     * create a rendition. By default this property will be cm:content.
+     */
     public static final String PARAM_SOURCE_CONTENT_PROPERTY = "sourceContentProperty";
+
+    /**
+     * This optional {@link QName} parameter specifies which property the
+     * Rendering Engine uses to write content to the rendition node. By default
+     * the property used is cm:content.
+     */
     public static final String PARAM_TARGET_CONTENT_PROPERTY = "targetContentProperty";
+
+    /**
+     * This optional {@link Boolean} flag property specifies whether a rendition
+     * should be updated automatically if the source node changes. If set to
+     * <code>true</code> then the rendition will be re-rendered any time any
+     * property changes occur on the source node. This parameter defaults to
+     * <code>false</code>.
+     */
     public static final String PARAM_UPDATE_RENDITIONS_ON_ANY_PROPERTY_CHANGE = "update-renditions-on-any-property-change";
+
+    /**
+     * This optional {@link String} parameter specifies what user permissions
+     * are used when creating a rendition. By default the system user is used.
+     */
     public static final String PARAM_RUN_AS = "runAs";
 
-    /*
+    // mime-type is not a common parameter on all Rendering Actions, but it is
-     * mime-type is not a common parameter on all Rendering Actions, but it is
+    // common to many and is used in some common handling code in this class.
-     * common to many and is used in some common handling code in this class.
+    /**
+     * This optional {@link String} parameter specifies the mime type of the
+     * rendition content. This defaults to the mime type of the source node
+     * content.
      */
     public static final String PARAM_MIME_TYPE = "mime-type";
+
+    /**
+     * This optional {@link String} paramter specifies the encoding used to
+     * create the rendition content. The derfault encoding is UTF-8.
+     */
     public static final String PARAM_ENCODING = "encoding";
 
     /**

source/java/org/alfresco/repo/rendition/executer/BaseTemplateRenderingEngine.java

@@ -21,8 +21,10 @@ package org.alfresco.repo.rendition.executer;
 
 import java.io.IOException;
 import java.io.OutputStreamWriter;
+import java.io.Serializable;
 import java.io.Writer;
 import java.util.Collection;
+import java.util.Map;
 
 import org.alfresco.repo.action.ParameterDefinitionImpl;
 import org.alfresco.service.cmr.action.ParameterDefinition;
@@ -38,8 +40,14 @@ import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 
 /**
- * This abstract class forms a basis for all rendering engines that are built around
+ * This abstract class forms a basis for all rendering engines that are built
- * the Template Service.
+ * around the Template Service.<br>
+ * A template must be specified either as a {@link String} using the
+ * PARAM_TEMPLATE parameter, as a {@link NodeRef} using the PARAM_TEMPLATE_NODE
+ * parameter or as a file path location using the PARAM_TEMPLATE_PATH parameter.
+ * The RenderingEngine reads from these parameters with the following priority:
+ * PARAM_TEMPLATE > PARAM_TEMPLATE_NODE > PARAM_TEMPLATE_PATH.
+ * 
  * @author Brian Remmington
  * @since 3.3
  */
@@ -48,9 +56,39 @@ public abstract class BaseTemplateRenderingEngine extends AbstractRenderingEngin
     private static final Log log = LogFactory.getLog(BaseTemplateRenderingEngine.class);
 
     public static final String NAME = "xsltRenderingEngine";
+
+    /**
+     * This optional {@link Map}<{@link String}, {@link Serializable}> parameter
+     * can be used to pass additional arguments to the templating engine when processing a
+     * template. 
+     */
     public static final String PARAM_MODEL = "model";
+
+    /**
+     * This optional {@link String} parameter specifies the template in a simple
+     * {@link String} format.<br>
+     * If this parameter is set the Rendering Engine will
+     * use it in preference to templates specified by either the
+     * PARAM_TEMPLATE_NODE or the PARAM_TEMPLATE_PATH parameters.
+     */
     public static final String PARAM_TEMPLATE = "template_string";
+
+    /**
+     * This optional {@link NodeRef} parameter specifies a node containing the
+     * template to be processed.<br>
+     * If a value is specified for PARAM_TEMPLATE then this parameter will be
+     * ignored.<br>
+     * If a value is specified for this parameter it will be used in preference
+     * to values specified for the PARAM_TEMPLATE_PATH parameter.
+     */
     public static final String PARAM_TEMPLATE_NODE = "template_node";
+
+    /**
+     * This optional {@link String} parameter specifies a file path location for
+     * the template to be processed.<br>
+     * If a value is specified for PARAM_TEMPLATE or PARAM_TEMPLATE_NODE then this parameter will be
+     * ignored.<br>
+     */
     public static final String PARAM_TEMPLATE_PATH = "template_path";
 
     private TemplateService templateService;
@@ -104,7 +142,7 @@ public abstract class BaseTemplateRenderingEngine extends AbstractRenderingEngin
         String template = context.getCheckedParam(PARAM_TEMPLATE, String.class);
         if (template != null)
         {
-            templateService.processTemplateString(templateType, (String)template, model, out);
+            templateService.processTemplateString(templateType, template, model, out);
         }
         else if (templateNode != null)
         {

source/java/org/alfresco/repo/rendition/executer/ImageRenderingEngine.java

@@ -49,20 +49,178 @@ public class ImageRenderingEngine extends AbstractTransformationRenderingEngine
     public static final String NAME = "imageRenderingEngine";
 
     // Resize params
+    /**
+     * This optional {@link Integer} or {@link Float} parameter specifies the
+     * width of the image after resizing. This may be expressed as pixels or it
+     * may represent a percentage of the original image width, depending on the
+     * value of the PARAM_IS_PERCENT_RESIZE parameter. <br>
+     * If no value is specified for this parameter then the width of the image
+     * will be unchanged. <br>
+     * If an image is being cropped and resized then the cropping happens first,
+     * followed by resizing of the cropped image.
+     */
     public static final String PARAM_RESIZE_WIDTH = "xsize";
+
+    /**
+     * This optional {@link Integer} or {@link Float} parameter specifies the
+     * height of the image after resizing. This may be expressed as pixels or it
+     * may represent a percentage of the original image width, depending on the
+     * value of the PARAM_IS_PERCENT_RESIZE parameter. <br>
+     * If no value is specified for this parameter then the height of the image
+     * will be unchanged.<br>
+     * If an image is being cropped and resized then the cropping happens
+     * first, followed by resizing of the cropped image.
+     */
     public static final String PARAM_RESIZE_HEIGHT = "ysize";
+
+    /**
+     * This optional {@link Boolean} flag parameter specifies how the
+     * PARAM_RESIZE_HEIGHT and PARAM_RESIZE_WIDTH parameters are interpreted. If
+     * this parameter is set to <code>true</code> then the rendition height and
+     * width are represented as a percentage of the original image height and
+     * width. If this parameter is set to <code>false</code> then the rendition
+     * height and width are represented as pixels. This parameter defaults to
+     * <code>false</code>.
+     */
     public static final String PARAM_IS_PERCENT_RESIZE = "isAbsolute";
+
+    /**
+     * This optional {@link Boolean} flag parameter determines whether the
+     * rendered image maintains its original aspect ratio or is stretched to fit
+     * the specified height and width. <br>
+     * If this parameter is <code>true</code> then the rendered image will
+     * always maintain its aspect ratio and will be resized to best fit within
+     * the given width and height. For example if an image starts at 100x200
+     * pixels and it is resized to 50x50 pixels then the rendered image will
+     * actually be 25x50 pixels. <br>
+     * If this parameter is <code>false</code> then the image will be stretched
+     * or compressed to fit the given height and width, regardless of the
+     * original aspect ratio. <br>
+     * This parameter defaults to <code>true</code>
+     */
     public static final String PARAM_MAINTAIN_ASPECT_RATIO = "maintainAspectRatio";
+
+    /**
+     * This optional {@link Boolean} flag parameter specifies a mode for
+     * dramatically shrinking large images in a performant way.<br>
+     * If set to <code>true</code> the rendering process will be more performant
+     * for large images but the rendered image will be of lower quality. <br>
+     * If set to <code>false</code> the rendering process will take longer but
+     * the resulting image will usually be of better quality.
+     */
     public static final String PARAM_RESIZE_TO_THUMBNAIL = "resizeToThumbnail";
 
     // Crop params
+    /**
+     * This optional {@link Integer} or {@link Float} parameter specifies the
+     * width of the image after cropping. This may be expressed as pixels or it
+     * may represent a percentage of the original image width, depending on the
+     * value of the PARAM_IS_PERCENT_CROP parameter. <br>
+     * If no value is specified for this parameter then the width of the image
+     * will be unchanged. <br>
+     * If an image is being cropped and resized then the cropping happens first,
+     * followed by resizing of the cropped image.
+     */
     public static final String PARAM_CROP_WIDTH = "crop_width";
+    
+    /**
+     * This optional {@link Integer} or {@link Float} parameter specifies the
+     * height of the image after cropping. This may be expressed as pixels or it
+     * may represent a percentage of the original image width, depending on the
+     * value of the PARAM_IS_PERCENT_CROP parameter. <br>
+     * If no value is specified for this parameter then the width of the image
+     * will be unchanged. <br>
+     * If an image is being cropped and resized then the cropping happens first,
+     * followed by resizing of the cropped image.
+     */
     public static final String PARAM_CROP_HEIGHT = "crop_height";
+
+    /**
+     * This optional {@link Integer} parameter specifies the horizontal position
+     * of the start point of the area to be cropped. By default this parameter
+     * sets the distance, in pixels, from the left-hand edge of the image to the
+     * start position of the crop area. By default a positive value will shift
+     * the start-position to the right, while a negative value will shift the
+     * start position to the left. Setting the PARAM_CROP_GRAVITY parameter may
+     * change this, however.<br>
+     * If this parameter is not set it is assumed to be 0.
+     */
     public static final String PARAM_CROP_X_OFFSET = "crop_x";
+
+    /**
+     * This optional {@link Integer} parameter specifies the vertical position
+     * of the start point of the area to be cropped. By default this parameter
+     * sets the distance, in pixels, from the top edge of the image to the start
+     * position of the crop area. By default a positive value will shift the
+     * start-position downwards, while a negative value will shift the start
+     * position upwards. Setting the PARAM_CROP_GRAVITY parameter may change
+     * this, however.<br>
+     * If this parameter is not set it is assumed to be 0.
+     */
     public static final String PARAM_CROP_Y_OFFSET = "crop_y";
+
+    /**
+     * This optional {@link String} parameter determines the 'zero' position
+     * from which offsets are measured and also determines the direction of
+     * offsets. The allowed values of gravity are the four cardinal points
+     * (North, East, etc.), the four ordinal points (NorhtWest, SouthEast, etc)
+     * and Center. By default NorthWest gravity is used.
+     * <p>
+     * 
+     * If an ordinal gravity is set then the point from which offsets originate
+     * will be the appropriate corner. For example, NorthWest gravity would
+     * originate at teh top-left corner while SouthWest origin would originate
+     * at the bottom-left corner. Cardinal gravity sets the origin at the center
+     * of the appropriate edge. Center origin sets the origin at the center of
+     * the image.
+     * <p>
+     * 
+     * Gravity also affects the direction of offsets and how the offset position
+     * relates to the cropped image. For example, NorthWest gravity sets
+     * positive horizontal offset direction to right, positive vertical
+     * direction to down and sets the cropped image origin to the top-left
+     * corner. Northerly gavities set the positive vertical direction to down.
+     * Southerly gavities set teh positive vertical direction to up. Easterly
+     * gavities set teh positive horizontal positive direction to left. Westerly
+     * gavities set teh positive horizontal positive direction to right.
+     * <p>
+     * Some gravity values do not specify a horizontal or a vertical direction
+     * explicitly. For example North does not specify a horizontal direction,
+     * while Center does not specify either horizontal or vertical direction. In
+     * thse cases the positive horizontal offset direction is always right and
+     * the positive vertical offset direction is always down.
+     * <p>
+     * 
+     * The gravity also affects how the cropped image relates to the offset
+     * position. For example, NorthWest gravity causes the top-left corner of
+     * the cropped area to be the offset position, while NorthEast gravity would
+     * set the top-right corner of the cropped are to the offset position. When
+     * a direction is not explicitly specified then the center of the cropped
+     * area is placed at the offset position. For example, with North gravity
+     * the horizontal position is unspecified so the cropped area would be
+     * horizontally centered on the offset position, but the top edge of the
+     * cropped area would be at the offset position. For Center gravity the
+     * cropped area will be centered over the offset position both horizontally
+     * and vertically.
+     */
     public static final String PARAM_CROP_GRAVITY = "crop_gravity";
+    
+    /**
+     * This optional {@link Boolean} flag parameter specifies how the
+     * PARAM_CROP_HEIGHT and PARAM_CROP_WIDTH parameters are interpreted. If
+     * this parameter is set to <code>true</code> then the cropped image height and
+     * width are represented as a percentage of the original image height and
+     * width. If this parameter is set to <code>false</code> then the rendition
+     * height and width are represented as pixels. This parameter defaults to
+     * <code>false</code>.
+     */
     public static final String PARAM_IS_PERCENT_CROP = "percent_crop";
 
+    /**
+     * This optional {@link String} parameter specifies any additional
+     * ImageMagick commands, that the user wishes to add. These commands are
+     * appended after the various crop and resize options.
+     */
     public static final String PARAM_COMMAND_OPTIONS = "commandOptions";
 
     /*

source/java/org/alfresco/repo/rendition/executer/ReformatRenderingEngine.java

@@ -51,7 +51,9 @@ public class ReformatRenderingEngine extends AbstractTransformationRenderingEngi
     private static Log logger = LogFactory.getLog(ReformatRenderingEngine.class);
 
     /**
-     * This parameter is only necessary when converting from pdf to flash.
+     * This optional {@link String} parameter is only necessary when converting
+     * from pdf to Flash and is used to specify which Flash version to convert
+     * to.
      */
     public static final String PARAM_FLASH_VERSION = "flashVersion";
 

source/java/org/alfresco/service/cmr/rendition/RenditionService.java

@@ -32,9 +32,40 @@ import org.alfresco.service.namespace.QName;
  */
 public interface RenditionService extends RenditionDefinitionPersister
 {
+    /**
+     * This optional {@link NodeRef} parameter specifies an existing {@link NodeRef} to use
+     * as the rendition node. Properties on this node (including the content
+     * property cm:content) will be updated as required but the location and
+     * name of the node will not change. This parameter takes precedence over
+     * PARAM_DESTINATION_PATH_TEMPLATE.
+     */
     public static final String PARAM_DESTINATION_NODE = "rendition-destination-node";
+
+    /**
+     * This optional {@link String} parameter indicates where the rendition will be
+     * created. The parameter may specify either the actual file path to the
+     * rendition or it may specify a Freemarker template which can be resolved
+     * to a file path. In either case the path is relative to the root node of
+     * the store in which the source node exists. If the parameter
+     * PARAM_DESTINATION_NODE has been set then this parameter will be ignored.
+     */
     public static final String PARAM_DESTINATION_PATH_TEMPLATE = "destination-path-template";
+
+    /**
+     * This optional {@link QName} parameter specifies what the node type of the created rendition will
+     * be. If no type is specified then this defaults to cm:content.
+     */
     public static final String PARAM_RENDITION_NODETYPE = "rendition-nodetype";
+
+    /**
+     * This optional {@link Boolean} flag parameter determines whether an
+     * existing rendition is moved or orphaned. If the source node already has a
+     * rendition and this parameter is <code>false</code> the old rendition will
+     * be moved to the new destination location and updated appropriately. If
+     * this parameter is set to <code>true</code> then the old rendition will be
+     * left in its current location and the rold rendition association from the
+     * source node to the old rendition will be deleted.
+     */
     public static final String PARAM_ORPHAN_EXISTING_RENDITION = "orphan-existing-rendition";
     
     /**