Merged HEAD (5.2) to 5.2.N (5.2.1)

126387 jkaabimofrad: Merged FILE-FOLDER-API (5.2.0) to HEAD (5.2)
      120472 jvonka: FileFolder API - minor (JavaDoc / comments only)


git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/BRANCHES/DEV/5.2.N/root@126733 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261

source/java/org/alfresco/rest/api/Nodes.java

@@ -41,6 +41,8 @@ import org.alfresco.service.namespace.QName;
 import org.springframework.extensions.webscripts.servlet.FormData;
 
 /**
+ * File Folder (Nodes) API
+ *
  * @author steveglover
  * @author janv
  */
@@ -50,13 +52,9 @@ public interface Nodes
     String PATH_MY = "-my-";
     String PATH_SHARED = "-shared-";
 
-    NodeRef validateNode(StoreRef storeRef, String nodeId);
-    NodeRef validateNode(String nodeId);
-    NodeRef validateNode(NodeRef nodeRef);
-    boolean nodeMatches(NodeRef nodeRef, Set<QName> expectedTypes, Set<QName> excludedTypes);
-
     /**
      * Get the node representation for the given node.
+     *
      * @param nodeId String
      * @return Node
      */
@@ -64,6 +62,7 @@ public interface Nodes
     
     /**
      * Get the document representation for the given node.
+     *
      * @param nodeRef NodeRef
      * @return Document
      */
@@ -71,6 +70,7 @@ public interface Nodes
     
     /**
      * Get the folder representation for the given node.
+     *
      * @param nodeRef NodeRef
      * @return Folder
      */
@@ -78,6 +78,7 @@ public interface Nodes
     
     /**
      * Get the folder or document representation (as appropriate) for the given node.
+     *
      * @param nodeId String nodeId or well-known alias, eg. "-root-" or "-my-"
      * @param parameters the {@link Parameters} object to get the parameters passed into the request
      *        including:
@@ -88,6 +89,7 @@ public interface Nodes
     
     /**
      * Get list of children of a parent folder.
+     *
      * @param parentFolderNodeId String id of parent folder node or well-known alias, eg. "-root-" or "-my-"
      * @param parameters the {@link Parameters} object to get the parameters passed into the request
      *        including:
@@ -99,12 +101,13 @@ public interface Nodes
     
     /**
      * Delete the given node. Note: will cascade delete for a folder.
+     *
      * @param nodeId String id of node (folder or document)
      */
     void deleteNode(String nodeId);
 
     /**
-     * Create node(s) - folder or (empty) file
+     * Create node(s) - folder or (empty) file.
      *
      * @param parentFolderNodeId
      * @param nodeInfo
@@ -114,6 +117,7 @@ public interface Nodes
     Node createNode(String parentFolderNodeId, Node nodeInfo, Parameters parameters);
 
     /**
+     * Update node meta-data.
      *
      * @param nodeId
      * @param entity
@@ -122,9 +126,26 @@ public interface Nodes
      */
     Node updateNode(String nodeId, Node entity, Parameters parameters);
 
-    // TODO update REST fwk - to optionally support "attachment" (Content-Disposition) header
+    /**
+     * Download file content.
+     *
+     * @param fileNodeId
+     * @param parameters
+     * @return
+     */
     BinaryResource getContent(String fileNodeId, Parameters parameters);
 
+    /**
+     * Uploads file content (updates existing node with new content).
+     *
+     * Note: may create a new version, depending on versioning behaviour.
+     *
+     * @param fileNodeId
+     * @param contentInfo
+     * @param stream
+     * @param parameters
+     * @return
+     */
     Node updateContent(String fileNodeId, BasicContentInfo contentInfo, InputStream stream, Parameters parameters);
 
     /**
@@ -136,4 +157,11 @@ public interface Nodes
      * @return {@code Node} if successful
      */
     Node upload(String parentFolderNodeId, FormData formData, Parameters parameters);
+    
+
+    NodeRef validateNode(StoreRef storeRef, String nodeId);
+    NodeRef validateNode(String nodeId);
+    NodeRef validateNode(NodeRef nodeRef);
+    boolean nodeMatches(NodeRef nodeRef, Set<QName> expectedTypes, Set<QName> excludedTypes);
+
 }