Author: arnaudsimon
Date: Thu Aug 16 01:16:19 2007
New Revision: 566538
URL: http://svn.apache.org/viewvc?view=rev&rev=566538
Log:
updated javadoc
Modified:
incubator/qpid/trunk/qpid/java/client/src/main/java/org/apache/qpidity/client/Session.java
Modified:
incubator/qpid/trunk/qpid/java/client/src/main/java/org/apache/qpidity/client/Session.java
URL:
http://svn.apache.org/viewvc/incubator/qpid/trunk/qpid/java/client/src/main/java/org/apache/qpidity/client/Session.java?view=diff&rev=566538&r1=566537&r2=566538
==============================================================================
---
incubator/qpid/trunk/qpid/java/client/src/main/java/org/apache/qpidity/client/Session.java
(original)
+++
incubator/qpid/trunk/qpid/java/client/src/main/java/org/apache/qpidity/client/Session.java
Thu Aug 16 01:16:19 2007
@@ -31,11 +31,16 @@
* <p>A session is associated with a connection.
* When created a Session is not attached with an underlying channel.
* Session is single threaded </p>
+ * <p/>
+ * All the Session commands are asynchronous, synchronous invocation is
achieved through invoking the sync method.
+ * That is to say that <code>command1</code> will be synchronously invoked
using the following sequence:
+ * <ul>
+ * <li> <code>session.command1()</code>
+ * <li> <code>session.sync()</code>
+ * </ul>
*/
public interface Session
{
- public static final short ACQUIRE_ANY_AVAILABLE_MESSAGE = 0;
- public static final short ACQUIRE_MESSAGES_IF_ALL_ARE_AVAILABLE = 0;
public static final short TRANSFER_ACQUIRE_MODE_NO_ACQUIRE = 0;
public static final short TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE = 1;
public static final short TRANSFER_CONFIRM_MODE_REQUIRED = 1;
@@ -44,17 +49,21 @@
public static final short MESSAGE_FLOW_MODE_WINDOW = 1;
public static final short MESSAGE_FLOW_UNIT_MESSAGE = 0;
public static final short MESSAGE_FLOW_UNIT_BYTE = 1;
+ public static final short MESSAGE_REJECT_CODE_GENERIC = 0;
+ public static final short MESSAGE_REJECT_CODE_IMMEDIATE_DELIVERY_FAILED =
1;
+ public static final short MESSAGE_ACQUIRE_ANY_AVAILABLE_MESSAGE = 0;
+ public static final short MESSAGE_ACQUIRE_MESSAGES_IF_ALL_ARE_AVAILABLE =
1;
//------------------------------------------------------
// Session housekeeping methods
//------------------------------------------------------
-
+
/**
* Sync method will block until all outstanding commands
* are executed.
*/
public void sync();
-
+
/**
* Close this session and any associated resources.
*/
@@ -73,93 +82,109 @@
//------------------------------------------------------
/**
* Transfer the given message to a specified exchange.
- *
+ * <p/>
* <p>This is a convinience method for providing a complete message
* using a single method which internaly is mapped to messageTransfer(),
headers() followed
- * by data() and an endData().
+ * by data() and an endData().
* <b><i>This method should only be used by small messages</b></i></p>
*
* @param destination The exchange the message is being sent.
* @param msg The Message to be sent
- * @param confirmMode <ul> </li>off (0): confirmation is not required,
once a message has been transferred in pre-acquire
+ * @param confirmMode <ul> </li>off ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation
+ * is not required, once a message has been transferred
in pre-acquire
* mode (or once acquire has been sent in no-acquire
mode) the message is considered
* transferred
* <p/>
- * <li> on (1): an acquired message (whether
acquisition was implicit as in pre-acquire mode or
+ * <li> on ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message
+ * (whether acquisition was implicit as in pre-acquire
mode or
* explicit as in no-acquire mode) is not considered
transferred until the original
* transfer is complete (signaled via
execution.complete)
* </ul>
- * @param acquireMode <ul>
- * <li> no-acquire (0): the message must be explicitly
acquired
- * <li> pre-acquire (1): the message is acquired when
the transfer starts
- * </ul>
+ * @param acquireMode <ul>
+ * <li> no-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message
+ * must be explicitly acquired
+ * <li> pre-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message is
+ * acquired when the transfer starts
+ * </ul>
+ * @throws java.io.IOException If transferring a message fails due to some
internal communication error.
*/
- public void messageTransfer(String destination, Message msg, short
confirmMode, short acquireMode)throws IOException;
-
+ public void messageTransfer(String destination, Message msg, short
confirmMode, short acquireMode)
+ throws IOException;
+
/**
* <p>This is a convinience method for streaming a message using pull
semantics
* using a single method as opposed to doing a push using
messageTransfer(), headers() followed
- * by a series of data() and an endData().</p>
+ * by a series of data() and an endData().</p>
* <p>Internally data will be pulled from Message object(which wrap's a
data stream) using it's read()
* and pushed using messageTransfer(), headers() followed by a series of
data() and an endData().
* <br><b><i>This method should only be used by large messages</b></i><br>
* There are two convinience Message classes provided to facilitate this.
* <ul>
- * <li> <code>FileMessage</code>
- * <li> <code>StreamingMessage</code>
+ * <li> <code>[EMAIL PROTECTED]
org.apache.qpidity.client.util.FileMessage}</code>
+ * <li> <code>[EMAIL PROTECTED]
org.apache.qpidity.client.util.StreamingMessage}</code>
* </ul>
* You could also implement a the <code>Message</code> interface to and
wrap any
* data stream you want.
* </p>
- *
+ *
* @param destination The exchange the message is being sent.
- * @param msg The Message to be sent
- * @param confirmMode <ul> </li>off (0): confirmation is not required,
once a message has been transferred in pre-acquire
+ * @param msg The Message to be sent
+ * @param confirmMode <ul> </li>off ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation
+ * is not required, once a message has been transferred
in pre-acquire
* mode (or once acquire has been sent in no-acquire
mode) the message is considered
* transferred
* <p/>
- * <li> on (1): an acquired message (whether
acquisition was implicit as in pre-acquire mode or
+ * <li> on ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message
+ * (whether acquisition was implicit as in pre-acquire
mode or
* explicit as in no-acquire mode) is not considered
transferred until the original
* transfer is complete (signaled via
execution.complete)
* </ul>
- * @param acquireMode <ul> <li> no-acquire (0): the message must be
explicitly acquired
- * <p/>
- * <li> pre-acquire (1): the message is acquired when
the transfer starts
+ * @param acquireMode <ul>
+ * <li> no-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message
+ * must be explicitly acquired
+ * <li> pre-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message
+ * is acquired when the transfer starts
* </ul>
+ * @throws java.io.IOException If transferring a message fails due to some
internal communication error.
*/
- public void messageStream(String destination, Message msg, short
confirmMode, short acquireMode)throws IOException;
+ public void messageStream(String destination, Message msg, short
confirmMode, short acquireMode) throws IOException;
/**
* Declare the beginning of a message transfer operation. This operation
must
- * be followed by [EMAIL PROTECTED] Session#addMessageHeaders} then
followed by any number of [EMAIL PROTECTED] Session#addData}.
- * The transfer is ended by endData.
+ * be followed by [EMAIL PROTECTED] Session#headers} then followed by any
number of [EMAIL PROTECTED] Session#data}.
+ * The transfer is ended by [EMAIL PROTECTED] Session#endData}.
* <p> This way of transferring messages is useful when streaming large
messages
* <p> In the interval [messageTransfer endData] any attempt to call a
method other than
- * [EMAIL PROTECTED] Session#addMessageHeaders}, [EMAIL PROTECTED]
Session#endData} ore [EMAIL PROTECTED] Session#close}
+ * [EMAIL PROTECTED] Session#headers}, [EMAIL PROTECTED] Session#endData}
ore [EMAIL PROTECTED] Session#sessionClose}
* will result in an exception being thrown.
*
- * @param confirmMode <ul> </li>off (0): confirmation is not required,
once a message has been transferred in pre-acquire
+ * @param destination The exchange the message is being sent.
+ * @param confirmMode <ul> </li>off ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation
+ * is not required, once a message has been transferred
in pre-acquire
* mode (or once acquire has been sent in no-acquire
mode) the message is considered
* transferred
* <p/>
- * <li> on (1): an acquired message (whether
acquisition was implicit as in pre-acquire mode or
+ * <li> on ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message
+ * (whether acquisition was implicit as in pre-acquire
mode or
* explicit as in no-acquire mode) is not considered
transferred until the original
* transfer is complete (signaled via
execution.complete)
* </ul>
- * @param acquireMode <ul> <li> no-acquire (0): the message must be
explicitly acquired
- * <p/>
- * <li> pre-acquire (1): the message is acquired when
the transfer starts
+ * @param acquireMode <ul>
+ * <li> no-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message
+ * must be explicitly acquired
+ * <li> pre-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message
+ * is acquired when the transfer starts
* </ul>
- * @param exchange The exchange the message is being sent.
*/
public void messageTransfer(String destination, short confirmMode, short
acquireMode);
/**
- * Add the following headers ( [EMAIL PROTECTED]
org.apache.qpidity.DeliveryProperties}
- * or to the message being sent.
+ * Add a set of headers the following headers to the message being sent.
*
- * @param headers are Either <code>DeliveryProperties</code> or
<code>ApplicationProperties</code>
+ * @param headers Are either <code>[EMAIL PROTECTED]
org.apache.qpidity.DeliveryProperties}</code>
+ * or <code>[EMAIL PROTECTED]
org.apache.qpidity.MessageProperties}</code>
* @see org.apache.qpidity.DeliveryProperties
+ * @see org.apache.qpidity.MessageProperties
*/
public void headers(Struct... headers);
@@ -169,21 +194,24 @@
* @param data Data to be added.
*/
public void data(byte[] data);
-
+
/**
* Add the following ByteBuffer to the content of the message being sent.
+ * <p> Note that only the data between the buffer current position and the
+ * buffer limit is added.
+ * It is therefore recommended to flip the buffer before adding it to the
message,
*
- * @param data Data to be added.
- */
+ * @param buf Data to be added.
+ */
public void data(ByteBuffer buf);
/**
* Add the following String to the content of the message being sent.
*
- * @param data Data to be added.
- */
+ * @param str String to be added.
+ */
public void data(String str);
-
+
/**
* Signals the end of data for the message.
*/
@@ -198,35 +226,38 @@
* Associate a message listener with a destination.
* <p> The destination is bound to a queue and messages are filtered based
* on the provider filter map (message filtering is specific to the
provider and may not be handled).
- * <p/>
- * <p> Following are the valid options
+ * <p> Following are valid options:
* <ul>
- * <li> NO_LOCAL
- * <li> EXCLUSIVE
- * </ul>
- * <p> In the absence of a particular option, defaul values are:
- * <ul>
- * <li> NO_LOCAL = false
- * <li> EXCLUSIVE = false
+ * <li>[EMAIL PROTECTED] Option#NO_LOCAL}: <p>If the no-local field is set
the server will not send
+ * messages to the connection that
+ * published them.
+ * <li>[EMAIL PROTECTED] Option#EXCLUSIVE}: <p> Request exclusive
subscription access, meaning only this
+ * ubscription can access the queue.
+ * <li>[EMAIL PROTECTED] Option#NO_OPTION}: <p> Has no effect as it
represents an empty option.
* </ul>
*
* @param queue The queue this receiver is receiving messages from.
* @param destination The destination for the subscriber ,a.k.a the
delivery tag.
- * @param confirmMode <ul> </li>off (0): confirmation is not required,
once a message has been transferred in pre-acquire
+ * @param confirmMode <ul> </li>off ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_NOT_REQUIRED}): confirmation is not
+ * required, once a message has been transferred in
pre-acquire
* mode (or once acquire has been sent in no-acquire
mode) the message is considered
* transferred
* <p/>
- * <li> on (1): an acquired message (whether
acquisition was implicit as in pre-acquire mode or
+ * <li> on ([EMAIL PROTECTED]
Session#TRANSFER_CONFIRM_MODE_REQUIRED}): an acquired message (whether
+ * acquisition was implicit as in pre-acquire mode or
* explicit as in no-acquire mode) is not considered
transferred until the original
* transfer is complete (signaled via
execution.complete)
* </ul>
- * @param acquireMode <ul> <li> no-acquire (0): the message must be
explicitly acquired
- * <p/>
- * <li> pre-acquire (1): the message is acquired when
the transfer starts
+ * @param acquireMode <ul>
+ * <li> no-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_NO_ACQUIRE}): the message must
+ * be explicitly acquired
+ * <li> pre-acquire ([EMAIL PROTECTED]
Session#TRANSFER_ACQUIRE_MODE_PRE_ACQUIRE}): the message is
+ * acquired when the transfer starts
* </ul>
* @param listener The listener for this destination. When big message
are transfered then
* it is recommended to use a [EMAIL PROTECTED]
org.apache.qpidity.client.MessagePartListener}.
- * @param options Set of Options.
+ * @param options Set of Options (valid options are [EMAIL PROTECTED]
Option#NO_LOCAL}, [EMAIL PROTECTED] Option#EXCLUSIVE}
+ * and [EMAIL PROTECTED] Option#NO_OPTION})
* @param filter A set of filters for the subscription. The syntax
and semantics of these filters depends
* on the providers implementation.
*/
@@ -245,12 +276,10 @@
/**
* Associate a message part listener with a destination.
- * We currently allow one listerner per destination this means
+ * <p> Only one listerner per destination is allowed. This means
* that the previous message listener is replaced. This is done gracefully
i.e. the message
* listener is replaced once it return from the processing of a message.
*
- * // todo when a listener is null then received messages must be released
- *
* @param destination The destination the listener is associated with.
* @param listener The new listener for this destination.
*/
@@ -258,20 +287,18 @@
/**
* Sets the mode of flow control used for a given destination.
- * <p/>
- * With credit based flow control, the broker continually maintains its
current
+ * <p> With credit based flow control, the broker continually maintains
its current
* credit balance with the recipient. The credit balance consists of two
values, a message
* count, and a byte count. Whenever message data is sent, both counts
must be decremented.
* If either value reaches zero, the flow of message data must stop.
Additional credit is
* received via the [EMAIL PROTECTED] Session#messageFlow} method.
- * <p/>
- * Window based flow control is identical to credit based flow control,
however message
+ * <p> Window based flow control is identical to credit based flow
control, however message
* acknowledgment implicitly grants a single unit of message credit, and
the size of the
* message in byte credits for each acknowledged message.
*
* @param destination The destination to set the flow mode on.
- * @param mode <ul> <li>credit (0): choose credit based flow control
- * <li> window (1): choose window based flow
control</ul>
+ * @param mode <ul> <li>credit ([EMAIL PROTECTED]
Session#MESSAGE_FLOW_MODE_CREDIT}): choose credit based flow control
+ * <li> window ([EMAIL PROTECTED]
Session#MESSAGE_FLOW_MODE_WINDOW}): choose window based flow control</ul>
*/
public void messageFlowMode(String destination, short mode);
@@ -289,8 +316,8 @@
* @param unit Specifies the unit of credit balance.
* <p/>
* One of: <ul>
- * <li> message (0)
- * <li> byte (1)
+ * <li> message ([EMAIL PROTECTED]
Session#MESSAGE_FLOW_UNIT_MESSAGE})
+ * <li> byte ([EMAIL PROTECTED]
Session#MESSAGE_FLOW_UNIT_BYTE})
* </ul>
* @param value Number of credits, a value of 0 indicates an
infinite amount of credit.
*/
@@ -300,7 +327,7 @@
* Forces the broker to exhaust its credit supply.
* <p> The broker's credit will always be zero when
* this method completes. This method does not complete until all the
message transfers occur.
- * <p> This method returns the number of flushed messages.
+ * <p> This method returns the number of flushed messages.
*
* @param destination The destination to call flush on.
*/
@@ -327,17 +354,31 @@
/**
* Reject ranges of acquired messages.
- * <p> A rejected message will not be delivered to any receiver
- * and may be either discarded or moved to the broker dead letter queue.
+ * <p> The broker MUST deliver rejected messages to the
+ * alternate-exchange on the queue from which it was delivered. If no
alternate-exchange is
+ * defined for that queue the broker MAY discard the message.
*
* @param ranges Range of rejected messages.
- * @param code TODO
- * @param text TODO
+ * @param code The reject code must be one of [EMAIL PROTECTED]
Session#MESSAGE_REJECT_CODE_GENERIC} or
+ * [EMAIL PROTECTED]
Session#MESSAGE_REJECT_CODE_IMMEDIATE_DELIVERY_FAILED} (immediate delivery was
attempted but
+ * failed).
+ * @param text String describing the reason for a message transfer
rejection.
*/
public void messageReject(RangeSet ranges, int code, String text);
-
- /**
- * @return the rejected message ranges
+
+ /**
+ * As it is possible that the broker does not manage to reject some
messages, after completion of
+ * [EMAIL PROTECTED] Session#messageReject} this method will return the
ranges of rejected messages.
+ * <p> Note that [EMAIL PROTECTED] Session#messageReject} and this methods
are asynchronous therefore for accessing to the
+ * previously rejected messages this method must be invoked in conjunction
with [EMAIL PROTECTED] Session#sync()}.
+ * <p> A recommended invocation sequence would be:
+ * <ul>
+ * <li> [EMAIL PROTECTED] Session#messageReject}
+ * <li> [EMAIL PROTECTED] Session#sync()}
+ * <li> [EMAIL PROTECTED] Session#getRejectedMessages()}
+ * </ul>
+ *
+ * @return The rejected message ranges
*/
public RangeSet getRejectedMessages();
@@ -348,21 +389,38 @@
* message acquisition can fail.
* The outcome of the acquisition is returned as an array of ranges of
qcquired messages.
* <p> This method should only be called on non-acquired messages.
- * @param mode TODO
- * @param range Ranges of messages to be acquired.
+ *
+ * @param mode One of: <ul>
+ * <li> any ([EMAIL PROTECTED]
Session#MESSAGE_ACQUIRE_ANY_AVAILABLE_MESSAGE}): acquire any available
+ * messages for consumption
+ * <li> all ([EMAIL PROTECTED]
Session#MESSAGE_ACQUIRE_MESSAGES_IF_ALL_ARE_AVAILABLE}): only acquire messages
+ * if all are available for consumption
+ * </ul>
+ * @param ranges Ranges of messages to be acquired.
*/
public void messageAcquire(RangeSet ranges, short mode);
- /**
+ /**
+ * As it is possible that the broker does not manage to acquire some
messages, after completion of
+ * [EMAIL PROTECTED] Session#messageAcquire} this method will return the
ranges of acquired messages.
+ * <p> Note that [EMAIL PROTECTED] Session#messageAcquire} and this
methods are asynchronous therefore for accessing to the
+ * previously acquired messages this method must be invoked in conjunction
with [EMAIL PROTECTED] Session#sync()}.
+ * <p> A recommended invocation sequence would be:
+ * <ul>
+ * <li> [EMAIL PROTECTED] Session#messageAcquire}
+ * <li> [EMAIL PROTECTED] Session#sync()}
+ * <li> [EMAIL PROTECTED] Session#getAccquiredMessages()}
+ * </ul>
+ *
* @return returns the message ranges marked by the broker as acquired.
*/
public RangeSet getAccquiredMessages();
-
+
/**
* Give up responsibility for processing ranges of messages.
* <p> Released messages are re-enqueued.
*
- * @param range Ranges of messages to be released.
+ * @param ranges Ranges of messages to be released.
*/
public void messageRelease(RangeSet ranges);
@@ -376,12 +434,14 @@
/**
* Commit the receipt and the delivery of all messages exchanged by this
session resources.
+ *
* @throws IllegalStateException If this session is not transacted.
*/
public void txCommit() throws IllegalStateException;
/**
* Rollback the receipt and the delivery of all messages exchanged by this
session resources.
+ *
* @throws IllegalStateException If this session is not transacted.
*/
public void txRollback() throws IllegalStateException;
@@ -392,26 +452,36 @@
/**
* Declare a queue with the given queueName
- * <p> Following are the valid options for declareQueue
+ * <p> Following are the valid options:
* <ul>
- * <li> AUTO_DELETE
- * <li> DURABLE
- * <li> EXCLUSIVE
- * <li> NO_WAIT
- * <li> PASSIVE
+ * <li> [EMAIL PROTECTED] Option#AUTO_DELETE}: <p> If this field is set
and the exclusive field is also set,
+ * then the queue is deleted when the connection closes.
+ * If this field is set and the exclusive field is not set the queue is
deleted when all
+ * the consumers have finished using it.
+ * <li> [EMAIL PROTECTED] Option#DURABLE}: <p> If set when creating a new
queue,
+ * the queue will be marked as durable. Durable queues
+ * remain active when a server restarts. Non-durable queues (transient
queues) are purged
+ * if/when a server restarts. Note that durable queues do not necessarily
hold persistent
+ * messages, although it does not make sense to send persistent messages
to a transient
+ * queue.
+ * <li> [EMAIL PROTECTED] Option#EXCLUSIVE}: <p> Exclusive queues can
only be used from one connection at a time.
+ * Once a connection declares an exclusive queue, that queue cannot be
used by any other connections until the
+ * declaring connection closes.
+ * <li> [EMAIL PROTECTED] Option#PASSIVE}: <p> If set, the server will not
create the queue.
+ * This field allows the client to assert the presence of a queue without
modifying the server state.
+ * <li>[EMAIL PROTECTED] Option#NO_OPTION}: <p> Has no effect as it
represents an empty option.
* </ul>
- * </p>
- * <p/>
* <p>In the absence of a particular option, the defaul value is false for
each option
*
* @param queueName The name of the delcared queue.
* @param alternateExchange If a message is rejected by a queue, then it
is sent to the alternate-exchange. A message
* may be rejected by a queue for the following
reasons:
* <oL> <li> The queue is deleted when it is not
empty;
- * <<li> Immediate delivery of a message is
requested, but there are no consumers connected to
+ * <li> Immediate delivery of a message is
requested, but there are no consumers connected to
* the queue. </ol>
* @param arguments Used for backward compatibility
- * @param options Set of Options.
+ * @param options Set of Options ( valide options are: [EMAIL
PROTECTED] Option#AUTO_DELETE}, [EMAIL PROTECTED] Option#DURABLE},
+ * [EMAIL PROTECTED] Option#EXCLUSIVE}, [EMAIL
PROTECTED] Option#PASSIVE} and [EMAIL PROTECTED] Option#NO_OPTION})
* @see Option
*/
public void queueDeclare(String queueName, String alternateExchange,
Map<String, ?> arguments, Option... options);
@@ -419,9 +489,16 @@
/**
* Bind a queue with an exchange.
*
- * @param queueName The queue to be bound.
+ * @param queueName Specifies the name of the queue to bind. If the
queue name is empty, refers to the current
+ * queue for the session, which is the last declared
queue.
* @param exchangeName The exchange name.
- * @param routingKey The routing key.
+ * @param routingKey Specifies the routing key for the binding. The
routing key is used for routing messages
+ * depending on the exchange configuration. Not all
exchanges use a routing key - refer to
+ * the specific exchange documentation. If the queue
name is empty, the server uses the last
+ * queue declared on the session. If the routing key
is also empty, the server uses this
+ * queue name for the routing key as well. If the
queue name is provided but the routing key
+ * is empty, the server does the binding with that
empty routing key. The meaning of empty
+ * routing keys depends on the exchange implementation.
* @param arguments Used for backward compatibility
*/
public void queueBind(String queueName, String exchangeName, String
routingKey, Map<String, ?> arguments);
@@ -429,37 +506,42 @@
/**
* Unbind a queue from an exchange.
*
- * @param queueName The queue to be unbound.
- * @param exchangeName The exchange name.
- * @param routingKey The routing key.
+ * @param queueName Specifies the name of the queue to unbind.
+ * @param exchangeName The name of the exchange to unbind from.
+ * @param routingKey Specifies the routing key of the binding to unbind.
* @param arguments Used for backward compatibility
*/
public void queueUnbind(String queueName, String exchangeName, String
routingKey, Map<String, ?> arguments);
/**
- * Purge a queue. i.e. delete all enqueued messages
+ * This method removes all messages from a queue. It does not cancel
consumers. Purged messages
+ * are deleted without any formal "undo" mechanism.
*
- * @param queueName The queue to be purged
+ * @param queueName Specifies the name of the queue to purge. If the queue
name is empty, refers to the
+ * current queue for the session, which is the last
declared queue.
*/
public void queuePurge(String queueName);
/**
- * Delet a queue.
- * <p> Following are the valid options for createReceive
+ * This method deletes a queue. When a queue is deleted any pending
messages are sent to a
+ * dead-letter queue if this is defined in the server configuration, and
all consumers on the
+ * queue are cancelled.
+ * <p> Following are the valid options:
* <ul>
- * <li> IF_EMPTY
- * <li> IF_UNUSE
- * <li> NO_WAIT
+ * <li> [EMAIL PROTECTED] Option#IF_EMPTY}: <p> If set, the server will
only delete the queue if it has no messages.
+ * <li> [EMAIL PROTECTED] Option#IF_UNUSED}: <p> If set, the server will
only delete the queue if it has no consumers.
+ * If the queue has consumers the server does does not delete it but
raises a channel exception instead.
+ * <li>[EMAIL PROTECTED] Option#NO_OPTION}: <p> Has no effect as it
represents an empty option.
* </ul>
* </p>
* <p/>
* <p>In the absence of a particular option, the defaul value is false for
each option</p>
*
- * @param queueName The name of the queue to be deleted
- * @param options Set of options
+ * @param queueName Specifies the name of the queue to delete. If the
queue name is empty, refers to the
+ * current queue for the session, which is the last
declared queue.
+ * @param options Set of options (Valid options are: [EMAIL PROTECTED]
Option#IF_EMPTY}, [EMAIL PROTECTED] Option#IF_UNUSED}
+ * and [EMAIL PROTECTED] Option#NO_OPTION})
* @see Option
- * <p/>
- * Following are the valid options
*/
public void queueDelete(String queueName, Option... options);
@@ -468,48 +550,53 @@
// --------------------------------------
/**
- * Declare an exchange.
- * <p> Following are the valid options for createReceive
+ * This method creates an exchange if it does not already exist, and if
the exchange exists,
+ * verifies that it is of the correct and expected class.
+ * <p> Following are the valid options:
* <ul>
- * <li> AUTO_DELETE
- * <li> DURABLE
- * <li> INTERNAL
- * <li> NO_WAIT
- * <li> PASSIVE
+ * <li> [EMAIL PROTECTED] Option#AUTO_DELETE}: <p> If set, the exchange is
deleted when all queues have finished using it.
+ * <li> [EMAIL PROTECTED] Option#DURABLE}: <p> If set when creating a new
exchange, the exchange will
+ * be marked as durable. Durable exchanges remain active when a server
restarts. Non-durable exchanges (transient
+ * exchanges) are purged if/when a server restarts.
+ * <li> [EMAIL PROTECTED] Option#PASSIVE}: <p> If set, the server will not
create the exchange.
+ * The client can use this to check whether an exchange exists without
modifying the server state.
+ * <li> [EMAIL PROTECTED] Option#NO_OPTION}: <p> Has no effect as it
represents an empty option.
* </ul>
- * </p>
- * <p/>
- * <p>In the absence of a particular option, the defaul value is false for
each option</p> *
+ * <p>In the absence of a particular option, the defaul value is false for
each option</p>
*
* @param exchangeName The exchange name.
- * @param exchangeClass The fully qualified name of the exchange class.
+ * @param type Each exchange belongs to one of a set of
exchange types implemented by the server. The
+ * exchange types define the functionality of the
exchange - i.e. how messages are routed
+ * through it. It is not valid or meaningful to
attempt to change the type of an existing
+ * exchange.
* @param alternateExchange In the event that a message cannot be routed,
this is the name of the exchange to which
* the message will be sent.
- * @param options Set of options.
+ * @param options Set of options (valid options are: [EMAIL
PROTECTED] Option#AUTO_DELETE}, [EMAIL PROTECTED] Option#DURABLE},
+ * [EMAIL PROTECTED] Option#PASSIVE}, [EMAIL
PROTECTED] Option#NO_OPTION})
* @param arguments Used for backward compatibility
* @see Option
*/
- public void exchangeDeclare(String exchangeName, String exchangeClass,
String alternateExchange,
- Map<String, ?> arguments, Option... options);
+ public void exchangeDeclare(String exchangeName, String type, String
alternateExchange, Map<String, ?> arguments,
+ Option... options);
/**
- * Delete an exchange.
- * <p> Following are the valid options for createReceive
+ * This method deletes an exchange. When an exchange is deleted all queue
bindings on the
+ * exchange are cancelled.
+ * <p> Following are the valid options:
* <ul>
- * <li> IF_UNUSEDL
- * <li> NO_WAIT
+ * <li> [EMAIL PROTECTED] Option#IF_UNUSED}: <p> If set, the server will
only delete the exchange if it has no queue bindings. If the
+ * exchange has queue bindings the server does not delete it but raises a
channel exception
+ * instead.
+ * <li> [EMAIL PROTECTED] Option#NO_OPTION}: <p> Has no effect as it
represents an empty option.
* </ul>
- * </p>
- * <p/>
* <p>In the absence of a particular option, the defaul value is false for
each option
- * Immediately deleted even if it is used by another resources.</p>
*
* @param exchangeName The name of exchange to be deleted.
- * @param options Set of options.
+ * @param options Set of options (valid options are: [EMAIL
PROTECTED] Option#IF_UNUSED}, [EMAIL PROTECTED] Option#NO_OPTION})
* @see Option
*/
public void exchangeDelete(String exchangeName, Option... options);
-
+
/**
* If the session receives a sessionClosed with an error code it
* informs the session's ExceptionListener
