Merge branch 'main' of https://github.com/DKE-Data/agrirouter-sdk-java …

…into releases/2.x

README.adoc

@@ -34,6 +34,68 @@ This project contains the SDK for the communication with the agrirouter. Everyth
 
 The release workflow follows the https://docs.microsoft.com/en-us/azure/devops/repos/git/git-branching-guidance?view=azure-devops[Microsoft DevOps Release Model] where a release shows up as a branch in the repository.
 
+=== Update from 1.4.x to 2.x
+
+The update for the new release includes some breaking changes. To have a rough overview what has to be done to have the new features from 2.x in you application, please see the following migration / update guide when updating.
+
+==== Update the Maven dependencies
+
+The first step is to update the coordinates of the dependencies. With the release 2.x the coordinates changed to a new name and a new version.
+
+[xml]
+----
+    <dependency>
+        <groupId>com.agrirouter.api</groupId>
+        <artifactId>agrirouter-sdk-java-api</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+    <dependency>
+        <groupId>com.agrirouter.api</groupId>
+        <artifactId>agrirouter-sdk-java-impl</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+    <dependency>
+        <groupId>com.agrirouter.api</groupId>
+        <artifactId>agrirouter-sdk-java-convenience</artifactId>
+        <version>2.0.0</version>
+    </dependency>
+----
+
+==== Update package declarations for services and internal classes
+
+Since the package declaration was updated along with the coordinates, there will be compiler errors that should be fixed. Some classes have moved to a more meaningful package.
+
+image::migration_1-4_to_2-0/compiler-errors-before.png[Compiler errors before the migration.]
+
+The new package declaration added the protocol part (`http` or in this case the `mqtt`).
+
+image::migration_1-4_to_2-0/package-declaration-after-refactoring.png[Package declaration after migrating.]
+
+==== Update the usage of the enums for message types
+
+To have a better understanding about system message types and content message types, the declaration for the different types has changed. There are two new classes, the `ContentMessageType` for content messages and the `SystemMessageType` for system messages. The former technical message type will cause a compiler error, since it was replaced.
+
+image::migration_1-4_to_2-0/former-technical-message-types.png[Former message types.]
+
+The new declaration uses the system message type.
+
+image::migration_1-4_to_2-0/system-message-type-afterwards.png[System message type usage afterwards.]
+
+==== Remove former URLs for ProtoBuf message types
+
+With the new release the URLs can be fetched from the content message types and there is no need to put them into a helper method any longer.
+
+image::migration_1-4_to_2-0/former-content-message-type-urls.png[Former content message types.]
+
+With the new release fetch the URLs is way more comfortable.
+
+image::migration_1-4_to_2-0/type-urls-from-technical-message-types.png[Type URLs from content message types.]
+
+==== Have a look at an example
+
+The http://www.agrirouter-middleware.de[agrirouter middleware] has been updated after the release of version 2.x and can be an indicator regarding the workload for the migration.
+Have a look at the following https://github.com/agrirouter-middleware/agrirouter-middleware/pull/12[PR #12] to see the necessary adaptions.
+
 == Modules
 
 === `api` Module

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/cancellation/CancellationToken.java

@@ -14,8 +14,8 @@ public interface CancellationToken {
    * Will be called if one step during the whole polling mechanism is done and the next iteration
    * will start afterwards.
    */
-  void step();
+  void nextStep();
 
   /** Will wait a dedicated amount of time before starting the next step. */
-  void waitBeforeStartingNextStep();
+  void waitIfNotCancelled();
 }

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/cancellation/DefaultCancellationToken.java

@@ -21,16 +21,18 @@ public boolean isNotCancelled() {
   }
 
   @Override
-  public void step() {
+  public void nextStep() {
     nrOfTries++;
   }
 
   @Override
-  public void waitBeforeStartingNextStep() {
-    try {
-      Thread.sleep(timeToWait);
-    } catch (InterruptedException nop) {
-      wasInterrupted = true;
+  public void waitIfNotCancelled() {
+    if (isNotCancelled()) {
+      try {
+        Thread.sleep(timeToWait);
+      } catch (InterruptedException nop) {
+        wasInterrupted = true;
+      }
     }
   }
 }

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/env/Environment.java

@@ -1,17 +1,31 @@
 package com.dke.data.agrirouter.api.env;
 
 import com.dke.data.agrirouter.api.enums.SecuredOnboardingResponseType;
+import org.apache.commons.lang3.BooleanUtils;
 
 /** Common Environment, holds some default methods pointing to the QA. */
 public interface Environment {
 
+  /** System property to enable logging for HTTP requests. */
+  String ENABLE_HTTP_REQUEST_LOGGING = "agrirouter.sdk.enable.http.request.logging";
+
   /** Template for MQTT connections. */
   String MQTT_URL_TEMPLATE = "ssl://%s:%s";
 
   /** Link template for the secured onboarding process. */
   String SECURED_ONBOARDING_AUTHORIZATION_LINK_TEMPLATE =
       "/application/%s/authorize?response_type=%s&state=%s&redirect_uri=%s";
 
+  /**
+   * Checks whether the HTTP request logging is enabled or not.
+   *
+   * @return -
+   */
+  static boolean httpRequestLoggingEnabled() {
+    final String httpRequestLoggingEnabled = System.getProperty(ENABLE_HTTP_REQUEST_LOGGING);
+    return BooleanUtils.toBoolean(httpRequestLoggingEnabled);
+  }
+
   /**
    * Returning the AR base URL without trailing '/'.
    *

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/ParameterValidation.java

@@ -52,7 +52,10 @@ default void rise(String message, String... parameterNames) {
   default void nullCheck(String parameterName, Object o) {
     if (null == o) {
       this.rise(
-          "The parameter '%s' should not have been null, please check your values.", parameterName);
+          String.format(
+              "The parameter '%s' should not have been null, please check your values.",
+              parameterName),
+          parameterName);
     }
   }
 
@@ -64,7 +67,9 @@ default void nullCheck(String parameterName, Object o) {
   default void isBlank(String parameterName, String s) {
     if (StringUtils.isBlank(s)) {
       this.rise(
-          "The parameter '%s' should not have been blank, please check your values.",
+          String.format(
+              "The parameter '%s' should not have been blank, please check your values.",
+              parameterName),
           parameterName);
     }
   }
@@ -78,7 +83,9 @@ default void nullOrEmpty(String parameterName, Collection<?> c) {
     nullCheck(parameterName, c);
     if (c.isEmpty()) {
       this.rise(
-          "The parameter '%s' should not have been empty, please check your values.",
+          String.format(
+              "The parameter '%s' should not have been empty, please check your values.",
+              parameterName),
           parameterName);
     }
   }

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/messaging/encoding/EncodeMessageService.java

@@ -35,7 +35,7 @@ String encode(
    * @param payloadParameters -
    * @return -
    */
-  List<MessageParameterTuple> chunkAndEncode(
+  List<MessageParameterTuple> chunkAndBase64EncodeEachChunk(
       MessageHeaderParameters messageHeaderParameters,
       PayloadParameters payloadParameters,
       OnboardingResponse onboardingResponse);

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/messaging/http/DeleteMessageService.java

@@ -1,5 +1,28 @@
 package com.dke.data.agrirouter.api.service.messaging.http;
 
+import com.dke.data.agrirouter.api.dto.onboard.OnboardingResponse;
+import com.dke.data.agrirouter.api.messaging.HttpAsyncMessageSendingResult;
 import com.dke.data.agrirouter.api.service.parameters.DeleteMessageParameters;
 
-public interface DeleteMessageService extends MessagingService<DeleteMessageParameters> {}
+public interface DeleteMessageService extends MessagingService<DeleteMessageParameters> {
+
+  /**
+   * Delete all messages in the feed. The function will delete all messages based on the time
+   * interval of 4 weeks (which is the maximum of time the messages are stored within the
+   * agrirouter).
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  String sendMessageToDeleteAll(OnboardingResponse onboardingResponse);
+
+  /**
+   * Delete all messages in the feed. The function will delete all messages based on the time
+   * interval of 4 weeks (which is the maximum of time the messages are stored within the
+   * agrirouter).
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  HttpAsyncMessageSendingResult sendMessageToDeleteAllAsync(OnboardingResponse onboardingResponse);
+}

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/messaging/http/ListEndpointsService.java

@@ -1,5 +1,41 @@
 package com.dke.data.agrirouter.api.service.messaging.http;
 
+import com.dke.data.agrirouter.api.dto.onboard.OnboardingResponse;
+import com.dke.data.agrirouter.api.messaging.HttpAsyncMessageSendingResult;
 import com.dke.data.agrirouter.api.service.parameters.ListEndpointsParameters;
 
-public interface ListEndpointsService extends MessagingService<ListEndpointsParameters> {}
+public interface ListEndpointsService extends MessagingService<ListEndpointsParameters> {
+
+  /**
+   * List all endpoints with a route to the dedicated endpoint.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  String sendMessageToListAllWithExistingRoute(OnboardingResponse onboardingResponse);
+
+  /**
+   * List all endpoints for the account, even those that do not have a route.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  String sendMessageToListAll(OnboardingResponse onboardingResponse);
+
+  /**
+   * List all endpoints with a route to the dedicated endpoint.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  HttpAsyncMessageSendingResult sendMessageToListAllWithExistingRouteAsync(
+      OnboardingResponse onboardingResponse);
+
+  /**
+   * List all endpoints for the account, even those that do not have a route.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  HttpAsyncMessageSendingResult sendMessageToListAllAsync(OnboardingResponse onboardingResponse);
+}

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/messaging/http/MessageHeaderQueryService.java

@@ -1,9 +1,31 @@
 package com.dke.data.agrirouter.api.service.messaging.http;
 
 import agrirouter.feed.response.FeedResponse;
+import com.dke.data.agrirouter.api.dto.onboard.OnboardingResponse;
+import com.dke.data.agrirouter.api.messaging.HttpAsyncMessageSendingResult;
 import com.dke.data.agrirouter.api.service.messaging.encoding.MessageDecoder;
 import com.dke.data.agrirouter.api.service.parameters.MessageQueryParameters;
 
 public interface MessageHeaderQueryService
     extends MessagingService<MessageQueryParameters>,
-        MessageDecoder<FeedResponse.HeaderQueryResponse> {}
+        MessageDecoder<FeedResponse.HeaderQueryResponse> {
+
+  /**
+   * Query all message headers as default function. The query will be based on a time period since
+   * message ID filtering or sender filtering can be achieved using the default message sending.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  String sendMessageToQueryAll(OnboardingResponse onboardingResponse);
+
+  /**
+   * Query all message headers as async default function. The query will be based on a time period
+   * since message ID filtering or sender filtering can be achieved using the default message
+   * sending.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  HttpAsyncMessageSendingResult sendMessageToQueryAllAsync(OnboardingResponse onboardingResponse);
+}

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/messaging/http/MessageQueryService.java

@@ -1,9 +1,30 @@
 package com.dke.data.agrirouter.api.service.messaging.http;
 
 import agrirouter.feed.response.FeedResponse;
+import com.dke.data.agrirouter.api.dto.onboard.OnboardingResponse;
+import com.dke.data.agrirouter.api.messaging.HttpAsyncMessageSendingResult;
 import com.dke.data.agrirouter.api.service.messaging.encoding.MessageDecoder;
 import com.dke.data.agrirouter.api.service.parameters.MessageQueryParameters;
 
 public interface MessageQueryService
     extends MessagingService<MessageQueryParameters>,
-        MessageDecoder<FeedResponse.MessageQueryResponse> {}
+        MessageDecoder<FeedResponse.MessageQueryResponse> {
+
+  /**
+   * Query all messages as default function. The query will be based on a time period since message
+   * ID filtering or sender filtering can be achieved using the default message sending.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  String sendMessageToQueryAll(OnboardingResponse onboardingResponse);
+
+  /**
+   * Query all messages as async default function. The query will be based on a time period since
+   * message ID filtering or sender filtering can be achieved using the default message sending.
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  HttpAsyncMessageSendingResult sendMessageToQueryAllAsync(OnboardingResponse onboardingResponse);
+}

agrirouter-sdk-java-api/src/main/java/com/dke/data/agrirouter/api/service/messaging/mqtt/DeleteMessageService.java

@@ -1,5 +1,28 @@
 package com.dke.data.agrirouter.api.service.messaging.mqtt;
 
+import com.dke.data.agrirouter.api.dto.onboard.OnboardingResponse;
+import com.dke.data.agrirouter.api.messaging.MqttAsyncMessageSendingResult;
 import com.dke.data.agrirouter.api.service.parameters.DeleteMessageParameters;
 
-public interface DeleteMessageService extends MessagingService<DeleteMessageParameters> {}
+public interface DeleteMessageService extends MessagingService<DeleteMessageParameters> {
+
+  /**
+   * Delete all messages in the feed. The function will delete all messages based on the time
+   * interval of 4 weeks (which is the maximum of time the messages are stored within the
+   * agrirouter).
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  String sendMessageToDeleteAll(OnboardingResponse onboardingResponse);
+
+  /**
+   * Delete all messages in the feed. The function will delete all messages based on the time
+   * interval of 4 weeks (which is the maximum of time the messages are stored within the
+   * agrirouter).
+   *
+   * @param onboardingResponse The onboard response for the endpoint.
+   * @return The message ID.
+   */
+  MqttAsyncMessageSendingResult sendMessageToDeleteAllAsync(OnboardingResponse onboardingResponse);
+}