Java doc tidy up in auditing and scheduled actions

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

source/java/org/alfresco/repo/action/scheduled/AbstractScheduledAction.java

@@ -69,8 +69,25 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
      */
     public enum TransactionMode
     {
-        ISOLATED_TRANSACTIONS, UNTIL_FIRST_FAILURE, ONE_TRANSACTION;
+        /**
+         * Run Each action in an isolated transaction
+         */
+        ISOLATED_TRANSACTIONS, 
+        /**
+         * Run each action in anisolated transaction, but stop at the first failure
+         */
+        UNTIL_FIRST_FAILURE, 
+        /**
+         * Run in one big transaction. Any failure rolls the whole lot b ack 
+         */
+        ONE_TRANSACTION;
 
+        /**
+         * Generate a mode from a string.
+         * 
+         * @param transactionModeString
+         * @return - the transaction mode.
+         */
         public static TransactionMode getTransactionMode(String transactionModeString)
         {
             TransactionMode transactionMode;
@@ -102,8 +119,21 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
      */
     public enum CompensatingActionMode
     {
-        RUN_COMPENSATING_ACTIONS_ON_FAILURE, IGNORE;
+        /**
+         * If failure occurs run the comensating actions.
+         */
+        RUN_COMPENSATING_ACTIONS_ON_FAILURE, 
+        /**
+         * Ignore compensating actions
+         */
+        IGNORE;
 
+        /**
+         * Parse a string to a compensating action mode - used in reading the config.
+         * 
+         * @param compensatingActionModeString
+         * @return - the compensating action mode.
+         */
         public static CompensatingActionMode getCompensatingActionMode(String compensatingActionModeString)
         {
             CompensatingActionMode compensatingActionMode;
@@ -170,7 +200,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     /**
      * Get the user in whose name to run the action.
      * 
-     * @return
+     * @return - the user as whom to run the action
      */
     public String getRunAsUser()
     {
@@ -189,6 +219,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
 
     /**
      * Get the template definition.
+     * @return - the template action definition
      */
     public TemplateActionDefinition getTemplateActionDefinition()
     {
@@ -208,7 +239,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     /**
      * Get the actions service.
      * 
-     * @return
+     * @return - the action service
      */
     public ActionService getActionService()
     {
@@ -238,7 +269,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     /**
      * Get the transaction service.
      * 
-     * @return
+     * @return - the transaction service.
      */
     public TransactionService getTransactionService()
     {
@@ -257,6 +288,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
 
     /**
      * Set the template action that is used to generate the real action for each node.
+     * @param templateActionDefinition 
      */
     public void setTemplateActionDefinition(TemplateActionDefinition templateActionDefinition)
     {
@@ -266,7 +298,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     /**
      * Get the behaviour for compensating actions.
      * 
-     * @return
+     * @return - the compensating action mode.
      */
     public CompensatingActionMode getCompensatingActionModeEnum()
     {
@@ -276,13 +308,19 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     /**
      * Get the transaction mode.
      * 
-     * @return
+     * @return - the transaction mode.
      */
     public TransactionMode getTransactionModeEnum()
     {
         return transactionMode;
     }
 
+    /**
+     * Register with teh scheduler.
+     * 
+     * @param scheduler 
+     * @throws SchedulerException 
+     */
     public void register(Scheduler scheduler) throws SchedulerException
     {
         JobDetail jobDetail = getJobDetail();
@@ -299,14 +337,14 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     /**
      * Get the trigger definition for this job. Used to register with the injected scheduler.
      * 
-     * @return
+     * @return - the trigger definition for this scheduled action.
      */
     public abstract Trigger getTrigger();
 
     /**
      * Get the list of nodes against which this action should run.
      * 
-     * @return
+     * @return - the list of node refs for which to run this action.
      */
     public abstract List<NodeRef> getNodes();
 
@@ -314,14 +352,14 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
      * Generate the actual action for the given node from the action template.
      * 
      * @param nodeRef
-     * @return
+     * @return - the action to execute.
      */
     public abstract Action getAction(NodeRef nodeRef);
 
     /**
      * Get the job detail.
      * 
-     * @return
+     * @return - the job detail.
      */
     private JobDetail getJobDetail()
     {
@@ -344,6 +382,13 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
     public static class JobDefinition implements Job
     {
 
+        /**
+         * Execute the job
+         * 
+         * @param ctx 
+         * @throws JobExecutionException 
+         * 
+         */
         public void execute(JobExecutionContext ctx) throws JobExecutionException
         {
             final AbstractScheduledAction abstractScheduledAction = (AbstractScheduledAction) ctx.getJobDetail()
@@ -609,6 +654,8 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
      * Simple class to hold to related objects
      * 
      * @author Andy Hind
+     * @param <FIRST> 
+     * @param <SECOND> 
      */
     public static class Pair<FIRST, SECOND>
     {
@@ -637,7 +684,7 @@ public abstract class AbstractScheduledAction implements ScheduledActionDefiniti
      * Support method to translate exceptions to runtime exceptions.
      * 
      * @param t
-     * @return
+     * @return - the exception as a wrapped RuntimeException.
      */
     private static Object throwRuntimeException(Throwable t)
     {

source/java/org/alfresco/repo/action/scheduled/AbstractTemplateActionDefinition.java

@@ -34,17 +34,17 @@ import org.alfresco.service.cmr.repository.TemplateService;
  */
 public abstract class AbstractTemplateActionDefinition implements TemplateActionDefinition
 {
-    /*
+    /**
      * The action service
      */
     public ActionService actionService;
 
-    /*
+    /**
      * The template service
      */
     public TemplateService templateService;
 
-    /*
+    /**
      * The compensating action
      */
     protected TemplateActionDefinition compensatingTemplateActionDefinition;
@@ -60,7 +60,7 @@ public abstract class AbstractTemplateActionDefinition implements TemplateAction
     /**
      * Get the action service.
      * 
-     * @return
+     * @return - the action service.
      */
     public ActionService getActionService()
     {
@@ -80,7 +80,7 @@ public abstract class AbstractTemplateActionDefinition implements TemplateAction
     /**
      * Get the template service.
      * 
-     * @return
+     * @return - the template service
      */
     public TemplateService getTemplateService()
     {
@@ -111,7 +111,7 @@ public abstract class AbstractTemplateActionDefinition implements TemplateAction
     /**
      * Get the template that defines the conpensating action.
      * 
-     * @return
+     * @return - the template action definition.
      */
     public TemplateActionDefinition getCompensatingTemplateCompositeActionDefinition()
     {

source/java/org/alfresco/repo/action/scheduled/CompensatingActionException.java

@@ -48,32 +48,63 @@ public class CompensatingActionException extends AlfrescoRuntimeException
 
     List<Pair<Action, NodeRef>> compensatingActions;
 
+    
+    /**
+     * @param msgId
+     */
     public CompensatingActionException(String msgId)
     {
         super(msgId);
     }
 
+    /**
+     * 
+     * @param msgId
+     * @param cause
+     * @param compensatingActions
+     */
     public CompensatingActionException(String msgId, Throwable cause, List<Pair<Action, NodeRef>> compensatingActions)
     {
         super(msgId, cause);
         this.compensatingActions = compensatingActions;
     }
 
+    /**
+     * Get the compensationg actions
+     * 
+     * @return - the compensating actions
+     */
     public List<Pair<Action, NodeRef>> getCompensatingActions()
     {
         return compensatingActions;
     }
 
+    /**
+     * 
+     * @param msgId
+     * @param msgParams
+     */
     public CompensatingActionException(String msgId, Object[] msgParams)
     {
         super(msgId, msgParams);
     }
 
+    /**
+     * 
+     * @param msgId
+     * @param cause
+     */
     public CompensatingActionException(String msgId, Throwable cause)
     {
         super(msgId, cause);
     }
 
+    /**
+     * 
+     * @param msgId
+     * @param msgParams
+     * @param cause
+     */
     public CompensatingActionException(String msgId, Object[] msgParams, Throwable cause)
     {
         super(msgId, msgParams, cause);

source/java/org/alfresco/repo/action/scheduled/CompositeTemplateActionDefinition.java

@@ -43,6 +43,10 @@ public class CompositeTemplateActionDefinition extends AbstractTemplateActionDef
      */
     private List<TemplateActionDefinition> templateActionDefinitions;
     
+    /**
+     * Default constructor.
+     *
+     */
     public CompositeTemplateActionDefinition()
     {
         super();
@@ -62,7 +66,7 @@ public class CompositeTemplateActionDefinition extends AbstractTemplateActionDef
     /**
      * Get the list of template actions.
      * 
-     * @return
+     * @return - a list of templates for action definitions.
      */
     public List<TemplateActionDefinition> templateActionDefinitions()
     {
@@ -71,6 +75,8 @@ public class CompositeTemplateActionDefinition extends AbstractTemplateActionDef
 
     /**
      * Build the composite action in the context of the given node.
+     * @param nodeRef 
+     * @return - the contextualised action.
      * 
      */
     public Action getAction(NodeRef nodeRef)

source/java/org/alfresco/repo/action/scheduled/CronScheduledQueryBasedTemplateActionDefinition.java

@@ -41,8 +41,8 @@ import org.quartz.Scheduler;
 import org.quartz.Trigger;
 
 /**
- * A scheduled action for which the trigger is defined in the standard cron format and the nodes to which the 
+ * A scheduled action for which the trigger is defined in the standard cron format and the nodes to which the action
- * action should be run is defined from the nodes selected by query.
+ * should be run is defined from the nodes selected by query.
  * 
  * @author Andy Hind
  */
@@ -104,12 +104,13 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
     private Scheduler scheduler;
 
     /*
-     * The templateModelFactory 
+     * The templateModelFactory This defines in which template language the query template is defined
-     * 
-     * This defines in which template language the query template is defined
      */
     private TemplateActionModelFactory templateActionModelFactory;
 
+    /**
+     * Default constructore
+     */
     public CronScheduledQueryBasedTemplateActionDefinition()
     {
         super();
@@ -119,41 +120,77 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
     // IOC
     //
 
+    /**
+     * Get the search service.
+     * 
+     * @return - the serach service.
+     */
     public SearchService getSearchService()
     {
         return searchService;
     }
 
+    /**
+     * Set the search service.
+     * 
+     * @param searchService
+     */
     public void setSearchService(SearchService searchService)
     {
         this.searchService = searchService;
     }
 
+    /**
+     * Get the template service.
+     * 
+     * @return - the template service.
+     */
     public TemplateService getTemplateService()
     {
         return templateService;
     }
 
+    /**
+     * Set the template service.
+     * 
+     * @param templateService
+     */
     public void setTemplateService(TemplateService templateService)
     {
         this.templateService = templateService;
     }
 
+    /**
+     * Get the scheduler.
+     * @return - the scheduler.
+     */
     public Scheduler getScheduler()
     {
         return scheduler;
     }
 
+    /**
+     * Set the scheduler.
+     * @param scheduler
+     */
     public void setScheduler(Scheduler scheduler)
     {
         this.scheduler = scheduler;
     }
 
+    /**
+     * Get the template action model factory.
+     * @return - the template action model factory.
+     */
     public TemplateActionModelFactory getTemplateActionModelFactory()
     {
         return templateActionModelFactory;
     }
 
+    /**
+     * Set the template action model factory.
+     * @param templateActionModelFactory
+     */
     public void setTemplateActionModelFactory(TemplateActionModelFactory templateActionModelFactory)
     {
         this.templateActionModelFactory = templateActionModelFactory;
@@ -163,6 +200,9 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
     // End of IOC
     //
     
+    /* (non-Javadoc)
+     * @see org.alfresco.repo.action.scheduled.AbstractScheduledAction#getTrigger()
+     */
     @Override
     public Trigger getTrigger()
     {
@@ -170,12 +210,15 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
         {
             return new CronTrigger(getTriggerName(), getTriggerGroup(), getCronExpression());
         }
-        catch (ParseException e)
+        catch (final ParseException e)
         {
             throw new InvalidCronExpression("Invalid chron expression: n" + getCronExpression());
         }
     }
 
+    /* (non-Javadoc)
+     * @see org.alfresco.repo.action.scheduled.AbstractScheduledAction#getNodes()
+     */
     @Override
     public List<NodeRef> getNodes()
     {
@@ -215,6 +258,9 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
         return nodeRefs;
     }
 
+    /* (non-Javadoc)
+     * @see org.alfresco.repo.action.scheduled.AbstractScheduledAction#getAction(org.alfresco.service.cmr.repository.NodeRef)
+     */
     @Override
     public Action getAction(NodeRef nodeRef)
     {
@@ -226,81 +272,150 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
     // IOC/Getters/Setters for instance variables
     //
 
+    /**
+     * Set the query language
+     * @param queryLanguage 
+     */
     public void setQueryLanguage(String queryLanguage)
     {
         this.queryLanguage = queryLanguage;
     }
 
+    /**
+     * Get the query language.
+     * @return - the query language.
+     */
     public String getQueryLanguage()
     {
         return queryLanguage;
     }
 
+    /**
+     * Set alist of stores to use.
+     * @param stores - the list of stores.
+     */
     public void setStores(List<String> stores)
     {
         this.stores = stores;
     }
 
+    /**
+     * Get the list of stores.
+     * 
+     * @return - the list of stores.
+     */
     public List<String> getStores()
     {
         return stores;
     }
 
+    /**
+     * Set the template for the query.
+     * 
+     * @param queryTemplate
+     */
     public void setQueryTemplate(String queryTemplate)
     {
         this.queryTemplate = queryTemplate;
     }
 
+    /**
+     * Get the template from which to build the query.
+     * @return - the template for the query.
+     */
     public String getQueryTemplate()
     {
         return queryTemplate;
     }
 
+    /**
+     * Set the cron expression - see the wiki for examples.
+     * @param cronExpression
+     */
     public void setCronExpression(String cronExpression)
     {
         this.cronExpression = cronExpression;
     }
 
+
+    /**
+     * Get the cron expression.
+     * @return - the cron expression.
+     */
     public String getCronExpression()
     {
         return cronExpression;
     }
 
+    /**
+     * Set the job name.
+     * @param jobName 
+     */
     public void setJobName(String jobName)
     {
         this.jobName = jobName;
     }
 
+    /**
+     * Get the job name
+     * @return - the job name.
+     * 
+     */
     public String getJobName()
     {
         return jobName;
     }
 
+    /**
+     * Set the job group.
+     * @param jobGroup 
+     */
     public void setJobGroup(String jobGroup)
     {
         this.jobGroup = jobGroup;
     }
 
+    /**
+     * Get the job group.
+     * @return - the job group.
+     */
     public String getJobGroup()
     {
         return jobGroup;
     }
 
+    /** 
+     * Set the trigger name.
+     * @param triggerName 
+     */
     public void setTriggerName(String triggerName)
     {
         this.triggerName = triggerName;
     }
 
+    /**
+     * Get the trigger name
+     * @return - the trigger name.
+     */
     public String getTriggerName()
     {
         return triggerName;
     }
 
+    /**
+     * Set the trigger group.
+     * @param triggerGroup 
+     */
     public void setTriggerGroup(String triggerGroup)
     {
         this.triggerGroup = triggerGroup;
     }
 
+    /**
+     * Get the name of the trigger group.
+     * @return - the trigger group.
+     * 
+     */
     public String getTriggerGroup()
     {
         return this.triggerGroup;
@@ -308,6 +423,7 @@ public class CronScheduledQueryBasedTemplateActionDefinition extends AbstractSch
 
     /**
      * Register with the scheduler.
+     * @throws Exception 
      */
     public void afterPropertiesSet() throws Exception
     {

source/java/org/alfresco/repo/action/scheduled/FreeMarkerModelLuceneFunctionTest.java

@@ -35,7 +35,6 @@ import junit.framework.TestCase;
 
 import org.alfresco.repo.security.authentication.AuthenticationComponent;
 import org.alfresco.service.ServiceRegistry;
-import org.alfresco.service.cmr.repository.datatype.Duration;
 import org.alfresco.service.transaction.TransactionService;
 import org.alfresco.util.ApplicationContextHelper;
 import org.alfresco.util.ISO8601DateFormat;
@@ -56,13 +55,19 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
     private ServiceRegistry serviceRegistry;
     private UserTransaction tx;
 
-    private Date today;
+    /**
-
+     * 
+     *
+     */
     public FreeMarkerModelLuceneFunctionTest()
     {
         super();
     }
 
+    /**
+     * 
+     * @param arg0
+     */
     public FreeMarkerModelLuceneFunctionTest(String arg0)
     {
         super(arg0);
@@ -80,16 +85,6 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
                 .getLocalName());
         tx = transactionService.getUserTransaction();
         tx.begin();
-
-        GregorianCalendar cal = new GregorianCalendar();
-        cal.set(Calendar.HOUR, 0);
-        cal.set(Calendar.MINUTE, 0);
-        cal.set(Calendar.SECOND, 0);
-        cal.set(Calendar.MILLISECOND, 0);
-        
-        today = cal.getTime();
-        
-        
     }
 
     @Override
@@ -100,6 +95,10 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
         super.tearDown();
     }
 
+    /**
+     * Test date formatting
+     *
+     */
     public void testDate()
     {
         String template = "${date?date?string(\"yyyy-MM-dd\")}";
@@ -109,6 +108,10 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
         assertEquals(result, SDF2.format(new Date()));
     }
     
+    /**
+     * Test generation of lucene date ranges
+     *
+     */
     public void testLuceneDateRangeFunction()
     {
         GregorianCalendar cal = new GregorianCalendar();
@@ -125,6 +128,10 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
         assertEquals(result, "["+isoStartDate+" TO "+isoEndDate+"]");
     }
     
+    /**
+     * Test generation of lucene date ranges
+     *
+     */
     public void testLuceneDateRangeFunctionToDate()
     {
         GregorianCalendar cal = new GregorianCalendar();
@@ -141,6 +148,10 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
         assertEquals(result, "["+isoStartDate+" TO "+isoEndDate+"]");
     }
     
+    /**
+     * Test generation of lucene date ranges
+     *
+     */
     public void testLuceneDateRangeFunctionTodayPlus4()
     {
         GregorianCalendar cal = new GregorianCalendar();
@@ -161,6 +172,10 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
         assertEquals(result, "["+isoStartDate+" TO "+isoEndDate+"]");
     }
     
+    /**
+     * Test generation of lucene date ranges
+     *
+     */
     public void testLuceneDateRangeFunctionTodayMinus4()
     {
         GregorianCalendar cal = new GregorianCalendar();
@@ -180,7 +195,10 @@ public class FreeMarkerModelLuceneFunctionTest extends TestCase
         assertEquals(result, "["+isoEndDate+" TO "+isoStartDate+"]");
     }
     
-    
+    /**
+     * Test generation of lucene date ranges
+     *
+     */
     public void testLuceneDateRangeFunctionTodayToday()
     {
         GregorianCalendar cal = new GregorianCalendar();

source/java/org/alfresco/repo/action/scheduled/FreeMarkerWithLuceneExtensionsModelFactory.java

@@ -58,6 +58,9 @@ public class FreeMarkerWithLuceneExtensionsModelFactory implements TemplateActio
      */
     private ServiceRegistry serviceRegistry;
 
+    /**
+     * Default constructor.
+     */
     public FreeMarkerWithLuceneExtensionsModelFactory()
     {
         super();
@@ -65,6 +68,10 @@ public class FreeMarkerWithLuceneExtensionsModelFactory implements TemplateActio
 
     // IOC
     
+    /**
+     * Set the service registry
+     * @param serviceRegistry 
+     */
     public void setServiceRegistry(ServiceRegistry serviceRegistry)
     {
         this.serviceRegistry = serviceRegistry;

source/java/org/alfresco/repo/action/scheduled/InvalidCronExpression.java

@@ -24,6 +24,12 @@
  */
 package org.alfresco.repo.action.scheduled;
 
+/**
+ * Exception for invalid cron expressions
+ * 
+ * @author andyh
+ *
+ */
 public class InvalidCronExpression extends ScheduledActionException
 {
 
@@ -32,21 +38,44 @@ public class InvalidCronExpression extends ScheduledActionException
      */
     private static final long serialVersionUID = -6618964886875008727L;
 
+    /**
+     * Invalid cron expression
+     * 
+     * @param msgId
+     */
     public InvalidCronExpression(String msgId)
     {
         super(msgId);
     }
 
+    /**
+     * Invalid cron expression
+     * 
+     * @param msgId
+     * @param msgParams
+     */
     public InvalidCronExpression(String msgId, Object[] msgParams)
     {
         super(msgId, msgParams);
     }
 
+    /**
+     * Invalid cron expression
+     * 
+     * @param msgId
+     * @param cause
+     */
     public InvalidCronExpression(String msgId, Throwable cause)
     {
         super(msgId, cause);
     }
 
+    /**
+     * Invalid cron expression
+     * @param msgId
+     * @param msgParams
+     * @param cause
+     */
     public InvalidCronExpression(String msgId, Object[] msgParams, Throwable cause)
     {
         super(msgId, msgParams, cause);

source/java/org/alfresco/repo/action/scheduled/ScheduledActionDefinition.java

@@ -49,7 +49,7 @@ public interface ScheduledActionDefinition extends InitializingBean
     /**
      * Get the template action definition that is used to build the Action to execute.
      * 
-     * @return
+     * @return - the template action definition.
      */
     public TemplateActionDefinition getTemplateActionDefinition();
 
@@ -71,7 +71,7 @@ public interface ScheduledActionDefinition extends InitializingBean
     /**
      * Get the name of the job - used for job admin
      * 
-     * @return
+     * @return - the job name
      */
     public String getJobName();
 
@@ -84,7 +84,7 @@ public interface ScheduledActionDefinition extends InitializingBean
 
     /**
      * Get the job group - used for job admin
-     * @return
+     * @return - the job group.
      */
     public String getJobGroup();
 
@@ -97,7 +97,7 @@ public interface ScheduledActionDefinition extends InitializingBean
 
     /**
      * Get the trigger name - used for job admin
-     * @return
+     * @return - the trigger name.
      */
     public String getTriggerName();
 
@@ -111,7 +111,7 @@ public interface ScheduledActionDefinition extends InitializingBean
     /**
      * Get the trigger group - used for job admin
      * 
-     * @return
+     * @return - the trigger group.
      */
     public String getTriggerGroup();
 

source/java/org/alfresco/repo/action/scheduled/ScheduledActionException.java

@@ -39,21 +39,45 @@ public class ScheduledActionException extends AlfrescoRuntimeException
      */
     private static final long serialVersionUID = -543079391770744598L;
 
+    /**
+     * Exception generated from scheduled actions
+     * 
+     * @param msgId
+     */
     public ScheduledActionException(String msgId)
     {
         super(msgId);
     }
 
+    /**
+     * Exception generated from scheduled actions
+     * 
+     * @param msgId
+     * @param msgParams
+     */
     public ScheduledActionException(String msgId, Object[] msgParams)
     {
         super(msgId, msgParams);
     }
 
+    /**
+     * Exception generated from scheduled actions
+     * 
+     * @param msgId
+     * @param cause
+     */
     public ScheduledActionException(String msgId, Throwable cause)
     {
         super(msgId, cause);
     }
 
+    /**
+     * Exception generated from scheduled actions
+     * 
+     * @param msgId
+     * @param msgParams
+     * @param cause
+     */
     public ScheduledActionException(String msgId, Object[] msgParams, Throwable cause)
     {
         super(msgId, msgParams, cause);

source/java/org/alfresco/repo/action/scheduled/SimpleTemplateActionDefinition.java

@@ -33,7 +33,6 @@ import org.alfresco.service.cmr.action.ActionDefinition;
 import org.alfresco.service.cmr.dictionary.DataTypeDefinition;
 import org.alfresco.service.cmr.dictionary.DictionaryService;
 import org.alfresco.service.cmr.repository.NodeRef;
-import org.alfresco.service.cmr.repository.NodeService;
 import org.alfresco.service.cmr.repository.datatype.DefaultTypeConverter;
 import org.alfresco.service.namespace.QName;
 import org.springframework.beans.BeansException;
@@ -87,7 +86,7 @@ public class SimpleTemplateActionDefinition extends AbstractTemplateActionDefini
     /**
      * Get the template model factory.
      * 
-     * @return
+     * @return - the template model factory
      */
     public TemplateActionModelFactory getTemplateActionModelFactory()
     {
@@ -107,7 +106,7 @@ public class SimpleTemplateActionDefinition extends AbstractTemplateActionDefini
     /**
      * Get the dictionary service.
      * 
-     * @return
+     * @return - the dictionary service.
      */
     public DictionaryService getDictionaryService()
     {
@@ -137,7 +136,7 @@ public class SimpleTemplateActionDefinition extends AbstractTemplateActionDefini
     /**
      * Get the name of the action.
      * 
-     * @return
+     * @return - the name of the action.
      */
     public String getActionName()
     {
@@ -159,7 +158,7 @@ public class SimpleTemplateActionDefinition extends AbstractTemplateActionDefini
     /**
      * Get the templates that define the parameters for the action.
      * 
-     * @return
+     * @return the templates used to create parameters for the generated action.
      */
     public Map<String, String> getParameterTemplates()
     {

source/java/org/alfresco/repo/action/scheduled/TemplateActionDefinition.java

@@ -39,7 +39,7 @@ public interface TemplateActionDefinition
      * Generate an action definition for the action defined by this template.
      * 
      * @param nodeRef
-     * @return
+     * @return - the action.
      */
     public Action getAction(NodeRef nodeRef);
 }

source/java/org/alfresco/repo/action/scheduled/TemplateActionModelFactory.java

@@ -37,14 +37,14 @@ public interface TemplateActionModelFactory
     /**
      * Get the name of the template engine for which this factory applies
      * 
-     * @return
+     * @return - the template engine.
      */
     public String getTemplateEngine();
     
     /**
      * Build a model with no default node context.
      * 
-     * @return
+     * @return - the model for the template engine.
      */
     public Object getModel();
     
@@ -52,7 +52,7 @@ public interface TemplateActionModelFactory
      * Build a model with a default node context.
      * 
      * @param nodeRef
-     * @return
+     * @return - the model (with nodeRef as its context).
      */
     public Object getModel(NodeRef nodeRef);
 }

source/java/org/alfresco/repo/audit/ApplicationAuditModel.java

@@ -26,43 +26,57 @@ package org.alfresco.repo.audit;
 
 import org.alfresco.service.cmr.repository.NodeRef;
 
+/**
+ * The audit model used for application level auditing.
+ * 
+ * @author andyh
+ */
 public interface ApplicationAuditModel
 {
     /**
      * Report if audit behaviour can be determined before the method call
      * 
-     * @param auditState,
+     * @param auditMode
-     * @param mi
+     * @param application
-     * @return
+     * @param description
+     * @param key
+     * @param args
+     * @return - the audit mode
      */
-    public AuditMode beforeExecution(AuditMode auditMode, String application, String description,
+    public AuditMode beforeExecution(AuditMode auditMode, String application, String description, NodeRef key,
-            NodeRef key, Object... args);
+            Object... args);
 
     /**
      * Report if audit behaviour can be determined after the method call
      * 
-     * @param auditState,
+     * @param auditMode
-     * @param mi
+     * @param application
-     * @return
+     * @param description
+     * @param key
+     * @param args
+     * @return - the audit mode
      */
-    public AuditMode afterExecution(AuditMode auditMode, String application,  String description,
+    public AuditMode afterExecution(AuditMode auditMode, String application, String description, NodeRef key,
-            NodeRef key, Object... args);
+            Object... args);
 
     /**
-     * Report if audit behaviour should be invoked on error. It could be we look at the error and filter - this is not supported at the moment.
+     * Report if audit behaviour should be invoked on error. It could be we look at the error and filter - this is not
+     * supported at the moment.
      * 
-     * @param auditState,
+     * @param auditMode
-     * @param mi
+     * @param application
-     * @return
+     * @param description
+     * @param key
+     * @param args
+     * @return - the audit mode
      */
-    public AuditMode onError(AuditMode auditMode, String application,  String description,
+    public AuditMode onError(AuditMode auditMode, String application, String description, NodeRef key, Object... args);
-            NodeRef key, Object... args);
 
    /**
     * Get the optional parameters that are to be recorded
     * 
-     * @param mi
+    * @param application
-     * @return
+    * @return - the audit mode
     */
     public RecordOptions getAuditRecordOptions(String application);
 }

source/java/org/alfresco/repo/audit/AuditMode.java

@@ -43,8 +43,37 @@ import org.alfresco.repo.audit.model.AuditModelException;
  */
 public enum AuditMode
 {
-    ALL, SUCCESS, FAIL, NONE, UNSET;
+    /**
+     * All 
+     */
+    ALL, 
     
+    /**
+     * Only success
+     */
+    SUCCESS, 
+     
+     /**
+      * Only exceptions/failures
+      */
+    FAIL, 
+    
+    /**
+     * Nothing
+     */
+    NONE,
+    
+    /**
+     * Don't know
+     */
+    UNSET;
+    
+    /**
+     * Parse the audit mode from a string
+     * 
+     * @param value
+     * @return - the audit mode.
+     */
     public static AuditMode getAuditMode(String value)
     {
         if(value.equalsIgnoreCase("all"))

source/java/org/alfresco/repo/audit/MethodAuditModel.java

@@ -27,32 +27,38 @@ package org.alfresco.repo.audit;
 import org.alfresco.repo.audit.model.TrueFalseUnset;
 import org.aopalliance.intercept.MethodInvocation;
 
+/**
+ * The audit model used to audit method calls.
+ * 
+ * @author andyh
+ */
 public interface MethodAuditModel
 {
     /**
      * Report if audit behaviour can be determined before the method call
      * 
-     * @param auditState,
+     * @param auditMode
      * @param mi
-     * @return
+     * @return - the audit mode
      */
     public AuditMode beforeExecution(AuditMode auditMode, MethodInvocation mi);
 
     /**
      * Report if audit behaviour can be determined after the method call
      * 
-     * @param auditState,
+     * @param auditMode
      * @param mi
-     * @return
+     * @return - the audit mode
      */
     public AuditMode afterExecution(AuditMode auditMode, MethodInvocation mi);
 
     /**
-     * Report if audit behaviour should be invoked on error. It could be we look at the error and filter - this is not supported at the moment.
+     * Report if audit behaviour should be invoked on error. It could be we look at the error and filter - this filter is not
+     * supported at the moment.
      * 
-     * @param auditState,
+     * @param auditMode
      * @param mi
-     * @return
+     * @return - the audit mode
      */
     public AuditMode onError(AuditMode auditMode, MethodInvocation mi);
 
@@ -60,14 +66,14 @@ public interface MethodAuditModel
      * Get the optional parameters that are to be recorded
      * 
      * @param mi
-     * @return
+     * @return - what to record 
      */
     public RecordOptions getAuditRecordOptions(MethodInvocation mi);
 
     /**
-     * Should internal service class be logged.
+     * Deteine if internal calls to public service shoud be audited
-     * 
+     * @param mi
-     * @return
+     * @return - mode
      */
     public TrueFalseUnset getAuditInternalServiceMethods(MethodInvocation mi);
 }