JavaDoc for transfer service.

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

source/java/org/alfresco/repo/transfer/AbstractManifestProcessorBase.java

@@ -24,7 +24,6 @@ import org.apache.commons.logging.LogFactory;
  * This abstract class handles the progress monitoring functionality as well as providing
  * some utility methods for sub-classes.
  * @author Brian
- *
  */
 public abstract class AbstractManifestProcessorBase implements TransferManifestProcessor
 {

source/java/org/alfresco/repo/transfer/ContentChunker.java

@@ -28,8 +28,17 @@ import org.alfresco.service.cmr.repository.ContentData;
 import org.alfresco.service.cmr.transfer.TransferException;
 
 /**
- * The Content Chunker Splits Content into "Chunks" of a given size
+ * The Content Chunker Splits Content into "Chunks" of a given size.
  * 
+ * So, for example, if the chunk size is 10MB and there are 6 files of 2MB then 
+ * there will be one chunk containing 5 chunks and the remaining 2MB will remain.
+ * <p>
+ * Call the addContent method to add ContentData to the chunker.
+ * <p>
+ * Call the setHandler method to set the handler to process chunks of content.
+ * <p>
+ * Call the flush() method after the last call to addContent to flush the remaining 
+ * buffered content.
  * @author Mark
  */
 public interface ContentChunker

source/java/org/alfresco/repo/transfer/manifest/TransferManifestNodeFactoryImpl.java

@@ -33,6 +33,12 @@ import org.alfresco.service.cmr.repository.StoreRef;
 import org.alfresco.service.cmr.transfer.TransferException;
 import org.alfresco.service.namespace.RegexQNamePattern;
 
+/**
+ * Factory to build TransferManifestNodes given their repository NodeRef.
+ * Extracts values from the nodeService and instantiates TransferManifestNode.
+ *
+ * @author Mark Rogers
+ */
 public class TransferManifestNodeFactoryImpl implements TransferManifestNodeFactory
 {
     private NodeService nodeService;

source/java/org/alfresco/repo/transfer/manifest/TransferManifestTest.java

@@ -55,6 +55,9 @@ import org.alfresco.util.TempFileProvider;
 
 import junit.framework.TestCase;
 
+/**
+ * Unit test for the transfer manifest
+ */
 public class TransferManifestTest extends TestCase 
 {
     /**

source/java/org/alfresco/repo/transfer/manifest/package-info.java

@@ -0,0 +1,8 @@
+/**
+ * Provides the implementation of the transfer manifest which is used by the transfer service.
+ * <p>
+ * XMLTransferManifestWriter writes the transfer manifest.  XMLTransferManifestReader reads the transfer manifest and calls the
+ * TransferManifestProcessor as the read progresses.    These classes are designed to stream content through, processing each node at a time, and not hold a large data objects in memory.
+ * @since 3.3
+ */
+package org.alfresco.repo.transfer.manifest;

source/java/org/alfresco/repo/transfer/package-info.java

@@ -0,0 +1,6 @@
+/**
+ * Provides the implementation of the transfer service which can be used to 
+ * transfer nodes from one repository to another.
+ * @since 3.3
+ */
+package org.alfresco.repo.transfer;

source/java/org/alfresco/repo/transfer/report/TransferReport.xsd

@@ -8,10 +8,16 @@
 
    <!-- XML Schema for the client side transferReport -->
    
+   <element name="transferReport" type="report:transferReport" >
+   <annotation>
+   <documentation>This is an Alfresco client side transfer report</documentation>
+   </annotation>
+   </element>
+   
    <complexType name="transferReport">
       <annotation>
          <documentation>
-            This is an alfresco client side transfer report
+         The Alfresco client side transfer report
          </documentation>
       </annotation>
       <sequence>

source/java/org/alfresco/repo/transfer/report/TransferReporter.java

@@ -33,6 +33,9 @@ import org.alfresco.service.cmr.transfer.TransferDefinition;
 import org.alfresco.service.cmr.transfer.TransferEvent;
 import org.alfresco.service.cmr.transfer.TransferTarget;
 
+/**
+ * Provides methods to create transfer report.
+ */
 public interface TransferReporter
 {
     /**

source/java/org/alfresco/repo/transfer/report/TransferReporterImpl.java

@@ -67,6 +67,10 @@ import org.springframework.extensions.surf.util.ISO8601DateFormat;
 import org.springframework.extensions.surf.util.PropertyCheck;
 import org.xml.sax.SAXException;
 
+/**
+ * Implementation of TransferReporter
+ *
+ */
 public class TransferReporterImpl implements TransferReporter
 {
     private NodeService nodeService;

source/java/org/alfresco/repo/transfer/report/XMLTransferReportWriter.java

@@ -20,6 +20,11 @@ import org.springframework.extensions.surf.util.ISO8601DateFormat;
 import org.xml.sax.SAXException;
 import org.xml.sax.helpers.AttributesImpl;
 
+/**
+ * Writes the Client Side Transfer Report out as XML.
+ *
+ * @author Mark Rogers
+ */
 public class XMLTransferReportWriter
 {
     public XMLTransferReportWriter()

source/java/org/alfresco/repo/transfer/report/package-info.java

@@ -0,0 +1,5 @@
+/**
+ * Provides the implementation of the client side transfer report which records details of a transfer.
+ * @since 3.3
+ */
+package org.alfresco.repo.transfer.report;

source/java/org/alfresco/service/cmr/transfer/NodeCrawler.java

@@ -4,9 +4,20 @@ import java.util.Set;
 
 import org.alfresco.service.cmr.repository.NodeRef;
 
+/**
+ * The NodeCrawler finds nodes related to an initial group of nodes for the 
+ * transfer service.
+ * <p>
+ * During the crawl method the node finders find nodes related to the staring nodes 
+ * and then the filters can exclude unwanted nodes.   For example you could use the finders 
+ * to walk down a tree of nodes and exclude nodes of a certain type.  
+ * 
+ * @see org.alfresco.repo.transfer.StandardNodeCrawlerImpl
+ *
+ * @author Brian 
+ */
 public interface NodeCrawler
 {
-
     public abstract Set<NodeRef> crawl(NodeRef... nodes);
 
     public abstract Set<NodeRef> crawl(Set<NodeRef> startingNodes);

source/java/org/alfresco/service/cmr/transfer/NodeFilter.java

@@ -31,6 +31,11 @@ import org.alfresco.service.cmr.repository.NodeRef;
 /**
  * @author brian
  *
+ * Examines the supplied node and indicates whether it has been accepted by the filter.
+ * <p>
+ * The NodeCrawler will first initialise this filter by calling the 
+ * setServiceRegistry and init methods. Then the accept method will be called to either accept or 
+ * reject the node.
  */
 public interface NodeFilter
 {
@@ -44,7 +49,14 @@ public interface NodeFilter
      */
     boolean accept(NodeRef thisNode);
     
+    /**
+     * 
+     */
     void init();
     
+    /**
+     * 
+     * @param serviceRegistry
+     */
     void setServiceRegistry(ServiceRegistry serviceRegistry);
 }

source/java/org/alfresco/service/cmr/transfer/NodeFinder.java

@@ -33,6 +33,12 @@ import org.alfresco.service.cmr.repository.NodeRef;
 /**
  * @author brian
  * 
+ * NodeFinders find nodes related to the current node.
+ * The NodeCrawler will first initialise this filter by calling the 
+ * setServiceRegistry and init methods.  Then the findFrom method will be called to find 
+ * other nodes.
+ * 
+ * @see org.alfresco.repo.transfer.ChildAssociatedNodeFinder
  */
 public interface NodeFinder
 {
@@ -44,7 +50,14 @@ public interface NodeFinder
      */
     Set<NodeRef> findFrom(NodeRef thisNode);
 
+    /**
+     * called by the node crawler to initialise this class.
+     */
     void init();
 
+    /**
+     * 
+     * @param serviceRegistry
+     */
     void setServiceRegistry(ServiceRegistry serviceRegistry);
 }

source/java/org/alfresco/service/cmr/transfer/TransferEvent.java

@@ -3,6 +3,13 @@ package org.alfresco.service.cmr.transfer;
 import java.util.Date;
 
 /**
+ * TransferEvents are produced by the Transfer service during an in flight 
+ * transfer.
+ * 
+ * <p>
+ * The TransferCallback presents TransferEvents for processing. 
+ * 
+ * @see TransferCallback
  * @author Mark Rogers
  */
 public interface TransferEvent

source/java/org/alfresco/service/cmr/transfer/TransferEventEndState.java

@@ -26,6 +26,9 @@ package org.alfresco.service.cmr.transfer;
 
 import org.alfresco.repo.transfer.TransferEventImpl;
 
+/**
+ * An end state is produces when a transfer ends a state.
+ */
 public class TransferEventEndState extends TransferEventImpl implements TransferEvent
 {
 

source/java/org/alfresco/service/cmr/transfer/TransferEventEnterState.java

@@ -26,6 +26,9 @@ package org.alfresco.service.cmr.transfer;
 
 import org.alfresco.repo.transfer.TransferEventImpl;
 
+/**
+ * An enter state is produced when a transfer enters a new state.
+ */ 
 public class TransferEventEnterState extends TransferEventImpl implements TransferEvent
 {
 

source/java/org/alfresco/service/cmr/transfer/TransferEventSendingManifest.java

@@ -27,7 +27,7 @@ package org.alfresco.service.cmr.transfer;
 import org.alfresco.repo.transfer.TransferEventImpl;
 
 /**
- * 
+ * Event for sending the transfer manifest.
  *
  */
 public class TransferEventSendingManifest extends TransferEventImpl implements RangedTransferEvent

source/java/org/alfresco/service/cmr/transfer/TransferEventSentContent.java

@@ -26,6 +26,9 @@ package org.alfresco.service.cmr.transfer;
 
 import org.alfresco.repo.transfer.TransferEventImpl;
 
+/**
+ * Event for sent content.
+ */
 public class TransferEventSentContent extends TransferEventImpl implements TransferEvent
 {
 

source/java/org/alfresco/service/cmr/transfer/TransferReceiver.java

@@ -33,7 +33,7 @@ import org.alfresco.service.cmr.repository.NodeRef;
 
 /**
  * @author brian
- *
+ * The server side Transfer Receiver.
  */
 public interface TransferReceiver
 {

source/java/org/alfresco/service/cmr/transfer/TransferTarget.java

@@ -3,7 +3,7 @@ package org.alfresco.service.cmr.transfer;
 import org.alfresco.service.cmr.repository.NodeRef;
 
 /**
- * Transfer Target.
+ * Transfer Target.    Definition of a remote target to transfer to, contains details such as its name and address.
  *
  * @author Mark Rogers
  */

source/java/org/alfresco/service/cmr/transfer/package-info.java

@@ -1,6 +1,15 @@
 /**
  * Provides the public interface for the transfer service which can be used to 
  * transfer nodes from one repository to another.
+ * <p>
+ * TransferService provides the methods to transfer nodes from one instance of Alfresco to another.   The TransferTarget contains details of where to transfer to.   
+ * The TransferDefinition contains details of what to transfer.
+ * <p>
+ * TransferEvents are produced by an ongoing transfer.   They can be use to monitor an in-flight transfer or build a user interface.
+ * <p>
+ * The NodeCrawler provides the ability to find a set of nodes to give to the transfer service.
+ *
+ * @see org.alfresco.service.cmr.transferTransferService
  * @since 3.3
  */
 package org.alfresco.service.cmr.transfer;