From 633368b15f8653317bbc667b63676a8ec8f9a461 Mon Sep 17 00:00:00 2001 From: Robert Gemmell Date: Fri, 8 Aug 2014 15:49:59 +0000 Subject: QPID-5980: continued javadoc fixups git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1616808 13f79535-47bb-0310-9956-ffa450edef68 --- .../qpid/client/AMQAuthenticationException.java | 9 +- .../java/org/apache/qpid/client/AMQConnection.java | 2 +- .../qpid/client/AMQNoConsumersException.java | 5 - .../apache/qpid/client/AMQNoRouteException.java | 5 - .../java/org/apache/qpid/client/AMQSession.java | 116 ++++++++++----------- .../qpid/client/AMQSessionDirtyException.java | 5 - .../main/java/org/apache/qpid/client/AMQTopic.java | 2 +- .../apache/qpid/client/BasicMessageConsumer.java | 7 +- .../java/org/apache/qpid/client/Closeable.java | 15 +-- .../org/apache/qpid/client/JMSAMQException.java | 5 - .../org/apache/qpid/client/RejectBehaviour.java | 2 +- .../org/apache/qpid/client/XAResourceImpl.java | 4 +- .../qpid/client/failover/FailoverException.java | 9 +- .../qpid/client/failover/FailoverHandler.java | 28 +++-- .../failover/FailoverProtectedOperation.java | 9 +- .../qpid/client/failover/FailoverRetrySupport.java | 30 +++--- .../apache/qpid/client/failover/FailoverState.java | 5 - .../qpid/client/failover/FailoverSupport.java | 9 +- .../qpid/client/protocol/AMQProtocolHandler.java | 39 +++---- .../qpid/client/protocol/AMQProtocolSession.java | 5 +- .../protocol/BlockingMethodFrameListener.java | 27 ++--- .../client/security/CallbackHandlerRegistry.java | 18 ++-- .../qpid/client/security/DynamicSaslRegistrar.java | 15 ++- .../apache/qpid/client/state/AMQStateManager.java | 14 +-- .../org/apache/qpid/client/state/StateWaiter.java | 4 +- .../org/apache/qpid/client/url/URLParser_0_10.java | 50 ++++----- .../apache/qpid/client/util/BlockingWaiter.java | 27 ++--- .../client/util/FlowControllingBlockingQueue.java | 8 +- .../java/org/apache/qpid/jms/ConnectionURL.java | 4 +- 29 files changed, 198 insertions(+), 280 deletions(-) (limited to 'qpid/java') diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQAuthenticationException.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQAuthenticationException.java index 6bae0166d1..67885777f0 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQAuthenticationException.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQAuthenticationException.java @@ -25,13 +25,8 @@ import org.apache.qpid.protocol.AMQConstant; /** * AMQAuthenticationException represents all failures to authenticate access to a broker. - * - *

- *
CRC Card
Responsibilities Collaborations - *
Represent failure to authenticate the client. - *
- * - * @todo Will this alwyas have the same status code, NOT_ALLOWED 530? Might set this up to always use that code. + *

+ * TODO Will this alwyas have the same status code, NOT_ALLOWED 530? Might set this up to always use that code. */ public class AMQAuthenticationException extends AMQException { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQConnection.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQConnection.java index 0dc5cc68c1..7d9dfcd600 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQConnection.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQConnection.java @@ -224,7 +224,7 @@ public class AMQConnection extends Closeable implements Connection, QueueConnect } /** - * @todo Some horrible stuff going on here with setting exceptions to be non-null to detect if an exception + * TODO Some horrible stuff going on here with setting exceptions to be non-null to detect if an exception * was thrown during the connection! Intention not clear. Use a flag anyway, not exceptions... Will fix soon. */ public AMQConnection(ConnectionURL connectionURL) throws AMQException diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoConsumersException.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoConsumersException.java index 08867b5de7..c50425c1a8 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoConsumersException.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoConsumersException.java @@ -25,11 +25,6 @@ import org.apache.qpid.protocol.AMQConstant; /** * AMQNoConsumersException indicates failure to pass an immediate message to a consumer. - * - *

- *
CRC Card
Responsibilities Collaborations - *
Represents failure to pass an immediate message to a consumer. - *
*/ public class AMQNoConsumersException extends AMQUndeliveredException { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoRouteException.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoRouteException.java index 42ed9c3df7..e5f780c203 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoRouteException.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQNoRouteException.java @@ -25,11 +25,6 @@ import org.apache.qpid.protocol.AMQConstant; /** * AMQNoRouteException indicates that a mandatory message could not be routed. - * - *

- *
CRC Card
Responsibilities Collaborations - *
Represents failure to route a mandatory message. - *
*/ public class AMQNoRouteException extends AMQUndeliveredException { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSession.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSession.java index 5723ce9b11..945645ccb1 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSession.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSession.java @@ -79,20 +79,15 @@ import org.apache.qpid.thread.Threading; import org.apache.qpid.transport.SessionException; import org.apache.qpid.transport.TransportException; -/** - *

- *
CRC Card
Responsibilities Collaborations - *
- *
- * - * @todo Different FailoverSupport implementation are needed on the same method call, in different situations. For +/* + * TODO Different FailoverSupport implementation are needed on the same method call, in different situations. For * example, when failing-over and reestablishing the bindings, the bind cannot be interrupted by a second * fail-over, if it fails with an exception, the fail-over process should also fail. When binding outside of * the fail-over process, the retry handler could be used to automatically retry the operation once the connection * has been reestablished. All fail-over protected operations should be placed in private methods, with * FailoverSupport passed in by the caller to provide the correct support for the calling context. Sometimes the * fail-over process sets a nowait flag and uses an async method call instead. - * @todo Two new objects created on every failover supported method call. Consider more efficient ways of doing this, + * TODO Two new objects created on every failover supported method call. Consider more efficient ways of doing this, * after looking at worse bottlenecks first. */ public abstract class AMQSession extends Closeable implements Session, QueueSession, TopicSession @@ -613,14 +608,14 @@ public abstract class AMQSessiontrue to acknowledge all messages up to and including the one specified by the * delivery tag, false to just acknowledge that message. * - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. */ public abstract void acknowledgeMessage(long deliveryTag, boolean multiple); /** * Binds the named queue, with the specified routing key, to the named exchange. - * - *

Note that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param queueName The name of the queue to bind. * @param routingKey The routing key to bind the queue with. @@ -628,8 +623,8 @@ public abstract class AMQSessionNote that this operation succeeds automatically if a fail-over interrupts the synchronous request to close + *

+ * Note that this operation succeeds automatically if a fail-over interrupts the synchronous request to close * the channel. This is because the channel is marked as closed before the request to close it is made, so the * fail-over should not re-open it. * * @param timeout The timeout in milliseconds to wait for the session close acknowledgement from the broker. * * @throws JMSException If the JMS provider fails to close the session due to some internal error. - * @todo Be aware of possible changes to parameter order as versions change. - * @todo Not certain about the logic of ignoring the failover exception, because the channel won't be + * TODO Be aware of possible changes to parameter order as versions change. + * TODO Not certain about the logic of ignoring the failover exception, because the channel won't be * re-opened. May need to examine this more carefully. - * @todo Note that taking the failover mutex doesn't prevent this operation being interrupted by a failover, + * TODO Note that taking the failover mutex doesn't prevent this operation being interrupted by a failover, * because the failover process sends the failover event before acquiring the mutex itself. */ public void close(long timeout) throws JMSException @@ -802,8 +797,8 @@ public abstract class AMQSessionIf the commit fails, because the commit itself is interrupted by a fail-over between requesting that the + *

+ * If the commit fails, because the commit itself is interrupted by a fail-over between requesting that the * commit be done, and receiving an acknowledgement that it has been done, then a JMSException will be thrown. * The client will be unable to determine whether or not the commit actually happened on the broker in this case. * @@ -1237,8 +1232,8 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param name The name of the queue to declare. * @param autoDelete @@ -1246,7 +1241,7 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param name The name of the queue to declare. * @param autoDelete @@ -1266,7 +1261,7 @@ public abstract class AMQSession arguments) throws AMQException @@ -1684,11 +1679,11 @@ public abstract class AMQSessionAll consumers deliver messages in a serial order. Acknowledging a received message automatically acknowledges + *

+ * All consumers deliver messages in a serial order. Acknowledging a received message automatically acknowledges * all messages that have been delivered to the client. - * - *

Restarting a session causes it to take the following actions: + *

+ * Restarting a session causes it to take the following actions: * *

    *
  • Stop message delivery.
    • @@ -1697,14 +1692,15 @@ public abstract class AMQSession *
* - *

If the recover operation is interrupted by a fail-over, between asking that the broker begin recovery and + *

+ * If the recover operation is interrupted by a fail-over, between asking that the broker begin recovery and * receiving acknowledgment that it has then a JMSException will be thrown. In this case it will not be possible * for the client to determine whether the broker is going to recover the session or not. * * @throws JMSException If the JMS provider fails to stop and restart message delivery due to some internal error. * Not that this does not necessarily mean that the recovery has failed, but simply that it is * not possible to tell if it has or not. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. * * Strategy for handling recover. * Flush any acks not yet sent. @@ -1806,15 +1802,15 @@ public abstract class AMQSessionIf the rollback fails, because the rollback itself is interrupted by a fail-over between requesting that the + *

+ * If the rollback fails, because the rollback itself is interrupted by a fail-over between requesting that the * rollback be done, and receiving an acknowledgement that it has been done, then a JMSException will be thrown. * The client will be unable to determine whether or not the rollback actually happened on the broker in this case. * * @throws JMSException If the JMS provider fails to rollback the transaction due to some internal error. This does * not mean that the rollback is known to have failed, merely that it is not known whether it * failed or not. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. */ public void rollback() throws JMSException { @@ -2120,8 +2116,8 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param exchangeName The exchange name to test for binding against. * @param queueName The queue name to check if bound. @@ -2130,7 +2126,7 @@ public abstract class AMQSessiontrue if the queue is bound to the exchange and routing key, false if not. * * @throws JMSException If the query fails for any reason. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. */ public abstract boolean isQueueBound(final AMQShortString exchangeName, final AMQShortString queueName, final AMQShortString routingKey) throws JMSException; @@ -2141,7 +2137,9 @@ public abstract class AMQSession The caller of this method must already hold the failover mutex. + * when the client has veoted resubscription. + *

+ * The caller of this method must already hold the failover mutex. */ void markClosed() { @@ -2296,7 +2294,7 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param amqd The destination to be checked * @@ -2685,8 +2683,8 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param name The name of the exchange to declare. * @param type The type of the exchange to declare. @@ -2695,7 +2693,7 @@ public abstract class AMQSessionNote that for queues but not topics the name is generated in the client rather than the server. This allows + *

+ * Note that for queues but not topics the name is generated in the client rather than the server. This allows * the name to be reused on failover if required. In general, the destination indicates whether it wants a name * generated or not. - * - *

Note that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * * @param amqd The destination to declare as a queue. @@ -2731,8 +2729,8 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param queueName The name of the queue to delete. * * @throws JMSException If the queue could not be deleted for any reason. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. */ protected void deleteQueue(final AMQShortString queueName) throws JMSException { @@ -2781,13 +2779,13 @@ public abstract class AMQSessionNote that this operation automatically retries in the event of fail-over. + *

+ * Note that this operation automatically retries in the event of fail-over. * * @param amqQueue The name of the temporary destination to delete. * * @throws JMSException If the queue could not be deleted for any reason. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. */ protected void deleteTemporaryDestination(final TemporaryDestination amqQueue) throws JMSException { @@ -3014,11 +3012,11 @@ public abstract class AMQSessiontrue indicates that the session should be suspended, false indicates that it + * @param suspend true indicates that the session should be suspended, false indicates that it * should be unsuspended. * * @throws AMQException If the session cannot be suspended for any reason. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Be aware of possible changes to parameter order as versions change. */ protected void suspendChannel(boolean suspend) throws AMQException // , FailoverException { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSessionDirtyException.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSessionDirtyException.java index a1b240ed54..a33d05f0c7 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSessionDirtyException.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQSessionDirtyException.java @@ -27,11 +27,6 @@ import org.apache.qpid.protocol.AMQConstant; * AMQSessionDirtyException represents all failures to send data on a transacted session that is * no longer in a state that the client expects. i.e. failover has occured so previously sent messages * will not be part of the transaction. - * - *

- *
CRC Card
Responsibilities Collaborations - *
Represent attempt to perform additional sends on a dirty session. - *
*/ public class AMQSessionDirtyException extends AMQException { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQTopic.java b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQTopic.java index d5724a2910..1a7b6bea80 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/AMQTopic.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/AMQTopic.java @@ -218,7 +218,7 @@ public class AMQTopic extends AMQDestination implements Topic * Override since the queue is always private and we must ensure it remains null. If not, * reuse of the topic when registering consumers will make all consumers listen on the same (private) queue rather * than getting their own (private) queue. - *

+ *

* This is relatively nasty but it is difficult to come up with a more elegant solution, given * the requirement in the case on AMQQueue and possibly other AMQDestination subclasses to * use the underlying queue name even where it is server generated. diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/BasicMessageConsumer.java b/qpid/java/client/src/main/java/org/apache/qpid/client/BasicMessageConsumer.java index 5086063a5a..01e89b78c1 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/BasicMessageConsumer.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/BasicMessageConsumer.java @@ -1024,8 +1024,11 @@ public abstract class BasicMessageConsumer extends Closeable implements Messa } /** - * Used in the blocking receive methods to receive a message from the Session thread.

Or to notify of errors - *

Argument true indicates we want strict FIFO semantics + * Used in the blocking receive methods to receive a message from the Session thread. + *

+ * Or to notify of errors. + *

+ * Argument true indicates we want strict FIFO semantics */ protected BlockingQueue getSynchronousQueue() { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/Closeable.java b/qpid/java/client/src/main/java/org/apache/qpid/client/Closeable.java index 2f7fbad30c..2a3eb40a07 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/Closeable.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/Closeable.java @@ -27,18 +27,11 @@ import java.util.concurrent.atomic.AtomicBoolean; /** * Captures the 'closed' state of an object, that is initially open, can be tested to see if it is closed, and provides * a 'close' method to close it. - * - *

- *
CRC Card
Responsibilities Collaborations - *
Mark an object as closed. - *
Check if an object is closed. - *
Raise a JMS exception if an object is closed. - *
- * - * @todo Might be better to make this an interface. This whole class doesn't really encapsulate a terribly neat + *

+ * TODO Might be better to make this an interface. This whole class doesn't really encapsulate a terribly neat * piece of re-usable functionality. A simple interface defining a close method would suffice. - * - * @todo The convenience method {@link #checkNotClosed} is not that helpfull, what if the caller wants to do something + *

+ * TODO The convenience method {@link #checkNotClosed} is not that helpfull, what if the caller wants to do something * other than throw an exception? It doesn't really represent a very usefull re-usable piece of code. Consider * inlining it and dropping the method. */ diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/JMSAMQException.java b/qpid/java/client/src/main/java/org/apache/qpid/client/JMSAMQException.java index 1151a97cf4..8bb88a273e 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/JMSAMQException.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/JMSAMQException.java @@ -28,11 +28,6 @@ import javax.jms.JMSException; * JMSException does not accept wrapped exceptions in its constructor. Presumably this is because it is a relatively old * Java exception class, before this was added as a default to Throwable. This exception class accepts wrapped exceptions * as well as error messages, through its constructor, but is a JMSException. - * - *

- *
CRC Card
Responsibilities Collaborations - *
Accept wrapped exceptions as a JMSException. - *
*/ public class JMSAMQException extends JMSException { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/RejectBehaviour.java b/qpid/java/client/src/main/java/org/apache/qpid/client/RejectBehaviour.java index e3c958044e..e58a356bdc 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/RejectBehaviour.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/RejectBehaviour.java @@ -23,7 +23,7 @@ package org.apache.qpid.client; /** * This enum can be used only with for 0-8/0-9/0-9-1 protocols connections to notify * the client to delegate the requeue/DLQ decision to the server - * if SERVER value is specified. Otherwise the messages won't be moved to + * if SERVER value is specified. Otherwise the messages won't be moved to * the DLQ (or dropped) when delivery count exceeds the maximum. */ public enum RejectBehaviour diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/XAResourceImpl.java b/qpid/java/client/src/main/java/org/apache/qpid/client/XAResourceImpl.java index 6c745feea8..7e82981ad3 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/XAResourceImpl.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/XAResourceImpl.java @@ -121,7 +121,7 @@ public class XAResourceImpl implements AMQXAResource * The transaction context is in a suspended state and must be resumed via the start method with TMRESUME specified. *

  • If TMFAIL is specified, the portion of work has failed. The resource manager may mark the transaction as rollback-only *
  • If TMSUCCESS is specified, the portion of work has completed successfully. - * /ul> + * * * @param xid A global transaction identifier that is the same as the identifier used previously in the start method * @param flag One of TMSUCCESS, TMFAIL, or TMSUSPEND. @@ -312,7 +312,7 @@ public class XAResourceImpl implements AMQXAResource /** * Obtains a list of prepared transaction branches. - *

    + *

    * The transaction manager calls this method during recovery to obtain the list of transaction branches * that are currently in prepared or heuristically completed states. * diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverException.java b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverException.java index 037b0dc2d1..31a2868c13 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverException.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverException.java @@ -24,13 +24,8 @@ package org.apache.qpid.client.failover; * FailoverException is used to indicate that a synchronous request has failed to receive the reply that it is waiting * for because the fail-over process has been started whilst it was waiting for its reply. Synchronous methods generally * raise this exception to indicate that they must be re-tried once the fail-over process has completed. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Used to indicate failure of a synchronous request due to fail-over. - *
    - * - * @todo This exception is created and passed as an argument to a method, rather than thrown. The exception is being + *

    + * TODO This exception is created and passed as an argument to a method, rather than thrown. The exception is being * used to represent an event, passed out to other threads. Use of exceptions as arguments rather than as * exceptions is extremly confusing. Ideally use a condition or set a flag and check it instead. * This exceptions-as-events pattern seems to be in a similar style to Mina code, which is not pretty, but diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverHandler.java b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverHandler.java index 4099da18d2..315e3c4a3f 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverHandler.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverHandler.java @@ -36,13 +36,13 @@ import java.util.concurrent.CountDownLatch; * connections, failing over to a new connection if the transport connection fails. The procedure to establish a new * connection is expressed as a continuation, in order that it may be run in a seperate thread to the i/o thread that * detected the failure and is used to handle the communication to establish a new connection. - * - *

    The reason this needs to be a separate thread is because this work cannot be done inside the i/o processor + *

    + * The reason this needs to be a separate thread is because this work cannot be done inside the i/o processor * thread. The significant task is the connection setup which involves a protocol exchange until a particular state * is achieved. This procedure waits until the state is achieved which would prevent the i/o thread doing the work * it needs to do to achieve the new state. - * - *

    The failover procedure does the following: + *

    + * The failover procedure does the following: * *

      *
    1. Sets the failing over condition to true.
      2. @@ -57,21 +57,17 @@ import java.util.concurrent.CountDownLatch; *
    2. Resets the failing over condition and releases the mutex.
      3. *
    * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Update fail-over state {@link AMQProtocolHandler} - *
    - * - * @todo The failover latch and mutex are used like a lock and condition. If the retrotranlator supports lock/condition + *

    + * TODO The failover latch and mutex are used like a lock and condition. If the retrotranlator supports lock/condition * then could change over to using them. 1.4 support still needed. - * - * @todo If the condition is set to null on a vetoes fail-over and there are already other threads waiting on the + *

    + * TODO If the condition is set to null on a vetoes fail-over and there are already other threads waiting on the * condition, they will never be released. It might be an idea to reset the condition in a finally block. - * - * @todo Creates a {@link AMQDisconnectedException} and passes it to the AMQConnection. No need to use an + *

    + * TODO Creates a {@link AMQDisconnectedException} and passes it to the AMQConnection. No need to use an * exception-as-argument here, could just as easily call a specific method for this purpose on AMQConnection. - * - * @todo Creates a {@link FailoverException} and propagates it to the MethodHandlers. No need to use an + *

    + * TODO Creates a {@link FailoverException} and propagates it to the MethodHandlers. No need to use an * exception-as-argument here, could just as easily call a specific method for this purpose on * {@link org.apache.qpid.protocol.AMQMethodListener}. */ diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverProtectedOperation.java b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverProtectedOperation.java index e9c5f24791..d7e4128183 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverProtectedOperation.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverProtectedOperation.java @@ -25,16 +25,11 @@ package org.apache.qpid.client.failover; * FailoverProtectedOperation is a continuation for an operation that may throw a {@link FailoverException} because * it has been interrupted by the fail-over process. The {@link FailoverRetrySupport} class defines support wrappers * for failover protected operations, in order to provide different handling schemes when failovers occurr. - * - *

    The type of checked exception that the operation may perform has been generified, in order that fail over + *

    + * The type of checked exception that the operation may perform has been generified, in order that fail over * protected operations can be defined that raise arbitrary exceptions. The actuall exception types used should not * be sub-classes of FailoverException, or else catching FailoverException in the {@link FailoverRetrySupport} classes * will mask the exception. - * - *

    - *
    CRC Card
    Responsibilities - *
    Perform an operation that may be interrupted by fail-over. - *
    */ public interface FailoverProtectedOperation { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverRetrySupport.java b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverRetrySupport.java index d3d33d3c75..ffe0baecd8 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverRetrySupport.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverRetrySupport.java @@ -32,40 +32,34 @@ import org.apache.qpid.client.AMQConnection; * FailoverRetrySupport automatcally rechecks the condition and re-acquires the mutex and re-runs the continution. This * automatic retrying is continued until the continuation succeeds, or throws an exception (different to * FailoverException, which is used to signal the failure of the original condition). - * - *

    The blocking condition used is that the connection is not currently failing over, and the mutex used is the + *

    + * The blocking condition used is that the connection is not currently failing over, and the mutex used is the * connection failover mutex, which guards against the fail-over process being run during fail-over vulnerable methods. * These are used like a lock and condition variable. - * - *

    The wrapped operation may throw a FailoverException, this is an exception that can be raised by a + *

    + * The wrapped operation may throw a FailoverException, this is an exception that can be raised by a * {@link org.apache.qpid.client.protocol.BlockingMethodFrameListener}, in response to it being notified that a * fail-over wants to start whilst it was waiting. Methods that are vulnerable to fail-over are those that are * synchronous, where a failure will prevent them from getting the reply they are waiting for and asynchronous * methods that should not be attempted when a fail-over is in progress. - * - *

    Wrapping a synchronous method in a FailoverRetrySupport will have the effect that the operation will not be + *

    + * Wrapping a synchronous method in a FailoverRetrySupport will have the effect that the operation will not be * started during fail-over, but be delayed until any current fail-over has completed. Should a fail-over process want * to start whilst waiting for the synchrnous reply, the FailoverRetrySupport will detect this and rety the operation * until it succeeds. Synchronous methods are usually coordinated with a * {@link org.apache.qpid.client.protocol.BlockingMethodFrameListener} which is notified when a fail-over process wants * to start and throws a FailoverException in response to this. - * - *

    Wrapping an asynchronous method in a FailoverRetrySupport will have the effect that the operation will not be + *

    + * Wrapping an asynchronous method in a FailoverRetrySupport will have the effect that the operation will not be * started during fail-over, but be delayed until any current fail-over has completed. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Provide a continuation synchronized on a fail-over lock and condition. - *
    Automatically retry the continuation accross fail-overs until it succeeds, or raises an exception. - *
    - * - * @todo Another continuation. Could use an interface Continuation (as described in other todos) + *

    + * TODO Another continuation. Could use an interface Continuation (as described in other todos) * Then have a wrapping continuation (this), which blocks on an arbitrary * Condition or Latch (specified in constructor call), that this blocks on before calling the wrapped Continuation. * Must work on Java 1.4, so check retrotranslator works on Lock/Condition or latch first. Argument and return type * to match wrapped condition as type parameters. Rename to AsyncConditionalContinuation or something like that. - * - * @todo InterruptedException not handled well. + *

    + * TODO InterruptedException not handled well. */ public class FailoverRetrySupport implements FailoverSupport { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverState.java b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverState.java index 807a5f7d13..268bac6155 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverState.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverState.java @@ -22,11 +22,6 @@ package org.apache.qpid.client.failover; /** * Defines the possible states of the failover process; not started, in progress, failed. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Represent a one of the states of the fail-over process. - *
    */ public final class FailoverState { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverSupport.java b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverSupport.java index ef2e7e1d65..be3fa230e1 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverSupport.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/failover/FailoverSupport.java @@ -26,13 +26,8 @@ package org.apache.qpid.client.failover; * behaviour for handling fail-overs during operations that can be interrupted by the fail-over process. For example, * the support could automatically retry once the fail-over process completes, could prevent an operation from being * started whilst fail-over is running, or could quietly abandon the operation or raise an exception, and so on. - * - *

    - *
    CRC Card
    Responsibilities - *
    Perform a fail-over protected operation with handling for fail-over conditions. - *
    - * - * @todo Continuation, extend some sort of re-usable Continuation interface, which might look very like this one. + *

    + * TODO Continuation, extend some sort of re-usable Continuation interface, which might look very like this one. */ public interface FailoverSupport { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolHandler.java b/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolHandler.java index 15300a5c3b..563518bdfe 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolHandler.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolHandler.java @@ -77,23 +77,24 @@ import org.apache.qpid.util.BytesDataOutput; * event on to more specific handlers for the type. In this sense, it channels the richer event model of AMQP, * expressed in terms of methods and so on, through the cruder, general purpose event model of MINA, expressed in * terms of "message received" and so on. - * - *

    There is a 1:1 mapping between an AMQProtocolHandler and an {@link AMQConnection}. The connection class is + *

    + * There is a 1:1 mapping between an AMQProtocolHandler and an {@link AMQConnection}. The connection class is * exposed to the end user of the AMQP client API, and also implements the JMS Connection API, so provides the public * API calls through which an individual connection can be manipulated. This protocol handler talks to the network * through MINA, in a behind the scenes role; it is not an exposed part of the client API. - * - *

    There is a 1:many mapping between an AMQProtocolHandler and a set of {@link AMQSession}s. At the MINA level, + *

    + * There is a 1:many mapping between an AMQProtocolHandler and a set of {@link AMQSession}s. At the MINA level, * there is one session per connection. At the AMQP level there can be many channels which are also called sessions in * JMS parlance. The {@link AMQSession}s are managed through an {@link AMQProtocolSession} instance. The protocol * session is similar to the MINA per-connection session, except that it can span the lifecycle of multiple MINA sessions * in the event of failover. See below for more information about this. - * - *

    Mina provides a session container that can be used to store/retrieve arbitrary objects as String named + *

    + * Mina provides a session container that can be used to store/retrieve arbitrary objects as String named * attributes. A more convenient, type-safe, container for session data is provided in the form of * {@link AMQProtocolSession}. * - *

    A common way to use MINA is to have a single instance of the event handler, and for MINA to pass in its session + *

    + * A common way to use MINA is to have a single instance of the event handler, and for MINA to pass in its session * object with every event, and for per-connection data to be held in the MINA session (perhaps using a type-safe wrapper * as described above). This event handler is different, because dealing with failover complicates things. To the * end client of an AMQConnection, a failed over connection is still handled through the same connection instance, but @@ -101,19 +102,13 @@ import org.apache.qpid.util.BytesDataOutput; * be used to track the state of the fail-over process, because it is destroyed and a new one is created, as the old * connection is shutdown and a new one created. For this reason, an AMQProtocolHandler is created per AMQConnection * and the protocol session data is held outside of the MINA IOSession. - * - *

    This handler is responsible for setting up the filter chain to filter all events for this handler through. + *

    + * This handler is responsible for setting up the filter chain to filter all events for this handler through. * The filter chain is set up as a stack of event handers that perform the following functions (working upwards from * the network traffic at the bottom), handing off incoming events to an asynchronous thread pool to do the work, * optionally handling secure sockets encoding/decoding, encoding/decoding the AMQP format itself. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Maintain fail-over state. - *
    - *
    - * - * @todo Use a single handler instance, by shifting everything to do with the 'protocol session' state, including + *

    + * TODO Use a single handler instance, by shifting everything to do with the 'protocol session' state, including * failover state, into AMQProtocolSession, and tracking that from AMQConnection? The lifecycles of * AMQProtocolSesssion and AMQConnection will be the same, so if there is high cohesion between them, they could * be merged, although there is sense in keeping the session model separate. Will clarify things by having data @@ -204,8 +199,8 @@ public class AMQProtocolHandler implements ProtocolEngine * where the connection died, an attempt to failover automatically to a new connection may be started. The failover * process will be started, provided that it is the clients policy to allow failover, and provided that a failover * has not already been started or failed. - * - * @todo Clarify: presumably exceptionCaught is called when the client is sending during a connection failure and + *

    + * TODO Clarify: presumably exceptionCaught is called when the client is sending during a connection failure and * not otherwise? The above comment doesn't make that clear. */ public void closed() @@ -413,7 +408,7 @@ public class AMQProtocolHandler implements ProtocolEngine * protocol level waits. * * This will would normally be used to notify all Frame Listeners that Failover is about to occur and they should - * stop waiting and relinquish the Failover lock {@see FailoverHandler}. + * stop waiting and relinquish the Failover lock. See {@link FailoverHandler}. * * Once the {@link FailoverHandler} has re-established the connection then the listeners will be able to re-attempt * their protocol request and so listen again for the correct frame. @@ -744,8 +739,8 @@ public class AMQProtocolHandler implements ProtocolEngine /** * Closes the connection. - * - *

    If a failover exception occurs whilst closing the connection it is ignored, as the connection is closed + *

    + * If a failover exception occurs whilst closing the connection it is ignored, as the connection is closed * anyway. * * @param timeout The timeout to wait for an acknowledgment to the close request. diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolSession.java b/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolSession.java index 4027ccb725..121715d439 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolSession.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/AMQProtocolSession.java @@ -55,8 +55,9 @@ import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; /** - * Wrapper for protocol session that provides type-safe access to session attributes.

    The underlying protocol - * session is still available but clients should not use it to obtain session attributes. + * Wrapper for protocol session that provides type-safe access to session attributes. + *

    + * The underlying protocol session is still available but clients should not use it to obtain session attributes. */ public class AMQProtocolSession implements AMQVersionAwareProtocolSession { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/BlockingMethodFrameListener.java b/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/BlockingMethodFrameListener.java index b865c51cb7..603e2ee10c 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/BlockingMethodFrameListener.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/protocol/BlockingMethodFrameListener.java @@ -32,31 +32,24 @@ import org.apache.qpid.protocol.AMQMethodListener; * incoming methods to a method listener implemented as a sub-class of this and hands off the processed method or * error to a consumer. The producer of the event does not have to wait for the consumer to take the event, so this * differs from a 'rendezvous' in that sense. - * - *

    BlockingMethodFrameListeners are used to coordinate waiting for replies to method calls that expect a response. + *

    + * BlockingMethodFrameListeners are used to coordinate waiting for replies to method calls that expect a response. * They are always used in a 'one-shot' manner, that is, to recieve just one response. Usually the caller has to register * them as method listeners with an event dispatcher and remember to de-register them (in a finally block) once they * have been completed. - * - *

    The {@link #processMethod} must return true on any incoming method that it handles. This indicates to + *

    + * The {@link #processMethod} must return true on any incoming method that it handles. This indicates to * this listeners that the method it is waiting for has arrived. Incoming methods are also filtered by channel prior to * being passed to the {@link #processMethod} method, so responses are only received for a particular channel. The * channel id must be passed to the constructor. - * - *

    Errors from the producer are rethrown to the consumer. - * - *

    - *
    CRC Card
    Responsibilities Collaborations - *
    Accept notification of AMQP method events. {@link AMQMethodEvent} - *
    Delegate handling of the method to another method listener. {@link AMQMethodBody} - *
    Block until a method is handled by the delegated to handler. - *
    Propagate the most recent exception to the consumer. - *
    - * - * @todo Might be neater if this method listener simply wrapped another that provided the method handling using a + *

    + * Errors from the producer are rethrown to the consumer. + *

    + * TODO Might be neater if this method listener simply wrapped another that provided the method handling using a * methodRecevied method. The processMethod takes an additional channelId, however none of the implementations * seem to use it. So wrapping the listeners is possible. - * @todo If the retrotranslator can handle it, could use a SynchronousQueue to implement this rendezvous. Need to + *

    + * TODO If the retrotranslator can handle it, could use a SynchronousQueue to implement this rendezvous. Need to * check that SynchronousQueue has a non-blocking put method available. */ public abstract class BlockingMethodFrameListener extends BlockingWaiter implements AMQMethodListener diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/security/CallbackHandlerRegistry.java b/qpid/java/client/src/main/java/org/apache/qpid/client/security/CallbackHandlerRegistry.java index ce6d9bdc50..6f99e53055 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/client/security/CallbackHandlerRegistry.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/client/security/CallbackHandlerRegistry.java @@ -44,23 +44,17 @@ import java.util.TreeMap; * authentication. It is capable of reading its configuration from a properties file containing call back handler * implementing class names for different SASL mechanism names. Instantiating this registry also has the effect of * configuring and registering the SASL client factory implementations using {@link DynamicSaslRegistrar}. - * - *

    The callback configuration should be specified in a properties file, refered to by the System property + *

    + * The callback configuration should be specified in a properties file, refered to by the System property * "amp.callbackhandler.properties". The format of the properties file is: - * - * 

    + * 
    
+ * 
      * CallbackHanlder.n.mechanism=fully.qualified.class.name where n is an ordinal
  * 
    
- *
- * 
    Where mechanism is an IANA-registered mechanism name and the fully qualified class name refers to a
+ * 
    
+ * Where mechanism is an IANA-registered mechanism name and the fully qualified class name refers to a
  * class that implements org.apache.qpid.client.security.AMQCallbackHanlder and provides a call back handler for the
  * specified mechanism.
- *
- * 
    
- * 
    CRC Card
     Responsibilities  Collaborations
- * 
     Parse callback properties.
- * 
     Provide mapping from SASL mechanisms to callback implementations.
- * 
    
  */
 public class CallbackHandlerRegistry
 {
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/security/DynamicSaslRegistrar.java b/qpid/java/client/src/main/java/org/apache/qpid/client/security/DynamicSaslRegistrar.java
index b43229292f..2be9a0ffde 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/client/security/DynamicSaslRegistrar.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/client/security/DynamicSaslRegistrar.java
@@ -40,19 +40,16 @@ import java.util.TreeMap;
  * DynamicSaslRegistrar provides a collection of helper methods for reading a configuration file that contains a mapping
  * from SASL mechanism names to implementing client factory class names and registering a security provider with the
  * Java runtime system, that uses the configured client factory implementations.
- *
- * 
    The sasl configuration should be specified in a properties file, refered to by the System property
+ * 
    
+ * The sasl configuration should be specified in a properties file, refered to by the System property
  * "amp.dynamicsaslregistrar.properties". The format of the properties file is:
- *
- * 
    + * 
    
+ * 
      * mechanism=fully.qualified.class.name
  * 
    
- *
- * 
    Where mechanism is an IANA-registered mechanism name and the fully qualified class name refers to a class that
+ * 
    
+ * Where mechanism is an IANA-registered mechanism name and the fully qualified class name refers to a class that
  * implements javax.security.sasl.SaslClientFactory and provides the specified mechanism.
- *
- * 
    CRC Card 
     Responsibilities  Collaborations 
     Parse SASL
- * mechanism properties. 
     Create and register security provider for SASL mechanisms. 
    
  */
 public class DynamicSaslRegistrar
 {
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/state/AMQStateManager.java b/qpid/java/client/src/main/java/org/apache/qpid/client/state/AMQStateManager.java
index ed75e1f4c3..fab0bcd71f 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/client/state/AMQStateManager.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/client/state/AMQStateManager.java
@@ -34,18 +34,20 @@ import java.util.Set;
 import java.util.concurrent.CopyOnWriteArrayList;
 
 /**
- * The state manager is responsible for managing the state of the protocol session. 
    
+ * The state manager is responsible for managing the state of the protocol session.
+ * 
    
  * For each {@link org.apache.qpid.client.protocol.AMQProtocolHandler} there is a separate state manager.
- *
+ * 
    
  * The AMQStateManager is now attached to the {@link org.apache.qpid.client.protocol.AMQProtocolHandler} and that is the sole point of reference so that
  * As the {@link AMQProtocolSession} changes due to failover the AMQStateManager need not be copied around.
- *
+ * 
    
  * The StateManager works by any component can wait for a state change to occur by using the following sequence.
- *
- * 
  • StateWaiter waiter = stateManager.createWaiter(Set states);
+ * 
      
+ * 
    • {@literal StateWaiter waiter = stateManager.createWaiter(Set states); }
  * 
    •  // Perform action that will cause state change
  * 
    • waiter.await();
- *
+ * 
    
+ * 
    
  * The two step process is required as there is an inherit race condition between starting a process that will cause
  * the state to change and then attempting to wait for that change. The interest in the change must be first set up so
  * that any asynchronous errors that occur can be delivered to the correct waiters.
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/state/StateWaiter.java b/qpid/java/client/src/main/java/org/apache/qpid/client/state/StateWaiter.java
index fd2f003a56..75b863ca2b 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/client/state/StateWaiter.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/client/state/StateWaiter.java
@@ -93,8 +93,8 @@ public class StateWaiter extends BlockingWaiter
 
     /**
      * Await for the required State to be achieved.
-     *
-     * It is the responsibility of this class to remove the waiter from the StateManager
+     * 
    
+     * It is the responsibility of this class to remove the waiter from the StateManager
      *
      * @param timeout The time in milliseconds to wait for any of the states to be achieved.
      * @return The achieved state that was requested.
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/url/URLParser_0_10.java b/qpid/java/client/src/main/java/org/apache/qpid/client/url/URLParser_0_10.java
index d81868f924..af5dbebb01 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/client/url/URLParser_0_10.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/client/url/URLParser_0_10.java
@@ -25,30 +25,32 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * The format Qpid URL is based on the AMQP one.
- * The grammar is as follows:
- * 
     qpid_url          = "qpid:" [client_props "@"] port_addr_list ["/" future-parameters]
- * 
     port_addr_list 	 = [port_addr ","]* port_addr
- * 
     port_addr         = tcp_port_addr | tls_prot_addr | future_prot_addr
- * 
     tcp_port_addr     = tcp_id tcp_addr
- * 
     tcp_id            = "tcp:" | ""
- * 
     tcp_addr          = host [":" port]
- * 
     host              = 
- * 
     port              = number
- * 
     tls_prot_addr     = tls_id tls_addr
- * 
     tls_id            = "tls:" | ""
- * 
     tls_addr          = host [":" port]
- * 
     future_prot_addr  = future_prot_id future_prot_addr
- * 
     future_prot_id    = 
- * 
     future_prot_addr  = 
- * 
     future_parameters = 
- * 
     client_props      = [client_prop ";"]*  client_prop
- * 
     client_prop       = prop "=" val
- * 
     prop              = chars as per 
- * 
     val               = valid as per 
- * 
    
- * Ex: qpid:virtualhost=tcp:host-foo,test,client_id=foo@tcp:myhost.com:5672,virtualhost=prod;
- * keystore=/opt/keystore@client_id2@tls:mysecurehost.com:5672
+ * The format Qpid URL is based on the AMQP one. The grammar is as follows:
+ * 
    
+ * 
    {@literal qpid_url          = "qpid:" [client_props "@"] port_addr_list ["/" future-parameters] }
+ * 
    {@literal port_addr_list 	 = [port_addr ","]* port_addr }
+ * 
    {@literal port_addr         = tcp_port_addr | tls_prot_addr | future_prot_addr }
+ * 
    {@literal tcp_port_addr     = tcp_id tcp_addr }
+ * 
    {@literal tcp_id            = "tcp:" | "" }
+ * 
    {@literal tcp_addr          = host [":" port] }
+ * 
    {@literal host              =  }
+ * 
    {@literal port              = number }
+ * 
    {@literal tls_prot_addr     = tls_id tls_addr }
+ * 
    {@literal tls_id            = "tls:" | "" }
+ * 
    {@literal tls_addr          = host [":" port] }
+ * 
    {@literal future_prot_addr  = future_prot_id future_prot_addr }
+ * 
    {@literal future_prot_id    =  }
+ * 
    {@literal future_prot_addr  =  }
+ * 
    {@literal future_parameters =  }
+ * 
    {@literal client_props      = [client_prop ";"]*  client_prop }
+ * 
    {@literal client_prop       = prop "=" val }
+ * 
    {@literal prop              = chars as per  }
+ * 
    {@literal val               = valid as per  }
+ * 
    
+ * Ex:
+ * 
    
+ * {@literal qpid:virtualhost=tcp:host-foo,test,client_id=foo@tcp:myhost.com:5672,virtualhost=prod;
+ * keystore=/opt/keystore@client_id2@tls:mysecurehost.com:5672 }
  */
 public class URLParser_0_10
 {
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/util/BlockingWaiter.java b/qpid/java/client/src/main/java/org/apache/qpid/client/util/BlockingWaiter.java
index 22dc17e53c..53b6730ef7 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/client/util/BlockingWaiter.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/client/util/BlockingWaiter.java
@@ -37,29 +37,22 @@ import java.util.concurrent.locks.ReentrantLock;
  * incoming Objects to a listener implemented as a sub-class of this and hands off the process or
  * error to a consumer. The producer of the event does not have to wait for the consumer to take the event, so this
  * differs from a 'rendezvous' in that sense.
- *
- * 
    BlockingWaiters are used to coordinate when waiting for an an event that expect a response.
+ * 
    
+ * BlockingWaiters are used to coordinate when waiting for an an event that expect a response.
  * They are always used in a 'one-shot' manner, that is, to receive just one response. Usually the caller has to register
  * them as method listeners with an event dispatcher and remember to de-register them (in a finally block) once they
  * have been completed.
- *
- * 
    The {@link #process} must return true on any incoming method that it handles. This indicates to
+ * 
    
+ * The {@link #process} must return true on any incoming method that it handles. This indicates to
  * this listeners that the object just processed ends the waiting process.
- *
- * 
    Errors from the producer are rethrown to the consumer.
- *
- * 
    
- * 
    CRC Card
     Responsibilities  Collaborations 
- * 
     Accept generic objects as events for processing via {@link #process}. 
- * 
     Delegate handling and understanding of the object to a concrete implementation. 
- * 
     Block until {@link #process} determines that waiting is no longer required 
- * 
     Propagate the most recent exception to the consumer.
- * 
    
- *
- * @todo Interruption is caught but not handled. This could be allowed to fall through. This might actually be useful
+ * 
    
+ * Errors from the producer are rethrown to the consumer.
+ * 
    
+ * TODO  Interruption is caught but not handled. This could be allowed to fall through. This might actually be useful
  * for fail-over where a thread is blocking when failure happens, it could be interrupted to abandon or retry
  * when this happens. At the very least, restore the interrupted status flag.
- * @todo If the retrotranslator can handle it, could use a SynchronousQueue to implement this rendezvous. Need to
+ * 
    
+ * TODO  If the retrotranslator can handle it, could use a SynchronousQueue to implement this rendezvous. Need to
  * check that SynchronousQueue has a non-blocking put method available.
  */
 public abstract class BlockingWaiter
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/client/util/FlowControllingBlockingQueue.java b/qpid/java/client/src/main/java/org/apache/qpid/client/util/FlowControllingBlockingQueue.java
index c8d12142e6..b194ac88de 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/client/util/FlowControllingBlockingQueue.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/client/util/FlowControllingBlockingQueue.java
@@ -30,10 +30,12 @@ import java.util.concurrent.ConcurrentLinkedQueue;
 /**
  * A blocking queue that emits events above a user specified threshold allowing the caller to take action (e.g. flow
  * control) to try to prevent the queue growing (much) further. The underlying queue itself is not bounded therefore the
- * caller is not obliged to react to the events. 
     This implementation is only safe where we have a single
+ * caller is not obliged to react to the events.
+ * 
    
+ * This implementation is only safe where we have a single
  * thread adding items and a single (different) thread removing items.
- *
- * @todo Make this implement java.util.Queue and hide the implementation. Then different queue types can be substituted.
+ * 
    
+ * TODO  Make this implement java.util.Queue and hide the implementation. Then different queue types can be substituted.
  */
 public class FlowControllingBlockingQueue
 {
diff --git a/qpid/java/client/src/main/java/org/apache/qpid/jms/ConnectionURL.java b/qpid/java/client/src/main/java/org/apache/qpid/jms/ConnectionURL.java
index 3050e84419..2901a5f983 100644
--- a/qpid/java/client/src/main/java/org/apache/qpid/jms/ConnectionURL.java
+++ b/qpid/java/client/src/main/java/org/apache/qpid/jms/ConnectionURL.java
@@ -25,9 +25,9 @@ import org.apache.qpid.framing.AMQShortString;
 
 /**
  Connection URL format
- amqp://[user:pass@][clientid]/virtualhost?brokerlist='tcp://host:port?option=\'value\'&option=\'value\';tcp://host:port/virtualpath?option=\'value\''&failover='method?option=\'value\'&option='value''"
+ {@literal amqp://[user:pass@][clientid]/virtualhost?brokerlist='tcp://host:port?option=\'value\'&option=\'value\';tcp://host:port/virtualpath?option=\'value\''&failover='method?option=\'value\'&option='value''" }
  Options are of course optional except for requiring a single broker in the broker list.
- The option seperator is defined to be either '&' or ','
+ The option seperator is defined to be either {@literal '&' or ','}
   */
 public interface ConnectionURL
 {
-- 
cgit v1.2.1