RM: Java Docs

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

rm-server/source/java/org/alfresco/module/org_alfresco_module_rm/recordfolder/RecordFolderService.java

@@ -34,7 +34,11 @@ import org.alfresco.service.namespace.QName;
 public interface RecordFolderService
 {
     /**
-     * @param nodeRef
+     * Initialises the a record folder from a standard folder.
+     * 
+     * @param nodeRef   node reference of the folder to initialise
+     * 
+     * @since 2.2
      */
     void initialiseRecordFolder(NodeRef nodeRef);
 
@@ -43,6 +47,8 @@ public interface RecordFolderService
      *
      * @param nodeRef   node reference
      * @return boolean  true if record folder, false otherwise
+     * 
+     * @since 2.2
      */
     boolean isRecordFolder(NodeRef nodeRef);
 
@@ -51,6 +57,8 @@ public interface RecordFolderService
      *
      * @param nodeRef   node reference (record folder)
      * @return boolean  true if record folder contents are declared, false otherwise
+     * 
+     * @since 2.2
      */
     boolean isRecordFolderDeclared(NodeRef nodeRef);
 
@@ -60,7 +68,7 @@ public interface RecordFolderService
      * @param nodeRef   node reference (record folder)
      * @return boolean  true if record folder is closed, false otherwise
      *
-     * @since 2.0
+     * @since 2.2
      */
     boolean isRecordFolderClosed(NodeRef nodeRef);
 
@@ -72,6 +80,8 @@ public interface RecordFolderService
      * @param  name          name
      * @param  type          type
      * @return NodeRef       node reference of record folder
+     * 
+     * @since 2.2
      */
     NodeRef createRecordFolder(NodeRef rmContainer, String name, QName type);
 
@@ -84,6 +94,8 @@ public interface RecordFolderService
      * @param type          type
      * @param properties    properties
      * @return NodeRef      node reference of record folder
+     * 
+     * @since 2.2
      */
     NodeRef createRecordFolder(NodeRef rmContainer, String name, QName type, Map<QName, Serializable> properties);
 
@@ -94,6 +106,8 @@ public interface RecordFolderService
      * @param  rmContainer   records management container
      * @param  name          name
      * @return NodeRef       node reference of record folder
+     * 
+     * @since 2.2
      */
     NodeRef createRecordFolder(NodeRef rmContainer, String name);
 
@@ -105,6 +119,8 @@ public interface RecordFolderService
      * @param name          name
      * @param properties    properties
      * @return NodeRef      node reference of record folder
+     * 
+     * @since 2.2
      */
     NodeRef createRecordFolder(NodeRef rmContainer, String name, Map<QName, Serializable> properties);
 
@@ -113,6 +129,8 @@ public interface RecordFolderService
      *
      * @param record        the record node reference
      * @return List         list of folder record node references
+     * 
+     * @since 2.2
      */
     // TODO rename to List<NodeRef> getParentRecordFolders(NodeRef record);
     List<NodeRef> getRecordFolders(NodeRef record);

rm-server/source/java/org/alfresco/module/org_alfresco_module_rm/recordfolder/RecordFolderServiceImpl.java

@@ -351,6 +351,9 @@ public class RecordFolderServiceImpl extends    ServiceBaseImpl
         return createRecordFolder(rmContainer, name, TYPE_RECORD_FOLDER, properties);
     }
 
+    /**
+     * @see org.alfresco.module.org_alfresco_module_rm.recordfolder.RecordFolderService#getRecordFolders(org.alfresco.service.cmr.repository.NodeRef)
+     */
     @Override
     public List<NodeRef> getRecordFolders(NodeRef record)
     {

rm-server/source/java/org/alfresco/module/org_alfresco_module_rm/security/ExtendedSecurityService.java

@@ -31,37 +31,87 @@ import org.alfresco.service.cmr.repository.NodeRef;
 public interface ExtendedSecurityService
 {
 	/**
+	 * Indicates whether a node has extended security.
 	 *  
-	 * @param nodeRef
-	 * @return
+	 * @param nodeRef      node reference
+	 * @return boolean     true if the node has extedned security, false otherwise
 	 */
     boolean hasExtendedSecurity(NodeRef nodeRef);
     
     /**
-     * Gets the set authorities that are extended readers for the given node.
+     * Gets the set of authorities that are extended readers for the given node.
      * 
      * @param nodeRef   node reference
-     * @return {@link Set}<{@link String}>  extended readers
+     * @return {@link Set}<{@link String}>  set of extended readers
      */
     Set<String> getExtendedReaders(NodeRef nodeRef);
     
     /**
+     * Get the set of authorities that are extended writers for the given node.
      * 
-     * @param nodeRef
-     * @return
+     * @param nodeRef   node reference
+     * @return {@link Set}<{@link String}>  set of extended writers
      */
     Set<String> getExtendedWriters(NodeRef nodeRef);
 
+    /**
+     * Add extended security for the specified authorities to a node.
+     * 
+     * @param nodeRef   node reference
+     * @param readers   set of authorities to add extended read permissions
+     * @param writers   set of authorities to add extended write permissions
+     */
     void addExtendedSecurity(NodeRef nodeRef, Set<String> readers, Set<String> writers);
     
+    /**
+     * Add extended security for the specified authorities to a node.
+     * <p>
+     * If specified, the read and write extended permissions are applied to all parents up to the file plan as 
+     * extended read.  This ensures parental read, but not parental write.
+     * 
+     * @param nodeRef   node reference
+     * @param readers   set of authorities to add extended read permissions
+     * @param writers   set of authorities to add extended write permissions
+     * @param applyToParents true if extended security applied to parents (read only) false otherwise.
+     */
     void addExtendedSecurity(NodeRef nodeRef, Set<String> readers, Set<String> writers, boolean applyToParents);
     
+    /**
+     * Remove the extended security for the specified authorities from a node.
+     * 
+     * @param nodeRef   node reference
+     * @param readers   set of authorities to remove as extended readers
+     * @param writers   set of authorities to remove as extended writers
+     */
     void removeExtendedSecurity(NodeRef nodeRef, Set<String> readers, Set<String> writers);
     
+    /**
+     * Remove the extended security for the specified authorities from a node.
+     * <p>
+     * If specified, extended security will also be removed from the parent hierarchy.(read only).  Note that 
+     * extended security is records as a reference count, so security will only be utterly removed from the parent
+     * hierarchy if all references to the authority are removed.
+     * 
+     * @param nodeRef           node reference
+     * @param readers           set of authorities to remove as extended readers
+     * @param writers           set of authorities to remove as extedned writers
+     * @param applyToParents    true if removal of extended security is applied to parent hierarchy (read only), false
+     *                          otherwise
+     */
     void removeExtendedSecurity(NodeRef nodeRef, Set<String> readers, Set<String> writers, boolean applyToParents);
     
+    /**
+     * Remove all extended readers and writers from the given node reference.
+     * 
+     * @param nodeRef   node reference
+     */
     void removeAllExtendedSecurity(NodeRef nodeRef);
     
+    /**
+     * Remove all extended readers and writers from the given node reference.
+     * 
+     * @param nodeRef           node reference
+     * @param applyToParents    if true then apply removal to parent hierarchy (read only) false otherwise.
+     */
     void removeAllExtendedSecurity(NodeRef nodeRef, boolean applyToParents);
-
 }