From cafa116c744e9e5ef0391219cb0fa57108e10827 Mon Sep 17 00:00:00 2001 From: Neil McErlean Date: Mon, 14 Jun 2010 10:41:13 +0000 Subject: [PATCH] Javadoc improvements and private variable renaming in the rendition service. git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@20622 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261 --- .../PerformRenditionActionExecuter.java | 72 +++++++++++++++---- .../repo/rendition/RenditionLocation.java | 20 +++++- .../repo/rendition/RenditionLocationImpl.java | 3 + .../repo/rendition/RenditionNodeManager.java | 9 ++- .../repo/rendition/RenditionServiceImpl.java | 9 +++ 5 files changed, 98 insertions(+), 15 deletions(-) diff --git a/source/java/org/alfresco/repo/rendition/PerformRenditionActionExecuter.java b/source/java/org/alfresco/repo/rendition/PerformRenditionActionExecuter.java index 90307b4677..babfbe033f 100644 --- a/source/java/org/alfresco/repo/rendition/PerformRenditionActionExecuter.java +++ b/source/java/org/alfresco/repo/rendition/PerformRenditionActionExecuter.java @@ -72,6 +72,7 @@ import org.springframework.extensions.surf.util.ParameterCheck; public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase { private static final Log log = LogFactory.getLog(PerformRenditionActionExecuter.class); + private static final String LINE_BREAK = System.getProperty("line.separator", "\n"); /** Action name and parameters */ public static final String NAME = "perform-rendition"; @@ -220,6 +221,12 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase }, runAsName); } + /** + * This method gets the (mandatory) rendition definition parameter from the containing action. + * @param containingAction the containing action. + * @return the rendition definition. + * @throws IllegalArgumentException if the rendition definition is missing. + */ private RenditionDefinition getRenditionDefinition(final Action containingAction) { Serializable rendDefObj = containingAction.getParameterValue(PARAM_RENDITION_DEFINITION); @@ -266,10 +273,11 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase } /** - * This method sets the renditionParent and rendition assocType. + * This method sets the temporary rendition parent node and the rendition assocType on the + * rendition definition. * * @param sourceNode - * @param definition + * @param definition the rendition definition. */ private void setTemporaryRenditionProperties(NodeRef sourceNode, RenditionDefinition definition) { @@ -281,9 +289,10 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase } /** + * This method delegates to the action service for the execution of the rendition. * @param sourceNode * @param definition - * @return + * @return the ChildAssociationRef result. */ private ChildAssociationRef executeRendition(NodeRef sourceNode, RenditionDefinition definition) { @@ -297,21 +306,22 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase RenditionDefinition renditionDefinition) { NodeRef tempRenditionNode = tempRendition.getChildRef(); - RenditionLocation location = getDestinationParentAssoc(sourceNode, renditionDefinition, tempRenditionNode); + RenditionLocation renditionLocation = resolveRenditionLocation(sourceNode, renditionDefinition, tempRenditionNode); QName renditionQName = renditionDefinition.getRenditionName(); if (log.isDebugEnabled()) { - final String lineBreak = System.getProperty("line.separator", "\n"); StringBuilder msg = new StringBuilder(); - msg.append("Creating/updating rendition based on:").append(lineBreak).append(" sourceNode: ").append( - sourceNode).append(lineBreak).append(" tempRendition: ").append(tempRendition).append( - lineBreak).append(" parentNode: ").append(location.getParentRef()).append(lineBreak).append( - " childName: ").append(location.getChildName()).append(lineBreak).append( + msg.append("Creating/updating rendition based on:").append(LINE_BREAK).append(" sourceNode: ").append( + sourceNode).append(LINE_BREAK).append(" tempRendition: ").append(tempRendition).append( + LINE_BREAK).append(" parentNode: ").append(renditionLocation.getParentRef()).append(LINE_BREAK).append( + " childName: ").append(renditionLocation.getChildName()).append(LINE_BREAK).append( " renditionDefinition.name: ").append(renditionQName); log.debug(msg.toString()); } NodeRef oldRendition=getOldRenditionIfExists(sourceNode, renditionDefinition); - RenditionNodeManager renditionNodeManager = new RenditionNodeManager(sourceNode, oldRendition, location, renditionDefinition, nodeService); + + RenditionNodeManager renditionNodeManager = new RenditionNodeManager(sourceNode, oldRendition, + renditionLocation, renditionDefinition, nodeService); ChildAssociationRef primaryAssoc = renditionNodeManager.findOrCreateRenditionNode(); // Copy relevant properties from the temporary node to the new rendition @@ -321,7 +331,7 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase // Set the name property on the rendition if it has not already been // set. - String renditionName = getRenditionName(tempRenditionNode, location, renditionDefinition); + String renditionName = getRenditionName(tempRenditionNode, renditionLocation, renditionDefinition); nodeService.setProperty(renditionNode, ContentModel.PROP_NAME, renditionName); // Delete the temporary rendition. @@ -339,6 +349,14 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase return renditionAssoc; } + /** + * This method returns the rendition on the given sourceNode with the given renditionDefinition, if such + * a rendition exists. + * + * @param sourceNode + * @param renditionDefinition + * @return the rendition node if one exists, else null. + */ private NodeRef getOldRenditionIfExists(NodeRef sourceNode, RenditionDefinition renditionDefinition) { QName renditionName=renditionDefinition.getRenditionName(); @@ -358,6 +376,11 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase return result; } + /** + * This method manages the rn:rendition aspects on the rendition node. It applies the + * correct rendition aspect based on the rendition node's location and removes any out-of-date rendition + * aspect. + */ private void manageRenditionAspects(NodeRef sourceNode, ChildAssociationRef renditionParentAssoc) { NodeRef renditionNode = renditionParentAssoc.getChildRef(); @@ -381,6 +404,20 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase } } + /** + * This method calculates the name for a rendition node. The following approaches are attempted in + * the order given below. + *
    + *
  1. If a name is defined in the {@link RenditionLocation} then that is used.
    2. + *
  2. If the temporary rendition has a cm:name value, then that is used.
    3. + *
  3. Otherwise use the rendition definition's rendition name.
    4. + *
+ * + * @param tempRenditionNode the temporary rendition node. + * @param location a RenditionLocation struct. + * @param renditionDefinition the rendition definition. + * @return the name for the rendition. + */ private String getRenditionName(NodeRef tempRenditionNode, RenditionLocation location, RenditionDefinition renditionDefinition) { @@ -400,6 +437,13 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase return renditionDefinition.getRenditionName().getLocalName(); } + /** + * This method copies properties from the sourceNode onto the targetNode as well as the node type. + * {@link PerformRenditionActionExecuter#unchangedProperties Some properties} are not copied. + * + * @param sourceNode the node from which the type and properties should be copied. + * @param targetNode the node to which the type and properties are copied. + */ private void transferNodeProperties(NodeRef sourceNode, NodeRef targetNode) { if (log.isDebugEnabled()) @@ -419,7 +463,11 @@ public class PerformRenditionActionExecuter extends ActionExecuterAbstractBase nodeService.setProperties(targetNode, newProps); } - private RenditionLocation getDestinationParentAssoc(NodeRef sourceNode, RenditionDefinition definition, + /** + * Given a rendition definition, a source node and a temporary rendition node, this method uses a + * {@link RenditionLocationResolver} to calculate the {@link RenditionLocation} of the rendition. + */ + private RenditionLocation resolveRenditionLocation(NodeRef sourceNode, RenditionDefinition definition, NodeRef tempRendition) { return renditionLocationResolver.getRenditionLocation(sourceNode, definition, tempRendition); diff --git a/source/java/org/alfresco/repo/rendition/RenditionLocation.java b/source/java/org/alfresco/repo/rendition/RenditionLocation.java index 4cd3c1ed76..7907e2b689 100644 --- a/source/java/org/alfresco/repo/rendition/RenditionLocation.java +++ b/source/java/org/alfresco/repo/rendition/RenditionLocation.java @@ -20,11 +20,27 @@ package org.alfresco.repo.rendition; import org.alfresco.service.cmr.repository.NodeRef; +/** + * This simple interface defines a data class which identifies a rendition node, its parent and its name. + */ + public interface RenditionLocation { + /** + * Gets the parent node of the rendition. + * @return + */ NodeRef getParentRef(); - + + /** + * Gets the rendition node itself. + * @return + */ NodeRef getChildRef(); - + + /** + * Gets the name of the rendition. + * @return + */ String getChildName(); } diff --git a/source/java/org/alfresco/repo/rendition/RenditionLocationImpl.java b/source/java/org/alfresco/repo/rendition/RenditionLocationImpl.java index 71e81b048c..95ed1060ee 100644 --- a/source/java/org/alfresco/repo/rendition/RenditionLocationImpl.java +++ b/source/java/org/alfresco/repo/rendition/RenditionLocationImpl.java @@ -20,6 +20,9 @@ package org.alfresco.repo.rendition; import org.alfresco.service.cmr.repository.NodeRef; +/** + * This simple class is a struct containing a rendition node, its parent and its name. + */ public class RenditionLocationImpl implements RenditionLocation { private final NodeRef parentRef; diff --git a/source/java/org/alfresco/repo/rendition/RenditionNodeManager.java b/source/java/org/alfresco/repo/rendition/RenditionNodeManager.java index 6c4cee2da2..1d0ed6de8b 100644 --- a/source/java/org/alfresco/repo/rendition/RenditionNodeManager.java +++ b/source/java/org/alfresco/repo/rendition/RenditionNodeManager.java @@ -62,6 +62,13 @@ public class RenditionNodeManager this.nodeService = nodeService; } + /** + * This method returns the {@link ChildAssociationRef} for the rendition node. In doing this + * it may reuse an existing rendition node, move an existing rendition node or create a new rendition node + * as appropriate. + * + * @return the {@link ChildAssociationRef} of the rendition node. + */ public ChildAssociationRef findOrCreateRenditionNode() { QName renditionName = renditionDefinition.getRenditionName(); @@ -79,7 +86,7 @@ public class RenditionNodeManager } // If the old rendition is in the wrong location and the 'orphan // existing rendition' param is set to true or the RenditionLocation - // specifies a destination NodeRef then ldelete the old + // specifies a destination NodeRef then delete the old // rendition association and create a new rendition node. if (orphanExistingRendition()) { diff --git a/source/java/org/alfresco/repo/rendition/RenditionServiceImpl.java b/source/java/org/alfresco/repo/rendition/RenditionServiceImpl.java index 81cd06eb5b..68fbf11cfa 100644 --- a/source/java/org/alfresco/repo/rendition/RenditionServiceImpl.java +++ b/source/java/org/alfresco/repo/rendition/RenditionServiceImpl.java @@ -194,6 +194,15 @@ public class RenditionServiceImpl implements RenditionService, RenditionDefiniti return; } + /** + * This methods creates a containing 'perform-rendition' action, within which the renditions + * will be performed. + * + * @param sourceNode the source node which is to be rendered. + * @param definition the rendition definition to be used. + * @param asynchronous + * @return + */ private ChildAssociationRef createAndExecuteRenditionAction(NodeRef sourceNode, RenditionDefinition definition, boolean asynchronous) {