Merge branch 'master' into feature/importing-policies

Author: Kalin Kostashki

CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Community Code of Conduct
+
+**Version 1.2  
+August 19, 2020**
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as community members, contributors, committers, and project leaders pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+*   Using welcoming and inclusive language
+*   Being respectful of differing viewpoints and experiences
+*   Gracefully accepting constructive criticism
+*   Focusing on what is best for the community
+*   Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+*   The use of sexualized language or imagery and unwelcome sexual attention or advances
+*   Trolling, insulting/derogatory comments, and personal or political attacks
+*   Public or private harassment
+*   Publishing others' private information, such as a physical or electronic address, without explicit permission
+*   Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+With the support of the Eclipse Foundation staff (the “Staff”), project committers and leaders are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project committers and leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the Eclipse Foundation project or its community in public spaces. Examples of representing a project or community include posting via an official social media account, or acting as a project representative at an online or offline event. Representation of a project may be further defined and clarified by project committers, leaders, or the EMO.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the Staff at codeofconduct@eclipse.org. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The Staff is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project committers or leaders who do not follow the Code of Conduct in good faith may face temporary or permanent repercussions as determined by the Staff.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org) , version 1.4, available at [https://www.contributor-covenant.org/version/1/4/code-of-conduct.html](https://www.contributor-covenant.org/version/1/4/code-of-conduct/)

SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+These versions of Eclipse Ditto Clients are currently being supported with security updates.
+
+| Version | Supported          |
+|---------| ------------------ |
+| 3.0.x   | :white_check_mark: |
+| 2.4.x   | :white_check_mark: |
+| < 2.4.0 | :x:                |
+
+## Reporting a Vulnerability
+
+Please report a found vulnerability here: [https://www.eclipse.org/security/](https://www.eclipse.org/security/)

java/pom.xml

@@ -239,7 +239,7 @@
         <!-- globally set version for checking binary compatibility against -->
         <!-- whoever changes this to ${revision} or ${project.version} is responsible for API breakage caused by this! -->
         <!-- in other words: never do that here! exclude the 'breakages' locally in the japicmp maven plugin if you intentionally break something -->
-        <binary-compatibility-check.version>2.4.0</binary-compatibility-check.version>
+        <binary-compatibility-check.version>3.0.0</binary-compatibility-check.version>
         <!-- skip until first release: -->
         <binary-compatibility-check.skip>false</binary-compatibility-check.skip>
 
@@ -452,8 +452,6 @@
                                 <exclude>org.eclipse.ditto.client.twin.internal</exclude>
                                 <!-- this builder is an internal implementation of a builder interface and should not be handled as API: -->
                                 <exclude>org.eclipse.ditto.client.configuration.ClientCredentialsAuthenticationConfiguration$ClientCredentialsAuthenticationConfigurationBuilder</exclude>
-                                <exclude>org.eclipse.ditto.client.streaming.ThingSearchPublisher#of(org.eclipse.ditto.base.model.signals.Signal,org.eclipse.ditto.protocol.adapter.ProtocolAdapter,org.eclipse.ditto.client.messaging.MessagingProvider)</exclude>
-                                <exclude>org.eclipse.ditto.client.live.commands.query.RetrieveThingsLiveCommand</exclude>
                             </excludes>
                         </parameter>
                     </configuration>

java/src/main/java/org/eclipse/ditto/client/DittoClient.java

@@ -52,7 +52,9 @@ public interface DittoClient {
      * Directly sends a Ditto Protocol {@link Adaptable} message to the established Ditto backend connection.
      *
      * @param dittoProtocolAdaptable the adaptable to send
-     * @return a CompletionStage containing the correlated response to the sent {@code dittoProtocolAdaptable}
+     * @return a CompletionStage containing the correlated response to the sent {@code dittoProtocolAdaptable} or
+     * which failed with a {@link org.eclipse.ditto.client.management.ClientReconnectingException} if the client is
+     * in a reconnecting state.
      * @throws IllegalStateException when no twin/live connection was configured for this client
      */
     CompletionStage<Adaptable> sendDittoProtocol(Adaptable dittoProtocolAdaptable);

java/src/main/java/org/eclipse/ditto/client/configuration/MessagingConfiguration.java

@@ -182,6 +182,7 @@ interface Builder {
          * Register a consumer of errors which occur during opening the connection initially and on reconnects.
          *
          * @param handler the handler that will be called with the cause of the connection error.
+         * @return this builder.
          * @since 1.2.0
          */
         Builder connectionErrorHandler(@Nullable Consumer<Throwable> handler);
@@ -190,6 +191,7 @@ interface Builder {
          * Register a contextListener which is notified whenever the connection is disconnected.
          *
          * @param contextListener the handler that will be called with details about the disconnection.
+         * @return this builder.
          * @since 2.1.0
          */
         Builder disconnectedListener(@Nullable Consumer<DisconnectedContext> contextListener);

java/src/main/java/org/eclipse/ditto/client/internal/AbstractHandle.java

@@ -18,6 +18,7 @@
 import java.time.Duration;
 import java.util.Map;
 import java.util.Optional;
+import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.CompletionStage;
 import java.util.function.Function;
 import java.util.function.Predicate;
@@ -40,6 +41,7 @@
 import org.eclipse.ditto.client.ack.internal.AcknowledgementRequestsValidator;
 import org.eclipse.ditto.client.internal.bus.Classification;
 import org.eclipse.ditto.client.management.AcknowledgementsFailedException;
+import org.eclipse.ditto.client.management.ClientReconnectingException;
 import org.eclipse.ditto.client.messaging.MessagingProvider;
 import org.eclipse.ditto.json.JsonField;
 import org.eclipse.ditto.json.JsonObject;
@@ -138,6 +140,8 @@ protected Signal signalFromAdaptable(final Adaptable adaptable) {
      * @param <R> type of the result.
      * @return future of the result if the expected response arrives or a failed future on error.
      * Type is {@code CompletionStage} to signify that the future will complete or fail without caller intervention.
+     * If the client is reconnecting while this method is called the future fails with a
+     * {@link ClientReconnectingException}.
      */
     protected <T extends PolicyCommand<T>, S extends PolicyCommandResponse<?>, R> CompletionStage<R> askPolicyCommand(
             final T command,
@@ -159,11 +163,14 @@ protected <T extends PolicyCommand<T>, S extends PolicyCommandResponse<?>, R> Co
      * @param <R> type of the result.
      * @return future of the result if the expected response arrives or a failed future on error.
      * Type is {@code CompletionStage} to signify that the future will complete or fail without caller intervention.
+     * If the client is reconnecting while this method is called the future fails with a
+     * {@link ClientReconnectingException}.
      */
     protected <T extends ThingCommand<T>, S extends CommandResponse<?>, R> CompletionStage<R> askThingCommand(
             final T command,
             final Class<S> expectedResponse,
             final Function<S, R> onSuccess) {
+
         final ThingCommand<?> commandWithChannel = validateAckRequests(setChannel(command, channel));
         return sendSignalAndExpectResponse(commandWithChannel, expectedResponse, onSuccess, ErrorResponse.class,
                 ErrorResponse::getDittoRuntimeException);
@@ -180,33 +187,42 @@ protected <T extends ThingCommand<T>, S extends CommandResponse<?>, R> Completio
      * @param <S> type of the expected success response.
      * @param <E> type of the expected error response.
      * @param <R> type of the result.
-     * @return future of the result.
+     * @return future of the result. The future can be exceptional with a {@link ClientReconnectingException} if the
+     * client is reconnecting while this method is called.
      */
     protected <S, E, R> CompletionStage<R> sendSignalAndExpectResponse(final Signal<?> signal,
             final Class<S> expectedResponseClass,
             final Function<S, R> onSuccess,
             final Class<E> expectedErrorResponseClass,
             final Function<E, ? extends RuntimeException> onError) {
 
-        final CompletionStage<Adaptable> responseFuture = messagingProvider.getAdaptableBus()
-                .subscribeOnceForAdaptable(Classification.forCorrelationId(signal), getTimeout());
-
-        messagingProvider.emit(signalToJsonString(signal));
-        return responseFuture.thenApply(responseAdaptable -> {
-            final Signal<?> response = signalFromAdaptable(responseAdaptable);
-            if (expectedErrorResponseClass.isInstance(response)) {
-                // extracted runtime exception will be wrapped in CompletionException.
-                throw onError.apply(expectedErrorResponseClass.cast(response));
-            } else if (response instanceof Acknowledgements) {
-                final CommandResponse<?> commandResponse =
-                        extractCommandResponseFromAcknowledgements(signal, (Acknowledgements) response);
-                return onSuccess.apply(expectedResponseClass.cast(commandResponse));
-            } else if (expectedResponseClass.isInstance(response)) {
-                return onSuccess.apply(expectedResponseClass.cast(response));
-            } else {
-                throw new ClassCastException("Expect " + expectedResponseClass.getSimpleName() + ", got: " + response);
-            }
-        });
+        try {
+            final CompletionStage<Adaptable> responseFuture = messagingProvider.getAdaptableBus()
+                    .subscribeOnceForAdaptable(Classification.forCorrelationId(signal), getTimeout());
+
+            messagingProvider.emit(signalToJsonString(signal));
+            return responseFuture.thenApply(responseAdaptable -> {
+                final Signal<?> response = signalFromAdaptable(responseAdaptable);
+                if (expectedErrorResponseClass.isInstance(response)) {
+                    // extracted runtime exception will be wrapped in CompletionException.
+                    throw onError.apply(expectedErrorResponseClass.cast(response));
+                } else if (response instanceof Acknowledgements) {
+                    final CommandResponse<?> commandResponse =
+                            extractCommandResponseFromAcknowledgements(signal, (Acknowledgements) response);
+                    return onSuccess.apply(expectedResponseClass.cast(commandResponse));
+                } else if (expectedResponseClass.isInstance(response)) {
+                    return onSuccess.apply(expectedResponseClass.cast(response));
+                } else {
+                    throw new ClassCastException(
+                            "Expect " + expectedResponseClass.getSimpleName() + ", got: " + response);
+                }
+            });
+        } catch (final ClientReconnectingException cre) {
+            return CompletableFuture.supplyAsync(() -> {
+                throw cre;
+            });
+        }
+
     }
 
     /**

java/src/main/java/org/eclipse/ditto/client/internal/CommonManagementImpl.java

@@ -163,7 +163,8 @@ public CompletionStage<Void> startConsumption(final Option<?>... consumptionOpti
      * Starts the consumption of twin events / messages / live events and commands.
      *
      * @param consumptionConfig the configuration Map to apply for the consumption.
-     * @return a CompletionStage that terminates when the start operation was successful.
+     * @return a CompletionStage that terminates when the start operation was successful or fails if the client is in
+     * a reconnecting state
      */
     protected abstract CompletionStage<Void> doStartConsumption(Map<String, String> consumptionConfig);
 
@@ -648,6 +649,7 @@ public void registerForThingChanges(final String registrationId, final Consumer<
      * @param futureToCompleteOrFailAfterAck the future to complete or fail after receiving the expected acknowledgement
      * or not.
      * @return the subscription ID.
+     * @throws org.eclipse.ditto.client.management.ClientReconnectingException if the client client is reconnecting.
      */
     protected AdaptableBus.SubscriptionId subscribe(
             @Nullable final AdaptableBus.SubscriptionId previousSubscriptionId,
@@ -730,6 +732,7 @@ private static String appendCorrelationIdParameter(final String protocolCommand,
      * @param protocolCommandAck the expected acknowledgement.
      * @param futureToCompleteOrFailAfterAck the future to complete or fail after receiving the expected acknowledgement
      * or not.
+     * @throws org.eclipse.ditto.client.management.ClientReconnectingException if the client client is reconnecting.
      */
     protected void unsubscribe(@Nullable final AdaptableBus.SubscriptionId subscriptionId,
             final String protocolCommand,

java/src/main/java/org/eclipse/ditto/client/internal/DefaultDittoClient.java

@@ -234,7 +234,6 @@ private static PoliciesImpl configurePolicyClient(final MessagingProvider messag
         final String busName = TopicPath.Channel.NONE.getName();
         final PointerBus bus = BusFactory.createPointerBus(busName, messagingProvider.getExecutorService());
         init(bus, messagingProvider);
-        final MessagingConfiguration messagingConfiguration = messagingProvider.getMessagingConfiguration();
         final OutgoingMessageFactory messageFactory = getOutgoingMessageFactoryForPolicies(messagingProvider);
         return PoliciesImpl.newInstance(messagingProvider, messageFactory, bus);
     }

java/src/main/java/org/eclipse/ditto/client/live/LiveCommandProcessor.java

@@ -41,6 +41,7 @@ public interface LiveCommandProcessor {
      * Publish a signal.
      *
      * @param signal the signal to publish.
+     * @throws org.eclipse.ditto.client.management.ClientReconnectingException if the client is in a reconnecting state.
      */
     void publishLiveSignal(Signal<?> signal);
 

java/src/main/java/org/eclipse/ditto/client/live/commands/LiveCommandHandler.java

@@ -34,6 +34,7 @@ public interface LiveCommandHandler<L extends LiveCommand<L, B>, B extends LiveC
      * @param type the type of live commands. MUST be an interface satisfying the recursive type bound.
      * @param commandHandler constructor of any response or event to publish.
      * @param <L> type of live commands.
+     * @param <B> type of live command answers.
      * @return the live command handler.
      */
     static <L extends LiveCommand<L, B>, B extends LiveCommandAnswerBuilder> LiveCommandHandler<L, B> of(
@@ -49,6 +50,7 @@ static <L extends LiveCommand<L, B>, B extends LiveCommandAnswerBuilder> LiveCom
      * @param type the type of live commands. MUST be an interface satisfying the recursive type bound.
      * @param commandHandler constructor of any response or event to publish and sender of any acknowledgements.
      * @param <L> type of live commands.
+     * @param <B> type of live command answers.
      * @return the live command handler.
      */
     static <L extends LiveCommand<L, B>, B extends LiveCommandAnswerBuilder> LiveCommandHandler<L, B> withAcks(
@@ -77,6 +79,7 @@ static <L extends LiveCommand<L, B>, B extends LiveCommandAnswerBuilder> LiveCom
      * To be called after runtime type check of the live command.
      *
      * @param liveCommand the live command.
+     * @param signalPublisher the signal publisher.
      * @return the result of calling the command handler on the command.
      */
     default LiveCommandAnswerBuilder.BuildStep castAndApply(final LiveCommand<?, ?> liveCommand,

java/src/main/java/org/eclipse/ditto/client/live/events/EventEmitter.java

@@ -30,6 +30,7 @@ public interface EventEmitter<F extends EventFactory> {
      *
      * @param eventFunction Function providing a EventFactory and requiring a Event as result.
      * @throws NullPointerException if {@code eventFunction} is {@code null}.
+     * @throws org.eclipse.ditto.client.management.ClientReconnectingException if the client is reconnecting.
      */
     void emitEvent(Function<F, Event<?>> eventFunction);