fix javadocs so release plugin can perform the release successfully

hawkular · May 19, 2015 · 0d7c89f · 0d7c89f
1 parent aec2b2f
commit 0d7c89f
Show file tree

Hide file tree

Showing 8 changed files with 78 additions and 87 deletions.
diff --git a/hawkular-bus-common/pom.xml b/hawkular-bus-common/pom.xml
@@ -59,6 +59,19 @@
       <scope>provided</scope>
     </dependency>
 
+    <!-- To avoid javadoc errors (and thus causing mvn release plugin to fail) we need this provided dependency.
+         Google Guava uses com.google.common.util.concurrent.ExecutionList which is annotated with @GuardedBy.
+         Without this dep to give us that annotation class, we get this error:
+            Cannot find annotation method 'value()' in type 'GuardedBy':
+            class file for javax.annotation.concurrent.GuardedBy not found
+    -->
+    <dependency>
+      <groupId>com.google.code.findbugs</groupId>
+      <artifactId>jsr305</artifactId>
+      <version>1.3.8</version>
+      <scope>provided</scope>
+    </dependency>
+
     <dependency>
       <groupId>com.google.code.gson</groupId>
       <artifactId>gson</artifactId>

diff --git a/hawkular-bus-common/src/main/java/org/hawkular/bus/common/ConnectionContextFactory.java b/hawkular-bus-common/src/main/java/org/hawkular/bus/common/ConnectionContextFactory.java
@@ -53,11 +53,10 @@ public class ConnectionContextFactory implements AutoCloseable {
     /**
      * Initializes the factory with the given broker URL.
      *
-     * @param brokerURL
-     *            the broker that is used for the contexts created by this factory - all messages sent and received
-     *            through the contexts will go through this broker.
+     * @param brokerURL the broker that is used for the contexts created by this factory;
+     *                  all messages sent and received through the contexts will go through this broker.
      *
-     * @throws JMSException
+     * @throws JMSException any error
      */
     public ConnectionContextFactory(String brokerURL) throws JMSException {
         connectionFactory = new ActiveMQConnectionFactory(brokerURL);
@@ -67,13 +66,12 @@ public ConnectionContextFactory(String brokerURL) throws JMSException {
     /**
      * Initializes the factory with the given broker URL and the given security credentials.
      *
-     * @param brokerURL
-     *            the broker that is used for the contexts created by this factory - all messages sent and received
-     *            through the contexts will go through this broker.
-     * @param username
-     * @param password
+     * @param brokerURL the broker that is used for the contexts created by this factory;
+     *                  all messages sent and received through the contexts will go through this broker.
+     * @param username user to connect to
+     * @param password credentials of user
      *
-     * @throws JMSException
+     * @throws JMSException any error
      */
     public ConnectionContextFactory(String brokerURL, String username, String password) throws JMSException {
         connectionFactory = new ActiveMQConnectionFactory(username, password, brokerURL);
@@ -84,10 +82,9 @@ public ConnectionContextFactory(String brokerURL, String username, String passwo
     /**
      * Initializes with the given factory.
      *
-     * @param connectionFactory
-     *            the factory that will be used to create contexts.
+     * @param connectionFactory the factory that will be used to create contexts.
      *
-     * @throws JMSException
+     * @throws JMSException any error
      */
     public ConnectionContextFactory(ConnectionFactory connectionFactory) throws JMSException {
         this.connectionFactory = connectionFactory;
@@ -99,10 +96,9 @@ public ConnectionContextFactory(ConnectionFactory connectionFactory) throws JMSE
      * Creates a new producer connection context, reusing any existing connection that might have already been created.
      * The destination of the connection's session will be that of the given endpoint.
      *
-     * @param endpoint
-     *            where the producer will send messages
+     * @param endpoint where the producer will send messages
      * @return the new producer connection context fully populated
-     * @throws JMSException
+     * @throws JMSException any error
      */
     public ProducerConnectionContext createProducerConnectionContext(Endpoint endpoint) throws JMSException {
         ProducerConnectionContext context = new ProducerConnectionContext();
@@ -117,27 +113,24 @@ public ProducerConnectionContext createProducerConnectionContext(Endpoint endpoi
      * Creates a new consumer connection context, reusing any existing connection that might have already been created.
      * The destination of the connection's session will be that of the given endpoint.
      *
-     * @param endpoint
-     *            where the consumer will listen for messages
+     * @param endpoint where the consumer will listen for messages
      * @return the new consumer connection context fully populated
-     * @throws JMSException
+     * @throws JMSException any error
      */
     public ConsumerConnectionContext createConsumerConnectionContext(Endpoint endpoint) throws JMSException {
         return createConsumerConnectionContext(endpoint, null);
     }
 
     /**
-     * Creates a new consumer connection context, reusing any existing connection that might have already been created.
-     * The destination of the connection's session will be that of the given endpoint. The consumer will filter messages
-     * based on the given message selector expression (which may be null in which case the consumer will consume all
-     * messages).
+     * Creates a new consumer connection context, reusing any existing connection that might have
+     * already been created. The destination of the connection's session will be that of the given endpoint.
+     * The consumer will filter messages based on the given message selector expression (which may be
+     * null in which case the consumer will consume all messages).
      *
-     * @param endpoint
-     *            where the consumer will listen for messages
-     * @param messageSelector
-     *            message consumer's message selector expression.
+     * @param endpoint where the consumer will listen for messages
+     * @param messageSelector message consumer's message selector expression.
      * @return the new consumer connection context fully populated
-     * @throws JMSException
+     * @throws JMSException any error
      */
     public ConsumerConnectionContext createConsumerConnectionContext(Endpoint endpoint, String messageSelector)
             throws JMSException {
@@ -150,10 +143,11 @@ public ConsumerConnectionContext createConsumerConnectionContext(Endpoint endpoi
     }
 
     /**
-     * This method should be called when this context factory is no longer needed. This will free up resources and close
-     * any open connections it has cached. Note this will invalidate contexts created by this factory.
+     * This method should be called when this context factory is no longer needed. This will free up
+     * resources and close any open connections it has cached.
+     * Note this will invalidate contexts created by this factory.
      *
-     * @throws JMSException
+     * @throws JMSException any error
      */
     @Override
     public void close() throws JMSException {
@@ -191,7 +185,7 @@ protected Connection getConnection() {
      * connection via this method if you want that connection cached here. See
      * also {@link #createOrReuseConnection(ConnectionContext, boolean)}.
      *
-     * @param connection
+     * @param connection the connection
      *
      * @see #createOrReuseConnection(ConnectionContext, boolean)
      */
@@ -217,11 +211,9 @@ protected void setConnection(Connection connection) {
      * is created or reused, that connection will be stored in the given
      * context.
      *
-     * @param context
-     *            the connection will be stored in this context
-     * @param start
-     *            if true, the created connection will be started.
-     * @throws JMSException
+     * @param context the connection will be stored in this context
+     * @param start if true, the created connection will be started.
+     * @throws JMSException any error
      */
     protected void createOrReuseConnection(ConnectionContext context, boolean start) throws JMSException {
         Connection conn = getConnection();
@@ -256,13 +248,11 @@ protected void createOrReuseConnection(ConnectionContext context, boolean start)
      * If the caller wants the created connection cached in this processor
      * object, {@link #setConnection(Connection)} must be passed the connection
      * found in the context after this method returns. See also
-     * {@link #createOrReuseConnection(ConnectionContext, boolean).
+     * {@link #createOrReuseConnection(ConnectionContext, boolean)}.
      *
-     * @param context
-     *            the context where the new connection is stored
-     * @throws JMSException
-     * @throws IllegalStateException
-     *             if the context is null
+     * @param context the context where the new connection is stored
+     * @throws JMSException any error
+     * @throws IllegalStateException if the context is null
      *
      * @see #createOrReuseConnection(ConnectionContext, boolean)
      * @see #setConnection(Connection)
@@ -280,11 +270,9 @@ protected void createConnection(ConnectionContext context) throws JMSException {
      * Creates a default session using the context's connection. This implementation creates a non-transacted,
      * auto-acknowledged session. Subclasses are free to override this behavior.
      *
-     * @param context
-     *            the context where the new session is stored
-     * @throws JMSException
-     * @throws IllegalStateException
-     *             if the context is null or the context's connection is null
+     * @param context the context where the new session is stored
+     * @throws JMSException any error
+     * @throws IllegalStateException if the context is null or the context's connection is null
      */
     protected void createSession(ConnectionContext context) throws JMSException {
         if (context == null) {
@@ -301,13 +289,10 @@ protected void createSession(ConnectionContext context) throws JMSException {
     /**
      * Creates a destination using the context's session. The destination correlates to the given named queue or topic.
      *
-     * @param context
-     *            the context where the new destination is stored
-     * @param endpoint
-     *            identifies the queue or topic
-     * @throws JMSException
-     * @throws IllegalStateException
-     *             if the context is null or the context's session is null or endpoint is null
+     * @param context the context where the new destination is stored
+     * @param endpoint identifies the queue or topic
+     * @throws JMSException any error
+     * @throws IllegalStateException if the context is null or the context's session is null or endpoint is null
      */
     protected void createDestination(ConnectionContext context, Endpoint endpoint) throws JMSException {
         if (endpoint == null) {
@@ -340,11 +325,10 @@ protected void createDestination(ConnectionContext context, Endpoint endpoint) t
     /**
      * Creates a message producer using the context's session and destination.
      *
-     * @param context
-     *            the context where the new producer is stored
-     * @throws JMSException
-     * @throws IllegalStateException
-     *             if the context is null or the context's session is null or the context's destination is null
+     * @param context the context where the new producer is stored
+     * @throws JMSException any error
+     * @throws IllegalStateException if the context is null or the context's session is null
+     *                               or the context's destination is null
      */
     protected void createProducer(ProducerConnectionContext context) throws JMSException {
         if (context == null) {
@@ -365,13 +349,11 @@ protected void createProducer(ProducerConnectionContext context) throws JMSExcep
     /**
      * Creates a message consumer using the context's session and destination.
      *
-     * @param context
-     *            the context where the new consumer is stored
-     * @param messageSelector
-     *            the message selector expression that the consumer will use to filter messages
-     * @throws JMSException
-     * @throws IllegalStateException
-     *             if the context is null or the context's session is null or the context's destination is null
+     * @param context the context where the new consumer is stored
+     * @param messageSelector the message selector expression that the consumer will use to filter messages
+     * @throws JMSException any error
+     * @throws IllegalStateException if the context is null or the context's session is null
+     *                               or the context's destination is null
      */
     protected void createConsumer(ConsumerConnectionContext context, String messageSelector) throws JMSException {
         if (context == null) {

diff --git a/hawkular-bus-common/src/main/java/org/hawkular/bus/common/Endpoint.java b/hawkular-bus-common/src/main/java/org/hawkular/bus/common/Endpoint.java
@@ -36,7 +36,7 @@ public enum Type {
     /**
      * An endpoint as specified in URI format: "type://name"
      *
-     * @param destination
+     * @param destination the endpoint
      * @throws IllegalArgumentException invalid or null destination string
      */
     public Endpoint(String destination) throws IllegalArgumentException {

diff --git a/hawkular-bus-common/src/main/java/org/hawkular/bus/common/MessageProcessor.java b/hawkular-bus-common/src/main/java/org/hawkular/bus/common/MessageProcessor.java
@@ -50,9 +50,9 @@ public class MessageProcessor {
      *
      * @param context information that determines where to listen
      * @param listener the listener that processes the incoming messages
-     * @throws JMSException
+     * @throws JMSException any error
      *
-     * @see {@link org.hawkular.bus.common.ConnectionContextFactory#createConsumerConnectionContext(Endpoint)}
+     * @see org.hawkular.bus.common.ConnectionContextFactory#createConsumerConnectionContext(Endpoint)
      */
     public <T extends BasicMessage> void listen(ConsumerConnectionContext context,
             AbstractBasicMessageListener<T> listener) throws JMSException {
@@ -89,9 +89,9 @@ public MessageId send(ProducerConnectionContext context, BasicMessage basicMessa
      * @param basicMessage the message to send with optional headers included
      * @param headers headers for the JMS transport that will override same-named headers in the basic message
      * @return the message ID
-     * @throws JMSException
+     * @throws JMSException any error
      *
-     * @see {@link ConnectionContextFactory#createProducerConnectionContext(Endpoint)}
+     * @see ConnectionContextFactory#createProducerConnectionContext(Endpoint)
      */
     public MessageId send(ProducerConnectionContext context, BasicMessage basicMessage, Map<String, String> headers)
             throws JMSException {
@@ -148,7 +148,7 @@ public <T extends BasicMessage> RPCConnectionContext sendAndListen(ProducerConne
      * expect multiple response messages.
      *
      * If the caller merely wants to wait for a single response and obtain the response message to process it further,
-     * consider using instead the method {@link #sendRPC(ProducerConnectionContext, BasicMessage)} and use its returned
+     * consider using instead the method {@link #sendRPC} and use its returned
      * Future to wait for the response, rather than having to supply your own response listener.
      *
      * @param context information that determines where the message is sent
@@ -157,12 +157,10 @@ public <T extends BasicMessage> RPCConnectionContext sendAndListen(ProducerConne
      *            its associated consumer when appropriate.
      * @param headers headers for the JMS transport that will override same-named headers in the basic message
      *
-     * @param T the expected basic message type that will be received as the response to the request
-     *
      * @return the RPC context which includes information about the handling of the expected response
-     * @throws JMSException
+     * @throws JMSException any error
      *
-     * @see {@link org.hawkular.bus.common.ConnectionContextFactory#createProducerConnectionContext(Endpoint)}
+     * @see org.hawkular.bus.common.ConnectionContextFactory#createProducerConnectionContext(Endpoint)
      */
     public <T extends BasicMessage> RPCConnectionContext sendAndListen(ProducerConnectionContext context,
             BasicMessage basicMessage, BasicMessageListener<T> responseListener, Map<String, String> headers)
@@ -247,12 +245,10 @@ public <R extends BasicMessage> ListenableFuture<R> sendRPC(ProducerConnectionCo
      * @param expectedResponseMessageClass this is the message class of the expected response object.
      * @param headers headers for the JMS transport that will override same-named headers in the basic message
      *
-     * @param R the expected basic message type that will be received as the response to the request
-     *
      * @return a future that allows you to wait for and get the response of the given response type
-     * @throws JMSException
+     * @throws JMSException any error
      *
-     * @see {@link org.hawkular.bus.common.ConnectionContextFactory#createProducerConnectionContext(Endpoint)}
+     * @see org.hawkular.bus.common.ConnectionContextFactory#createProducerConnectionContext(Endpoint)
      */
     public <R extends BasicMessage> ListenableFuture<R> sendRPC(ProducerConnectionContext context,
             BasicMessage basicMessage, Class<R> expectedResponseMessageClass, Map<String, String> headers)
@@ -278,7 +274,7 @@ protected Message createMessage(ConnectionContext context, BasicMessage basicMes
      *                     optional headers included
      * @param headers headers for the Message that will override same-named headers in the basic message
      * @return the message that can be produced
-     * @throws JMSException
+     * @throws JMSException any error
      * @throws NullPointerException if the context is null or the context's session is null
      */
     protected Message createMessage(ConnectionContext context, BasicMessage basicMessage, Map<String, String> headers)

diff --git a/hawkular-bus-common/src/main/java/org/hawkular/bus/common/consumer/BasicMessageListener.java b/hawkular-bus-common/src/main/java/org/hawkular/bus/common/consumer/BasicMessageListener.java
@@ -54,7 +54,7 @@ public void onMessage(Message message) {
     /**
      * Subclasses implement this method to process the received message.
      *
-     * @param message the message to process
+     * @param basicMessage the message to process
      */
     protected abstract void onBasicMessage(T basicMessage);
 }
diff --git a/...ar-bus-common/src/main/java/org/hawkular/bus/common/consumer/RPCBasicMessageListener.java b/...ar-bus-common/src/main/java/org/hawkular/bus/common/consumer/RPCBasicMessageListener.java
@@ -124,7 +124,7 @@ public void onMessage(Message message) {
     /**
      * Subclasses implement this method to process the received message.
      *
-     * @param message the message to process
+     * @param basicMessage the message to process
      * @return the response message - this will be forwarded to the sender of the request message
      */
     protected abstract U onBasicMessage(T basicMessage);

diff --git a/hawkular-bus-rest-client/src/main/java/org/hawkular/bus/restclient/RestClient.java b/hawkular-bus-rest-client/src/main/java/org/hawkular/bus/restclient/RestClient.java
@@ -53,7 +53,7 @@ public static enum Type {
     /**
      * Creates the sender with a default HTTP endpoint of the REST server.
      *
-     * @param host
+     * @param host the remote server
      * @param port if null or -1, no port will be specified in the URL
      * @throws RestClientException if the endpoint cannot be used to refer to queues or topics
      *                             or if one of the parameters consists of invalid URL syntax
@@ -66,7 +66,7 @@ public RestClient(String host, Integer port) throws RestClientException {
      * Creates the sender with a default endpoint of the REST server.
      *
      * @param protocol http or https
-     * @param host
+     * @param host the remote server
      * @param port if null or -1, no port will be specified in the URL
      * @throws RestClientException if the endpoint cannot be used to refer to queues or topics
      *                             or if one of the parameters consists of invalid URL syntax

diff --git a/hawkular-bus-test-common/src/main/java/org/hawkular/bus/common/test/SimpleTestListener.java b/hawkular-bus-test-common/src/main/java/org/hawkular/bus/common/test/SimpleTestListener.java
@@ -24,7 +24,7 @@
 
 /**
  * Simple test listener that allows you to wait for a message and when it comes in you can retrieve it. See
- * {@link #waitForMessage(long)} and {@link #getBasicMessage()}. This can retrieve multiple messages serially,
+ * {@link #waitForMessage(long)} and {@link #getReceivedMessage()}. This can retrieve multiple messages serially,
  * but if you don't retrieve a message before a new one comes in, the first message is lost.
  *
  * This class is not thread safe. Its purpose is just to fascilitate unit tests.