docs: add Javadoc

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/domain/registration/Authorization.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -23,14 +24,25 @@ public interface Authorization {
 
     /**
      * Return the authorization profile type string
+     *
+     * @return the authorization profile type string
      */
     String type();
 
     /**
      * Function that applies the authorization profile to the request builder.
      * e.g. the Authorization header could be added with proper content.
+     *
+     * @return a successful result containing the authorization header, or a failed result providing error details
      */
     Result<String> authorizationHeader(AuthorizationProfile profile);
 
+    /**
+     * Function that extract the id of the requesting control plane from a received Authorization
+     * header.
+     *
+     * @param authorizationHeader the authorization header
+     * @return a successful result containing the control plane id, or a failed result providing error details
+     */
     Result<String> extractCallerId(String authorizationHeader);
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnCompleted.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,20 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the completed endpoint is called for a DataFlow. The completed
+ * notification signals to the data plane that a data flow has been completed. The dataplane can
+ * close/remove resources used for the transfer.
+ */
 public interface OnCompleted {
 
+    /**
+     * Performs the logic when a completed notification is received.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
 
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnPrepare.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,28 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the prepare endpoint is called for a data flow. This endpoint is
+ * only called on the consumer side. The prepare request signals to the consumer dataplane to
+ * initialize a data flow and any resources required for data transfer.
+ */
 public interface OnPrepare {
 
+    /**
+     * Performs the logic when a prepare request is received. For a PUSH transfer, the consumer
+     * dataplane must return a DataAddress providing endpoint information for the provider to
+     * push the data to.
+     *
+     * Preparation of the data flow may happen asynchronously, e.g. for long-running provision tasks.
+     * If the preparation should happen asynchronously, set the DataFlow's state to
+     * {@link DataFlow.State#PREPARING} before returning. Once preparation is completed, use the
+     * {@link org.eclipse.dataplane.Dataplane#notifyPrepared(String, OnPrepare)} to signal that
+     * preparation is complete. The Dataplane will then call this method again so that the
+     * DataAddress can be set on the DataFlow before continuing.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
-
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnResume.java

@@ -17,8 +17,24 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the resume endpoint is called for a DataFlow. The resume request
+ * signals to the dataplane to resume a suspended data flow and start data transmission again.
+ */
 public interface OnResume {
 
+    /**
+     * Performs the logic when a resume request is received. The dataplane should start transmitting
+     * any data for the data flow.
+     *
+     * For PUSH transfers, a consumer data plane must provide a DataAddress. For PULL transfers,
+     * a provider data plane must provide a DataAddress. Either, the original DataAddress may be
+     * used, or a new DataAddress may be generated and set on the DataFlow.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
 
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStart.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,30 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the start endpoint is called for a data flow. This endpoint is only
+ * called on the provider side. The start request signals to the dataplane to begin a data transfer
+ * or to initialize a data flow and any resources required for data transfer.
+ */
 public interface OnStart {
 
+    /**
+     * Performs the logic when a start request is received. For a PUSH transfer, the provider
+     * dataplane receives a DataAddress in the start message and should start sending data to
+     * the respective endpoint. For a PULL transfer, the provider dataplane must return a
+     * DataAddress providing endpoint information for the consumer to pull the data from.
+     *
+     * Starting of the data flow may happen asynchronously, e.g. for long-running provision tasks.
+     * If the start should happen asynchronously, set the DataFlow's state to
+     * {@link DataFlow.State#STARTING} before returning. Once start logic is completed, use the
+     * {@link org.eclipse.dataplane.Dataplane#notifyStarted(String, OnStart)} to signal that
+     * start is complete. The Dataplane will then call this method again so that the
+     * DataAddress can be set on the DataFlow before continuing.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
 
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStarted.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,22 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the started endpoint is called for a data flow. This endpoint is only
+ * called on the consumer side. The started request signals to the dataplane to begin a data
+ * transfer or that a data transmission has begun.
+ */
 public interface OnStarted {
 
+    /**
+     * Performs the logic when a started request is received. For a PULL transfer, the consumer
+     * dataplane receives a DataAddress in the started message and should start pulling data from
+     * the respective endpoint.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
 
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnSuspend.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,22 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the suspend endpoint is called for a DataFlow. The suspend request
+ * signals to the dataplane to pause a data flow and stop data transmission. The data flow can
+ * be resumed at a later time.
+ */
 public interface OnSuspend {
 
+    /**
+     * Performs the logic when a suspend request is received. The dataplane must stop any data
+     * transmission for the data flow. It may leave resources available for when the data flow
+     * is resumed.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
 
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnTerminate.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,20 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Contains the logic for when the terminate endpoint is called for a DataFlow. The terminate
+ * request signals to the dataplane to terminate a data flow. The dataplane must close/remove
+ * resource for the data flow so that data transmission is stopped.
+ */
 public interface OnTerminate {
 
+    /**
+     * Performs the logic when a terminated request is received.
+     *
+     * @param dataFlow the data flow
+     * @return a successful or failed {@link Result}, indicating whether the action was successful;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<DataFlow> action(DataFlow dataFlow);
 
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/ControlPlaneStore.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,12 +18,43 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.controlplane.ControlPlane;
 
+/**
+ * Store for {@link ControlPlane}s.
+ */
 public interface ControlPlaneStore {
+
+    /**
+     * Persists the given ControlPlane.
+     *
+     * @param controlPlane the DataFlow to persist
+     * @return a successful or failed {@link Result}, indicating whether the ControlPlane was persisted;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<Void> save(ControlPlane controlPlane);
 
+    /**
+     * Retrieves a stored ControlPlane by id.
+     *
+     * @param controlplaneId the id of the ControlPlane
+     * @return a successful {@link Result} holding the ControlPlane, or a failed result with an
+     *         exception providing error details
+     */
     Result<ControlPlane> findById(String controlplaneId);
 
+    /**
+     * Deletes a stored ControlPlane by id.
+     *
+     * @param id the id of the ControlPlane
+     * @return a successful or failed {@link Result}, indicating whether the ControlPlane was deleted;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<Void> delete(String id);
 
+    /**
+     * Checks for existence of a ControlPlane by id.
+     *
+     * @param controlplaneId the id of the ControlPlane
+     * @return true, if the ControlPlane exists in the store, false otherwise
+     */
     boolean exists(String controlplaneId);
 }

dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/DataFlowStore.java

@@ -9,6 +9,7 @@
  *
  *  Contributors:
  *       Think-it GmbH - initial API and implementation
+ *       Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V. - Javadoc
  *
  */
 
@@ -17,8 +18,26 @@
 import org.eclipse.dataplane.domain.Result;
 import org.eclipse.dataplane.domain.dataflow.DataFlow;
 
+/**
+ * Store for {@link DataFlow}s.
+ */
 public interface DataFlowStore {
+
+    /**
+     * Persists the given DataFlow.
+     *
+     * @param dataFlow the DataFlow to persist
+     * @return a successful or failed {@link Result}, indicating whether the DataFlow was persisted;
+     *         in case of a failed result, it should provide an exception with error details
+     */
     Result<Void> save(DataFlow dataFlow);
 
+    /**
+     * Retrieves a stored DataFlow by id.
+     *
+     * @param flowId the id of the DataFlow
+     * @return a successful {@link Result} holding the DataFlow, or a failed result with an
+     *         exception providing error details
+     */
     Result<DataFlow> findById(String flowId);
 }