Bunch of minor JavaDoc fixes

Bunch of minor JavaDoc fixes

#2021

messaging/src/main/java/org/axonframework/common/StringUtils.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.common;
 
 import java.util.Objects;
@@ -18,7 +34,7 @@ private StringUtils() {
 
     /**
      * Validate whether the given {@link String} {@code s} is not {@code null} and not empty (where empty is defined as
-     * {@code ""}.
+     * {@code ""}).
      *
      * @param s the {@link String} to validate whether it is not {@code null} and not empty
      * @return {@code true} if the given {@link String} {@code s} is not {@code null} and not empty, {@code false}
@@ -42,7 +58,7 @@ public static boolean emptyOrNull(String s) {
 
     /**
      * Validate whether the given {@link String} {@code s} not empty (where empty is defined as
-     * {@code ""}.
+     * {@code ""}).
      *
      * @param s the {@link String} to validate whether not empty
      * @return {@code true} if the given {@link String} {@code s} is not empty, {@code false}

messaging/src/main/java/org/axonframework/messaging/deadletter/Decisions.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
@@ -16,10 +32,10 @@
 public abstract class Decisions {
 
     /**
-     * Construct a {@link Ignore} defining that a {@link DeadLetter dead letter} should remain in the queue.
+     * Construct an {@link Ignore} defining that a {@link DeadLetter dead letter} should remain in the queue.
      *
-     * @param <M> The type of message contained in  the {@link DeadLetter} that's been made a decision on.
-     * @return A {@link Ignore} defining that a {@link DeadLetter dead letter} should remain in the queue.
+     * @param <M> The type of message contained in the {@link DeadLetter} that's been made a decision on.
+     * @return An {@link Ignore} defining that a {@link DeadLetter dead letter} should remain in the queue.
      */
     public static <M extends Message<?>> Ignore<M> ignore() {
         return new Ignore<>();
@@ -28,7 +44,7 @@ public static <M extends Message<?>> Ignore<M> ignore() {
     /**
      * Construct a {@link DoNotEnqueue} defining that a {@link DeadLetter dead letter} should not be enqueued at all.
      *
-     * @param <M> The type of message contained in  the {@link DeadLetter} that's been made a decision on.
+     * @param <M> The type of message contained in the {@link DeadLetter} that's been made a decision on.
      * @return A {@link DoNotEnqueue} defining that a {@link DeadLetter dead letter} should not be enqueued at all.
      */
     public static <M extends Message<?>> DoNotEnqueue<M> doNotEnqueue() {
@@ -39,7 +55,7 @@ public static <M extends Message<?>> DoNotEnqueue<M> doNotEnqueue() {
      * Construct a {@link DoNotEnqueue} defining that a {@link DeadLetter dead letter} should be evicted from the
      * queue.
      *
-     * @param <M> The type of message contained in  the {@link DeadLetter} that's been made a decision on.
+     * @param <M> The type of message contained in the {@link DeadLetter} that's been made a decision on.
      * @return A {@link DoNotEnqueue} defining that a {@link DeadLetter dead letter} should be evicted from the queue.
      */
     public static <M extends Message<?>> DoNotEnqueue<M> evict() {
@@ -49,7 +65,7 @@ public static <M extends Message<?>> DoNotEnqueue<M> evict() {
     /**
      * Construct a {@link ShouldEnqueue} defining that a {@link DeadLetter dead letter} should be enqueued.
      *
-     * @param <M> The type of message contained in  the {@link DeadLetter} that's been made a decision on.
+     * @param <M> The type of message contained in the {@link DeadLetter} that's been made a decision on.
      * @return A {@link ShouldEnqueue} defining that a {@link DeadLetter dead letter} should be enqueued.
      */
     public static <M extends Message<?>> ShouldEnqueue<M> enqueue() {
@@ -61,7 +77,7 @@ public static <M extends Message<?>> ShouldEnqueue<M> enqueue() {
      * the given {@code enqueueCause}.
      *
      * @param enqueueCause The reason for enqueueing a {@link DeadLetter dead letter}.
-     * @param <M>          The type of message contained in  the {@link DeadLetter} that's been made a decision on.
+     * @param <M>          The type of message contained in the {@link DeadLetter} that's been made a decision on.
      * @return A {@link ShouldEnqueue} defining that a {@link DeadLetter dead letter} should be enqueued because of the
      * given {@code enqueueCause}.
      */
@@ -76,7 +92,7 @@ public static <M extends Message<?>> ShouldEnqueue<M> enqueue(Throwable enqueueC
      *
      * @param enqueueCause       The reason for enqueueing a {@link DeadLetter dead letter}.
      * @param diagnosticsBuilder A builder of {@link DeadLetter#diagnostics() diagnostic} {@link MetaData}.
-     * @param <M>                The type of message contained in  the {@link DeadLetter} that's been made a decision
+     * @param <M>                The type of message contained in the {@link DeadLetter} that's been made a decision
      *                           on.
      * @return A {@link ShouldEnqueue} defining that a {@link DeadLetter dead letter} should be enqueued because of the
      * given {@code enqueueCause}.
@@ -93,7 +109,7 @@ public static <M extends Message<?>> ShouldEnqueue<M> enqueue(
      * the given {@code requeueCause}.
      *
      * @param requeueCause The reason for requeueing a {@link DeadLetter dead letter}.
-     * @param <M>          The type of message contained in  the {@link DeadLetter} that's been made a decision on.
+     * @param <M>          The type of message contained in the {@link DeadLetter} that's been made a decision on.
      * @return A {@link ShouldEnqueue} defining that a {@link DeadLetter dead letter} should be requeued because of the
      * given {@code requeueCause}.
      */
@@ -108,7 +124,7 @@ public static <M extends Message<?>> ShouldEnqueue<M> requeue(Throwable requeueC
      *
      * @param requeueCause       The reason for requeueing a {@link DeadLetter dead letter}.
      * @param diagnosticsBuilder A builder of {@link DeadLetter#diagnostics() diagnostic} {@link MetaData}.
-     * @param <M>                The type of message contained in  the {@link DeadLetter} that's been made a decision
+     * @param <M>                The type of message contained in the {@link DeadLetter} that's been made a decision
      *                           on.
      * @return A {@link ShouldEnqueue} defining that a {@link DeadLetter dead letter} should be requeued because of the
      * given {@code requeueCause}.

messaging/src/main/java/org/axonframework/messaging/deadletter/DoNotEnqueue.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
@@ -7,8 +23,7 @@
 /**
  * An {@link EnqueueDecision} stating a {@link DeadLetter dead letter} should not be enqueued.
  *
- * @param <M> An implementation of {@link Message} contained in the {@link DeadLetter dead letter} that's been made a
- *            decision on.
+ * @param <M> An implementation of {@link Message} contained in the {@link DeadLetter dead letter} that is decided on.
  * @author Steven van Beelen
  * @since 4.6.0
  */

messaging/src/main/java/org/axonframework/messaging/deadletter/EnqueueDecision.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
@@ -8,10 +24,13 @@
  * A contract towards describing a decision among a {@link DeadLetter dead letter} containing a message of type
  * {@code M}.
  * <p>
- * Describes that the letter should be {@link #shouldEnqueue() enqueued} or evicted. If the letter should be enqueued
- * the {@link #enqueueCause()} may contain a {@link Throwable}. Furthermore, {@link #withDiagnostics(DeadLetter)} may add
+ * Describes that the letter should be {@link #shouldEnqueue() enqueued} or not. If the letter should be enqueued the
+ * {@link #enqueueCause()} may contain a {@link Throwable}. Furthermore, {@link #withDiagnostics(DeadLetter)} may add
  * {@link DeadLetter#diagnostics() diagnostic} information to the dead letter that should be taken into account when
  * enqueueing the letter.
+ * <p>
+ * If {@link #shouldEnqueue()} returns {@code false}, that means the dead letter will not be inserted in the queue to
+ * begin with, or it will be {@link SequencedDeadLetterQueue#evict(DeadLetter) evicted} from the dead-letter queue.
  *
  * @param <M> An implementation of {@link Message} contained in the {@link DeadLetter dead letter} that's been made a
  *            decision on.

messaging/src/main/java/org/axonframework/messaging/deadletter/EnqueuePolicy.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
@@ -6,9 +22,11 @@
  * A functional interface constructing an {@link EnqueueDecision} based on a {@link DeadLetter dead letter} and
  * {@link Throwable cause}. Should be used by components that insert dead letters into and processes dead letters from a
  * {@link SequencedDeadLetterQueue}.
+ * <p>
+ * Implementers of a policy can use {@link Decisions} to construct the basic types of {@code EnqueueDecision}.
  *
  * @param <M> An implementation of {@link Message} contained in the {@link DeadLetter dead letter} that will be decided
- *            on.
+ *            on through this policy.
  * @author Steven van Beelen
  * @see Decisions
  * @since 4.6.0

messaging/src/main/java/org/axonframework/messaging/deadletter/GenericDeadLetter.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
@@ -11,7 +27,8 @@
 import javax.annotation.Nonnull;
 
 /**
- * Generic implementation of the {@link DeadLetter} allowing any type of {@link Message} to be dead lettered.
+ * Generic implementation of the {@link DeadLetter dead letter} allowing any type of {@link Message} to be dead
+ * lettered.
  *
  * @author Steven van Beelen
  * @author Mitchell Herrijgers

messaging/src/main/java/org/axonframework/messaging/deadletter/Ignore.java

@@ -1,12 +1,30 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
 
 import java.util.Optional;
 
 /**
- * An {@link EnqueueDecision} stating a {@link DeadLetter dead letter} should be ignored. This typically means that a
- * dead letter remains in the queue.
+ * An {@link EnqueueDecision} stating a {@link DeadLetter dead letter} should be ignored.
+ * <p>
+ * This means the decision can be ignored entirely. As such the component enqueueing a letter will decide what to do
+ * with it. In most scenarios this result in enqueueing the given {@code letter}, or keeping it in the queue.
  *
  * @param <M> An implementation of {@link Message} contained in the {@link DeadLetter dead letter} that's been made a
  *            decision on.

messaging/src/main/java/org/axonframework/messaging/deadletter/NoSuchDeadLetterException.java

@@ -1,9 +1,25 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.common.AxonException;
 
 /**
- * An {@link AxonException} describing that there is no such {@link DeadLetter} present in a
+ * An {@link AxonException} describing that there is no such {@link DeadLetter dead letter} present in a
  * {@link SequencedDeadLetterQueue}.
  *
  * @author Steven van Beelen

messaging/src/main/java/org/axonframework/messaging/deadletter/SequencedDeadLetterProcessor.java

@@ -1,3 +1,19 @@
+/*
+ * Copyright (c) 2010-2022. Axon Framework
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
 package org.axonframework.messaging.deadletter;
 
 import org.axonframework.messaging.Message;
@@ -7,8 +23,8 @@
 /**
  * Contract describing a component that can process {@link DeadLetter dead letters} that it has enqueued.
  * <p>
- * Should use the {@link SequencedDeadLetterQueue} as this ensures dead lettered {@link Message Messages} are kept in
- * sequence. Thus processed in order through this component.
+ * Should use the {@link SequencedDeadLetterQueue} for processing as this ensures dead lettered {@link Message Messages}
+ * are kept in sequence. Thus processed in order through this component.
  *
  * @param <M> An implementation of {@link Message} contained in the processed {@link DeadLetter dead letters}.
  * @author Steven van Beelen