From 9a61ebaae1febd069c8834a26fb1c56d236e15ed Mon Sep 17 00:00:00 2001 From: Mark Rogers Date: Mon, 1 Mar 2010 15:06:38 +0000 Subject: [PATCH] JavaDoc for transfer service. git-svn-id: https://svn.alfresco.com/repos/alfresco-enterprise/alfresco/HEAD/root@18913 c4b6b30b-aa2e-2d43-bbcb-ca4b014f7261 --- .../transfer/AbstractManifestProcessorBase.java | 1 - .../alfresco/repo/transfer/ContentChunker.java | 13 +++++++++++-- .../manifest/TransferManifestNodeFactoryImpl.java | 6 ++++++ .../transfer/manifest/TransferManifestTest.java | 3 +++ .../repo/transfer/manifest/package-info.java | 8 ++++++++ .../org/alfresco/repo/transfer/package-info.java | 6 ++++++ .../repo/transfer/report/TransferReport.xsd | 8 +++++++- .../repo/transfer/report/TransferReporter.java | 3 +++ .../transfer/report/TransferReporterImpl.java | 4 ++++ .../transfer/report/XMLTransferReportWriter.java | 5 +++++ .../repo/transfer/report/package-info.java | 5 +++++ .../service/cmr/transfer/NodeCrawler.java | 13 ++++++++++++- .../alfresco/service/cmr/transfer/NodeFilter.java | 12 ++++++++++++ .../alfresco/service/cmr/transfer/NodeFinder.java | 15 ++++++++++++++- .../service/cmr/transfer/TransferDefinition.java | 2 +- .../service/cmr/transfer/TransferEvent.java | 7 +++++++ .../cmr/transfer/TransferEventEndState.java | 3 +++ .../cmr/transfer/TransferEventEnterState.java | 3 +++ .../transfer/TransferEventSendingManifest.java | 2 +- .../cmr/transfer/TransferEventSentContent.java | 3 +++ .../service/cmr/transfer/TransferReceiver.java | 2 +- .../service/cmr/transfer/TransferTarget.java | 2 +- .../service/cmr/transfer/package-info.java | 9 +++++++++ 23 files changed, 125 insertions(+), 10 deletions(-) create mode 100644 source/java/org/alfresco/repo/transfer/manifest/package-info.java create mode 100644 source/java/org/alfresco/repo/transfer/package-info.java create mode 100644 source/java/org/alfresco/repo/transfer/report/package-info.java diff --git a/source/java/org/alfresco/repo/transfer/AbstractManifestProcessorBase.java b/source/java/org/alfresco/repo/transfer/AbstractManifestProcessorBase.java index 3ca519fbb1..73b8a25aa5 100644 --- a/source/java/org/alfresco/repo/transfer/AbstractManifestProcessorBase.java +++ b/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 { diff --git a/source/java/org/alfresco/repo/transfer/ContentChunker.java b/source/java/org/alfresco/repo/transfer/ContentChunker.java index 83e777aa1b..74ad02b833 100644 --- a/source/java/org/alfresco/repo/transfer/ContentChunker.java +++ b/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. + *

+ * Call the addContent method to add ContentData to the chunker. + *

+ * Call the setHandler method to set the handler to process chunks of content. + *

+ * Call the flush() method after the last call to addContent to flush the remaining + * buffered content. * @author Mark */ public interface ContentChunker diff --git a/source/java/org/alfresco/repo/transfer/manifest/TransferManifestNodeFactoryImpl.java b/source/java/org/alfresco/repo/transfer/manifest/TransferManifestNodeFactoryImpl.java index 6559df7069..ee5ef20457 100644 --- a/source/java/org/alfresco/repo/transfer/manifest/TransferManifestNodeFactoryImpl.java +++ b/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; diff --git a/source/java/org/alfresco/repo/transfer/manifest/TransferManifestTest.java b/source/java/org/alfresco/repo/transfer/manifest/TransferManifestTest.java index 2028dcdb51..59479e41ab 100644 --- a/source/java/org/alfresco/repo/transfer/manifest/TransferManifestTest.java +++ b/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 { /** diff --git a/source/java/org/alfresco/repo/transfer/manifest/package-info.java b/source/java/org/alfresco/repo/transfer/manifest/package-info.java new file mode 100644 index 0000000000..119be1b6a0 --- /dev/null +++ b/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. + *

+ * 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; diff --git a/source/java/org/alfresco/repo/transfer/package-info.java b/source/java/org/alfresco/repo/transfer/package-info.java new file mode 100644 index 0000000000..56da0eb236 --- /dev/null +++ b/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; diff --git a/source/java/org/alfresco/repo/transfer/report/TransferReport.xsd b/source/java/org/alfresco/repo/transfer/report/TransferReport.xsd index 28b307f797..9bb48367c8 100644 --- a/source/java/org/alfresco/repo/transfer/report/TransferReport.xsd +++ b/source/java/org/alfresco/repo/transfer/report/TransferReport.xsd @@ -8,10 +8,16 @@ + + + This is an Alfresco client side transfer report + + + - This is an alfresco client side transfer report + The Alfresco client side transfer report diff --git a/source/java/org/alfresco/repo/transfer/report/TransferReporter.java b/source/java/org/alfresco/repo/transfer/report/TransferReporter.java index fe787bf0dd..bc1e9ee333 100644 --- a/source/java/org/alfresco/repo/transfer/report/TransferReporter.java +++ b/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 { /** diff --git a/source/java/org/alfresco/repo/transfer/report/TransferReporterImpl.java b/source/java/org/alfresco/repo/transfer/report/TransferReporterImpl.java index d6b8d876cb..8d50f9cfa0 100644 --- a/source/java/org/alfresco/repo/transfer/report/TransferReporterImpl.java +++ b/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; diff --git a/source/java/org/alfresco/repo/transfer/report/XMLTransferReportWriter.java b/source/java/org/alfresco/repo/transfer/report/XMLTransferReportWriter.java index 7920ac349f..4fbed1571f 100644 --- a/source/java/org/alfresco/repo/transfer/report/XMLTransferReportWriter.java +++ b/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() diff --git a/source/java/org/alfresco/repo/transfer/report/package-info.java b/source/java/org/alfresco/repo/transfer/report/package-info.java new file mode 100644 index 0000000000..50bb2263ba --- /dev/null +++ b/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; diff --git a/source/java/org/alfresco/service/cmr/transfer/NodeCrawler.java b/source/java/org/alfresco/service/cmr/transfer/NodeCrawler.java index fdfbf0c105..1cca41a8e9 100644 --- a/source/java/org/alfresco/service/cmr/transfer/NodeCrawler.java +++ b/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. + *

+ * 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 crawl(NodeRef... nodes); public abstract Set crawl(Set startingNodes); diff --git a/source/java/org/alfresco/service/cmr/transfer/NodeFilter.java b/source/java/org/alfresco/service/cmr/transfer/NodeFilter.java index 251ec6a804..20884febd9 100644 --- a/source/java/org/alfresco/service/cmr/transfer/NodeFilter.java +++ b/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. + *

+ * 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); } diff --git a/source/java/org/alfresco/service/cmr/transfer/NodeFinder.java b/source/java/org/alfresco/service/cmr/transfer/NodeFinder.java index f95657fbc2..608c1b429f 100644 --- a/source/java/org/alfresco/service/cmr/transfer/NodeFinder.java +++ b/source/java/org/alfresco/service/cmr/transfer/NodeFinder.java @@ -32,7 +32,13 @@ 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 findFrom(NodeRef thisNode); + /** + * called by the node crawler to initialise this class. + */ void init(); + /** + * + * @param serviceRegistry + */ void setServiceRegistry(ServiceRegistry serviceRegistry); } diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferDefinition.java b/source/java/org/alfresco/service/cmr/transfer/TransferDefinition.java index 4b240d4056..f11cd49fe3 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferDefinition.java +++ b/source/java/org/alfresco/service/cmr/transfer/TransferDefinition.java @@ -35,7 +35,7 @@ import org.alfresco.service.cmr.repository.NodeRef; /** * Definition of a transfer. * - * Specifies which node to transfer + * Specifies which node to transfer * */ public class TransferDefinition implements Serializable diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferEvent.java b/source/java/org/alfresco/service/cmr/transfer/TransferEvent.java index 4bb473c2f3..2620b3df58 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferEvent.java +++ b/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. + * + *

+ * The TransferCallback presents TransferEvents for processing. + * + * @see TransferCallback * @author Mark Rogers */ public interface TransferEvent diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferEventEndState.java b/source/java/org/alfresco/service/cmr/transfer/TransferEventEndState.java index 9d8367aec5..85c9903f6b 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferEventEndState.java +++ b/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 { diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferEventEnterState.java b/source/java/org/alfresco/service/cmr/transfer/TransferEventEnterState.java index 090cd1dcc3..bbdf0cc6f7 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferEventEnterState.java +++ b/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 { diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferEventSendingManifest.java b/source/java/org/alfresco/service/cmr/transfer/TransferEventSendingManifest.java index a092d225f0..c8ca6526ed 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferEventSendingManifest.java +++ b/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 diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferEventSentContent.java b/source/java/org/alfresco/service/cmr/transfer/TransferEventSentContent.java index d8328fc32f..bbcb8009dc 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferEventSentContent.java +++ b/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 { diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferReceiver.java b/source/java/org/alfresco/service/cmr/transfer/TransferReceiver.java index bbcb5907b3..3d047ed1ff 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferReceiver.java +++ b/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 { diff --git a/source/java/org/alfresco/service/cmr/transfer/TransferTarget.java b/source/java/org/alfresco/service/cmr/transfer/TransferTarget.java index 7aa3c1f112..c0ab10ece3 100644 --- a/source/java/org/alfresco/service/cmr/transfer/TransferTarget.java +++ b/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 */ diff --git a/source/java/org/alfresco/service/cmr/transfer/package-info.java b/source/java/org/alfresco/service/cmr/transfer/package-info.java index eef5e7ad98..2f4b56f10d 100644 --- a/source/java/org/alfresco/service/cmr/transfer/package-info.java +++ b/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. + *

+ * 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. + *

+ * TransferEvents are produced by an ongoing transfer. They can be use to monitor an in-flight transfer or build a user interface. + *

+ * 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;