Java doc updates

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

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

@@ -31,9 +31,7 @@ import org.alfresco.service.cmr.repository.NodeRef;
 import org.aopalliance.intercept.MethodInvocation;
 
 /**
- * The audit component.
+ * The audit component. Used by the AuditService and AuditMethodInterceptor to insert audit entries.
- * 
- * Used by the AuditService and AuditMethodInterceptor to insert audit entries.
  * 
  * @author Andy Hind
  */
@@ -43,11 +41,12 @@ public interface AuditComponent
      * Audit entry point for method interceptors.
      * 
      * @param methodInvocation
+     * @return - the return onbject from the normal invocation of the audited method.
+     * @throws Throwable
      */
     public Object audit(MethodInvocation methodInvocation) throws Throwable;
 
     /**
-     * 
      * @param source -
      *            a string that represents the application
      * @param description -
@@ -58,14 +57,14 @@ public interface AuditComponent
      *            an arbitrary list of parameters
      */
     public void audit(String source, String description, NodeRef key, Object... args);
-    
+
     /**
      * Get the audit trail for a node.
      * 
-     * @param nodeRef
+     * @param nodeRef -
-     * @return
+     *            the node ref for which we want the audit trail
+     * @return - a list of AuditInfo objects that represent the audit trail for the given node reference.
      */
     public List<AuditInfo> getAuditTrail(NodeRef nodeRef);
 
-
 }

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

@@ -88,6 +88,10 @@ public class AuditComponentImpl implements AuditComponent
 
     private InetAddress auditHost;
 
+    /**
+     * Default constructor
+     *
+     */
     public AuditComponentImpl()
     {
         super();
@@ -106,26 +110,47 @@ public class AuditComponentImpl implements AuditComponent
      * IOC property setters
      */
 
+    /**
+     * Set the DAO for recording auditable information when no exception occurs.
+     * @param auditDAO 
+     */
     public void setAuditDAO(AuditDAO auditDAO)
     {
         this.auditDAO = auditDAO;
     }
 
+    /**
+     * Set the DAO for recording failed actions - this is done in another transaction.
+     * @param auditFailedDAO
+     */
     public void setAuditFailedDAO(AuditDAO auditFailedDAO)
     {
         this.auditFailedDAO = auditFailedDAO;
     }
 
+    /**
+     * Set the audit configuration.
+     * 
+     * @param auditConfiguration
+     */
     public void setAuditConfiguration(AuditConfiguration auditConfiguration)
     {
         this.auditConfiguration = auditConfiguration;
     }
 
+    /**
+     * Set the helper used to identify public services
+     * @param publicServiceIdentifier
+     */
     public void setPublicServiceIdentifier(PublicServiceIdentifier publicServiceIdentifier)
     {
         this.publicServiceIdentifier = publicServiceIdentifier;
     }
 
+    /** 
+     * Set the audit model.
+     * @param auditModel
+     */
     public void setAuditModel(AuditModel auditModel)
     {
         this.auditModel = auditModel;
@@ -215,7 +240,10 @@ public class AuditComponentImpl implements AuditComponent
     }
 
     /**
-     * Audit a method invocation
+     * Internal audit of a method invocation
+     * @param mi - the method to audit
+     * @return - the return object from the audited method
+     * @throws Throwable - any Throwable that can be thrown by th audtied method.
      */
     public Object auditImpl(MethodInvocation mi) throws Throwable
     {
@@ -256,8 +284,9 @@ public class AuditComponentImpl implements AuditComponent
      * 
      * @param auditMode
      * @param auditInfo
+     * @param mi
      * @param t
-     * @return
+     * @return - the audit mode 
      */
     private AuditMode onError(AuditMode auditMode, AuditState auditInfo, MethodInvocation mi, Throwable t)
     {
@@ -277,7 +306,7 @@ public class AuditComponentImpl implements AuditComponent
      * @param auditInfo
      * @param mi
      * @param returnObject
-     * @return
+     * @return - the audit mode.
      */
     private AuditMode postInvocation(AuditMode auditMode, AuditState auditInfo, MethodInvocation mi, Object returnObject)
     {
@@ -341,7 +370,7 @@ public class AuditComponentImpl implements AuditComponent
      * @param auditMode
      * @param auditInfo
      * @param mi
-     * @return
+     * @return - the audit mode.
      */
     private AuditMode beforeInvocation(AuditMode auditMode, AuditState auditInfo, MethodInvocation mi)
     {

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

@@ -38,19 +38,26 @@ public class AuditConfigurationImpl implements InitializingBean, AuditConfigurat
 
     private String config;
     
+    /**
+     * Default constructor
+     *
+     */
     public AuditConfigurationImpl()
     {
         super();
     }
     
+    /**
+     * Set the audit config
+     * 
+     * @param config
+     */
     public void setConfig(String config)
     {
         this.config = config;
     }
 
-    /* (non-Javadoc)
+
-     * @see org.alfresco.repo.audit.getInputStream#getInputStream()
-     */
     /* (non-Javadoc)
      * @see org.alfresco.repo.audit.AuditConfiguration#getInputStream()
      */

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

@@ -39,21 +39,45 @@ public class AuditException extends AlfrescoRuntimeException
      */
     private static final long serialVersionUID = -7947190775692164588L;
 
+    /**
+     * Simple message
+     * 
+     * @param msgId
+     */
     public AuditException(String msgId)
     {
         super(msgId);
     }
 
+    /**
+     * I18n message
+     * 
+     * @param msgId
+     * @param msgParams
+     */
     public AuditException(String msgId, Object[] msgParams)
     {
         super(msgId, msgParams);
     }
 
+    /**
+     * Simple message ad nested exception
+     * 
+     * @param msgId
+     * @param cause
+     */
     public AuditException(String msgId, Throwable cause)
     {
         super(msgId, cause);
     }
 
+    /**
+     * I18n message and exception.
+     * 
+     * @param msgId
+     * @param msgParams
+     * @param cause
+     */
     public AuditException(String msgId, Object[] msgParams, Throwable cause)
     {
         super(msgId, msgParams, cause);

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

@@ -169,6 +169,11 @@ public class AuditInfo
         }
     }
     
+    /**
+     * Create the default audit info from the audit configuration.
+     * 
+     * @param auditConfiguration
+     */
     public AuditInfo(AuditConfiguration auditConfiguration)
     {
         super();
@@ -180,121 +185,231 @@ public class AuditInfo
         hostAddress = s_hostAddress;
     }
 
+    /**
+     * Get the name of the audited application.
+     * 
+     * @return - the name of the audited application.
+     */
     public String getAuditApplication()
     {
         return auditApplication;
     }
 
+    /**
+     * Set the name of the audited application.
+     * 
+     * @param auditApplication
+     */
     public void setAuditApplication(String auditApplication)
     {
         this.auditApplication = auditApplication;
     }
 
+    /**
+     * Get the audit configuration.
+     * 
+     * @return - the audit configuration.
+     */
     public AuditConfiguration getAuditConfiguration()
     {
         return auditConfiguration;
     }
 
+    /**
+     * Set the audit configuration.
+     * 
+     * @param auditConfiguration
+     */
     public void setAuditConfiguration(AuditConfiguration auditConfiguration)
     {
         this.auditConfiguration = auditConfiguration;
     }
 
+    /**
+     * Get the name of the audited method - if it makes sense in the uadited context.
+     * 
+     * @return - the name of the audited method or null
+     */
     public String getAuditMethod()
     {
         return auditMethod;
     }
 
+    /**
+     * Set the name of the audited method.
+     * 
+     * @param auditMethod
+     */
     public void setAuditMethod(String auditMethod)
     {
         this.auditMethod = auditMethod;
     }
 
+    /**
+     * Get the audit service.
+     * 
+     * @return - the audit service.
+     */
     public String getAuditService()
     {
         return auditService;
     }
 
+    /**
+     * Set the audit service (IOC)
+     * 
+     * @param auditService
+     */
     public void setAuditService(String auditService)
     {
         this.auditService = auditService;
     }
 
+    
+  /**
+   * Get the address o which the client application is running if available
+   * @return - the address or null.
+   */
     public InetAddress getClientAddress()
     {
         return clientAddress;
     }
 
+    /**
+     * Set the client address that casued the audit.
+     * @param clientAddress
+     */
     public void setClientAddress(InetAddress clientAddress)
     {
         this.clientAddress = clientAddress;
     }
 
+    /**
+     * Get the date for the audit entry/
+     * 
+     * @return - the date for the audit entry.
+     */
     public Date getDate()
     {
         return date;
     }
 
+    /**
+     * Set the date for the audit entry
+     * @param date
+     */
     public void setDate(Date date)
     {
         this.date = date;
     }
 
+    /**
+     * Is this an audit of a failed method invocation?
+     * @return - true if the audited methoed threw any kind of exception.
+     */
     public boolean isFail()
     {
         return fail;
     }
 
+    /**
+     * Set that this is an audit of a failed method invoation.
+     * 
+     * @param fail
+     */
     public void setFail(boolean fail)
     {
         this.fail = fail;
     }
 
+    /**
+     * Could some audit information have been filtered?
+     * If true there may have been some unaudited operations of the same type.
+     *  
+     * @return - true if there were any filter definitions in the audit model; false otherwise.
+     */
     public boolean isFiltered()
     {
         return filtered;
     }
 
+    /**
+     * Set if a filter was present for this audit entry
+     * 
+     * @param filtered
+     */
     public void setFiltered(boolean filtered)
     {
         this.filtered = filtered;
     }
 
+    /**
+     * Get the host address where the repository is running.
+     * @return - the host address.
+     */
     public InetAddress getHostAddress()
     {
         return hostAddress;
     }
 
+    /**
+     * Set the host address where the repository is running.
+     * @param hostAddress
+     */
     public void setHostAddress(InetAddress hostAddress)
     {
         this.hostAddress = hostAddress;
     }
 
+    /**
+     * Get the GUID for the key node ref
+     * @return - the guid part of the node ref
+     */
     public String getKeyGUID()
     {
         return keyGUID;
     }
 
+    /**
+     * Set the GUID for the key node ref in the audited method invoation.
+     * @param keyGUID
+     */
     public void setKeyGUID(String keyGUID)
     {
         this.keyGUID = keyGUID;
     }
 
+    /**
+     * Get the properies of the key node after the method invoation. 
+     * @return - the properties to be stored in the audit trail 
+     */
     public Map<QName, Serializable> getKeyPropertiesAfter()
     {
         return keyPropertiesAfter;
     }
 
+    /**
+     * Set the preperties to be stored in the audit trail for the key node ref after the audited method has been invoked. 
+     * @param keyPropertiesAfter
+     */
     public void setKeyPropertiesAfter(Map<QName, Serializable> keyPropertiesAfter)
     {
         this.keyPropertiesAfter = keyPropertiesAfter;
     }
-
+    
+    /**
+     * Get the properies of the key node before the method invoation. 
+     * @return - the properties to be stored in the audit trail 
+     */
     public Map<QName, Serializable> getKeyPropertiesBefore()
     {
         return keyPropertiesBefore;
     }
 
+    /**
+     * Set the preperties to be stored in the audit trail for the key node ref before the audited method has been invoked. 
+     * @param keyPropertiesAfter
+     */
     public void setKeyPropertiesBefore(Map<QName, Serializable> keyPropertiesBefore)
     {
         this.keyPropertiesBefore = keyPropertiesBefore;