docs: add comments and Javadoc

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/controller/MultipartController.java

@@ -110,7 +110,7 @@ public Response request(@FormDataParam(HEADER) InputStream headerInputStream,
             return Response.ok(createResponse(malformedMessage(null, connectorId))).build();
         }
 
-        // Check if any required field missing
+        // Check if any required header field missing
         if (header.getId() == null || header.getIssuerConnector() == null || header.getSenderAgent() == null) {
             return Response.ok(createResponse(malformedMessage(header, connectorId))).build();
         }
@@ -138,13 +138,15 @@ public Response request(@FormDataParam(HEADER) InputStream headerInputStream,
             return Response.ok(createResponse(notAuthenticated(header, connectorId))).build();
         }
 
+        // Build the multipart request
         var claimToken = verificationResult.getContent();
         var multipartRequest = MultipartRequest.Builder.newInstance()
                 .header(header)
                 .payload(payload)
                 .claimToken(claimToken)
                 .build();
 
+        // Find handler for the multipart request
         var handler = multipartHandlers.stream()
                 .filter(h -> h.canHandle(multipartRequest))
                 .findFirst()

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/handler/ArtifactRequestHandler.java

@@ -85,52 +85,59 @@ public boolean canHandle(@NotNull MultipartRequest multipartRequest) {
         var claimToken = multipartRequest.getClaimToken();
         var message = (ArtifactRequestMessage) multipartRequest.getHeader();
 
+        // Validate request artifact ID
         var artifactUri = message.getRequestedArtifact();
         var artifactIdsId = IdsIdParser.parse(artifactUri.toString());
         if (artifactIdsId.getType() != IdsType.ARTIFACT) {
             monitor.debug("ArtifactRequestHandler: Requested artifact URI not of type artifact.");
             return createMultipartResponse(badParameters(multipartRequest.getHeader(), connectorId));
         }
 
+        // Validate contract ID
         var contractUri = message.getTransferContract();
         var contractIdsId = IdsIdParser.parse(contractUri.toString());
         if (contractIdsId.getType() != IdsType.CONTRACT) {
             monitor.debug("ArtifactRequestHandler: Transfer contract URI not of type contract.");
             return createMultipartResponse(badParameters(multipartRequest.getHeader(), connectorId));
         }
 
+        // Get contract agreement for received contract ID
         var contractAgreement = contractNegotiationStore.findContractAgreement(contractIdsId.getValue());
         if (contractAgreement == null) {
             monitor.debug(String.format("ArtifactRequestHandler: No contract agreement with id %s found.", contractIdsId.getValue()));
             return createMultipartResponse(badParameters(multipartRequest.getHeader(), connectorId));
         }
 
+        // Validate contract agreement
         var isContractValid = contractValidationService.validate(claimToken, contractAgreement);
         if (!isContractValid) {
             monitor.debug("ArtifactRequestHandler: Contract is invalid");
             return createMultipartResponse(badParameters(multipartRequest.getHeader(), connectorId));
         }
 
+        // Verify that contract agreement is valid for requested artifact
         if (!artifactIdsId.getValue().equals(contractAgreement.getAssetId())) {
             monitor.debug(String.format("ArtifactRequestHandler: invalid artifact id specified %s for contract: %s", artifactIdsId.getValue(), contractIdsId.getValue()));
             return createMultipartResponse(badParameters(multipartRequest.getHeader(), connectorId));
         }
 
+        // Read request payload, which contains the data destination and an optional secret
         ArtifactRequestMessagePayload artifactRequestMessagePayload;
         try {
-            artifactRequestMessagePayload =
-                    objectMapper.readValue(multipartRequest.getPayload(), ArtifactRequestMessagePayload.class);
+            artifactRequestMessagePayload = objectMapper.readValue(multipartRequest.getPayload(), ArtifactRequestMessagePayload.class);
         } catch (IOException e) {
             return createMultipartResponse(badParameters(multipartRequest.getHeader(), connectorId));
         }
 
-        var dataAddress = artifactRequestMessagePayload.getDataDestination();
+        var dataDestination = artifactRequestMessagePayload.getDataDestination();
 
+        // Read request message properties
         Map<String, String> props = new HashMap<>();
         if (message.getProperties() != null) {
             message.getProperties().forEach((k, v) -> props.put(k, v.toString()));
         }
 
+        // Get webhook address of requesting connector from message properties
         var idsWebhookAddress = Optional.ofNullable(props.remove(IDS_WEBHOOK_ADDRESS_PROPERTY))
                 .map(Object::toString)
                 .orElse(null);
@@ -146,18 +153,19 @@ public boolean canHandle(@NotNull MultipartRequest multipartRequest) {
         var dataRequest = DataRequest.Builder.newInstance()
                 .id(message.getId().toString())
                 .protocol(Protocols.IDS_MULTIPART)
-                .dataDestination(dataAddress)
+                .dataDestination(dataDestination)
                 .connectorId(connectorId)
                 .assetId(contractAgreement.getAssetId())
                 .contractId(contractAgreement.getId())
                 .properties(props)
                 .connectorAddress(idsWebhookAddress)
                 .build();
 
+        // Initiate a transfer process for the request
         var transferInitiateResult = transferProcessManager.initiateProviderRequest(dataRequest);
 
         if (artifactRequestMessagePayload.getSecret() != null) {
-            vault.storeSecret(dataAddress.getKeyName(), artifactRequestMessagePayload.getSecret());
+            vault.storeSecret(dataDestination.getKeyName(), artifactRequestMessagePayload.getSecret());
         }
 
         return createMultipartResponse(inProcessFromStatusResult(transferInitiateResult, multipartRequest.getHeader(), connectorId));

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/handler/ContractRequestHandler.java

@@ -89,7 +89,8 @@ public boolean canHandle(@NotNull MultipartRequest multipartRequest) {
             monitor.severe("ContractRequestHandler: Contract Request is invalid", e);
             return createMultipartResponse(badParameters(message, connectorId));
         }
-
+
+        // Get webhook address of requesting connector from message properties
         var idsWebhookAddress = message.getProperties().get(IDS_WEBHOOK_ADDRESS_PROPERTY);
         if (idsWebhookAddress == null || idsWebhookAddress.toString().isBlank()) {
             var msg = "Ids webhook address is invalid";

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/handler/DescriptionRequestHandler.java

@@ -49,7 +49,6 @@
 import static org.eclipse.dataspaceconnector.ids.api.multipart.util.ResponseUtil.badParameters;
 import static org.eclipse.dataspaceconnector.ids.api.multipart.util.ResponseUtil.descriptionResponse;
 import static org.eclipse.dataspaceconnector.ids.api.multipart.util.ResponseUtil.createMultipartResponse;
-import static org.eclipse.dataspaceconnector.ids.api.multipart.util.ResponseUtil.messageTypeNotSupported;
 import static org.eclipse.dataspaceconnector.ids.api.multipart.util.ResponseUtil.notFound;
 
 public class DescriptionRequestHandler implements Handler {
@@ -92,6 +91,7 @@ public MultipartResponse handleRequest(@NotNull MultipartRequest multipartReques
         var claimToken = multipartRequest.getClaimToken();
         var message = (DescriptionRequestMessage) multipartRequest.getHeader();
 
+        // Get ID of requested element
         var requestedElement = message.getRequestedElement();
         IdsId idsId = null;
         if (requestedElement != null) {
@@ -111,6 +111,7 @@ public MultipartResponse handleRequest(@NotNull MultipartRequest multipartReques
         var to = getInt(message, Range.TO, Integer.MAX_VALUE);
         var range = new Range(from, to);
 
+        // Retrieve and transform requested element
         Result<? extends ModelClass> result;
         if (idsId == null || (idsId.getType() == IdsType.CONNECTOR)) {
             result = getConnector(claimToken, range);
@@ -141,6 +142,15 @@ private Result<Connector> getConnector(ClaimToken claimToken, Range range) {
         return transformerRegistry.transform(connectorService.getConnector(claimToken, range), de.fraunhofer.iais.eis.Connector.class);
     }
 
+    /**
+     * Retrieves the requested element specified by the IdsId. If the requested element is a
+     * catalog or resource, the given range is used.
+     *
+     * @param idsId the ID.
+     * @param claimToken the claim token of the requesting connector.
+     * @param range the range.
+     * @return the requested element.
+     */
     private Object retrieveRequestedElement(IdsId idsId, ClaimToken claimToken, Range range) {
         var type = idsId.getType();
         switch (type) {
@@ -168,6 +178,13 @@ private Object retrieveRequestedElement(IdsId idsId, ClaimToken claimToken, Rang
         }
     }
 
+    /**
+     * Transforms the requested element as defined by the IdsType.
+     *
+     * @param object the object to transform.
+     * @param type the IDS target type.
+     * @return the transformation result,
+     */
     private Result<? extends ModelClass> transformRequestedElement(Object object, IdsType type) {
         switch (type) {
             case ARTIFACT:

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/handler/EndpointDataReferenceHandler.java

@@ -76,6 +76,7 @@ public boolean canHandle(@NotNull MultipartRequest multipartRequest) {
     public @Nullable MultipartResponse handleRequest(@NotNull MultipartRequest multipartRequest) {
         Objects.requireNonNull(multipartRequest);
 
+        // Read and transform the endpoint data reference from the request payload
         var edr = typeManager.readValue(multipartRequest.getPayload(), EndpointDataReference.class);
         var transformationResult = transformerRegistry.transform(edr);
         if (transformationResult.failed()) {
@@ -85,6 +86,7 @@ public boolean canHandle(@NotNull MultipartRequest multipartRequest) {
 
         var transformedEdr = transformationResult.getContent();
 
+        // Apply all endpoint data reference receivers to the endpoint data reference
         var receiveResult = receiverRegistry.receiveAll(transformedEdr).join();
         if (receiveResult.failed()) {
             monitor.severe("EDR dispatch failed: " + String.join(", ", receiveResult.getFailureMessages()));

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/message/MultipartRequest.java

@@ -21,6 +21,10 @@
 
 import java.util.Objects;
 
+/**
+ * Represents an IDS multipart request. Contains the IDS message header, an optional payload and
+ * the claim token for the requesting connector.
+ */
 public class MultipartRequest {
 
     private final Message header;

data-protocols/ids/ids-api-multipart-endpoint-v1/src/main/java/org/eclipse/dataspaceconnector/ids/api/multipart/message/MultipartResponse.java

@@ -20,6 +20,9 @@
 
 import java.util.Objects;
 
+/**
+ * Represents an IDS multipart response. Contains the IDS message header and an optional payload.
+ */
 public class MultipartResponse {
 
     private final Message header;