From 4497f980723feb61d6f6b45ea377c590830837ab Mon Sep 17 00:00:00 2001
From: cramakri <cramakri>
Date: Thu, 26 Jul 2012 08:52:13 +0000
Subject: [PATCH] BIS-131 SP-214 : Added javadoc to
IJavaDataSetRegistrationDropboxV2
SVN: 26218
---
.../v2/IJavaDataSetRegistrationDropboxV2.java | 63 ++++++++++++++++++-
1 file changed, 60 insertions(+), 3 deletions(-)
diff --git a/datastore_server/source/java/ch/systemsx/cisd/etlserver/registrator/api/v2/IJavaDataSetRegistrationDropboxV2.java b/datastore_server/source/java/ch/systemsx/cisd/etlserver/registrator/api/v2/IJavaDataSetRegistrationDropboxV2.java
index 88b6738c230..853f24b5e18 100644
--- a/datastore_server/source/java/ch/systemsx/cisd/etlserver/registrator/api/v2/IJavaDataSetRegistrationDropboxV2.java
+++ b/datastore_server/source/java/ch/systemsx/cisd/etlserver/registrator/api/v2/IJavaDataSetRegistrationDropboxV2.java
@@ -20,22 +20,79 @@ import ch.systemsx.cisd.common.exceptions.NotImplementedException;
import ch.systemsx.cisd.etlserver.registrator.DataSetRegistrationContext;
/**
+ * The interface that V2 dropboxes must implement. Defines the process method, which is called to
+ * handle new data in the dropbox's incoming folder, and various event methods called as the
+ * registration process progresses.
+ *
* @author Pawel Glyzewski
*/
public interface IJavaDataSetRegistrationDropboxV2
{
- public void process(IDataSetRegistrationTransactionV2 transaction);
- public void postStorage(DataSetRegistrationContext context);
+ /**
+ * Invoked when new data is found in the incoming folder. Implements the logic of registering
+ * and modifying entities.
+ *
+ * @param transaction The transaction that offers methods for registering and modifying entities
+ * and performing operations on the file system.
+ */
+ public void process(IDataSetRegistrationTransactionV2 transaction);
+ /**
+ * Invoked just before the metadata is registered with the openBIS AS. Gives dropbox
+ * implementations an opportunity to perform additional operations. If an exception is thrown in
+ * this method, the transaction is rolledback.
+ *
+ * @param context Context of the registration. Offers access to the global state and persistent
+ * map.
+ */
public void preMetadataRegistration(DataSetRegistrationContext context);
+ /**
+ * Invoked if the transaction is rolledback before the metadata is registered with the openBIS
+ * AS.
+ *
+ * @param context Context of the registration. Offers access to the global state and persistent
+ * map.
+ * @param throwable The throwable that triggered rollback.
+ */
+ public void rollbackPreRegistration(DataSetRegistrationContext context, Throwable throwable);
+
+ /**
+ * Invoked just after the metadata is registered with the openBIS AS. Gives dropbox
+ * implementations an opportunity to perform additional operations. If an exception is thrown in
+ * this method, it is logged but otherwise ignored.
+ *
+ * @param context Context of the registration. Offers access to the global state and persistent
+ * map.
+ */
public void postMetadataRegistration(DataSetRegistrationContext context);
- public void rollbackPreRegistration(DataSetRegistrationContext context, Throwable throwable);
+ /**
+ * Invoked after the data has been stored in its final location on the file system and the
+ * storage has been confirmed with the AS.
+ *
+ * @param context Context of the registration. Offers access to the global state and persistent
+ * map.
+ */
+ public void postStorage(DataSetRegistrationContext context);
+ /**
+ * Is a function defined that can be used to check if a failed registration should be retried?
+ * Primarily for use implementations of this interface that dispatch to dynamic languages.
+ *
+ * @return true shouldRetryProcessing is defined, false otherwise.
+ */
public boolean isRetryFunctionDefined();
+ /**
+ * Given the problem with registration, should it be retried?
+ *
+ * @param context Context of the registration. Offers access to the global state and persistent
+ * map.
+ * @param problem The exception that caused the registration to fail.
+ * @return true if the registration should be retried.
+ */
public boolean shouldRetryProcessing(DataSetRegistrationContext context, Exception problem)
throws NotImplementedException;
--
GitLab