diff options
Diffstat (limited to 'qpid/java/client/src/main')
31 files changed, 202 insertions, 289 deletions
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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Represent failure to authenticate the client. - * </table> - * - * @todo Will this alwyas have the same status code, NOT_ALLOWED 530? Might set this up to always use that code. + * <p> + * 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Represents failure to pass an immediate message to a consumer. - * <tr><td> */ 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Represents failure to route a mandatory message. - * <tr><td> */ 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; -/** - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> - * </table> - * - * @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<C extends BasicMessageConsumer, P extends BasicMessageProducer> extends Closeable implements Session, QueueSession, TopicSession @@ -613,14 +608,14 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic * @param multiple <tt>true</tt> to acknowledge all messages up to and including the one specified by the * delivery tag, <tt>false</tt> 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. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic * @param exchangeName The exchange to bind the queue on. * * @throws AMQException If the queue cannot be bound for any reason. - * @todo Be aware of possible changes to parameter order as versions change. - * @todo Document the additional arguments that may be passed in the field table. Are these for headers exchanges? + * TODO Be aware of possible changes to parameter order as versions change. + * TODO Document the additional arguments that may be passed in the field table. Are these for headers exchanges? */ public void bindQueue(final AMQShortString queueName, final AMQShortString routingKey, final FieldTable arguments, final AMQShortString exchangeName, final AMQDestination destination) throws AMQException @@ -666,18 +661,18 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Closes the session. - * - * <p/>Note that this operation succeeds automatically if a fail-over interrupts the synchronous request to close + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic } /** * Commits all messages done in this transaction and releases any locks currently held. - * - * <p/>If the commit fails, because the commit itself is interrupted by a fail-over between requesting that the + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Declares the named queue. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic * @param exclusive Flag to indicate that the queue is exclusive to this client. * * @throws AMQException If the queue cannot be declared 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 void createQueue(final AMQShortString name, final boolean autoDelete, final boolean durable, final boolean exclusive) throws AMQException @@ -1256,8 +1251,8 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Declares the named queue. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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<C extends BasicMessageConsumer, P extends Basic * @param arguments Arguments used to set special properties of the queue * * @throws AMQException If the queue cannot be declared 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 void createQueue(final AMQShortString name, final boolean autoDelete, final boolean durable, final boolean exclusive, final Map<String, Object> arguments) throws AMQException @@ -1684,11 +1679,11 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Stops message delivery in this session, and restarts message delivery with the oldest unacknowledged message. - * - * <p/>All consumers deliver messages in a serial order. Acknowledging a received message automatically acknowledges + * <p> + * All consumers deliver messages in a serial order. Acknowledging a received message automatically acknowledges * all messages that have been delivered to the client. - * - * <p/>Restarting a session causes it to take the following actions: + * <p> + * Restarting a session causes it to take the following actions: * * <ul> * <li>Stop message delivery.</li> @@ -1697,14 +1692,15 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic * Redelivered messages do not have to be delivered in exactly their original delivery order.</li> * </ul> * - * <p/>If the recover operation is interrupted by a fail-over, between asking that the broker begin recovery and + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Commits all messages done in this transaction and releases any locks currently held. - * - * <p/>If the rollback fails, because the rollback itself is interrupted by a fail-over between requesting that the + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Tests whether or not the specified queue is bound to the specified exchange under a particular routing key. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic * @return <tt>true</tt> if the queue is bound to the exchange and routing key, <tt>false</tt> 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<C extends BasicMessageConsumer, P extends Basic /** * Called to mark the session as being closed. Useful when the session needs to be made invalid, e.g. after failover - * when the client has veoted resubscription. <p/> The caller of this method must already hold the failover mutex. + * when the client has veoted resubscription. + * <p> + * The caller of this method must already hold the failover mutex. */ void markClosed() { @@ -2296,7 +2294,7 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic * Starts the session, which ensures that it is not suspended and that its event dispatcher is running. * * @throws AMQException If the session cannot be started for any reason. - * @todo This should be controlled by _stopped as it pairs with the stop method fixme or check the + * TODO This should be controlled by _stopped as it pairs with the stop method fixme or check the * FlowControlledBlockingQueue _queue to see if we have flow controlled. will result in sending Flow messages * for each subsequent call to flow.. only need to do this if we have called stop. */ @@ -2638,8 +2636,8 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Returns the number of messages currently queued for the given destination. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Declares the named exchange and type of exchange. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic * @param autoDelete * @param internal * @throws AMQException If the exchange cannot be declared 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. */ private void declareExchange(final AMQShortString name, final AMQShortString type, final boolean nowait, final boolean durable, @@ -2716,12 +2714,12 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Declares a queue for a JMS destination. - * - * <p/>Note that for queues but not topics the name is generated in the client rather than the server. This allows + * <p> + * 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. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic * * * @throws AMQException If the queue cannot be declared for any reason. - * @todo Verify the destiation is valid or throw an exception. - * @todo Be aware of possible changes to parameter order as versions change. + * TODO Verify the destiation is valid or throw an exception. + * TODO Be aware of possible changes to parameter order as versions change. */ protected AMQShortString declareQueue(final AMQDestination amqd, final boolean noLocal) throws AMQException @@ -2752,13 +2750,13 @@ public abstract class AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Undeclares the specified queue. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Undeclares the specified temporary queue/topic. - * - * <p/>Note that this operation automatically retries in the event of fail-over. + * <p> + * 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 AMQSession<C extends BasicMessageConsumer, P extends Basic /** * Suspends or unsuspends this session. * - * @param suspend <tt>true</tt> indicates that the session should be suspended, <tt>false<tt> 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Represent attempt to perform additional sends on a dirty session. - * </table> */ 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. - * <p/> + * <p> * 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<U> extends Closeable implements Messa } /** - * Used in the blocking receive methods to receive a message from the Session thread. <p/> Or to notify of errors - * <p/> Argument true indicates we want strict FIFO semantics + * Used in the blocking receive methods to receive a message from the Session thread. + * <p> + * Or to notify of errors. + * <p> + * 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Mark an object as closed. - * <tr><td> Check if an object is closed. - * <tr><td> Raise a JMS exception if an object is closed. - * </table> - * - * @todo Might be better to make this an interface. This whole class doesn't really encapsulate a terribly neat + * <p> + * 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 + * <p> + * 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Accept wrapped exceptions as a JMSException. - * </table> */ 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 <code>SERVER</server> value is specified. Otherwise the messages won't be moved to + * if <code>SERVER</code> 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. * <li> If TMFAIL is specified, the portion of work has failed. The resource manager may mark the transaction as rollback-only * <li> If TMSUCCESS is specified, the portion of work has completed successfully. - * /ul> + * </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. - * <p/> + * <p> * 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Used to indicate failure of a synchronous request due to fail-over. - * </table> - * - * @todo This exception is created and passed as an argument to a method, rather than thrown. The exception is being + * <p> + * 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. - * - * </p>The reason this needs to be a separate thread is because this work cannot be done inside the i/o processor + * <p> + * 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. - * - * <p/>The failover procedure does the following: + * <p> + * The failover procedure does the following: * * <ol> * <li>Sets the failing over condition to true.</li> @@ -57,21 +57,17 @@ import java.util.concurrent.CountDownLatch; * <li>Resets the failing over condition and releases the mutex.</li> * </ol> * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Update fail-over state <td> {@link AMQProtocolHandler} - * </table> - * - * @todo The failover latch and mutex are used like a lock and condition. If the retrotranlator supports lock/condition + * <p> + * 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 + * <p> + * 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 + * <p> + * 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 + * <p> + * 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. - * - * <p/>The type of checked exception that the operation may perform has been generified, in order that fail over + * <p> + * 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. - * - * <p><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities - * <tr><td> Perform an operation that may be interrupted by fail-over. - * </table> */ public interface FailoverProtectedOperation<T, E extends Exception> { 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). - * - * <p/>The blocking condition used is that the connection is not currently failing over, and the mutex used is the + * <p> + * 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. - * - * <p/>The wrapped operation may throw a FailoverException, this is an exception that can be raised by a + * <p> + * 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. - * - * <p/>Wrapping a synchronous method in a FailoverRetrySupport will have the effect that the operation will not be + * <p> + * 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. - * - * <p/>Wrapping an asynchronous method in a FailoverRetrySupport will have the effect that the operation will not be + * <p> + * 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Provide a continuation synchronized on a fail-over lock and condition. - * <tr><td> Automatically retry the continuation accross fail-overs until it succeeds, or raises an exception. - * </table> - * - * @todo Another continuation. Could use an interface Continuation (as described in other todos) + * <p> + * 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. + * <p> + * TODO InterruptedException not handled well. */ public class FailoverRetrySupport<T, E extends Exception> implements FailoverSupport<T, E> { 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Represent a one of the states of the fail-over process. - * </table> */ 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. - * - * <p><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities - * <tr><td> Perform a fail-over protected operation with handling for fail-over conditions. - * </table> - * - * @todo Continuation, extend some sort of re-usable Continuation interface, which might look very like this one. + * <p> + * TODO Continuation, extend some sort of re-usable Continuation interface, which might look very like this one. */ public interface FailoverSupport<T, E extends Exception> { 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 ba5a98411f..c8ebb7f9c7 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 java.util.concurrent.TimeUnit; * 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. - * - * <p/>There is a 1:1 mapping between an AMQProtocolHandler and an {@link AMQConnection}. The connection class is + * <p> + * 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. - * - * <p/>There is a 1:many mapping between an AMQProtocolHandler and a set of {@link AMQSession}s. At the MINA level, + * <p> + * 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. - * - * <p/>Mina provides a session container that can be used to store/retrieve arbitrary objects as String named + * <p> + * 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}. * - * <p/>A common way to use MINA is to have a single instance of the event handler, and for MINA to pass in its session + * <p> + * 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 java.util.concurrent.TimeUnit; * 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. - * - * <p/>This handler is responsible for setting up the filter chain to filter all events for this handler through. + * <p> + * 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. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Maintain fail-over state. - * <tr><td> - * </table> - * - * @todo Use a single handler instance, by shifting everything to do with the 'protocol session' state, including + * <p> + * 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 @@ -203,8 +198,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 + * <p> + * 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() @@ -396,7 +391,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. @@ -727,8 +722,8 @@ public class AMQProtocolHandler implements ProtocolEngine /** * Closes the connection. - * - * <p/>If a failover exception occurs whilst closing the connection it is ignored, as the connection is closed + * <p> + * 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. <p/> 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. + * <p> + * 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. - * - * <p/>BlockingMethodFrameListeners are used to coordinate waiting for replies to method calls that expect a response. + * <p> + * 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. - * - * <p/>The {@link #processMethod} must return <tt>true</tt> on any incoming method that it handles. This indicates to + * <p> + * The {@link #processMethod} must return <tt>true</tt> 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. - * - * <p/>Errors from the producer are rethrown to the consumer. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Accept notification of AMQP method events. <td> {@link AMQMethodEvent} - * <tr><td> Delegate handling of the method to another method listener. <td> {@link AMQMethodBody} - * <tr><td> Block until a method is handled by the delegated to handler. - * <tr><td> Propagate the most recent exception to the consumer. - * </table> - * - * @todo Might be neater if this method listener simply wrapped another that provided the method handling using a + * <p> + * Errors from the producer are rethrown to the consumer. + * <p> + * 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 + * <p> + * 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<AMQMethodEvent> 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}. - * - * <p/>The callback configuration should be specified in a properties file, refered to by the System property + * <p> + * 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: - * - * <p/><pre> + * <p> + * <pre> * CallbackHanlder.n.mechanism=fully.qualified.class.name where n is an ordinal * </pre> - * - * <p/>Where mechanism is an IANA-registered mechanism name and the fully qualified class name refers to a + * <p> + * 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. - * - * <p><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations - * <tr><td> Parse callback properties. - * <tr><td> Provide mapping from SASL mechanisms to callback implementations. - * </table> */ 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. - * - * <p/>The sasl configuration should be specified in a properties file, refered to by the System property + * <p> + * 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: - * - * <p/><pre> + * <p> + * <pre> * mechanism=fully.qualified.class.name * </pre> - * - * <p/>Where mechanism is an IANA-registered mechanism name and the fully qualified class name refers to a class that + * <p> + * 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. - * - * <p><table id="crc"><caption>CRC Card</caption> <tr><th> Responsibilities <th> Collaborations <tr><td> Parse SASL - * mechanism properties. <tr><td> Create and register security provider for SASL mechanisms. </table> */ 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. <p/> + * The state manager is responsible for managing the state of the protocol session. + * <p> * For each {@link org.apache.qpid.client.protocol.AMQProtocolHandler} there is a separate state manager. - * + * <p> * 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. - * + * <p> * The StateManager works by any component can wait for a state change to occur by using the following sequence. - * - * <li>StateWaiter waiter = stateManager.createWaiter(Set<AMQState> states); + * <ul> + * <li>{@literal StateWaiter waiter = stateManager.createWaiter(Set<AMQState> states); } * <li> // Perform action that will cause state change * <li>waiter.await(); - * + * </ul> + * <p> * 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<AMQState> /** * Await for the required State to be achieved. - * - * <b>It is the responsibility of this class to remove the waiter from the StateManager + * <p> + * 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: - * <p> qpid_url = "qpid:" [client_props "@"] port_addr_list ["/" future-parameters] - * <p> port_addr_list = [port_addr ","]* port_addr - * <p> port_addr = tcp_port_addr | tls_prot_addr | future_prot_addr - * <p> tcp_port_addr = tcp_id tcp_addr - * <p> tcp_id = "tcp:" | "" - * <p> tcp_addr = host [":" port] - * <p> host = <as per http://www.apps.ietf.org/> - * <p> port = number - * <p> tls_prot_addr = tls_id tls_addr - * <p> tls_id = "tls:" | "" - * <p> tls_addr = host [":" port] - * <p> future_prot_addr = future_prot_id future_prot_addr - * <p> future_prot_id = <placeholder, must end in ":". Example "sctp:"> - * <p> future_prot_addr = <placeholder, protocl-specific address> - * <p> future_parameters = <placeholder, not used in failover addresses> - * <p> client_props = [client_prop ";"]* client_prop - * <p> client_prop = prop "=" val - * <p> prop = chars as per <as per http://www.apps.ietf.org/> - * <p> val = valid as per <as per http://www.apps.ietf.org/> - * <p/> - * 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: + * <p> + * <p>{@literal qpid_url = "qpid:" [client_props "@"] port_addr_list ["/" future-parameters] } + * <p>{@literal port_addr_list = [port_addr ","]* port_addr } + * <p>{@literal port_addr = tcp_port_addr | tls_prot_addr | future_prot_addr } + * <p>{@literal tcp_port_addr = tcp_id tcp_addr } + * <p>{@literal tcp_id = "tcp:" | "" } + * <p>{@literal tcp_addr = host [":" port] } + * <p>{@literal host = <as per http://www.apps.ietf.org/> } + * <p>{@literal port = number } + * <p>{@literal tls_prot_addr = tls_id tls_addr } + * <p>{@literal tls_id = "tls:" | "" } + * <p>{@literal tls_addr = host [":" port] } + * <p>{@literal future_prot_addr = future_prot_id future_prot_addr } + * <p>{@literal future_prot_id = <placeholder, must end in ":". Example "sctp:"> } + * <p>{@literal future_prot_addr = <placeholder, protocl-specific address> } + * <p>{@literal future_parameters = <placeholder, not used in failover addresses> } + * <p>{@literal client_props = [client_prop ";"]* client_prop } + * <p>{@literal client_prop = prop "=" val } + * <p>{@literal prop = chars as per <as per http://www.apps.ietf.org/> } + * <p>{@literal val = valid as per <as per http://www.apps.ietf.org/> } + * <p> + * Ex: + * <p> + * {@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. - * - * <p/>BlockingWaiters are used to coordinate when waiting for an an event that expect a response. + * <p> + * 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. - * - * <p/>The {@link #process} must return <tt>true</tt> on any incoming method that it handles. This indicates to + * <p> + * The {@link #process} must return <tt>true</tt> on any incoming method that it handles. This indicates to * this listeners that the object just processed ends the waiting process. - * - * <p/>Errors from the producer are rethrown to the consumer. - * - * <p/><table id="crc"><caption>CRC Card</caption> - * <tr><th> Responsibilities <th> Collaborations </td> - * <tr><td> Accept generic objects as events for processing via {@link #process}. <td> - * <tr><td> Delegate handling and understanding of the object to a concrete implementation. <td> - * <tr><td> Block until {@link #process} determines that waiting is no longer required <td> - * <tr><td> Propagate the most recent exception to the consumer.<td> - * </table> - * - * @todo Interruption is caught but not handled. This could be allowed to fall through. This might actually be useful + * <p> + * Errors from the producer are rethrown to the consumer. + * <p> + * 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 + * <p> + * 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<T> 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. <p/> This implementation is <b>only</b> safe where we have a single + * caller is not obliged to react to the events. + * <p> + * This implementation is <b>only</b> 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. + * <p> + * 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 { diff --git a/qpid/java/client/src/main/java/org/apache/qpid/jndi/NameParserImpl.java b/qpid/java/client/src/main/java/org/apache/qpid/jndi/NameParserImpl.java index a3174aec7a..d7b16fcd6d 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/jndi/NameParserImpl.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/jndi/NameParserImpl.java @@ -25,7 +25,7 @@ import javax.naming.NamingException; /** * A default implementation of {@link NameParser} - * <p/> + * <p> * Based on class from ActiveMQ. */ public class NameParserImpl implements NameParser diff --git a/qpid/java/client/src/main/java/org/apache/qpid/jndi/ReadOnlyContext.java b/qpid/java/client/src/main/java/org/apache/qpid/jndi/ReadOnlyContext.java index 76ec5f9498..1d7525ca91 100644 --- a/qpid/java/client/src/main/java/org/apache/qpid/jndi/ReadOnlyContext.java +++ b/qpid/java/client/src/main/java/org/apache/qpid/jndi/ReadOnlyContext.java @@ -44,13 +44,13 @@ import java.util.Map; /** * Based on class from ActiveMQ. * A read-only Context - * <p/> + * <p> * This version assumes it and all its subcontext are read-only and any attempt * to modify (e.g. through bind) will result in an OperationNotSupportedException. * Each Context in the tree builds a cache of the entries in all sub-contexts * to optimise the performance of lookup. - * </p> - * <p>This implementation is intended to optimise the performance of lookup(String) + * <p> + * This implementation is intended to optimise the performance of lookup(String) * to about the level of a HashMap get. It has been observed that the scheme * resolution phase performed by the JVM takes considerably longer, so for * optimum performance lookups should be coded like:</p> @@ -147,11 +147,6 @@ public class ReadOnlyContext implements Context, Serializable * to bind the remaining name. It returns a map containing all the bindings from the next context, plus * the context it just created (if it in fact created it). (the names are suitably extended by the segment * originally lopped off). - * - * @param name - * @param value - * @return - * @throws javax.naming.NamingException */ protected Map internalBind(String name, Object value) throws NamingException { |