From edabfd2159a604973f76917281970780f65bec9b Mon Sep 17 00:00:00 2001 From: Ronja Quensel Date: Fri, 26 Jun 2026 16:59:42 +0200 Subject: [PATCH] docs: add Javadoc --- .../domain/registration/Authorization.java | 12 +++++++ .../eclipse/dataplane/logic/OnCompleted.java | 13 ++++++++ .../eclipse/dataplane/logic/OnPrepare.java | 23 ++++++++++++- .../org/eclipse/dataplane/logic/OnResume.java | 16 ++++++++++ .../org/eclipse/dataplane/logic/OnStart.java | 23 +++++++++++++ .../eclipse/dataplane/logic/OnStarted.java | 15 +++++++++ .../eclipse/dataplane/logic/OnSuspend.java | 15 +++++++++ .../eclipse/dataplane/logic/OnTerminate.java | 13 ++++++++ .../port/store/ControlPlaneStore.java | 32 +++++++++++++++++++ .../dataplane/port/store/DataFlowStore.java | 19 +++++++++++ 10 files changed, 180 insertions(+), 1 deletion(-) diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/domain/registration/Authorization.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/domain/registration/Authorization.java index 6ec1ed8..07dc211 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/domain/registration/Authorization.java +++ b/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 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 extractCallerId(String authorizationHeader); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnCompleted.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnCompleted.java index 1c7516b..51665ec 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnCompleted.java +++ b/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 action(DataFlow dataFlow); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnPrepare.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnPrepare.java index 429edfe..5279b31 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnPrepare.java +++ b/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 action(DataFlow dataFlow); - } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnResume.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnResume.java index e38fc53..d2c5684 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnResume.java +++ b/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 action(DataFlow dataFlow); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStart.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStart.java index c716c0a..a334bbf 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStart.java +++ b/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 action(DataFlow dataFlow); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStarted.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStarted.java index c1a0cd0..9a46315 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnStarted.java +++ b/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 action(DataFlow dataFlow); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnSuspend.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnSuspend.java index 0187b21..1d5bcf4 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnSuspend.java +++ b/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 action(DataFlow dataFlow); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnTerminate.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnTerminate.java index c522bbb..ec69669 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/logic/OnTerminate.java +++ b/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 action(DataFlow dataFlow); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/ControlPlaneStore.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/ControlPlaneStore.java index 747e672..dbd3131 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/ControlPlaneStore.java +++ b/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 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 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 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); } diff --git a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/DataFlowStore.java b/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/DataFlowStore.java index 71a4604..6501a83 100644 --- a/dataplane-sdk-core/src/main/java/org/eclipse/dataplane/port/store/DataFlowStore.java +++ b/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 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 findById(String flowId); }