true then the rendition will be re-rendered any time any
+ * property changes occur on the source node. This parameter defaults to
+ * false.
+ */
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
- * common to many and is used in some common handling code in this class.
+ // 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.
+ /**
+ * 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";
/**
diff --git a/source/java/org/alfresco/repo/rendition/executer/BaseTemplateRenderingEngine.java b/source/java/org/alfresco/repo/rendition/executer/BaseTemplateRenderingEngine.java
index 45124ebaf2..74a2aa6afb 100644
--- a/source/java/org/alfresco/repo/rendition/executer/BaseTemplateRenderingEngine.java
+++ b/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
- * the Template Service.
+ * This abstract class forms a basis for all rendering engines that are built
+ * around the Template Service.true then the rendition height and
+ * width are represented as a percentage of the original image height and
+ * width. If this parameter is set to false then the rendition
+ * height and width are represented as pixels. This parameter defaults to
+ * false.
+ */
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. true 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. false then the image will be stretched
+ * or compressed to fit the given height and width, regardless of the
+ * original aspect ratio. true
+ */
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.true the rendering process will be more performant
+ * for large images but the rendered image will be of lower quality. false 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. + * + * 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. + *
+ * + * 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. + *
+ * 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. + *
+ *
+ * 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 true 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 false then the rendition
+ * height and width are represented as pixels. This parameter defaults to
+ * false.
+ */
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";
/*
diff --git a/source/java/org/alfresco/repo/rendition/executer/ReformatRenderingEngine.java b/source/java/org/alfresco/repo/rendition/executer/ReformatRenderingEngine.java
index 8ba7cbf01a..c371710bab 100644
--- a/source/java/org/alfresco/repo/rendition/executer/ReformatRenderingEngine.java
+++ b/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";
diff --git a/source/java/org/alfresco/service/cmr/rendition/RenditionService.java b/source/java/org/alfresco/service/cmr/rendition/RenditionService.java
index e42707662e..927ccb81f9 100644
--- a/source/java/org/alfresco/service/cmr/rendition/RenditionService.java
+++ b/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 false the old rendition will
+ * be moved to the new destination location and updated appropriately. If
+ * this parameter is set to true 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";
/**