Merge pull request microprofile#53 from eclipse/features/javadoc-impr…

…ovements-for-rc2

Small improvements in the Javadoc

api/pom.xml

@@ -75,6 +75,16 @@
                         </goals>
                     </execution>
                 </executions>
+                <configuration>
+                    <detectJavaApiLink>true</detectJavaApiLink>
+                    <detectOfflineLinks>true</detectOfflineLinks>
+                    <links>
+                        <link>https://docs.jboss.org/cdi/api/${cdi-api.version}/</link>
+                        <link>https://download.eclipse.org/microprofile/microprofile-reactive-streams-operators-${microprofile.reactive.streams.operators.version}/apidocs/</link>
+                        <link>https://download.eclipse.org/microprofile/microprofile-config-${microprofile-config-api.version}/apidocs/</link>
+                        <link>https://osgi.org/javadoc/r6/annotation/</link>
+                    </links>
+                </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>

api/src/main/java/org/eclipse/microprofile/reactive/messaging/Acknowledgment.java

@@ -24,45 +24,15 @@
 /**
  * Configure the acknowledgement policy for the given {@code @Incoming}.
  *
- * The set of supported acknowledgment policy depends on the method signature. The given list indicates the supported
- * policies for each type of signature:
+ * The set of supported acknowledgment policies depends on the method signature. The following list gives the supported
+ * strategies for some common use cases.
+ * Please refer to the specification for the full list.
  *
  * <ul>
- *     <li><code>@Incoming Subscriber&lt;Message&lt;I&gt;&gt; method()</code>: None, Pre, Manual</li>
- *     <li><code>@Incoming Subscriber&lt;I&gt; method()</code>: None, Pre, Post</li>
- *     <li><code>@Incoming void method(I msg)</code>: None, Pre, Post</li>
- *     <li><code>@Incoming CompletionStage&lt;?&gt; method(Message&lt;I&gt; msg)</code>: None, Pre, Post, Manual</li>
- *     <li><code>@Incoming CompletionStage&lt;?&gt; method(I msg)</code>: None, Pre, Post</li>
- *
- *     <li><code>@Outgoing @Incoming Processor&lt;Message&lt;I&gt;, Message&lt;O&gt;&gt; method()</code>: None, Pre,
- *     Manual, Post with the assumption that each incoming message produces a single outgoing message</li>
- *     <li><code>@Outgoing @Incoming Processor&lt;I, O&gt; method()</code>: None, Pre, Post with the assumption
- *     that each incoming payload produces a single outgoing payload</li>
- *     <li><code>@Outgoing @Incoming ProcessorBuilder&lt;Message&lt;I&gt;, Message&lt;O&gt;&gt; method()</code>: None,
- *     Manual, Pre, Post with the assumption that each incoming message produces a single outgoing message</li>
- *     <li><code>@Outgoing @Incoming ProcessorBuilder&lt;I, O&gt; method()</code>: None, Manual, Pre, Post with the
- *     assumption that each incoming payload produces a single outgoing payload</li>
- *
- *     <li><code>@Outgoing @Incoming Publisher&lt;Message&lt;O&gt;&gt; method(Message&lt;I&gt; msg)</code>: None,
- *     Manual,Pre</li>
- *     <li><code>@Outgoing @Incoming Publisher&lt;O&gt; method(I payload)</code>: None, Pre</li>
- *     <li><code>@Outgoing @Incoming PublisherBuilder&lt;Message&lt;O&gt;&gt; method(Message&lt;I&gt; msg)</code>: None,
- *     Pre, Manual</li>
- *     <li><code>@Outgoing @Incoming PublisherBuilder&lt;O&gt; method(I payload)</code>: None, Pre</li>
- *
- *     <li><code>@Outgoing @Incoming Message&lt;O&gt; method(Message&lt;I&gt; msg)</code>: None, Manual, Pre, Post</li>
- *     <li><code>@Outgoing @Incoming O method(I payload)</code>: None, Pre, Post</li>
- *     <li><code>@Outgoing @Incoming CompletionStage&lt;Message&lt;O&gt;&gt; method(Message&lt;I&gt; msg)</code>: None,
- *     Manual, Pre, Post</li>
- *     <li><code>@Outgoing @Incoming CompletionStage&lt;O&gt; method(I msg)</code>: None, Pre, Post</li>
- *
- *     <li><code>@Outgoing @Incoming Publisher&lt;Message&lt;O&gt;&gt; method(Publisher&lt;Message&lt;I&gt;&gt; pub)
- *     </code>: None, Manual, Pre</li>
- *     <li><code>@Outgoing @Incoming Publisher&lt;O&gt; method(Publisher&lt;I&gt; pub)</code>: None, Pre</li>
- *     <li><code>@Outgoing @Incoming PublisherBuilder&lt;Message&lt;O&gt;&gt; method(PublisherBuilder&lt;Message&lt;I&gt;&gt; pub)
- *     </code>: None, Manual, Pre</li>
- *     <li><code>@Outgoing @Incoming PublisherBuilder&lt;O&gt; method(PublisherBuilder&lt;I&gt; pub)</code>: None, Pre
- *     </li>
+ *     <li><code> @Incoming("channel") void method(I payload)</code>: Post-processing (default), Pre-processing, None</li>
+ *     <li><code> @Incoming("channel") CompletionStage&lt;?&gt; method(I payload)</code>: Post-processing (default), Pre-processing, None</li>
+ *     <li><code> @Incoming("in") @Outgoing("out") Message&lt;O&gt; method(Message&lt;I&gt; msg)</code>: Pre-processing (default), None, Manual</li>
+ *     <li><code> @Incoming("in") @Outgoing("out") O method(I payload)</code>: Post-Processing (default), Pre-processing, None</li>
  * </ul>
  *
  */
@@ -87,10 +57,11 @@ enum Strategy {
     PRE_PROCESSING,
 
     /**
-     * Acknowledgment performed automatically after the user processing of the message.
+     * Acknowledgment performed automatically once the message has been processed.
+     * When {@code POST_PROCESSING} is used, the incoming message is acknowledged when the produced message is
+     * acknowledged.
      *
-     * Notice that this mode is not supported for all signatures. check the list above.
-     * When supported it's the default policy.
+     * Notice that this mode is not supported for all signatures. When supported, it's the default policy.
      *
      */
     POST_PROCESSING

api/src/main/java/org/eclipse/microprofile/reactive/messaging/spi/Connector.java

@@ -40,7 +40,7 @@
 public @interface Connector {
 
     /**
-     * @return the name of the connector associated with the bean implementing {@link IncomingConnectorFactory}
+     * @return The name of the connector associated with the bean implementing {@link IncomingConnectorFactory}
      * or {@link OutgoingConnectorFactory}. Must not be {@code null}. Returning {@code null} will cause a deployment
      * failure.
      */

api/src/main/java/org/eclipse/microprofile/reactive/messaging/spi/IncomingConnectorFactory.java

@@ -22,7 +22,6 @@
 import org.eclipse.microprofile.reactive.messaging.Message;
 import org.eclipse.microprofile.reactive.streams.operators.PublisherBuilder;
 
-import javax.enterprise.inject.spi.DeploymentException;
 import java.util.NoSuchElementException;
 
 /**
@@ -75,7 +74,7 @@
  * In the previous configuration, the reactive messaging implementation would need to find the
  * {@link IncomingConnectorFactory} qualified using the {@link Connector} qualifier with the value
  * {@code acme.kafka} class to create the {@code my-channel} channel. Note that if the
- * connector cannot be found, the deployment must be failed with a {@link DeploymentException}.
+ * connector cannot be found, the deployment must be failed with a {@link javax.enterprise.inject.spi.DeploymentException}.
  * <p>
  * The {@link #getPublisherBuilder(Config)} is called for every channel that needs to be created. The {@link Config} object
  * passed to the method contains a subset of the global configuration, and with the prefixes removed. So for the previous
@@ -94,7 +93,7 @@
  * <p>
  * If the configuration is invalid, the {@link #getPublisherBuilder(Config)} method must throw an
  * {@link IllegalArgumentException}, caught by the reactive messaging implementation and failing the deployment by
- * throwing a {@link DeploymentException} wrapping the exception.
+ * throwing a {@link javax.enterprise.inject.spi.DeploymentException} wrapping the exception.
  * <p>
  * Note that a Reactive Messaging implementation must support the configuration format described here. Implementations
  * are free to provide additional support for other approaches.

api/src/main/java/org/eclipse/microprofile/reactive/messaging/spi/OutgoingConnectorFactory.java

@@ -22,6 +22,7 @@
 import org.eclipse.microprofile.reactive.messaging.Message;
 import org.eclipse.microprofile.reactive.streams.operators.SubscriberBuilder;
 
+
 import java.util.NoSuchElementException;
 
 /**
@@ -72,8 +73,7 @@
  * In the previous configuration, the reactive messaging implementation would need to find the
  * {@link OutgoingConnectorFactory} implementation qualified with the {@link Connector} qualifier with the value
  * {@code acme.kafka} to create the {@code my-channel} <em>subscriber</em>. Note that if
- * the connector cannot be found, the deployment must be failed with a
- * {@link javax.enterprise.inject.spi.DeploymentException}.
+ * the connector cannot be found, the deployment must be failed with a {@link javax.enterprise.inject.spi.DeploymentException}.
  * <p>
  * The {@link #getSubscriberBuilder(Config)} is called for every <em>channel</em> that needs to be created. The
  * {@link Config} object passed to the method contains a subset of the global configuration, and with the prefixes removed.

api/src/main/java/org/eclipse/microprofile/reactive/messaging/spi/package-info.java

@@ -0,0 +1,43 @@
+/**
+ * Copyright (c) 2018-2019 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * 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.
+ */
+
+/**
+ * The MicroProfile Reactive Messaging API Connector SPI
+ * <p>
+ * This package provides the SPI to implement {@code connectors}. A {@code connector} can be seen as a Reactive Messaging
+ * plug-in to support a specific messaging technology. For example, you can have a Kafka connector to deal with Kafka,
+ * an AMQP connector to interact with AMQP brokers and routers and so on. Connector implementation should be
+ * agnostic to the Reactive Messaging implementation.
+ *
+ * A connector can be seen as:
+ * <ul>
+ *     <li>a source of messages - it retrieves messages and injects them into the Reactive Messaging application. To
+ *     manage this direction, the connector implementation must implement the
+ *     {@link org.eclipse.microprofile.reactive.messaging.spi.IncomingConnectorFactory} interface.</li>
+ *     <li>a sink of messages - it forwards messages emitted by the Reactive Messaging application to the managed
+ *     technology. To achieve this, the connector implementation must implement the
+ *     {@link org.eclipse.microprofile.reactive.messaging.spi.OutgoingConnectorFactory} interface.</li>
+ * </ul>
+ *
+ * Connectors are  implemented as CDI beans and identified using the
+ * {@link org.eclipse.microprofile.reactive.messaging.spi.Connector} qualifier. Connectors receive the channel
+ * configuration matching their {@link Connector} name.
+ */
+@org.osgi.annotation.versioning.Version("1.0")
+package org.eclipse.microprofile.reactive.messaging.spi;

pom.xml

@@ -47,6 +47,7 @@
         <!-- keeping closed repos with failure - default is false because the errors are visible in the maven output, but true will leave the repo open for investigation in Sonatype Nexus -->
         <keepStagingReposOnFailure>false</keepStagingReposOnFailure>
         <microprofile-config-api.version>1.3</microprofile-config-api.version>
+        <cdi-api.version>2.0</cdi-api.version>
     </properties>
 
     <licenses>
@@ -168,7 +169,7 @@
             <dependency>
                 <groupId>javax.enterprise</groupId>
                 <artifactId>cdi-api</artifactId>
-                <version>2.0</version>
+                <version>${cdi-api.version}</version>
             </dependency>
             <dependency>
                 <groupId>javax.json.bind</groupId>

spec/src/main/asciidoc/architecture.asciidoc

@@ -57,8 +57,8 @@ These channels are managed by _connectors_.
 ==== Message
 
 At the core of the Reactive Messaging specification is the concept of _message_. 
-A _message_  is an enveloppe wrapping a _payload_. 
-A message is sent to a specific channel and, when received and processed successfuly, _acknowledged_.
+A _message_  is an envelope wrapping a _payload_.
+A message is sent to a specific channel and, when received and processed successfully, _acknowledged_.
 
 Reactive Messaging application components are addressable recipients which await the arrival of messages on a channel and react to them, otherwise lying dormant. 
 
@@ -73,7 +73,7 @@ Note that the `ack` method is asynchronous as acknowledgement is generally an as
 _Plain_ messages are created using:
 
 * `org.eclipse.microprofile.reactive.messaging.Message#of(T)` - wraps the given payload, no acknowledgement
-* `org.eclipse.microprofile.reactive.messaging.Message#of(T, java.util.function.Supplier<java.util.concurrent.CompletionStage<java.lang.Void>>)` - wraps the given payload and provides the acknowlegment logic
+* `org.eclipse.microprofile.reactive.messaging.Message#of(T, java.util.function.Supplier<java.util.concurrent.CompletionStage<java.lang.Void>>)` - wraps the given payload and provides the acknowledgment logic
 
 ==== Message consumption with @Incoming
 
@@ -163,7 +163,7 @@ This mapping is configured in the application configuration.
 Note that an implementation may provide various ways to configure the mapping, but support for MicroProfile Config as a configuration source is mandatory.
 
 Connector implementations are associated with a name corresponding to a messaging transport, such as Apache Kafka, Amazon Kinesis, RabbitMQ or Apache ActiveMQ.
-For instance, an hypothetic Kafka connector could be associated with the following name: `acme.kafka`.
+For instance, an hypothetical Kafka connector could be associated with the following name: `acme.kafka`.
 This name is indicated using a qualifier on the connector implementation.
 
 The user can associate a channel with this connector using the associated name: