With all the talk of Sun License, I decided to examine and rework the
JMS files to provide a clean[er] room implementation.
Brent Worden
http://www.brent.worden.org/
Index: specs/jms/src/java/javax/jms/BytesMessage.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/BytesMessage.java,v
retrieving revision 1.1
diff -u -r1.1 BytesMessage.java
--- specs/jms/src/java/javax/jms/BytesMessage.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/BytesMessage.java 19 Aug 2003 23:12:48
-0000
@@ -62,523 +62,61 @@
package javax.jms;
-
-/** A <CODE>BytesMessage</CODE> object is used to send a message containing a
- * stream of uninterpreted bytes. It inherits from the <CODE>Message</CODE>
- * interface and adds a bytes
- * message body. The receiver of the message supplies the interpretation
- * of the bytes.
- *
- * <P>The <CODE>BytesMessage</CODE> methods are based largely on those found in
- * <CODE>java.io.DataInputStream</CODE> and
- * <CODE>java.io.DataOutputStream</CODE>.
- *
- * <P>This message type is for client encoding of existing message formats.
- * If possible, one of the other self-defining message types should be used
- * instead.
- *
- * <P>Although the JMS API allows the use of message properties with byte
- * messages, they are typically not used, since the inclusion of properties
- * may affect the format.
- *
- * <P>The primitive types can be written explicitly using methods
- * for each type. They may also be written generically as objects.
- * For instance, a call to <CODE>BytesMessage.writeInt(6)</CODE> is
- * equivalent to <CODE>BytesMessage.writeObject(new Integer(6))</CODE>.
- * Both forms are provided, because the explicit form is convenient for
- * static programming, and the object form is needed when types are not known
- * at compile time.
- *
- * <P>When the message is first created, and when <CODE>clearBody</CODE>
- * is called, the body of the message is in write-only mode. After the
- * first call to <CODE>reset</CODE> has been made, the message body is in
- * read-only mode.
- * After a message has been sent, the client that sent it can retain and
- * modify it without affecting the message that has been sent. The same message
- * object can be sent multiple times.
- * When a message has been received, the provider has called
- * <CODE>reset</CODE> so that the message body is in read-only mode for the
client.
- *
- * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode,
- * the message body is cleared and the message is in write-only mode.
- *
- * <P>If a client attempts to read a message in write-only mode, a
- * <CODE>MessageNotReadableException</CODE> is thrown.
- *
- * <P>If a client attempts to write a message in read-only mode, a
- * <CODE>MessageNotWriteableException</CODE> is thrown.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session#createBytesMessage()
- * @see javax.jms.MapMessage
- * @see javax.jms.Message
- * @see javax.jms.ObjectMessage
- * @see javax.jms.StreamMessage
- * @see javax.jms.TextMessage
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface BytesMessage extends Message {
-
- /** Gets the number of bytes of the message body when the message
- * is in read-only mode. The value returned can be used to allocate
- * a byte array. The value returned is the entire length of the message
- * body, regardless of where the pointer for reading the message
- * is currently located.
- *
- * @return number of bytes in the message
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- * @since 1.1
- */
-
long getBodyLength() throws JMSException;
- /** Reads a <code>boolean</code> from the bytes message stream.
- *
- * @return the <code>boolean</code> value read
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
-
boolean readBoolean() throws JMSException;
-
- /** Reads a signed 8-bit value from the bytes message stream.
- *
- * @return the next byte from the bytes message stream as a signed 8-bit
- * <code>byte</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
byte readByte() throws JMSException;
-
- /** Reads an unsigned 8-bit number from the bytes message stream.
- *
- * @return the next byte from the bytes message stream, interpreted as an
- * unsigned 8-bit number
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
int readUnsignedByte() throws JMSException;
-
- /** Reads a signed 16-bit number from the bytes message stream.
- *
- * @return the next two bytes from the bytes message stream, interpreted as
- * a signed 16-bit number
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
short readShort() throws JMSException;
-
- /** Reads an unsigned 16-bit number from the bytes message stream.
- *
- * @return the next two bytes from the bytes message stream, interpreted as
- * an unsigned 16-bit integer
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
int readUnsignedShort() throws JMSException;
-
- /** Reads a Unicode character value from the bytes message stream.
- *
- * @return the next two bytes from the bytes message stream as a Unicode
- * character
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
char readChar() throws JMSException;
-
- /** Reads a signed 32-bit integer from the bytes message stream.
- *
- * @return the next four bytes from the bytes message stream, interpreted
- * as an <code>int</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
int readInt() throws JMSException;
-
- /** Reads a signed 64-bit integer from the bytes message stream.
- *
- * @return the next eight bytes from the bytes message stream, interpreted
- * as a <code>long</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
long readLong() throws JMSException;
-
- /** Reads a <code>float</code> from the bytes message stream.
- *
- * @return the next four bytes from the bytes message stream, interpreted
- * as a <code>float</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
float readFloat() throws JMSException;
-
- /** Reads a <code>double</code> from the bytes message stream.
- *
- * @return the next eight bytes from the bytes message stream, interpreted
- * as a <code>double</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
double readDouble() throws JMSException;
-
- /** Reads a string that has been encoded using a modified UTF-8
- * format from the bytes message stream.
- *
- * <P>For more information on the UTF-8 format, see "File System Safe
- * UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification,
- * X/Open Company Ltd., Document Number: P316. This information also
- * appears in ISO/IEC 10646, Annex P.
- *
- * @return a Unicode string from the bytes message stream
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of bytes stream has
- * been reached.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
String readUTF() throws JMSException;
-
- /** Reads a byte array from the bytes message stream.
- *
- * <P>If the length of array <code>value</code> is less than the number of
- * bytes remaining to be read from the stream, the array should
- * be filled. A subsequent call reads the next increment, and so on.
- *
- * <P>If the number of bytes remaining in the stream is less than the
- * length of
- * array <code>value</code>, the bytes should be read into the array.
- * The return value of the total number of bytes read will be less than
- * the length of the array, indicating that there are no more bytes left
- * to be read from the stream. The next read of the stream returns -1.
- *
- * @param value the buffer into which the data is read
- *
- * @return the total number of bytes read into the buffer, or -1 if
- * there is no more data because the end of the stream has been reached
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
int readBytes(byte[] value) throws JMSException;
-
- /** Reads a portion of the bytes message stream.
- *
- * <P>If the length of array <code>value</code> is less than the number of
- * bytes remaining to be read from the stream, the array should
- * be filled. A subsequent call reads the next increment, and so on.
- *
- * <P>If the number of bytes remaining in the stream is less than the
- * length of
- * array <code>value</code>, the bytes should be read into the array.
- * The return value of the total number of bytes read will be less than
- * the length of the array, indicating that there are no more bytes left
- * to be read from the stream. The next read of the stream returns -1.
- *
- * <p> If <code>length</code> is negative, or
- * <code>length</code> is greater than the length of the array
- * <code>value</code>, then an <code>IndexOutOfBoundsException</code> is
- * thrown. No bytes will be read from the stream for this exception case.
- *
- * @param value the buffer into which the data is read
- * @param length the number of bytes to read; must be less than or equal to
- * <code>value.length</code>
- *
- * @return the total number of bytes read into the buffer, or -1 if
- * there is no more data because the end of the stream has been reached
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
int readBytes(byte[] value, int length) throws JMSException;
-
- /** Writes a <code>boolean</code> to the bytes message stream as a 1-byte
- * value.
- * The value <code>true</code> is written as the value
- * <code>(byte)1</code>; the value <code>false</code> is written as
- * the value <code>(byte)0</code>.
- *
- * @param value the <code>boolean</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeBoolean(boolean value) throws JMSException;
-
- /** Writes a <code>byte</code> to the bytes message stream as a 1-byte
- * value.
- *
- * @param value the <code>byte</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeByte(byte value) throws JMSException;
-
- /** Writes a <code>short</code> to the bytes message stream as two bytes,
- * high byte first.
- *
- * @param value the <code>short</code> to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeShort(short value) throws JMSException;
-
- /** Writes a <code>char</code> to the bytes message stream as a 2-byte
- * value, high byte first.
- *
- * @param value the <code>char</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeChar(char value) throws JMSException;
-
- /** Writes an <code>int</code> to the bytes message stream as four bytes,
- * high byte first.
- *
- * @param value the <code>int</code> to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeInt(int value) throws JMSException;
-
- /** Writes a <code>long</code> to the bytes message stream as eight bytes,
- * high byte first.
- *
- * @param value the <code>long</code> to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeLong(long value) throws JMSException;
-
- /** Converts the <code>float</code> argument to an <code>int</code> using
- * the
- * <code>floatToIntBits</code> method in class <code>Float</code>,
- * and then writes that <code>int</code> value to the bytes message
- * stream as a 4-byte quantity, high byte first.
- *
- * @param value the <code>float</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeFloat(float value) throws JMSException;
-
- /** Converts the <code>double</code> argument to a <code>long</code> using
- * the
- * <code>doubleToLongBits</code> method in class <code>Double</code>,
- * and then writes that <code>long</code> value to the bytes message
- * stream as an 8-byte quantity, high byte first.
- *
- * @param value the <code>double</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeDouble(double value) throws JMSException;
-
- /** Writes a string to the bytes message stream using UTF-8 encoding in a
- * machine-independent manner.
- *
- * <P>For more information on the UTF-8 format, see "File System Safe
- * UCS Transformation Format (FSS_UTF)", X/Open Preliminary Specification,
- * X/Open Company Ltd., Document Number: P316. This information also
- * appears in ISO/IEC 10646, Annex P.
- *
- * @param value the <code>String</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeUTF(String value) throws JMSException;
-
- /** Writes a byte array to the bytes message stream.
- *
- * @param value the byte array to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeBytes(byte[] value) throws JMSException;
-
- /** Writes a portion of a byte array to the bytes message stream.
- *
- * @param value the byte array value to be written
- * @param offset the initial offset within the byte array
- * @param length the number of bytes to use
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeBytes(byte[] value, int offset, int length) throws JMSException;
-
- /** Writes an object to the bytes message stream.
- *
- * <P>This method works only for the objectified primitive
- * object types (<code>Integer</code>, <code>Double</code>,
- * <code>Long</code> ...), <code>String</code> objects, and byte
- * arrays.
- *
- * @param value the object in the Java programming language ("Java
- * object") to be written; it must not be null
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageFormatException if the object is of an invalid type.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- * @exception java.lang.NullPointerException if the parameter
- * <code>value</code> is null.
- */
-
void writeObject(Object value) throws JMSException;
-
-
- /** Puts the message body in read-only mode and repositions the stream of
- * bytes to the beginning.
- *
- * @exception JMSException if the JMS provider fails to reset the message
- * due to some internal error.
- * @exception MessageFormatException if the message has an invalid
- * format.
- */
void reset() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/Connection.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/Connection.java,v
retrieving revision 1.1
diff -u -r1.1 Connection.java
--- specs/jms/src/java/javax/jms/Connection.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/Connection.java 19 Aug 2003 23:12:48
-0000
@@ -62,371 +62,41 @@
package javax.jms;
-/** A <CODE>Connection</CODE> object is a client's active connection to its JMS
- * provider. It typically allocates provider resources outside the Java virtual
- * machine (JVM).
- *
- * <P>Connections support concurrent use.
- *
- * <P>A connection serves several purposes:
- *
- * <UL>
- * <LI>It encapsulates an open connection with a JMS provider. It
- * typically represents an open TCP/IP socket between a client and
- * the service provider software.
- * <LI>Its creation is where client authentication takes place.
- * <LI>It can specify a unique client identifier.
- * <LI>It provides a <CODE>ConnectionMetaData</CODE> object.
- * <LI>It supports an optional <CODE>ExceptionListener</CODE> object.
- * </UL>
- *
- * <P>Because the creation of a connection involves setting up authentication
- * and communication, a connection is a relatively heavyweight
- * object. Most clients will do all their messaging with a single connection.
- * Other more advanced applications may use several connections. The JMS API
- * does
- * not architect a reason for using multiple connections; however, there may
- * be operational reasons for doing so.
- *
- * <P>A JMS client typically creates a connection, one or more sessions,
- * and a number of message producers and consumers. When a connection is
- * created, it is in stopped mode. That means that no messages are being
- * delivered.
- *
- * <P>It is typical to leave the connection in stopped mode until setup
- * is complete (that is, until all message consumers have been
- * created). At that point, the client calls
- * the connection's <CODE>start</CODE> method, and messages begin arriving at
- * the connection's consumers. This setup
- * convention minimizes any client confusion that may result from
- * asynchronous message delivery while the client is still in the process
- * of setting itself up.
- *
- * <P>A connection can be started immediately, and the setup can be done
- * afterwards. Clients that do this must be prepared to handle asynchronous
- * message delivery while they are still in the process of setting up.
- *
- * <P>A message producer can send messages while a connection is stopped.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.ConnectionFactory
- * @see javax.jms.QueueConnection
- * @see javax.jms.TopicConnection
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface Connection {
+ Session createSession(boolean transacted, int acknowledgeMode)
+ throws JMSException;
- /** Creates a <CODE>Session</CODE> object.
- *
- * @param transacted indicates whether the session is transacted
- * @param acknowledgeMode indicates whether the consumer or the
- * client will acknowledge any messages it receives; ignored if the session
- * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
- * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
- * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
- *
- * @return a newly created session
- *
- * @exception JMSException if the <CODE>Connection</CODE> object fails
- * to create a session due to some internal error
or
- * lack of support for the specific transaction
- * and acknowledgement mode.
- * @since 1.1
- *
- * @see Session#AUTO_ACKNOWLEDGE
- * @see Session#CLIENT_ACKNOWLEDGE
- * @see Session#DUPS_OK_ACKNOWLEDGE
-
- */
-
- Session createSession(boolean transacted, int acknowledgeMode) throws
JMSException;
-
-
- /** Gets the client identifier for this connection.
- *
- * <P>This value is specific to the JMS provider. It is either
preconfigured
- * by an administrator in a <CODE>ConnectionFactory</CODE> object
- * or assigned dynamically by the application by calling the
- * <code>setClientID</code> method.
- *
- *
- * @return the unique client identifier
- *
- * @exception JMSException if the JMS provider fails to return
- * the client ID for this connection due
- * to some internal error.
- *
- **/
String getClientID() throws JMSException;
-
- /** Sets the client identifier for this connection.
- *
- * <P>The preferred way to assign a JMS client's client identifier is for
- * it to be configured in a client-specific <CODE>ConnectionFactory</CODE>
- * object and transparently assigned to the <CODE>Connection</CODE> object
- * it creates.
- *
- * <P>Alternatively, a client can set a connection's client identifier
- * using a provider-specific value. The facility to set a connection's
- * client identifier explicitly is not a mechanism for overriding the
- * identifier that has been administratively configured. It is provided
- * for the case where no administratively specified identifier exists.
- * If one does exist, an attempt to change it by setting it must throw an
- * <CODE>IllegalStateException</CODE>. If a client sets the client
identifier
- * explicitly, it must do so immediately after it creates the connection
- * and before any other
- * action on the connection is taken. After this point, setting the
- * client identifier is a programming error that should throw an
- * <CODE>IllegalStateException</CODE>.
- *
- * <P>The purpose of the client identifier is to associate a connection and
- * its objects with a state maintained on behalf of the client by a
- * provider. The only such state identified by the JMS API is that required
- * to support durable subscriptions.
- *
- * <P>If another connection with the same <code>clientID</code> is already
running when
- * this method is called, the JMS provider should detect the duplicate ID
and throw
- * an <CODE>InvalidClientIDException</CODE>.
- *
- * @param clientID the unique client identifier
- *
- * @exception JMSException if the JMS provider fails to
- * set the client ID for this connection due
- * to some internal error.
- *
- * @exception InvalidClientIDException if the JMS client specifies an
- * invalid or duplicate client ID.
- * @exception IllegalStateException if the JMS client attempts to set
- * a connection's client ID at the wrong time or
- * when it has been administratively configured.
- */
-
void setClientID(String clientID) throws JMSException;
-
- /** Gets the metadata for this connection.
- *
- * @return the connection metadata
- *
- * @exception JMSException if the JMS provider fails to
- * get the connection metadata for this connection.
- *
- * @see javax.jms.ConnectionMetaData
- */
-
ConnectionMetaData getMetaData() throws JMSException;
- /**
- * Gets the <CODE>ExceptionListener</CODE> object for this connection.
- * Not every <CODE>Connection</CODE> has an <CODE>ExceptionListener</CODE>
- * associated with it.
- *
- * @return the <CODE>ExceptionListener</CODE> for this connection, or null.
- * if no <CODE>ExceptionListener</CODE> is associated
- * with this connection.
- *
- * @exception JMSException if the JMS provider fails to
- * get the <CODE>ExceptionListener</CODE> for this
- * connection.
- * @see javax.jms.Connection#setExceptionListener
- */
-
ExceptionListener getExceptionListener() throws JMSException;
-
- /** Sets an exception listener for this connection.
- *
- * <P>If a JMS provider detects a serious problem with a connection, it
- * informs the connection's <CODE>ExceptionListener</CODE>, if one has been
- * registered. It does this by calling the listener's
- * <CODE>onException</CODE> method, passing it a <CODE>JMSException</CODE>
- * object describing the problem.
- *
- * <P>An exception listener allows a client to be notified of a problem
- * asynchronously.
- * Some connections only consume messages, so they would have no other
- * way to learn their connection has failed.
- *
- * <P>A connection serializes execution of its
- * <CODE>ExceptionListener</CODE>.
- *
- * <P>A JMS provider should attempt to resolve connection problems
- * itself before it notifies the client of them.
- *
- * @param listener the exception listener
- *
- * @exception JMSException if the JMS provider fails to
- * set the exception listener for this connection.
- *
- */
-
void setExceptionListener(ExceptionListener listener) throws JMSException;
- /** Starts (or restarts) a connection's delivery of incoming messages.
- * A call to <CODE>start</CODE> on a connection that has already been
- * started is ignored.
- *
- * @exception JMSException if the JMS provider fails to start
- * message delivery due to some internal error.
- *
- * @see javax.jms.Connection#stop
- */
-
void start() throws JMSException;
-
- /** Temporarily stops a connection's delivery of incoming messages.
- * Delivery can be restarted using the connection's <CODE>start</CODE>
- * method. When the connection is stopped,
- * delivery to all the connection's message consumers is inhibited:
- * synchronous receives block, and messages are not delivered to message
- * listeners.
- *
- * <P>This call blocks until receives and/or message listeners in progress
- * have completed.
- *
- * <P>Stopping a connection has no effect on its ability to send messages.
- * A call to <CODE>stop</CODE> on a connection that has already been
- * stopped is ignored.
- *
- * <P>A call to <CODE>stop</CODE> must not return until delivery of
messages
- * has paused. This means that a client can rely on the fact that none of
- * its message listeners will be called and that all threads of control
- * waiting for <CODE>receive</CODE> calls to return will not return with a
- * message until the
- * connection is restarted. The receive timers for a stopped connection
- * continue to advance, so receives may time out while the connection is
- * stopped.
- *
- * <P>If message listeners are running when <CODE>stop</CODE> is invoked,
- * the <CODE>stop</CODE> call must
- * wait until all of them have returned before it may return. While these
- * message listeners are completing, they must have the full services of
the
- * connection available to them.
- *
- * @exception JMSException if the JMS provider fails to stop
- * message delivery due to some internal error.
- *
- * @see javax.jms.Connection#start
- */
-
void stop() throws JMSException;
-
- /** Closes the connection.
- *
- * <P>Since a provider typically allocates significant resources outside
- * the JVM on behalf of a connection, clients should close these resources
- * when they are not needed. Relying on garbage collection to eventually
- * reclaim these resources may not be timely enough.
- *
- * <P>There is no need to close the sessions, producers, and consumers
- * of a closed connection.
- *
- * <P>Closing a connection causes all temporary destinations to be
- * deleted.
- *
- * <P>When this method is invoked, it should not return until message
- * processing has been shut down in an orderly fashion. This means that all
- * message
- * listeners that may have been running have returned, and that all pending
- * receives have returned. A close terminates all pending message receives
- * on the connection's sessions' consumers. The receives may return with a
- * message or with null, depending on whether there was a message available
- * at the time of the close. If one or more of the connection's sessions'
- * message listeners is processing a message at the time when connection
- * <CODE>close</CODE> is invoked, all the facilities of the connection and
- * its sessions must remain available to those listeners until they return
- * control to the JMS provider.
- *
- * <P>Closing a connection causes any of its sessions' transactions
- * in progress to be rolled back. In the case where a session's
- * work is coordinated by an external transaction manager, a session's
- * <CODE>commit</CODE> and <CODE>rollback</CODE> methods are
- * not used and the result of a closed session's work is determined
- * later by the transaction manager.
- *
- * Closing a connection does NOT force an
- * acknowledgment of client-acknowledged sessions.
- *
- * <P>Invoking the <CODE>acknowledge</CODE> method of a received message
- * from a closed connection's session must throw an
- * <CODE>IllegalStateException</CODE>. Closing a closed connection must
- * NOT throw an exception.
- *
- * @exception JMSException if the JMS provider fails to close the
- * connection due to some internal error. For
- * example, a failure to release resources
- * or to close a socket connection can cause
- * this exception to be thrown.
- *
- */
-
void close() throws JMSException;
- /** Creates a connection consumer for this connection (optional operation).
- * This is an expert facility not used by regular JMS clients.
- *
- * @param destination the destination to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param sessionPool the server session pool to associate with this
- * connection consumer
- * @param maxMessages the maximum number of messages that can be
- * assigned to a server session at one time
- *
- * @return the connection consumer
- *
- * @exception JMSException if the <CODE>Connection</CODE> object fails
- * to create a connection consumer due to some
- * internal error or invalid arguments for
- * <CODE>sessionPool</CODE> and
- * <CODE>messageSelector</CODE>.
- * @exception InvalidDestinationException if an invalid destination is
specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- *
- * @since 1.1
- * @see javax.jms.ConnectionConsumer
- */
-
- ConnectionConsumer createConnectionConsumer(Destination destination,
String messageSelector, ServerSessionPool sessionPool, int maxMessages) throws
JMSException;
-
-
- /** Create a durable connection consumer for this connection (optional
operation).
- * This is an expert facility not used by regular JMS clients.
- *
- * @param topic topic to access
- * @param subscriptionName durable subscription name
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param sessionPool the server session pool to associate with this
- * durable connection consumer
- * @param maxMessages the maximum number of messages that can be
- * assigned to a server session at one time
- *
- * @return the durable connection consumer
- *
- * @exception JMSException if the <CODE>Connection</CODE> object fails
- * to create a connection consumer due to some
- * internal error or invalid arguments for
- * <CODE>sessionPool</CODE> and
- * <CODE>messageSelector</CODE>.
- * @exception InvalidDestinationException if an invalid destination
- * is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- * @since 1.1
- * @see javax.jms.ConnectionConsumer
- */
-
- ConnectionConsumer createDurableConnectionConsumer(Topic topic, String
subscriptionName, String messageSelector, ServerSessionPool sessionPool, int
maxMessages) throws JMSException;
+ ConnectionConsumer createConnectionConsumer(
+ Destination destination,
+ String messageSelector,
+ ServerSessionPool sessionPool,
+ int maxMessages)
+ throws JMSException;
+
+ ConnectionConsumer createDurableConnectionConsumer(
+ Topic topic,
+ String subscriptionName,
+ String messageSelector,
+ ServerSessionPool sessionPool,
+ int maxMessages)
+ throws JMSException;
}
-
Index: specs/jms/src/java/javax/jms/ConnectionConsumer.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ConnectionConsumer.java,v
retrieving revision 1.1
diff -u -r1.1 ConnectionConsumer.java
--- specs/jms/src/java/javax/jms/ConnectionConsumer.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/ConnectionConsumer.java 19 Aug 2003
23:12:48 -0000
@@ -62,62 +62,11 @@
package javax.jms;
-/** For application servers, <CODE>Connection</CODE> objects provide a special
- * facility
- * for creating a <CODE>ConnectionConsumer</CODE> (optional). The messages it
- * is to consume are
- * specified by a <CODE>Destination</CODE> and a message selector. In addition,
- * a <CODE>ConnectionConsumer</CODE> must be given a
- * <CODE>ServerSessionPool</CODE> to use for
- * processing its messages.
- *
- * <P>Normally, when traffic is light, a <CODE>ConnectionConsumer</CODE> gets a
- * <CODE>ServerSession</CODE> from its pool, loads it with a single message,
and
- * starts it. As traffic picks up, messages can back up. If this happens,
- * a <CODE>ConnectionConsumer</CODE> can load each <CODE>ServerSession</CODE>
- * with more than one
- * message. This reduces the thread context switches and minimizes resource
- * use at the expense of some serialization of message processing.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.Connection#createConnectionConsumer
- * @see javax.jms.Connection#createDurableConnectionConsumer
- * @see javax.jms.QueueConnection#createConnectionConsumer
- * @see javax.jms.TopicConnection#createConnectionConsumer
- * @see javax.jms.TopicConnection#createDurableConnectionConsumer
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ConnectionConsumer {
+ ServerSessionPool getServerSessionPool() throws JMSException;
- /** Gets the server session pool associated with this connection consumer.
- *
- * @return the server session pool used by this connection consumer
- *
- * @exception JMSException if the JMS provider fails to get the server
- * session pool associated with this consumer due
- * to some internal error.
- */
-
- ServerSessionPool
- getServerSessionPool() throws JMSException;
-
-
- /** Closes the connection consumer.
- *
- * <P>Since a provider may allocate some resources on behalf of a
- * connection consumer outside the Java virtual machine, clients should
- * close these resources when
- * they are not needed. Relying on garbage collection to eventually
- * reclaim these resources may not be timely enough.
- *
- * @exception JMSException if the JMS provider fails to release resources
- * on behalf of the connection consumer or fails
- * to close the connection consumer.
- */
-
- void
- close() throws JMSException;
+ void close() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/ConnectionFactory.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ConnectionFactory.java,v
retrieving revision 1.1
diff -u -r1.1 ConnectionFactory.java
--- specs/jms/src/java/javax/jms/ConnectionFactory.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/ConnectionFactory.java 19 Aug 2003 23:12:48
-0000
@@ -62,101 +62,12 @@
package javax.jms;
-/** A <CODE>ConnectionFactory</CODE> object encapsulates a set of connection
- * configuration
- * parameters that has been defined by an administrator. A client uses
- * it to create a connection with a JMS provider.
- *
- * <P>A <CODE>ConnectionFactory</CODE> object is a JMS administered object and
- * supports concurrent use.
- *
- * <P>JMS administered objects are objects containing configuration
- * information that are created by an administrator and later used by
- * JMS clients. They make it practical to administer the JMS API in the
- * enterprise.
- *
- * <P>Although the interfaces for administered objects do not explicitly
- * depend on the Java Naming and Directory Interface (JNDI) API, the JMS API
- * establishes the convention that JMS clients find administered objects by
- * looking them up in a JNDI namespace.
- *
- * <P>An administrator can place an administered object anywhere in a
- * namespace. The JMS API does not define a naming policy.
- *
- * <P>It is expected that JMS providers will provide the tools an
- * administrator needs to create and configure administered objects in a
- * JNDI namespace. JMS provider implementations of administered objects
- * should be both <CODE>javax.jndi.Referenceable</CODE> and
- * <CODE>java.io.Serializable</CODE> so that they can be stored in all
- * JNDI naming contexts. In addition, it is recommended that these
- * implementations follow the JavaBeans<SUP><FONT SIZE="-2">TM</FONT></SUP>
- * design patterns.
- *
- * <P>This strategy provides several benefits:
- *
- * <UL>
- * <LI>It hides provider-specific details from JMS clients.
- * <LI>It abstracts administrative information into objects in the Java
- * programming language ("Java objects")
- * that are easily organized and administered from a common
- * management console.
- * <LI>Since there will be JNDI providers for all popular naming
- * services, this means that JMS providers can deliver one implementation
- * of administered objects that will run everywhere.
- * </UL>
- *
- * <P>An administered object should not hold on to any remote resources.
- * Its lookup should not use remote resources other than those used by the
- * JNDI API itself.
- *
- * <P>Clients should think of administered objects as local Java objects.
- * Looking them up should not have any hidden side effects or use surprising
- * amounts of local resources.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Connection
- * @see javax.jms.QueueConnectionFactory
- * @see javax.jms.TopicConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ConnectionFactory {
- /** Creates a connection with the default user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @return a newly created connection
- *
- * @exception JMSException if the JMS provider fails to create the
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- * @since 1.1
- */
-
Connection createConnection() throws JMSException;
-
- /** Creates a connection with the specified user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @param userName the caller's user name
- * @param password the caller's password
- *
- * @return a newly created connection
- *
- * @exception JMSException if the JMS provider fails to create the
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- * @since 1.1
- */
-
- Connection createConnection(String userName, String password) throws
JMSException;
+ Connection createConnection(String userName, String password)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/ConnectionMetaData.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ConnectionMetaData.java,v
retrieving revision 1.1
diff -u -r1.1 ConnectionMetaData.java
--- specs/jms/src/java/javax/jms/ConnectionMetaData.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/ConnectionMetaData.java 19 Aug 2003
23:12:48 -0000
@@ -64,100 +64,24 @@
import java.util.Enumeration;
-/** A <CODE>ConnectionMetaData</CODE> object provides information describing
the
- * <CODE>Connection</CODE> object.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ConnectionMetaData {
- /** Gets the JMS API version.
- *
- * @return the JMS API version
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
String getJMSVersion() throws JMSException;
-
- /** Gets the JMS major version number.
- *
- * @return the JMS API major version number
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
int getJMSMajorVersion() throws JMSException;
-
- /** Gets the JMS minor version number.
- *
- * @return the JMS API minor version number
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
int getJMSMinorVersion() throws JMSException;
-
- /** Gets the JMS provider name.
- *
- * @return the JMS provider name
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
String getJMSProviderName() throws JMSException;
-
- /** Gets the JMS provider version.
- *
- * @return the JMS provider version
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
String getProviderVersion() throws JMSException;
-
- /** Gets the JMS provider major version number.
- *
- * @return the JMS provider major version number
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
int getProviderMajorVersion() throws JMSException;
-
- /** Gets the JMS provider minor version number.
- *
- * @return the JMS provider minor version number
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
-
int getProviderMinorVersion() throws JMSException;
-
-
- /** Gets an enumeration of the JMSX property names.
- *
- * @return an Enumeration of JMSX property names
- *
- * @exception JMSException if the JMS provider fails to retrieve the
- * metadata due to some internal error.
- */
Enumeration getJMSXPropertyNames() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/DeliveryMode.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/DeliveryMode.java,v
retrieving revision 1.1
diff -u -r1.1 DeliveryMode.java
--- specs/jms/src/java/javax/jms/DeliveryMode.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/DeliveryMode.java 19 Aug 2003 23:12:48
-0000
@@ -62,56 +62,11 @@
package javax.jms;
-/** The delivery modes supported by the JMS API are <CODE>PERSISTENT</CODE> and
- * <CODE>NON_PERSISTENT</CODE>.
- *
- * <P>A client marks a message as persistent if it feels that the
- * application will have problems if the message is lost in transit.
- * A client marks a message as non-persistent if an occasional
- * lost message is tolerable. Clients use delivery mode to tell a
- * JMS provider how to balance message transport reliability with throughput.
- *
- * <P>Delivery mode covers only the transport of the message to its
- * destination. Retention of a message at the destination until
- * its receipt is acknowledged is not guaranteed by a <CODE>PERSISTENT</CODE>
- * delivery mode. Clients should assume that message retention
- * policies are set administratively. Message retention policy
- * governs the reliability of message delivery from destination
- * to message consumer. For example, if a client's message storage
- * space is exhausted, some messages may be dropped in accordance with
- * a site-specific message retention policy.
- *
- * <P>A message is guaranteed to be delivered once and only once
- * by a JMS provider if the delivery mode of the message is
- * <CODE>PERSISTENT</CODE>
- * and if the destination has a sufficient message retention policy.
- *
- *
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface DeliveryMode {
-
- /** This is the lowest-overhead delivery mode because it does not require
- * that the message be logged to stable storage. The level of JMS provider
- * failure that causes a <CODE>NON_PERSISTENT</CODE> message to be lost is
- * not defined.
- *
- * <P>A JMS provider must deliver a <CODE>NON_PERSISTENT</CODE> message
- * with an
- * at-most-once guarantee. This means that it may lose the message, but it
- * must not deliver it twice.
- */
-
static final int NON_PERSISTENT = 1;
-
- /** This delivery mode instructs the JMS provider to log the message to
stable
- * storage as part of the client's send operation. Only a hard media
- * failure should cause a <CODE>PERSISTENT</CODE> message to be lost.
- */
static final int PERSISTENT = 2;
}
Index: specs/jms/src/java/javax/jms/Destination.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/Destination.java,v
retrieving revision 1.1
diff -u -r1.1 Destination.java
--- specs/jms/src/java/javax/jms/Destination.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/Destination.java 19 Aug 2003 23:12:48
-0000
@@ -62,74 +62,8 @@
package javax.jms;
-/** A <CODE>Destination</CODE> object encapsulates a provider-specific
- * address.
- * The JMS API does not define a standard address syntax. Although a standard
- * address syntax was considered, it was decided that the differences in
- * address semantics between existing message-oriented middleware (MOM)
- * products were too wide to bridge with a single syntax.
- *
- * <P>Since <CODE>Destination</CODE> is an administered object, it may
- * contain
- * provider-specific configuration information in addition to its address.
- *
- * <P>The JMS API also supports a client's use of provider-specific address
- * names.
- *
- * <P><CODE>Destination</CODE> objects support concurrent use.
- *
- * <P>A <CODE>Destination</CODE> object is a JMS administered object.
- *
- * <P>JMS administered objects are objects containing configuration
- * information that are created by an administrator and later used by
- * JMS clients. They make it practical to administer the JMS API in the
- * enterprise.
- *
- * <P>Although the interfaces for administered objects do not explicitly
- * depend on the Java Naming and Directory Interface (JNDI) API, the JMS API
- * establishes the convention that JMS clients find administered objects by
- * looking them up in a JNDI namespace.
- *
- * <P>An administrator can place an administered object anywhere in a
- * namespace. The JMS API does not define a naming policy.
- *
- * <P>It is expected that JMS providers will provide the tools an
- * administrator needs to create and configure administered objects in a
- * JNDI namespace. JMS provider implementations of administered objects
- * should implement the <CODE>javax.naming.Referenceable</CODE> and
- * <CODE>java.io.Serializable</CODE> interfaces so that they can be stored in
- * all JNDI naming contexts. In addition, it is recommended that these
- * implementations follow the JavaBeans<SUP><FONT SIZE="-2">TM</FONT></SUP>
- * design patterns.
- *
- * <P>This strategy provides several benefits:
- *
- * <UL>
- * <LI>It hides provider-specific details from JMS clients.
- * <LI>It abstracts JMS administrative information into objects in the Java
- * programming language ("Java objects")
- * that are easily organized and administered from a common
- * management console.
- * <LI>Since there will be JNDI providers for all popular naming
- * services, JMS providers can deliver one implementation
- * of administered objects that will run everywhere.
- * </UL>
- *
- * <P>An administered object should not hold on to any remote resources.
- * Its lookup should not use remote resources other than those used by the
- * JNDI API itself.
- *
- * <P>Clients should think of administered objects as local Java objects.
- * Looking them up should not have any hidden side effects or use surprising
- * amounts of local resources.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.Queue
- * @see javax.jms.Topic
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface Destination {
}
Index: specs/jms/src/java/javax/jms/ExceptionListener.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ExceptionListener.java,v
retrieving revision 1.1
diff -u -r1.1 ExceptionListener.java
--- specs/jms/src/java/javax/jms/ExceptionListener.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/ExceptionListener.java 19 Aug 2003 23:12:48
-0000
@@ -62,33 +62,9 @@
package javax.jms;
-
-/** If a JMS provider detects a serious problem with a <CODE>Connection</CODE>
- * object, it informs the <CODE>Connection</CODE> object's
- * <CODE>ExceptionListener</CODE>, if one has been registered.
- * It does this by calling the listener's <CODE>onException</CODE> method,
- * passing it a <CODE>JMSException</CODE> argument describing the problem.
- *
- * <P>An exception listener allows a client to be notified of a problem
- * asynchronously. Some connections only consume messages, so they would have
no
- * other way to learn that their connection has failed.
- *
- * <P>A JMS provider should attempt to resolve connection problems
- * itself before it notifies the client of them.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.Connection#setExceptionListener(ExceptionListener)
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ExceptionListener {
-
- /** Notifies user of a JMS exception.
- *
- * @param exception the JMS exception
- */
-
void onException(JMSException exception);
}
Index: specs/jms/src/java/javax/jms/IllegalStateException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/IllegalStateException.java,v
retrieving revision 1.1
diff -u -r1.1 IllegalStateException.java
--- specs/jms/src/java/javax/jms/IllegalStateException.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/IllegalStateException.java 19 Aug 2003
23:12:48 -0000
@@ -63,40 +63,14 @@
package javax.jms;
/**
- * <P> This exception is thrown when a method is
- * invoked at an illegal or inappropriate time or if the provider is
- * not in an appropriate state for the requested operation. For example,
- * this exception must be thrown if <CODE>Session.commit</CODE> is
- * called on a non-transacted session. This exception is also called when
- * a domain inappropriate method is called, such as calling
- * <CODE>TopicSession.CreateQueueBrowser</CODE>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- * @author Kate Stout
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class IllegalStateException extends JMSException {
-
- /** Constructs an <CODE>IllegalStateException</CODE> with the specified
reason
- * and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public IllegalStateException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs an <CODE>IllegalStateException</CODE> with the specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public IllegalStateException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/InvalidClientIDException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/InvalidClientIDException.java,v
retrieving revision 1.1
diff -u -r1.1 InvalidClientIDException.java
--- specs/jms/src/java/javax/jms/InvalidClientIDException.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/InvalidClientIDException.java 19 Aug 2003
23:12:48 -0000
@@ -63,35 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a
- * client attempts to set a connection's client ID to a value that
- * is rejected by a provider.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class InvalidClientIDException extends JMSException {
-
- /** Constructs an <CODE>InvalidClientIDException</CODE> with the specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public InvalidClientIDException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs an <CODE>InvalidClientIDException</CODE> with the specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public InvalidClientIDException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/InvalidDestinationException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/InvalidDestinationException.java,v
retrieving revision 1.1
diff -u -r1.1 InvalidDestinationException.java
--- specs/jms/src/java/javax/jms/InvalidDestinationException.java 16 Aug
2003 02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/InvalidDestinationException.java 19 Aug
2003 23:12:48 -0000
@@ -63,35 +63,15 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a
- * destination either is not understood by a provider or is no
- * longer valid.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class InvalidDestinationException extends JMSException {
-
- /** Constructs an <CODE>InvalidDestinationException</CODE> with the
specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public InvalidDestinationException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs an <CODE>InvalidDestinationException</CODE> with the
specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public InvalidDestinationException(String reason) {
- super(reason);
+ this(reason, null);
}
}
Index: specs/jms/src/java/javax/jms/InvalidSelectorException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/InvalidSelectorException.java,v
retrieving revision 1.1
diff -u -r1.1 InvalidSelectorException.java
--- specs/jms/src/java/javax/jms/InvalidSelectorException.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/InvalidSelectorException.java 19 Aug 2003
23:12:48 -0000
@@ -63,35 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a
- * JMS client attempts to give a provider a message selector with
- * invalid syntax.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class InvalidSelectorException extends JMSException {
-
- /** Constructs an <CODE>InvalidSelectorException</CODE> with the specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public InvalidSelectorException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs an <CODE>InvalidSelectorException</CODE> with the specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public InvalidSelectorException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/JMSException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/JMSException.java,v
retrieving revision 1.1
diff -u -r1.1 JMSException.java
--- specs/jms/src/java/javax/jms/JMSException.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/JMSException.java 19 Aug 2003 23:12:48
-0000
@@ -63,81 +63,33 @@
package javax.jms;
/**
- * <P>This is the root class of all JMS API exceptions.
- *
- * <P>It provides the following information:
- * <UL>
- * <LI> A provider-specific string describing the error. This string is
- * the standard exception message and is available via the
- * <CODE>getMessage</CODE> method.
- * <LI> A provider-specific string error code
- * <LI> A reference to another exception. Often a JMS API exception will
- * be the result of a lower-level problem. If appropriate, this
- * lower-level exception can be linked to the JMS API exception.
- * </UL>
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class JMSException extends Exception {
-
- /** Vendor-specific error code.
- **/
private String errorCode;
- /** <CODE>Exception</CODE> reference.
- **/
private Exception linkedException;
-
- /** Constructs a <CODE>JMSException</CODE> with the specified reason and
- * error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- **/
public JMSException(String reason, String errorCode) {
super(reason);
this.errorCode = errorCode;
linkedException = null;
}
- /** Constructs a <CODE>JMSException</CODE> with the specified reason and
with
- * the error code defaulting to null.
- *
- * @param reason a description of the exception
- **/
public JMSException(String reason) {
- super(reason);
- this.errorCode = null;
+ this(reason, null);
linkedException = null;
}
- /** Gets the vendor-specific error code.
- * @return a string specifying the vendor-specific
- * error code
- **/
public String getErrorCode() {
- return this.errorCode;
+ return errorCode;
}
- /**
- * Gets the exception linked to this one.
- *
- * @return the linked <CODE>Exception</CODE>, null if none
- **/
public Exception getLinkedException() {
- return (linkedException);
+ return linkedException;
}
- /**
- * Adds a linked <CODE>Exception</CODE>.
- *
- * @param ex the linked <CODE>Exception</CODE>
- **/
- public synchronized void setLinkedException(Exception ex) {
+ public void setLinkedException(Exception ex) {
linkedException = ex;
}
}
Index: specs/jms/src/java/javax/jms/JMSSecurityException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/JMSSecurityException.java,v
retrieving revision 1.1
diff -u -r1.1 JMSSecurityException.java
--- specs/jms/src/java/javax/jms/JMSSecurityException.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/JMSSecurityException.java 19 Aug 2003
23:12:48 -0000
@@ -63,35 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a provider rejects a user
- * name/password submitted by a client. It may also be thrown for any case
- * where a security restriction prevents a method from completing.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class JMSSecurityException extends JMSException {
-
- /** Constructs a <CODE>JMSSecurityException</CODE> with the specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public JMSSecurityException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>JMSSecurityException</CODE> with the specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public JMSSecurityException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/MapMessage.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MapMessage.java,v
retrieving revision 1.1
diff -u -r1.1 MapMessage.java
--- specs/jms/src/java/javax/jms/MapMessage.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/MapMessage.java 19 Aug 2003 23:12:48
-0000
@@ -64,441 +64,58 @@
import java.util.Enumeration;
-/** A <CODE>MapMessage</CODE> object is used to send a set of name-value pairs.
- * The names are <CODE>String</CODE> objects, and the values are primitive
- * data types in the Java programming language. The names must have a value
that
- * is not null, and not an empty string. The entries can be accessed
- * sequentially or randomly by name. The order of the entries is undefined.
- * <CODE>MapMessage</CODE> inherits from the <CODE>Message</CODE> interface
- * and adds a message body that contains a Map.
- *
- * <P>The primitive types can be read or written explicitly using methods
- * for each type. They may also be read or written generically as objects.
- * For instance, a call to <CODE>MapMessage.setInt("foo", 6)</CODE> is
- * equivalent to <CODE>MapMessage.setObject("foo", new Integer(6))</CODE>.
- * Both forms are provided, because the explicit form is convenient for
- * static programming, and the object form is needed when types are not known
- * at compile time.
- *
- * <P>When a client receives a <CODE>MapMessage</CODE>, it is in read-only
- * mode. If a client attempts to write to the message at this point, a
- * <CODE>MessageNotWriteableException</CODE> is thrown. If
- * <CODE>clearBody</CODE> is called, the message can now be both read from and
- * written to.
- *
- * <P><CODE>MapMessage</CODE> objects support the following conversion table.
- * The marked cases must be supported. The unmarked cases must throw a
- * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
- * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE>
- * method does not accept it as a valid <CODE>String</CODE> representation of
- * the primitive.
- *
- * <P>A value written as the row type can be read as the column type.
- *
- * <PRE>
- * | | boolean byte short char int long float double String byte[]
- * |----------------------------------------------------------------------
- * |boolean | X X
- * |byte | X X X X X
- * |short | X X X X
- * |char | X X
- * |int | X X X
- * |long | X X
- * |float | X X X
- * |double | X X
- * |String | X X X X X X X X
- * |byte[] | X
- * |----------------------------------------------------------------------
- * </PRE>
- *
- * <P>Attempting to read a null value as a primitive type must be treated
- * as calling the primitive's corresponding <code>valueOf(String)</code>
- * conversion method with a null value. Since <code>char</code> does not
- * support a <code>String</code> conversion, attempting to read a null value
- * as a <code>char</code> must throw a <code>NullPointerException</code>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.Session#createMapMessage()
- * @see javax.jms.BytesMessage
- * @see javax.jms.Message
- * @see javax.jms.ObjectMessage
- * @see javax.jms.StreamMessage
- * @see javax.jms.TextMessage
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface MapMessage extends Message {
-
-
- /** Returns the <CODE>boolean</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>boolean</CODE>
- *
- * @return the <CODE>boolean</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
boolean getBoolean(String name) throws JMSException;
-
- /** Returns the <CODE>byte</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>byte</CODE>
- *
- * @return the <CODE>byte</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
byte getByte(String name) throws JMSException;
-
- /** Returns the <CODE>short</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>short</CODE>
- *
- * @return the <CODE>short</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
short getShort(String name) throws JMSException;
-
- /** Returns the Unicode character value with the specified name.
- *
- * @param name the name of the Unicode character
- *
- * @return the Unicode character value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
char getChar(String name) throws JMSException;
-
- /** Returns the <CODE>int</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>int</CODE>
- *
- * @return the <CODE>int</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
int getInt(String name) throws JMSException;
-
- /** Returns the <CODE>long</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>long</CODE>
- *
- * @return the <CODE>long</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
long getLong(String name) throws JMSException;
-
- /** Returns the <CODE>float</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>float</CODE>
- *
- * @return the <CODE>float</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
float getFloat(String name) throws JMSException;
-
- /** Returns the <CODE>double</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>double</CODE>
- *
- * @return the <CODE>double</CODE> value with the specified name
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
double getDouble(String name) throws JMSException;
-
- /** Returns the <CODE>String</CODE> value with the specified name.
- *
- * @param name the name of the <CODE>String</CODE>
- *
- * @return the <CODE>String</CODE> value with the specified name; if there
- * is no item by this name, a null value is returned
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
String getString(String name) throws JMSException;
-
- /** Returns the byte array value with the specified name.
- *
- * @param name the name of the byte array
- *
- * @return a copy of the byte array value with the specified name; if there
- * is no
- * item by this name, a null value is returned.
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
byte[] getBytes(String name) throws JMSException;
-
- /** Returns the value of the object with the specified name.
- *
- * <P>This method can be used to return, in objectified format,
- * an object in the Java programming language ("Java object") that had
- * been stored in the Map with the equivalent
- * <CODE>setObject</CODE> method call, or its equivalent primitive
- * <CODE>set<I>type</I></CODE> method.
- *
- * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not
- * <CODE>Byte[]</CODE>.
- *
- * @param name the name of the Java object
- *
- * @return a copy of the Java object value with the specified name, in
- * objectified format (for example, if the object was set as an
- * <CODE>int</CODE>, an <CODE>Integer</CODE> is returned); if there is no
- * item by this name, a null value is returned
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- */
Object getObject(String name) throws JMSException;
-
- /** Returns an <CODE>Enumeration</CODE> of all the names in the
- * <CODE>MapMessage</CODE> object.
- *
- * @return an enumeration of all the names in this <CODE>MapMessage</CODE>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- */
Enumeration getMapNames() throws JMSException;
-
- /** Sets a <CODE>boolean</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>boolean</CODE>
- * @param value the <CODE>boolean</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setBoolean(String name, boolean value) throws JMSException;
-
- /** Sets a <CODE>byte</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>byte</CODE>
- * @param value the <CODE>byte</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setByte(String name, byte value) throws JMSException;
-
- /** Sets a <CODE>short</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>short</CODE>
- * @param value the <CODE>short</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setShort(String name, short value) throws JMSException;
-
- /** Sets a Unicode character value with the specified name into the Map.
- *
- * @param name the name of the Unicode character
- * @param value the Unicode character value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setChar(String name, char value) throws JMSException;
-
- /** Sets an <CODE>int</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>int</CODE>
- * @param value the <CODE>int</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setInt(String name, int value) throws JMSException;
-
- /** Sets a <CODE>long</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>long</CODE>
- * @param value the <CODE>long</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setLong(String name, long value) throws JMSException;
-
- /** Sets a <CODE>float</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>float</CODE>
- * @param value the <CODE>float</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setFloat(String name, float value) throws JMSException;
-
- /** Sets a <CODE>double</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>double</CODE>
- * @param value the <CODE>double</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setDouble(String name, double value) throws JMSException;
-
- /** Sets a <CODE>String</CODE> value with the specified name into the Map.
- *
- * @param name the name of the <CODE>String</CODE>
- * @param value the <CODE>String</CODE> value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setString(String name, String value) throws JMSException;
-
- /** Sets a byte array value with the specified name into the Map.
- *
- * @param name the name of the byte array
- * @param value the byte array value to set in the Map; the array
- * is copied so that the value for <CODE>name</CODE> will
- * not be altered by future modifications
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception NullPointerException if the name is null, or if the name is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setBytes(String name, byte[] value) throws JMSException;
+ void setBytes(String name, byte[] value, int offset, int length)
+ throws JMSException;
- /** Sets a portion of the byte array value with the specified name into the
- * Map.
- *
- * @param name the name of the byte array
- * @param value the byte array value to set in the Map
- * @param offset the initial offset within the byte array
- * @param length the number of bytes to use
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
- void setBytes(String name, byte[] value, int offset, int length) throws
JMSException;
-
-
- /** Sets an object value with the specified name into the Map.
- *
- * <P>This method works only for the objectified primitive
- * object types (<code>Integer</code>, <code>Double</code>,
- * <code>Long</code> ...), <code>String</code> objects, and byte
- * arrays.
- *
- * @param name the name of the Java object
- * @param value the Java object value to set in the Map
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageFormatException if the object is invalid.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
void setObject(String name, Object value) throws JMSException;
-
- /** Indicates whether an item exists in this <CODE>MapMessage</CODE>
object.
- *
- * @param name the name of the item to test
- *
- * @return true if the item exists
- *
- * @exception JMSException if the JMS provider fails to determine if the
- * item exists due to some internal error.
- */
boolean itemExists(String name) throws JMSException;
}
Index: specs/jms/src/java/javax/jms/Message.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/Message.java,v
retrieving revision 1.1
diff -u -r1.1 Message.java
--- specs/jms/src/java/javax/jms/Message.java 16 Aug 2003 02:29:57 -0000
1.1
+++ specs/jms/src/java/javax/jms/Message.java 19 Aug 2003 23:12:48 -0000
@@ -64,1431 +64,104 @@
import java.util.Enumeration;
-/** The <CODE>Message</CODE> interface is the root interface of all JMS
- * messages. It defines the message header and the <CODE>acknowledge</CODE>
- * method used for all messages.
- *
- * <P>Most message-oriented middleware (MOM) products treat messages as
- * lightweight entities that consist
- * of a header and a payload. The header contains fields used for message
- * routing and identification; the payload contains the application data
- * being sent.
- *
- * <P>Within this general form, the definition of a message varies
- * significantly across products. It would be quite difficult for the JMS API
- * to support all of these message models.
- *
- * <P>With this in mind, the JMS message model has the following goals:
- * <UL>
- * <LI>Provide a single, unified message API
- * <LI>Provide an API suitable for creating messages that match the
- * format used by provider-native messaging applications
- * <LI>Support the development of heterogeneous applications that span
- * operating systems, machine architectures, and computer languages
- * <LI>Support messages containing objects in the Java programming language
- * ("Java objects")
- * <LI>Support messages containing Extensible Markup Language (XML) pages
- * </UL>
- *
- * <P>JMS messages are composed of the following parts:
- * <UL>
- * <LI>Header - All messages support the same set of header fields.
- * Header fields contain values used by both clients and providers to
- * identify and route messages.
- * <LI>Properties - Each message contains a built-in facility for supporting
- * application-defined property values. Properties provide an efficient
- * mechanism for supporting application-defined message filtering.
- * <LI>Body - The JMS API defines several types of message body, which cover
- * the majority of messaging styles currently in use.
- * </UL>
- *
- * <H4>Message Bodies</H4>
- *
- * <P>The JMS API defines five types of message body:
- * <UL>
- * <LI>Stream - A <CODE>StreamMessage</CODE> object's message body contains
- * a stream of primitive values in the Java programming
- * language ("Java primitives"). It is filled and read sequentially.
- * <LI>Map - A <CODE>MapMessage</CODE> object's message body contains a set
- * of name-value pairs, where names are <CODE>String</CODE>
- * objects, and values are Java primitives. The entries can be accessed
- * sequentially or randomly by name. The order of the entries is
- * undefined.
- * <LI>Text - A <CODE>TextMessage</CODE> object's message body contains a
- * <CODE>java.lang.String</CODE> object. This message type can be used
- * to transport plain-text messages, and XML messages.
- * <LI>Object - An <CODE>ObjectMessage</CODE> object's message body contains
- * a <CODE>Serializable</CODE> Java object.
- * <LI>Bytes - A <CODE>BytesMessage</CODE> object's message body contains a
- * stream of uninterpreted bytes. This message type is for
- * literally encoding a body to match an existing message format. In
- * many cases, it is possible to use one of the other body types,
- * which are easier to use. Although the JMS API allows the use of
- * message properties with byte messages, they are typically not used,
- * since the inclusion of properties may affect the format.
- * </UL>
- *
- * <H4>Message Headers</H4>
- *
- * <P>The <CODE>JMSCorrelationID</CODE> header field is used for linking one
- * message with
- * another. It typically links a reply message with its requesting message.
- *
- * <P><CODE>JMSCorrelationID</CODE> can hold a provider-specific message ID,
- * an application-specific <CODE>String</CODE> object, or a provider-native
- * <CODE>byte[]</CODE> value.
- *
- * <H4>Message Properties</H4>
- *
- * <P>A <CODE>Message</CODE> object contains a built-in facility for supporting
- * application-defined property values. In effect, this provides a mechanism
- * for adding application-specific header fields to a message.
- *
- * <P>Properties allow an application, via message selectors, to have a JMS
- * provider select, or filter, messages on its behalf using
- * application-specific criteria.
- *
- * <P>Property names must obey the rules for a message selector identifier.
- * Property names must not be null, and must not be empty strings. If a
property
- * name is set and it is either null or an empty string, an
- * <CODE>IllegalArgumentException</CODE> must be thrown.
- *
- * <P>Property values can be <CODE>boolean</CODE>, <CODE>byte</CODE>,
- * <CODE>short</CODE>, <CODE>int</CODE>, <CODE>long</CODE>, <CODE>float</CODE>,
- * <CODE>double</CODE>, and <CODE>String</CODE>.
- *
- * <P>Property values are set prior to sending a message. When a client
- * receives a message, its properties are in read-only mode. If a
- * client attempts to set properties at this point, a
- * <CODE>MessageNotWriteableException</CODE> is thrown. If
- * <CODE>clearProperties</CODE> is called, the properties can now be both
- * read from and written to. Note that header fields are distinct from
- * properties. Header fields are never in read-only mode.
- *
- * <P>A property value may duplicate a value in a message's body, or it may
- * not. Although JMS does not define a policy for what should or should not
- * be made a property, application developers should note that JMS providers
- * will likely handle data in a message's body more efficiently than data in
- * a message's properties. For best performance, applications should use
- * message properties only when they need to customize a message's header.
- * The primary reason for doing this is to support customized message
- * selection.
- *
- * <P>Message properties support the following conversion table. The marked
- * cases must be supported. The unmarked cases must throw a
- * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
- * may throw a runtime exception if the
- * primitive's <CODE>valueOf</CODE> method does not accept the
- * <CODE>String</CODE> as a valid representation of the primitive.
- *
- * <P>A value written as the row type can be read as the column type.
- *
- * <PRE>
- * | | boolean byte short int long float double String
- * |----------------------------------------------------------
- * |boolean | X X
- * |byte | X X X X X
- * |short | X X X X
- * |int | X X X
- * |long | X X
- * |float | X X X
- * |double | X X
- * |String | X X X X X X X X
- * |----------------------------------------------------------
- * </PRE>
- *
- * <P>In addition to the type-specific set/get methods for properties, JMS
- * provides the <CODE>setObjectProperty</CODE> and
- * <CODE>getObjectProperty</CODE> methods. These support the same set of
- * property types using the objectified primitive values. Their purpose is
- * to allow the decision of property type to made at execution time rather
- * than at compile time. They support the same property value conversions.
- *
- * <P>The <CODE>setObjectProperty</CODE> method accepts values of class
- * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>,
- * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>,
- * <CODE>Double</CODE>, and <CODE>String</CODE>. An attempt
- * to use any other class must throw a <CODE>JMSException</CODE>.
- *
- * <P>The <CODE>getObjectProperty</CODE> method only returns values of class
- * <CODE>Boolean</CODE>, <CODE>Byte</CODE>, <CODE>Short</CODE>,
- * <CODE>Integer</CODE>, <CODE>Long</CODE>, <CODE>Float</CODE>,
- * <CODE>Double</CODE>, and <CODE>String</CODE>.
- *
- * <P>The order of property values is not defined. To iterate through a
- * message's property values, use <CODE>getPropertyNames</CODE> to retrieve
- * a property name enumeration and then use the various property get methods
- * to retrieve their values.
- *
- * <P>A message's properties are deleted by the <CODE>clearProperties</CODE>
- * method. This leaves the message with an empty set of properties.
- *
- * <P>Getting a property value for a name which has not been set returns a
- * null value. Only the <CODE>getStringProperty</CODE> and
- * <CODE>getObjectProperty</CODE> methods can return a null value.
- * Attempting to read a null value as a primitive type must be treated as
- * calling the primitive's corresponding <CODE>valueOf(String)</CODE>
- * conversion method with a null value.
- *
- * <P>The JMS API reserves the <CODE>JMSX</CODE> property name prefix for JMS
- * defined properties.
- * The full set of these properties is defined in the Java Message Service
- * specification. New JMS defined properties may be added in later versions
- * of the JMS API. Support for these properties is optional. The
- * <CODE>String[] ConnectionMetaData.getJMSXPropertyNames</CODE> method
- * returns the names of the JMSX properties supported by a connection.
- *
- * <P>JMSX properties may be referenced in message selectors whether or not
- * they are supported by a connection. If they are not present in a
- * message, they are treated like any other absent property.
- *
- * <P>JMSX properties defined in the specification as "set by provider on
- * send" are available to both the producer and the consumers of the message.
- * JMSX properties defined in the specification as "set by provider on
- * receive" are available only to the consumers.
- *
- * <P><CODE>JMSXGroupID</CODE> and <CODE>JMSXGroupSeq</CODE> are standard
- * properties that clients
- * should use if they want to group messages. All providers must support them.
- * Unless specifically noted, the values and semantics of the JMSX properties
- * are undefined.
- *
- * <P>The JMS API reserves the <CODE>JMS_<I>vendor_name</I></CODE> property
- * name prefix for provider-specific properties. Each provider defines its own
- * value for <CODE><I>vendor_name</I></CODE>. This is the mechanism a JMS
- * provider uses to make its special per-message services available to a JMS
- * client.
- *
- * <P>The purpose of provider-specific properties is to provide special
- * features needed to integrate JMS clients with provider-native clients in a
- * single JMS application. They should not be used for messaging between JMS
- * clients.
- *
- * <H4>Provider Implementations of JMS Message Interfaces</H4>
- *
- * <P>The JMS API provides a set of message interfaces that define the JMS
- * message
- * model. It does not provide implementations of these interfaces.
- *
- * <P>Each JMS provider supplies a set of message factories with its
- * <CODE>Session</CODE> object for creating instances of messages. This allows
- * a provider to use message implementations tailored to its specific needs.
- *
- * <P>A provider must be prepared to accept message implementations that are
- * not its own. They may not be handled as efficiently as its own
- * implementation; however, they must be handled.
- *
- * <P>Note the following exception case when a provider is handling a foreign
- * message implementation. If the foreign message implementation contains a
- * <CODE>JMSReplyTo</CODE> header field that is set to a foreign destination
- * implementation, the provider is not required to handle or preserve the
- * value of this header field.
- *
- * <H4>Message Selectors</H4>
- *
- * <P>A JMS message selector allows a client to specify, by
- * header field references and property references, the
- * messages it is interested in. Only messages whose header
- * and property values
- * match the
- * selector are delivered. What it means for a message not to be delivered
- * depends on the <CODE>MessageConsumer</CODE> being used (see
- * [EMAIL PROTECTED] javax.jms.QueueReceiver QueueReceiver} and
- * [EMAIL PROTECTED] javax.jms.TopicSubscriber TopicSubscriber}).
- *
- * <P>Message selectors cannot reference message body values.
- *
- * <P>A message selector matches a message if the selector evaluates to
- * true when the message's header field values and property values are
- * substituted for their corresponding identifiers in the selector.
- *
- * <P>A message selector is a <CODE>String</CODE> whose syntax is based on a
- * subset of
- * the SQL92 conditional expression syntax. If the value of a message selector
- * is an empty string, the value is treated as a null and indicates that there
- * is no message selector for the message consumer.
- *
- * <P>The order of evaluation of a message selector is from left to right
- * within precedence level. Parentheses can be used to change this order.
- *
- * <P>Predefined selector literals and operator names are shown here in
- * uppercase; however, they are case insensitive.
- *
- * <P>A selector can contain:
- *
- * <UL>
- * <LI>Literals:
- * <UL>
- * <LI>A string literal is enclosed in single quotes, with a single quote
- * represented by doubled single quote; for example,
- * <CODE>'literal'</CODE> and <CODE>'literal''s'</CODE>. Like
- * string literals in the Java programming language, these use the
- * Unicode character encoding.
- * <LI>An exact numeric literal is a numeric value without a decimal
- * point, such as <CODE>57</CODE>, <CODE>-957</CODE>, and
- * <CODE>+62</CODE>; numbers in the range of <CODE>long</CODE> are
- * supported. Exact numeric literals use the integer literal
- * syntax of the Java programming language.
- * <LI>An approximate numeric literal is a numeric value in scientific
- * notation, such as <CODE>7E3</CODE> and <CODE>-57.9E2</CODE>, or a
- * numeric value with a decimal, such as <CODE>7.</CODE>,
- * <CODE>-95.7</CODE>, and <CODE>+6.2</CODE>; numbers in the range of
- * <CODE>double</CODE> are supported. Approximate literals use the
- * floating-point literal syntax of the Java programming language.
- * <LI>The boolean literals <CODE>TRUE</CODE> and <CODE>FALSE</CODE>.
- * </UL>
- * <LI>Identifiers:
- * <UL>
- * <LI>An identifier is an unlimited-length sequence of letters
- * and digits, the first of which must be a letter. A letter is any
- * character for which the method <CODE>Character.isJavaLetter</CODE>
- * returns true. This includes <CODE>'_'</CODE> and <CODE>'$'</CODE>.
- * A letter or digit is any character for which the method
- * <CODE>Character.isJavaLetterOrDigit</CODE> returns true.
- * <LI>Identifiers cannot be the names <CODE>NULL</CODE>,
- * <CODE>TRUE</CODE>, and <CODE>FALSE</CODE>.
- * <LI>Identifiers cannot be <CODE>NOT</CODE>, <CODE>AND</CODE>,
- * <CODE>OR</CODE>, <CODE>BETWEEN</CODE>, <CODE>LIKE</CODE>,
- * <CODE>IN</CODE>, <CODE>IS</CODE>, or <CODE>ESCAPE</CODE>.
- * <LI>Identifiers are either header field references or property
- * references. The type of a property value in a message selector
- * corresponds to the type used to set the property. If a property
- * that does not exist in a message is referenced, its value is
- * <CODE>NULL</CODE>.
- * <LI>The conversions that apply to the get methods for properties do not
- * apply when a property is used in a message selector expression.
- * For example, suppose you set a property as a string value, as in the
- * following:
- * <PRE>myMessage.setStringProperty("NumberOfOrders", "2");</PRE>
- * The following expression in a message selector would evaluate to
- * false, because a string cannot be used in an arithmetic expression:
- * <PRE>"NumberOfOrders > 1"</PRE>
- * <LI>Identifiers are case-sensitive.
- * <LI>Message header field references are restricted to
- * <CODE>JMSDeliveryMode</CODE>, <CODE>JMSPriority</CODE>,
- * <CODE>JMSMessageID</CODE>, <CODE>JMSTimestamp</CODE>,
- * <CODE>JMSCorrelationID</CODE>, and <CODE>JMSType</CODE>.
- * <CODE>JMSMessageID</CODE>, <CODE>JMSCorrelationID</CODE>, and
- * <CODE>JMSType</CODE> values may be null and if so are treated as a
- * <CODE>NULL</CODE> value.
- * <LI>Any name beginning with <CODE>'JMSX'</CODE> is a JMS defined
- * property name.
- * <LI>Any name beginning with <CODE>'JMS_'</CODE> is a provider-specific
- * property name.
- * <LI>Any name that does not begin with <CODE>'JMS'</CODE> is an
- * application-specific property name.
- * </UL>
- * <LI>White space is the same as that defined for the Java programming
- * language: space, horizontal tab, form feed, and line terminator.
- * <LI>Expressions:
- * <UL>
- * <LI>A selector is a conditional expression; a selector that evaluates
- * to <CODE>true</CODE> matches; a selector that evaluates to
- * <CODE>false</CODE> or unknown does not match.
- * <LI>Arithmetic expressions are composed of themselves, arithmetic
- * operations, identifiers (whose value is treated as a numeric
- * literal), and numeric literals.
- * <LI>Conditional expressions are composed of themselves, comparison
- * operations, and logical operations.
- * </UL>
- * <LI>Standard bracketing <CODE>()</CODE> for ordering expression evaluation
- * is supported.
- * <LI>Logical operators in precedence order: <CODE>NOT</CODE>,
- * <CODE>AND</CODE>, <CODE>OR</CODE>
- * <LI>Comparison operators: <CODE>=</CODE>, <CODE>></CODE>, <CODE>>=</CODE>,
- * <CODE><</CODE>, <CODE><=</CODE>, <CODE><></CODE> (not equal)
- * <UL>
- * <LI>Only like type values can be compared. One exception is that it
- * is valid to compare exact numeric values and approximate numeric
- * values; the type conversion required is defined by the rules of
- * numeric promotion in the Java programming language. If the
- * comparison of non-like type values is attempted, the value of the
- * operation is false. If either of the type values evaluates to
- * <CODE>NULL</CODE>, the value of the expression is unknown.
- * <LI>String and boolean comparison is restricted to <CODE>=</CODE> and
- * <CODE><></CODE>. Two strings are equal
- * if and only if they contain the same sequence of characters.
- * </UL>
- * <LI>Arithmetic operators in precedence order:
- * <UL>
- * <LI><CODE>+</CODE>, <CODE>-</CODE> (unary)
- * <LI><CODE>*</CODE>, <CODE>/</CODE> (multiplication and division)
- * <LI><CODE>+</CODE>, <CODE>-</CODE> (addition and subtraction)
- * <LI>Arithmetic operations must use numeric promotion in the Java
- * programming language.
- * </UL>
- * <LI><CODE><I>arithmetic-expr1</I> [NOT] BETWEEN <I>arithmetic-expr2</I>
- * AND <I>arithmetic-expr3</I></CODE> (comparison operator)
- * <UL>
- * <LI><CODE>"age BETWEEN 15 AND 19"</CODE> is
- * equivalent to
- * <CODE>"age >= 15 AND age <= 19"</CODE>
- * <LI><CODE>"age NOT BETWEEN 15 AND 19"</CODE>
- * is equivalent to
- * <CODE>"age < 15 OR age > 19"</CODE>
- * </UL>
- * <LI><CODE><I>identifier</I> [NOT] IN (<I>string-literal1</I>,
- * <I>string-literal2</I>,...)</CODE> (comparison operator where
- * <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> or
- * <CODE>NULL</CODE> value)
- * <UL>
- *
<LI><CODE>"Country IN (' UK', 'US', 'France')"</CODE>
- * is true for
- * <CODE>'UK'</CODE> and false for <CODE>'Peru'</CODE>; it is
- * equivalent to the expression
- *
<CODE>"(Country = ' UK') OR (Country = ' US') OR (Country = ' France')"</CODE>
- *
<LI><CODE>"Country NOT IN (' UK', 'US', 'France')"</CODE>
- * is false for <CODE>'UK'</CODE> and true for <CODE>'Peru'</CODE>; it
- * is equivalent to the expression
- *
<CODE>"NOT ((Country = ' UK') OR (Country = ' US') OR (Country = ' France'))"</CODE>
- * <LI>If identifier of an <CODE>IN</CODE> or <CODE>NOT IN</CODE>
- * operation is <CODE>NULL</CODE>, the value of the operation is
- * unknown.
- * </UL>
- * <LI><CODE><I>identifier</I> [NOT] LIKE <I>pattern-value</I> [ESCAPE
- * <I>escape-character</I>]</CODE> (comparison operator, where
- * <CODE><I>identifier</I></CODE> has a <CODE>String</CODE> value;
- * <CODE><I>pattern-value</I></CODE> is a string literal where
- * <CODE>'_'</CODE> stands for any single character; <CODE>'%'</CODE>
- * stands for any sequence of characters, including the empty sequence;
- * and all other characters stand for themselves. The optional
- * <CODE><I>escape-character</I></CODE> is a single-character string
- * literal whose character is used to escape the special meaning of the
- * <CODE>'_'</CODE> and <CODE>'%'</CODE> in
- * <CODE><I>pattern-value</I></CODE>.)
- * <UL>
- * <LI><CODE>"phone LIKE '12%3'"</CODE> is true for
- * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and false for
- * <CODE>'1234'</CODE>
- * <LI><CODE>"word LIKE 'l_se'"</CODE> is true for
- * <CODE>'lose'</CODE> and false for <CODE>'loose'</CODE>
- * <LI><CODE>"underscored LIKE '\_%' ESCAPE '\'"</CODE>
- * is true for <CODE>'_foo'</CODE> and false for <CODE>'bar'</CODE>
- * <LI><CODE>"phone NOT LIKE '12%3'"</CODE> is false for
- * <CODE>'123'</CODE> or <CODE>'12993'</CODE> and true for
- * <CODE>'1234'</CODE>
- * <LI>If <CODE><I>identifier</I></CODE> of a <CODE>LIKE</CODE> or
- * <CODE>NOT LIKE</CODE> operation is <CODE>NULL</CODE>, the value
- * of the operation is unknown.
- * </UL>
- * <LI><CODE><I>identifier</I> IS NULL</CODE> (comparison operator that tests
- * for a null header field value or a missing property value)
- * <UL>
- * <LI><CODE>"prop_name IS NULL"</CODE>
- * </UL>
- * <LI><CODE><I>identifier</I> IS NOT NULL</CODE> (comparison operator that
- * tests for the existence of a non-null header field value or a property
- * value)
- * <UL>
- * <LI><CODE>"prop_name IS NOT NULL"</CODE>
- * </UL>
- *
- * <P>JMS providers are required to verify the syntactic correctness of a
- * message selector at the time it is presented. A method that provides a
- * syntactically incorrect selector must result in a
<CODE>JMSException</CODE>.
- * JMS providers may also optionally provide some semantic checking at the time
- * the selector is presented. Not all semantic checking can be performed at
- * the time a message selector is presented, because property types are not
known.
- *
- * <P>The following message selector selects messages with a message type
- * of car and color of blue and weight greater than 2500 pounds:
- *
- *
<PRE>"JMSType = 'car' AND color = 'blue' AND weight > 2500"</PRE>
- *
- * <H4>Null Values</H4>
- *
- * <P>As noted above, property values may be <CODE>NULL</CODE>. The evaluation
- * of selector expressions containing <CODE>NULL</CODE> values is defined by
- * SQL92 <CODE>NULL</CODE> semantics. A brief description of these semantics
- * is provided here.
- *
- * <P>SQL treats a <CODE>NULL</CODE> value as unknown. Comparison or arithmetic
- * with an unknown value always yields an unknown value.
- *
- * <P>The <CODE>IS NULL</CODE> and <CODE>IS NOT NULL</CODE> operators convert
- * an unknown value into the respective <CODE>TRUE</CODE> and
- * <CODE>FALSE</CODE> values.
- *
- * <P>The boolean operators use three-valued logic as defined by the
- * following tables:
- *
- * <P><B>The definition of the <CODE>AND</CODE> operator</B>
- *
- * <PRE>
- * | AND | T | F | U
- * +------+-------+-------+-------
- * | T | T | F | U
- * | F | F | F | F
- * | U | U | F | U
- * +------+-------+-------+-------
- * </PRE>
- *
- * <P><B>The definition of the <CODE>OR</CODE> operator</B>
- *
- * <PRE>
- * | OR | T | F | U
- * +------+-------+-------+--------
- * | T | T | T | T
- * | F | T | F | U
- * | U | T | U | U
- * +------+-------+-------+-------
- * </PRE>
- *
- * <P><B>The definition of the <CODE>NOT</CODE> operator</B>
- *
- * <PRE>
- * | NOT
- * +------+------
- * | T | F
- * | F | T
- * | U | U
- * +------+-------
- * </PRE>
- *
- * <H4>Special Notes</H4>
- *
- * <P>When used in a message selector, the <CODE>JMSDeliveryMode</CODE> header
- * field is treated as having the values <CODE>'PERSISTENT'</CODE> and
- * <CODE>'NON_PERSISTENT'</CODE>.
- *
- * <P>Date and time values should use the standard <CODE>long</CODE>
- * millisecond value. When a date or time literal is included in a message
- * selector, it should be an integer literal for a millisecond value. The
- * standard way to produce millisecond values is to use
- * <CODE>java.util.Calendar</CODE>.
- *
- * <P>Although SQL supports fixed decimal comparison and arithmetic, JMS
- * message selectors do not. This is the reason for restricting exact
- * numeric literals to those without a decimal (and the addition of
- * numerics with a decimal as an alternate representation for
- * approximate numeric values).
- *
- * <P>SQL comments are not supported.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.MessageConsumer#receive()
- * @see javax.jms.MessageConsumer#receive(long)
- * @see javax.jms.MessageConsumer#receiveNoWait()
- * @see javax.jms.MessageListener#onMessage(Message)
- * @see javax.jms.BytesMessage
- * @see javax.jms.MapMessage
- * @see javax.jms.ObjectMessage
- * @see javax.jms.StreamMessage
- * @see javax.jms.TextMessage
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface Message {
- /** The message producer's default delivery mode is
<CODE>PERSISTENT</CODE>.
- *
- * @see DeliveryMode#PERSISTENT
- */
static final int DEFAULT_DELIVERY_MODE = DeliveryMode.PERSISTENT;
- /** The message producer's default priority is 4.
- */
static final int DEFAULT_PRIORITY = 4;
- /** The message producer's default time to live is unlimited; the message
- * never expires.
- */
static final long DEFAULT_TIME_TO_LIVE = 0;
-
- /** Gets the message ID.
- *
- * <P>The <CODE>JMSMessageID</CODE> header field contains a value that
- * uniquely identifies each message sent by a provider.
- *
- * <P>When a message is sent, <CODE>JMSMessageID</CODE> can be ignored.
- * When the <CODE>send</CODE> or <CODE>publish</CODE> method returns, it
- * contains a provider-assigned value.
- *
- * <P>A <CODE>JMSMessageID</CODE> is a <CODE>String</CODE> value that
- * should function as a
- * unique key for identifying messages in a historical repository.
- * The exact scope of uniqueness is provider-defined. It should at
- * least cover all messages for a specific installation of a
- * provider, where an installation is some connected set of message
- * routers.
- *
- * <P>All <CODE>JMSMessageID</CODE> values must start with the prefix
- * <CODE>'ID:'</CODE>.
- * Uniqueness of message ID values across different providers is
- * not required.
- *
- * <P>Since message IDs take some effort to create and increase a
- * message's size, some JMS providers may be able to optimize message
- * overhead if they are given a hint that the message ID is not used by
- * an application. By calling the
- * <CODE>MessageProducer.setDisableMessageID</CODE> method, a JMS client
- * enables this potential optimization for all messages sent by that
- * message producer. If the JMS provider accepts this
- * hint, these messages must have the message ID set to null; if the
- * provider ignores the hint, the message ID must be set to its normal
- * unique value.
- *
- * @return the message ID
- *
- * @exception JMSException if the JMS provider fails to get the message ID
- * due to some internal error.
- * @see javax.jms.Message#setJMSMessageID(String)
- * @see javax.jms.MessageProducer#setDisableMessageID(boolean)
- */
-
String getJMSMessageID() throws JMSException;
-
- /** Sets the message ID.
- *
- * <P>JMS providers set this field when a message is sent. This method
- * can be used to change the value for a message that has been received.
- *
- * @param id the ID of the message
- *
- * @exception JMSException if the JMS provider fails to set the message ID
- * due to some internal error.
- *
- * @see javax.jms.Message#getJMSMessageID()
- */
-
void setJMSMessageID(String id) throws JMSException;
-
- /** Gets the message timestamp.
- *
- * <P>The <CODE>JMSTimestamp</CODE> header field contains the time a
- * message was
- * handed off to a provider to be sent. It is not the time the
- * message was actually transmitted, because the actual send may occur
- * later due to transactions or other client-side queueing of messages.
- *
- * <P>When a message is sent, <CODE>JMSTimestamp</CODE> is ignored. When
- * the <CODE>send</CODE> or <CODE>publish</CODE>
- * method returns, it contains a time value somewhere in the interval
- * between the call and the return. The value is in the format of a normal
- * millis time value in the Java programming language.
- *
- * <P>Since timestamps take some effort to create and increase a
- * message's size, some JMS providers may be able to optimize message
- * overhead if they are given a hint that the timestamp is not used by an
- * application. By calling the
- * <CODE>MessageProducer.setDisableMessageTimestamp</CODE> method, a JMS
- * client enables this potential optimization for all messages sent by
- * that message producer. If the JMS provider accepts this
- * hint, these messages must have the timestamp set to zero; if the
- * provider ignores the hint, the timestamp must be set to its normal
- * value.
- *
- * @return the message timestamp
- *
- * @exception JMSException if the JMS provider fails to get the timestamp
- * due to some internal error.
- *
- * @see javax.jms.Message#setJMSTimestamp(long)
- * @see javax.jms.MessageProducer#setDisableMessageTimestamp(boolean)
- */
-
long getJMSTimestamp() throws JMSException;
-
- /** Sets the message timestamp.
- *
- * <P>JMS providers set this field when a message is sent. This method
- * can be used to change the value for a message that has been received.
- *
- * @param timestamp the timestamp for this message
- *
- * @exception JMSException if the JMS provider fails to set the timestamp
- * due to some internal error.
- *
- * @see javax.jms.Message#getJMSTimestamp()
- */
-
void setJMSTimestamp(long timestamp) throws JMSException;
-
- /** Gets the correlation ID as an array of bytes for the message.
- *
- * <P>The use of a <CODE>byte[]</CODE> value for
- * <CODE>JMSCorrelationID</CODE> is non-portable.
- *
- * @return the correlation ID of a message as an array of bytes
- *
- * @exception JMSException if the JMS provider fails to get the correlation
- * ID due to some internal error.
- *
- * @see javax.jms.Message#setJMSCorrelationID(String)
- * @see javax.jms.Message#getJMSCorrelationID()
- * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
- */
-
byte[] getJMSCorrelationIDAsBytes() throws JMSException;
-
- /** Sets the correlation ID as an array of bytes for the message.
- *
- * <P>The array is copied before the method returns, so
- * future modifications to the array will not alter this message header.
- *
- * <P>If a provider supports the native concept of correlation ID, a
- * JMS client may need to assign specific <CODE>JMSCorrelationID</CODE>
- * values to match those expected by native messaging clients.
- * JMS providers without native correlation ID values are not required to
- * support this method and its corresponding get method; their
- * implementation may throw a
- * <CODE>java.lang.UnsupportedOperationException</CODE>.
- *
- * <P>The use of a <CODE>byte[]</CODE> value for
- * <CODE>JMSCorrelationID</CODE> is non-portable.
- *
- * @param correlationID the correlation ID value as an array of bytes
- *
- * @exception JMSException if the JMS provider fails to set the correlation
- * ID due to some internal error.
- *
- * @see javax.jms.Message#setJMSCorrelationID(String)
- * @see javax.jms.Message#getJMSCorrelationID()
- * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
- */
-
void setJMSCorrelationIDAsBytes(byte[] correlationID) throws JMSException;
-
- /** Sets the correlation ID for the message.
- *
- * <P>A client can use the <CODE>JMSCorrelationID</CODE> header field to
- * link one message with another. A typical use is to link a response
- * message with its request message.
- *
- * <P><CODE>JMSCorrelationID</CODE> can hold one of the following:
- * <UL>
- * <LI>A provider-specific message ID
- * <LI>An application-specific <CODE>String</CODE>
- * <LI>A provider-native <CODE>byte[]</CODE> value
- * </UL>
- *
- * <P>Since each message sent by a JMS provider is assigned a message ID
- * value, it is convenient to link messages via message ID. All message ID
- * values must start with the <CODE>'ID:'</CODE> prefix.
- *
- * <P>In some cases, an application (made up of several clients) needs to
- * use an application-specific value for linking messages. For instance,
- * an application may use <CODE>JMSCorrelationID</CODE> to hold a value
- * referencing some external information. Application-specified values
- * must not start with the <CODE>'ID:'</CODE> prefix; this is reserved for
- * provider-generated message ID values.
- *
- * <P>If a provider supports the native concept of correlation ID, a JMS
- * client may need to assign specific <CODE>JMSCorrelationID</CODE> values
- * to match those expected by clients that do not use the JMS API. A
- * <CODE>byte[]</CODE> value is used for this
- * purpose. JMS providers without native correlation ID values are not
- * required to support <CODE>byte[]</CODE> values. The use of a
- * <CODE>byte[]</CODE> value for <CODE>JMSCorrelationID</CODE> is
- * non-portable.
- *
- * @param correlationID the message ID of a message being referred to
- *
- * @exception JMSException if the JMS provider fails to set the correlation
- * ID due to some internal error.
- *
- * @see javax.jms.Message#getJMSCorrelationID()
- * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
- * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
- */
-
void setJMSCorrelationID(String correlationID) throws JMSException;
-
- /** Gets the correlation ID for the message.
- *
- * <P>This method is used to return correlation ID values that are
- * either provider-specific message IDs or application-specific
- * <CODE>String</CODE> values.
- *
- * @return the correlation ID of a message as a <CODE>String</CODE>
- *
- * @exception JMSException if the JMS provider fails to get the correlation
- * ID due to some internal error.
- *
- * @see javax.jms.Message#setJMSCorrelationID(String)
- * @see javax.jms.Message#getJMSCorrelationIDAsBytes()
- * @see javax.jms.Message#setJMSCorrelationIDAsBytes(byte[])
- */
-
String getJMSCorrelationID() throws JMSException;
-
- /** Gets the <CODE>Destination</CODE> object to which a reply to this
- * message should be sent.
- *
- * @return <CODE>Destination</CODE> to which to send a response to this
- * message
- *
- * @exception JMSException if the JMS provider fails to get the
- * <CODE>JMSReplyTo</CODE> destination due to some
- * internal error.
- *
- * @see javax.jms.Message#setJMSReplyTo(Destination)
- */
-
Destination getJMSReplyTo() throws JMSException;
-
- /** Sets the <CODE>Destination</CODE> object to which a reply to this
- * message should be sent.
- *
- * <P>The <CODE>JMSReplyTo</CODE> header field contains the destination
- * where a reply
- * to the current message should be sent. If it is null, no reply is
- * expected. The destination may be either a <CODE>Queue</CODE> object or
- * a <CODE>Topic</CODE> object.
- *
- * <P>Messages sent with a null <CODE>JMSReplyTo</CODE> value may be a
- * notification of some event, or they may just be some data the sender
- * thinks is of interest.
- *
- * <P>Messages with a <CODE>JMSReplyTo</CODE> value typically expect a
- * response. A response is optional; it is up to the client to decide.
- * These messages are called requests. A message sent in response to a
- * request is called a reply.
- *
- * <P>In some cases a client may wish to match a request it sent earlier
- * with a reply it has just received. The client can use the
- * <CODE>JMSCorrelationID</CODE> header field for this purpose.
- *
- * @param replyTo <CODE>Destination</CODE> to which to send a response to
- * this message
- *
- * @exception JMSException if the JMS provider fails to set the
- * <CODE>JMSReplyTo</CODE> destination due to some
- * internal error.
- *
- * @see javax.jms.Message#getJMSReplyTo()
- */
-
void setJMSReplyTo(Destination replyTo) throws JMSException;
-
- /** Gets the <CODE>Destination</CODE> object for this message.
- *
- * <P>The <CODE>JMSDestination</CODE> header field contains the
- * destination to which the message is being sent.
- *
- * <P>When a message is sent, this field is ignored. After completion
- * of the <CODE>send</CODE> or <CODE>publish</CODE> method, the field
- * holds the destination specified by the method.
- *
- * <P>When a message is received, its <CODE>JMSDestination</CODE> value
- * must be equivalent to the value assigned when it was sent.
- *
- * @return the destination of this message
- *
- * @exception JMSException if the JMS provider fails to get the destination
- * due to some internal error.
- *
- * @see javax.jms.Message#setJMSDestination(Destination)
- */
-
Destination getJMSDestination() throws JMSException;
-
- /** Sets the <CODE>Destination</CODE> object for this message.
- *
- * <P>JMS providers set this field when a message is sent. This method
- * can be used to change the value for a message that has been received.
- *
- * @param destination the destination for this message
- *
- * @exception JMSException if the JMS provider fails to set the destination
- * due to some internal error.
- *
- * @see javax.jms.Message#getJMSDestination()
- */
-
void setJMSDestination(Destination destination) throws JMSException;
-
- /** Gets the <CODE>DeliveryMode</CODE> value specified for this message.
- *
- * @return the delivery mode for this message
- *
- * @exception JMSException if the JMS provider fails to get the
- * delivery mode due to some internal error.
- *
- * @see javax.jms.Message#setJMSDeliveryMode(int)
- * @see javax.jms.DeliveryMode
- */
-
int getJMSDeliveryMode() throws JMSException;
-
- /** Sets the <CODE>DeliveryMode</CODE> value for this message.
- *
- * <P>JMS providers set this field when a message is sent. This method
- * can be used to change the value for a message that has been received.
- *
- * @param deliveryMode the delivery mode for this message
- *
- * @exception JMSException if the JMS provider fails to set the
- * delivery mode due to some internal error.
- *
- * @see javax.jms.Message#getJMSDeliveryMode()
- * @see javax.jms.DeliveryMode
- */
-
void setJMSDeliveryMode(int deliveryMode) throws JMSException;
-
- /** Gets an indication of whether this message is being redelivered.
- *
- * <P>If a client receives a message with the <CODE>JMSRedelivered</CODE>
- * field set,
- * it is likely, but not guaranteed, that this message was delivered
- * earlier but that its receipt was not acknowledged
- * at that time.
- *
- * @return true if this message is being redelivered
- *
- * @exception JMSException if the JMS provider fails to get the redelivered
- * state due to some internal error.
- *
- * @see javax.jms.Message#setJMSRedelivered(boolean)
- */
-
boolean getJMSRedelivered() throws JMSException;
-
- /** Specifies whether this message is being redelivered.
- *
- * <P>This field is set at the time the message is delivered. This
- * method can be used to change the value for a message that has
- * been received.
- *
- * @param redelivered an indication of whether this message is being
- * redelivered
- *
- * @exception JMSException if the JMS provider fails to set the redelivered
- * state due to some internal error.
- *
- * @see javax.jms.Message#getJMSRedelivered()
- */
-
void setJMSRedelivered(boolean redelivered) throws JMSException;
-
- /** Gets the message type identifier supplied by the client when the
- * message was sent.
- *
- * @return the message type
- *
- * @exception JMSException if the JMS provider fails to get the message
- * type due to some internal error.
- *
- * @see javax.jms.Message#setJMSType(String)
- */
-
String getJMSType() throws JMSException;
-
- /** Sets the message type.
- *
- * <P>Some JMS providers use a message repository that contains the
- * definitions of messages sent by applications. The <CODE>JMSType</CODE>
- * header field may reference a message's definition in the provider's
- * repository.
- *
- * <P>The JMS API does not define a standard message definition repository,
- * nor does it define a naming policy for the definitions it contains.
- *
- * <P>Some messaging systems require that a message type definition for
- * each application message be created and that each message specify its
- * type. In order to work with such JMS providers, JMS clients should
- * assign a value to <CODE>JMSType</CODE>, whether the application makes
- * use of it or not. This ensures that the field is properly set for those
- * providers that require it.
- *
- * <P>To ensure portability, JMS clients should use symbolic values for
- * <CODE>JMSType</CODE> that can be configured at installation time to the
- * values defined in the current provider's message repository. If string
- * literals are used, they may not be valid type names for some JMS
- * providers.
- *
- * @param type the message type
- *
- * @exception JMSException if the JMS provider fails to set the message
- * type due to some internal error.
- *
- * @see javax.jms.Message#getJMSType()
- */
-
void setJMSType(String type) throws JMSException;
-
- /** Gets the message's expiration value.
- *
- * <P>When a message is sent, the <CODE>JMSExpiration</CODE> header field
- * is left unassigned. After completion of the <CODE>send</CODE> or
- * <CODE>publish</CODE> method, it holds the expiration time of the
- * message. This is the sum of the time-to-live value specified by the
- * client and the GMT at the time of the <CODE>send</CODE> or
- * <CODE>publish</CODE>.
- *
- * <P>If the time-to-live is specified as zero, <CODE>JMSExpiration</CODE>
- * is set to zero to indicate that the message does not expire.
- *
- * <P>When a message's expiration time is reached, a provider should
- * discard it. The JMS API does not define any form of notification of
- * message expiration.
- *
- * <P>Clients should not receive messages that have expired; however,
- * the JMS API does not guarantee that this will not happen.
- *
- * @return the time the message expires, which is the sum of the
- * time-to-live value specified by the client and the GMT at the
- * time of the send
- *
- * @exception JMSException if the JMS provider fails to get the message
- * expiration due to some internal error.
- *
- * @see javax.jms.Message#setJMSExpiration(long)
- */
-
long getJMSExpiration() throws JMSException;
-
- /** Sets the message's expiration value.
- *
- * <P>JMS providers set this field when a message is sent. This method
- * can be used to change the value for a message that has been received.
- *
- * @param expiration the message's expiration time
- *
- * @exception JMSException if the JMS provider fails to set the message
- * expiration due to some internal error.
- *
- * @see javax.jms.Message#getJMSExpiration()
- */
-
void setJMSExpiration(long expiration) throws JMSException;
-
- /** Gets the message priority level.
- *
- * <P>The JMS API defines ten levels of priority value, with 0 as the
- * lowest
- * priority and 9 as the highest. In addition, clients should consider
- * priorities 0-4 as gradations of normal priority and priorities 5-9
- * as gradations of expedited priority.
- *
- * <P>The JMS API does not require that a provider strictly implement
- * priority
- * ordering of messages; however, it should do its best to deliver
- * expedited messages ahead of normal messages.
- *
- * @return the default message priority
- *
- * @exception JMSException if the JMS provider fails to get the message
- * priority due to some internal error.
- *
- * @see javax.jms.Message#setJMSPriority(int)
- */
-
int getJMSPriority() throws JMSException;
-
- /** Sets the priority level for this message.
- *
- * <P>JMS providers set this field when a message is sent. This method
- * can be used to change the value for a message that has been received.
- *
- * @param priority the priority of this message
- *
- * @exception JMSException if the JMS provider fails to set the message
- * priority due to some internal error.
- *
- * @see javax.jms.Message#getJMSPriority()
- */
-
void setJMSPriority(int priority) throws JMSException;
-
- /** Clears a message's properties.
- *
- * <P>The message's header fields and body are not cleared.
- *
- * @exception JMSException if the JMS provider fails to clear the message
- * properties due to some internal error.
- */
-
void clearProperties() throws JMSException;
-
- /** Indicates whether a property value exists.
- *
- * @param name the name of the property to test
- *
- * @return true if the property exists
- *
- * @exception JMSException if the JMS provider fails to determine if the
- * property exists due to some internal error.
- */
-
boolean propertyExists(String name) throws JMSException;
-
- /** Returns the value of the <CODE>boolean</CODE> property with the
- * specified name.
- *
- * @param name the name of the <CODE>boolean</CODE> property
- *
- * @return the <CODE>boolean</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
boolean getBooleanProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>byte</CODE> property with the specified
- * name.
- *
- * @param name the name of the <CODE>byte</CODE> property
- *
- * @return the <CODE>byte</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
byte getByteProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>short</CODE> property with the specified
- * name.
- *
- * @param name the name of the <CODE>short</CODE> property
- *
- * @return the <CODE>short</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
short getShortProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>int</CODE> property with the specified
- * name.
- *
- * @param name the name of the <CODE>int</CODE> property
- *
- * @return the <CODE>int</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
int getIntProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>long</CODE> property with the specified
- * name.
- *
- * @param name the name of the <CODE>long</CODE> property
- *
- * @return the <CODE>long</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
long getLongProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>float</CODE> property with the specified
- * name.
- *
- * @param name the name of the <CODE>float</CODE> property
- *
- * @return the <CODE>float</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
float getFloatProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>double</CODE> property with the
specified
- * name.
- *
- * @param name the name of the <CODE>double</CODE> property
- *
- * @return the <CODE>double</CODE> property value for the specified name
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
double getDoubleProperty(String name) throws JMSException;
-
- /** Returns the value of the <CODE>String</CODE> property with the
specified
- * name.
- *
- * @param name the name of the <CODE>String</CODE> property
- *
- * @return the <CODE>String</CODE> property value for the specified name;
- * if there is no property by this name, a null value is returned
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- * @exception MessageFormatException if this type conversion is invalid.
- */
-
String getStringProperty(String name) throws JMSException;
-
- /** Returns the value of the Java object property with the specified name.
- *
- * <P>This method can be used to return, in objectified format,
- * an object that has been stored as a property in the message with the
- * equivalent <CODE>setObjectProperty</CODE> method call, or its equivalent
- * primitive <CODE>set<I>type</I>Property</CODE> method.
- *
- * @param name the name of the Java object property
- *
- * @return the Java object property value with the specified name, in
- * objectified format (for example, if the property was set as an
- * <CODE>int</CODE>, an <CODE>Integer</CODE> is
- * returned); if there is no property by this name, a null value
- * is returned
- *
- * @exception JMSException if the JMS provider fails to get the property
- * value due to some internal error.
- */
-
Object getObjectProperty(String name) throws JMSException;
-
- /** Returns an <CODE>Enumeration</CODE> of all the property names.
- *
- * <P>Note that JMS standard header fields are not considered
- * properties and are not returned in this enumeration.
- *
- * @return an enumeration of all the names of property values
- *
- * @exception JMSException if the JMS provider fails to get the property
- * names due to some internal error.
- */
-
Enumeration getPropertyNames() throws JMSException;
-
- /** Sets a <CODE>boolean</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>boolean</CODE> property
- * @param value the <CODE>boolean</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setBooleanProperty(String name, boolean value) throws JMSException;
-
- /** Sets a <CODE>byte</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>byte</CODE> property
- * @param value the <CODE>byte</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setByteProperty(String name, byte value) throws JMSException;
-
- /** Sets a <CODE>short</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>short</CODE> property
- * @param value the <CODE>short</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setShortProperty(String name, short value) throws JMSException;
-
- /** Sets an <CODE>int</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>int</CODE> property
- * @param value the <CODE>int</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setIntProperty(String name, int value) throws JMSException;
-
- /** Sets a <CODE>long</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>long</CODE> property
- * @param value the <CODE>long</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setLongProperty(String name, long value) throws JMSException;
-
- /** Sets a <CODE>float</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>float</CODE> property
- * @param value the <CODE>float</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setFloatProperty(String name, float value) throws JMSException;
-
- /** Sets a <CODE>double</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>double</CODE> property
- * @param value the <CODE>double</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setDoubleProperty(String name, double value) throws JMSException;
-
- /** Sets a <CODE>String</CODE> property value with the specified name into
- * the message.
- *
- * @param name the name of the <CODE>String</CODE> property
- * @param value the <CODE>String</CODE> property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setStringProperty(String name, String value) throws JMSException;
-
- /** Sets a Java object property value with the specified name into the
- * message.
- *
- * <P>Note that this method works only for the objectified primitive
- * object types (<CODE>Integer</CODE>, <CODE>Double</CODE>,
- * <CODE>Long</CODE> ...) and <CODE>String</CODE> objects.
- *
- * @param name the name of the Java object property
- * @param value the Java object property value to set
- *
- * @exception JMSException if the JMS provider fails to set the property
- * due to some internal error.
- * @exception IllegalArgumentException if the name is null or if the name
is
- * an empty string.
- * @exception MessageFormatException if the object is invalid
- * @exception MessageNotWriteableException if properties are read-only
- */
-
void setObjectProperty(String name, Object value) throws JMSException;
-
- /** Acknowledges all consumed messages of the session of this consumed
- * message.
- *
- * <P>All consumed JMS messages support the <CODE>acknowledge</CODE>
- * method for use when a client has specified that its JMS session's
- * consumed messages are to be explicitly acknowledged. By invoking
- * <CODE>acknowledge</CODE> on a consumed message, a client acknowledges
- * all messages consumed by the session that the message was delivered to.
- *
- * <P>Calls to <CODE>acknowledge</CODE> are ignored for both transacted
- * sessions and sessions specified to use implicit acknowledgement modes.
- *
- * <P>A client may individually acknowledge each message as it is consumed,
- * or it may choose to acknowledge messages as an application-defined group
- * (which is done by calling acknowledge on the last received message of
the group,
- * thereby acknowledging all messages consumed by the session.)
- *
- * <P>Messages that have been received but not acknowledged may be
- * redelivered.
- *
- * @exception JMSException if the JMS provider fails to acknowledge the
- * messages due to some internal error.
- * @exception IllegalStateException if this method is called on a closed
- * session.
- *
- * @see javax.jms.Session#CLIENT_ACKNOWLEDGE
- */
-
void acknowledge() throws JMSException;
-
-
- /** Clears out the message body. Clearing a message's body does not clear
- * its header values or property entries.
- *
- * <P>If this message body was read-only, calling this method leaves
- * the message body in the same state as an empty body in a newly
- * created message.
- *
- * @exception JMSException if the JMS provider fails to clear the message
- * body due to some internal error.
- */
void clearBody() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/MessageConsumer.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageConsumer.java,v
retrieving revision 1.1
diff -u -r1.1 MessageConsumer.java
--- specs/jms/src/java/javax/jms/MessageConsumer.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/MessageConsumer.java 19 Aug 2003 23:12:48
-0000
@@ -62,169 +62,21 @@
package javax.jms;
-/** A client uses a <CODE>MessageConsumer</CODE> object to receive messages
- * from a destination. A <CODE>MessageConsumer</CODE> object is created by
- * passing a <CODE>Destination</CODE> object to a message-consumer creation
- * method supplied by a session.
- *
- * <P><CODE>MessageConsumer</CODE> is the parent interface for all message
- * consumers.
- *
- * <P>A message consumer can be created with a message selector. A message
- * selector allows
- * the client to restrict the messages delivered to the message consumer to
- * those that match the selector.
- *
- * <P>A client may either synchronously receive a message consumer's messages
- * or have the consumer asynchronously deliver them as they arrive.
- *
- * <P>For synchronous receipt, a client can request the next message from a
- * message consumer using one of its <CODE>receive</CODE> methods. There are
- * several variations of <CODE>receive</CODE> that allow a
- * client to poll or wait for the next message.
- *
- * <P>For asynchronous delivery, a client can register a
- * <CODE>MessageListener</CODE> object with a message consumer.
- * As messages arrive at the message consumer, it delivers them by calling the
- * <CODE>MessageListener</CODE>'s <CODE>onMessage</CODE> method.
- *
- * <P>It is a client programming error for a <CODE>MessageListener</CODE> to
- * throw an exception.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.QueueReceiver
- * @see javax.jms.TopicSubscriber
- * @see javax.jms.Session
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface MessageConsumer {
+ String getMessageSelector() throws JMSException;
+
+ MessageListener getMessageListener() throws JMSException;
+
+ void setMessageListener(MessageListener listener) throws JMSException;
+
+ Message receive() throws JMSException;
+
+ Message receive(long timeout) throws JMSException;
- /** Gets this message consumer's message selector expression.
- *
- * @return this message consumer's message selector, or null if no
- * message selector exists for the message consumer (that is, if
- * the message selector was not set or was set to null or the
- * empty string)
- *
- * @exception JMSException if the JMS provider fails to get the message
- * selector due to some internal error.
- */
-
- String
- getMessageSelector() throws JMSException;
-
-
- /** Gets the message consumer's <CODE>MessageListener</CODE>.
- *
- * @return the listener for the message consumer, or null if no listener
- * is set
- *
- * @exception JMSException if the JMS provider fails to get the message
- * listener due to some internal error.
- * @see javax.jms.MessageConsumer#setMessageListener
- */
-
- MessageListener
- getMessageListener() throws JMSException;
-
-
- /** Sets the message consumer's <CODE>MessageListener</CODE>.
- *
- * <P>Setting the message listener to null is the equivalent of
- * unsetting the message listener for the message consumer.
- *
- * <P>The effect of calling <CODE>MessageConsumer.setMessageListener</CODE>
- * while messages are being consumed by an existing listener
- * or the consumer is being used to consume messages synchronously
- * is undefined.
- *
- * @param listener the listener to which the messages are to be
- * delivered
- *
- * @exception JMSException if the JMS provider fails to set the message
- * listener due to some internal error.
- * @see javax.jms.MessageConsumer#getMessageListener
- */
-
- void
- setMessageListener(MessageListener listener) throws JMSException;
-
-
- /** Receives the next message produced for this message consumer.
- *
- * <P>This call blocks indefinitely until a message is produced
- * or until this message consumer is closed.
- *
- * <P>If this <CODE>receive</CODE> is done within a transaction, the
- * consumer retains the message until the transaction commits.
- *
- * @return the next message produced for this message consumer, or
- * null if this message consumer is concurrently closed
- *
- * @exception JMSException if the JMS provider fails to receive the next
- * message due to some internal error.
- *
- */
-
- Message
- receive() throws JMSException;
-
-
- /** Receives the next message that arrives within the specified
- * timeout interval.
- *
- * <P>This call blocks until a message arrives, the
- * timeout expires, or this message consumer is closed.
- * A <CODE>timeout</CODE> of zero never expires, and the call blocks
- * indefinitely.
- *
- * @param timeout the timeout value (in milliseconds)
- *
- * @return the next message produced for this message consumer, or
- * null if the timeout expires or this message consumer is concurrently
- * closed
- *
- * @exception JMSException if the JMS provider fails to receive the next
- * message due to some internal error.
- */
-
- Message
- receive(long timeout) throws JMSException;
-
-
- /** Receives the next message if one is immediately available.
- *
- * @return the next message produced for this message consumer, or
- * null if one is not available
- *
- * @exception JMSException if the JMS provider fails to receive the next
- * message due to some internal error.
- */
-
- Message
- receiveNoWait() throws JMSException;
-
-
- /** Closes the message consumer.
- *
- * <P>Since a provider may allocate some resources on behalf of a
- * <CODE>MessageConsumer</CODE> outside the Java virtual machine, clients
- * should close them when they
- * are not needed. Relying on garbage collection to eventually reclaim
- * these resources may not be timely enough.
- *
- * <P>This call blocks until a <CODE>receive</CODE> or message listener in
- * progress has completed. A blocked message consumer <CODE>receive</CODE>
- * call
- * returns null when this message consumer is closed.
- *
- * @exception JMSException if the JMS provider fails to close the consumer
- * due to some internal error.
- */
+ Message receiveNoWait() throws JMSException;
- void
- close() throws JMSException;
+ void close() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/MessageEOFException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageEOFException.java,v
retrieving revision 1.1
diff -u -r1.1 MessageEOFException.java
--- specs/jms/src/java/javax/jms/MessageEOFException.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/MessageEOFException.java 19 Aug 2003
23:12:48 -0000
@@ -63,35 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when an unexpected
- * end of stream has been reached when a <CODE>StreamMessage</CODE> or
- * <CODE>BytesMessage</CODE> is being read.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class MessageEOFException extends JMSException {
-
- /** Constructs a <CODE>MessageEOFException</CODE> with the specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public MessageEOFException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>MessageEOFException</CODE> with the specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public MessageEOFException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/MessageFormatException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageFormatException.java,v
retrieving revision 1.1
diff -u -r1.1 MessageFormatException.java
--- specs/jms/src/java/javax/jms/MessageFormatException.java 16 Aug 2003
02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/MessageFormatException.java 19 Aug 2003
23:12:48 -0000
@@ -63,43 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a JMS client
- * attempts to use a data type not supported by a message or attempts to
- * read data in a message as the wrong type. It must also be thrown when
- * equivalent type errors are made with message property values. For
- * example, this exception must be thrown if
- * <CODE>StreamMessage.writeObject</CODE> is given an unsupported class or
- * if <CODE>StreamMessage.readShort</CODE> is used to read a
- * <CODE>boolean</CODE> value. Note that the special case of a failure
- * caused by an attempt to read improperly formatted <CODE>String</CODE>
- * data as numeric values must throw the
- * <CODE>java.lang.NumberFormatException</CODE>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class MessageFormatException extends JMSException {
-
- /** Constructs a <CODE>MessageFormatException</CODE> with the specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public MessageFormatException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>MessageFormatException</CODE> with the specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public MessageFormatException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/MessageListener.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageListener.java,v
retrieving revision 1.1
diff -u -r1.1 MessageListener.java
--- specs/jms/src/java/javax/jms/MessageListener.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/MessageListener.java 19 Aug 2003 23:12:48
-0000
@@ -62,27 +62,9 @@
package javax.jms;
-
-/** A <CODE>MessageListener</CODE> object is used to receive asynchronously
- * delivered messages.
- *
- * <P>Each session must insure that it passes messages serially to the
- * listener. This means that a listener assigned to one or more consumers
- * of the same session can assume that the <CODE>onMessage</CODE> method
- * is not called with the next message until the session has completed the
- * last call.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface MessageListener {
-
- /** Passes a message to the listener.
- *
- * @param message the message passed to the listener
- */
-
void onMessage(Message message);
}
Index: specs/jms/src/java/javax/jms/MessageNotReadableException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageNotReadableException.java,v
retrieving revision 1.1
diff -u -r1.1 MessageNotReadableException.java
--- specs/jms/src/java/javax/jms/MessageNotReadableException.java 16 Aug
2003 02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/MessageNotReadableException.java 19 Aug
2003 23:12:48 -0000
@@ -63,34 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a JMS client attempts to read a
- * write-only message.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class MessageNotReadableException extends JMSException {
-
- /** Constructs a <CODE>MessageNotReadableException</CODE> with the
specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public MessageNotReadableException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>MessageNotReadableException</CODE> with the
specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public MessageNotReadableException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/MessageNotWriteableException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageNotWriteableException.java,v
retrieving revision 1.1
diff -u -r1.1 MessageNotWriteableException.java
--- specs/jms/src/java/javax/jms/MessageNotWriteableException.java 16 Aug
2003 02:29:57 -0000 1.1
+++ specs/jms/src/java/javax/jms/MessageNotWriteableException.java 19 Aug
2003 23:12:48 -0000
@@ -63,34 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a JMS client attempts to write to a
- * read-only message.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class MessageNotWriteableException extends JMSException {
-
- /** Constructs a <CODE>MessageNotWriteableException</CODE> with the
specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public MessageNotWriteableException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>MessageNotWriteableException</CODE> with the
specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public MessageNotWriteableException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/MessageProducer.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/MessageProducer.java,v
retrieving revision 1.1
diff -u -r1.1 MessageProducer.java
--- specs/jms/src/java/javax/jms/MessageProducer.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/MessageProducer.java 19 Aug 2003 23:12:48
-0000
@@ -62,365 +62,46 @@
package javax.jms;
-/** A client uses a <CODE>MessageProducer</CODE> object to send messages to a
- * destination. A <CODE>MessageProducer</CODE> object is created by passing a
- * <CODE>Destination</CODE> object to a message-producer creation method
- * supplied by a session.
- *
- * <P><CODE>MessageProducer</CODE> is the parent interface for all message
- * producers.
- *
- * <P>A client also has the option of creating a message producer without
- * supplying a destination. In this case, a destination must be provided with
- * every send operation. A typical use for this kind of message producer is
- * to send replies to requests using the request's <CODE>JMSReplyTo</CODE>
- * destination.
- *
- * <P>A client can specify a default delivery mode, priority, and time to live
- * for messages sent by a message producer. It can also specify the delivery
- * mode, priority, and time to live for an individual message.
- *
- * <P>A client can specify a time-to-live value in milliseconds for each
- * message it sends. This value defines a message expiration time that
- * is the sum of the message's time-to-live and the GMT when it is sent (for
- * transacted sends, this is the time the client sends the message, not
- * the time the transaction is committed).
- *
- * <P>A JMS provider should do its best to expire messages accurately;
- * however, the JMS API does not define the accuracy provided.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.TopicPublisher
- * @see javax.jms.QueueSender
- * @see javax.jms.Session#createProducer
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface MessageProducer {
+ void setDisableMessageID(boolean value) throws JMSException;
+
+ boolean getDisableMessageID() throws JMSException;
+
+ void setDisableMessageTimestamp(boolean value) throws JMSException;
+
+ boolean getDisableMessageTimestamp() throws JMSException;
+
+ void setDeliveryMode(int deliveryMode) throws JMSException;
+
+ int getDeliveryMode() throws JMSException;
+
+ void setPriority(int defaultPriority) throws JMSException;
+
+ int getPriority() throws JMSException;
+
+ void setTimeToLive(long timeToLive) throws JMSException;
+
+ long getTimeToLive() throws JMSException;
+
+ Destination getDestination() throws JMSException;
+
+ void close() throws JMSException;
+
+ void send(Message message) throws JMSException;
- /** Sets whether message IDs are disabled.
- *
- * <P>Since message IDs take some effort to create and increase a
- * message's size, some JMS providers may be able to optimize message
- * overhead if they are given a hint that the message ID is not used by
- * an application. By calling the <CODE>setDisableMessageID</CODE>
- * method on this message producer, a JMS client enables this potential
- * optimization for all messages sent by this message producer. If the JMS
- * provider accepts this hint,
- * these messages must have the message ID set to null; if the provider
- * ignores the hint, the message ID must be set to its normal unique value.
- *
- * <P>Message IDs are enabled by default.
- *
- * @param value indicates if message IDs are disabled
- *
- * @exception JMSException if the JMS provider fails to set message ID to
- * disabled due to some internal error.
- */
-
- void
- setDisableMessageID(boolean value) throws JMSException;
-
-
- /** Gets an indication of whether message IDs are disabled.
- *
- * @return an indication of whether message IDs are disabled
- *
- * @exception JMSException if the JMS provider fails to determine if
- * message IDs are disabled due to some internal
- * error.
- */
-
- boolean
- getDisableMessageID() throws JMSException;
-
-
- /** Sets whether message timestamps are disabled.
- *
- * <P>Since timestamps take some effort to create and increase a
- * message's size, some JMS providers may be able to optimize message
- * overhead if they are given a hint that the timestamp is not used by an
- * application. By calling the <CODE>setDisableMessageTimestamp</CODE>
- * method on this message producer, a JMS client enables this potential
- * optimization for all messages sent by this message producer. If the
- * JMS provider accepts this hint,
- * these messages must have the timestamp set to zero; if the provider
- * ignores the hint, the timestamp must be set to its normal value.
- *
- * <P>Message timestamps are enabled by default.
- *
- * @param value indicates if message timestamps are disabled
- *
- * @exception JMSException if the JMS provider fails to set timestamps to
- * disabled due to some internal error.
- */
-
- void
- setDisableMessageTimestamp(boolean value) throws JMSException;
-
-
- /** Gets an indication of whether message timestamps are disabled.
- *
- * @return an indication of whether message timestamps are disabled
- *
- * @exception JMSException if the JMS provider fails to determine if
- * timestamps are disabled due to some internal
- * error.
- */
-
- boolean
- getDisableMessageTimestamp() throws JMSException;
-
-
- /** Sets the producer's default delivery mode.
- *
- * <P>Delivery mode is set to <CODE>PERSISTENT</CODE> by default.
- *
- * @param deliveryMode the message delivery mode for this message
- * producer; legal values are <code>DeliveryMode.NON_PERSISTENT</code>
- * and <code>DeliveryMode.PERSISTENT</code>
- *
- * @exception JMSException if the JMS provider fails to set the delivery
- * mode due to some internal error.
- *
- * @see javax.jms.MessageProducer#getDeliveryMode
- * @see javax.jms.DeliveryMode#NON_PERSISTENT
- * @see javax.jms.DeliveryMode#PERSISTENT
- * @see javax.jms.Message#DEFAULT_DELIVERY_MODE
- */
-
- void
- setDeliveryMode(int deliveryMode) throws JMSException;
-
-
- /** Gets the producer's default delivery mode.
- *
- * @return the message delivery mode for this message producer
- *
- * @exception JMSException if the JMS provider fails to get the delivery
- * mode due to some internal error.
- *
- * @see javax.jms.MessageProducer#setDeliveryMode
- */
-
- int
- getDeliveryMode() throws JMSException;
-
-
- /** Sets the producer's default priority.
- *
- * <P>The JMS API defines ten levels of priority value, with 0 as the
- * lowest priority and 9 as the highest. Clients should consider priorities
- * 0-4 as gradations of normal priority and priorities 5-9 as gradations
- * of expedited priority. Priority is set to 4 by default.
- *
- * @param defaultPriority the message priority for this message producer;
- * must be a value between 0 and 9
- *
- *
- * @exception JMSException if the JMS provider fails to set the priority
- * due to some internal error.
- *
- * @see javax.jms.MessageProducer#getPriority
- * @see javax.jms.Message#DEFAULT_PRIORITY
- */
-
- void
- setPriority(int defaultPriority) throws JMSException;
-
-
- /** Gets the producer's default priority.
- *
- * @return the message priority for this message producer
- *
- * @exception JMSException if the JMS provider fails to get the priority
- * due to some internal error.
- *
- * @see javax.jms.MessageProducer#setPriority
- */
-
- int
- getPriority() throws JMSException;
-
-
- /** Sets the default length of time in milliseconds from its dispatch time
- * that a produced message should be retained by the message system.
- *
- * <P>Time to live is set to zero by default.
- *
- * @param timeToLive the message time to live in milliseconds; zero is
- * unlimited
- *
- * @exception JMSException if the JMS provider fails to set the time to
- * live due to some internal error.
- *
- * @see javax.jms.MessageProducer#getTimeToLive
- * @see javax.jms.Message#DEFAULT_TIME_TO_LIVE
- */
-
- void
- setTimeToLive(long timeToLive) throws JMSException;
-
-
- /** Gets the default length of time in milliseconds from its dispatch time
- * that a produced message should be retained by the message system.
- *
- * @return the message time to live in milliseconds; zero is unlimited
- *
- * @exception JMSException if the JMS provider fails to get the time to
- * live due to some internal error.
- *
- * @see javax.jms.MessageProducer#setTimeToLive
- */
-
- long
- getTimeToLive() throws JMSException;
-
- /** Gets the destination associated with this <CODE>MessageProducer</CODE>.
- *
- * @return this producer's <CODE>Destination/<CODE>
- *
- * @exception JMSException if the JMS provider fails to get the
destination for
- * this <CODE>MessageProducer</CODE>
- * due to some internal error.
- [EMAIL PROTECTED] 1.1
- */
-
- Destination
- getDestination() throws JMSException;
-
- /** Closes the message producer.
- *
- * <P>Since a provider may allocate some resources on behalf of a
- * <CODE>MessageProducer</CODE> outside the Java virtual machine, clients
- * should close them when they
- * are not needed. Relying on garbage collection to eventually reclaim
- * these resources may not be timely enough.
- *
- * @exception JMSException if the JMS provider fails to close the producer
- * due to some internal error.
- */
-
- void
- close() throws JMSException;
-
-
- /** Sends a message using the <CODE>MessageProducer</CODE>'s
- * default delivery mode, priority, and time to live.
- *
- * @param message the message to send
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with a <CODE>MessageProducer</CODE>
with
- * an invalid destination.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>MessageProducer</CODE> that
did
- * not specify a destination at creation time.
- *
- * @see javax.jms.Session#createProducer
- * @see javax.jms.MessageProducer
- *
- * @since 1.1
- */
-
- void
- send(Message message) throws JMSException;
-
- /** Sends a message to the destination, specifying delivery mode,
priority, and
- * time to live.
- *
- * @param message the message to send
- * @param deliveryMode the delivery mode to use
- * @param priority the priority for this message
- * @param timeToLive the message's lifetime (in milliseconds)
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with a <CODE>MessageProducer</CODE>
with
- * an invalid destination.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>MessageProducer</CODE> that
did
- * not specify a destination at creation time.
- *
- * @see javax.jms.Session#createProducer
- * @since 1.1
- */
-
- void
- send(Message message,
- int deliveryMode,
- int priority,
- long timeToLive) throws JMSException;
-
-
- /**Sends a message to a destination for an unidentified message producer.
- * Uses the <CODE>MessageProducer</CODE>'s default delivery mode, priority,
- * and time to live.
- *
- * <P>Typically, a message producer is assigned a destination at creation
- * time; however, the JMS API also supports unidentified message producers,
- * which require that the destination be supplied every time a message is
- * sent.
- *
- * @param destination the destination to send this message to
- * @param message the message to send
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with an invalid destination.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>MessageProducer</CODE> that
- * specified a destination at creation time.
- *
- * @see javax.jms.Session#createProducer
- * @see javax.jms.MessageProducer
- * @since 1.1
- */
-
- void
- send(Destination destination, Message message) throws JMSException;
-
-
- /** Sends a message to a destination for an unidentified message producer,
- * specifying delivery mode, priority and time to live.
- *
- * <P>Typically, a message producer is assigned a destination at creation
- * time; however, the JMS API also supports unidentified message producers,
- * which require that the destination be supplied every time a message is
- * sent.
- *
- * @param destination the destination to send this message to
- * @param message the message to send
- * @param deliveryMode the delivery mode to use
- * @param priority the priority for this message
- * @param timeToLive the message's lifetime (in milliseconds)
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with an invalid destination.
- *
- * @see javax.jms.Session#createProducer
- * @since 1.1
- */
-
- void
- send(Destination destination,
- Message message,
- int deliveryMode,
- int priority,
- long timeToLive) throws JMSException;
+ void send(Message message, int deliveryMode, int priority, long timeToLive)
+ throws JMSException;
+ void send(Destination destination, Message message) throws JMSException;
+ void send(
+ Destination destination,
+ Message message,
+ int deliveryMode,
+ int priority,
+ long timeToLive)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/ObjectMessage.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ObjectMessage.java,v
retrieving revision 1.1
diff -u -r1.1 ObjectMessage.java
--- specs/jms/src/java/javax/jms/ObjectMessage.java 16 Aug 2003 02:29:57
-0000 1.1
+++ specs/jms/src/java/javax/jms/ObjectMessage.java 19 Aug 2003 23:12:48
-0000
@@ -64,63 +64,11 @@
import java.io.Serializable;
-/** An <CODE>ObjectMessage</CODE> object is used to send a message that
contains
- * a serializable object in the Java programming language ("Java object").
- * It inherits from the <CODE>Message</CODE> interface and adds a body
- * containing a single reference to an object. Only <CODE>Serializable</CODE>
- * Java objects can be used.
- *
- * <P>If a collection of Java objects must be sent, one of the
- * <CODE>Collection</CODE> classes provided since JDK 1.2 can be used.
- *
- * <P>When a client receives an <CODE>ObjectMessage</CODE>, it is in read-only
- * mode. If a client attempts to write to the message at this point, a
- * <CODE>MessageNotWriteableException</CODE> is thrown. If
- * <CODE>clearBody</CODE> is called, the message can now be both read from and
- * written to.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:57 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.Session#createObjectMessage()
- * @see javax.jms.Session#createObjectMessage(Serializable)
- * @see javax.jms.BytesMessage
- * @see javax.jms.MapMessage
- * @see javax.jms.Message
- * @see javax.jms.StreamMessage
- * @see javax.jms.TextMessage
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ObjectMessage extends Message {
-
- /** Sets the serializable object containing this message's data.
- * It is important to note that an <CODE>ObjectMessage</CODE>
- * contains a snapshot of the object at the time <CODE>setObject()</CODE>
- * is called; subsequent modifications of the object will have no
- * effect on the <CODE>ObjectMessage</CODE> body.
- *
- * @param object the message's data
- *
- * @exception JMSException if the JMS provider fails to set the object
- * due to some internal error.
- * @exception MessageFormatException if object serialization fails.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void setObject(Serializable object) throws JMSException;
-
-
- /** Gets the serializable object containing this message's data. The
- * default value is null.
- *
- * @return the serializable object containing this message's data
- *
- * @exception JMSException if the JMS provider fails to get the object
- * due to some internal error.
- * @exception MessageFormatException if object deserialization fails.
- */
Serializable getObject() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/Queue.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/Queue.java,v
retrieving revision 1.1
diff -u -r1.1 Queue.java
--- specs/jms/src/java/javax/jms/Queue.java 16 Aug 2003 02:29:58 -0000
1.1
+++ specs/jms/src/java/javax/jms/Queue.java 19 Aug 2003 23:12:48 -0000
@@ -62,56 +62,11 @@
package javax.jms;
-
-/** A <CODE>Queue</CODE> object encapsulates a provider-specific queue name.
- * It is the way a client specifies the identity of a queue to JMS API methods.
- * For those methods that use a <CODE>Destination</CODE> as a parameter, a
- * <CODE>Queue</CODE> object used as an argument. For example, a queue can
- * be used to create a <CODE>MessageConsumer</CODE> and a
- * <CODE>MessageProducer</CODE> by calling:
- *<UL>
- *<LI> <CODE>Session.CreateConsumer(Destination destination)</CODE>
- *<LI> <CODE>Session.CreateProducer(Destination destination)</CODE>
- *
- *</UL>
- *
- * <P>The actual length of time messages are held by a queue and the
- * consequences of resource overflow are not defined by the JMS API.
- *
- *
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see Session#createConsumer(Destination)
- * @see Session#createProducer(Destination)
- * @see Session#createQueue(String)
- * @see QueueSession#createQueue(String)
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface Queue extends Destination {
-
- /** Gets the name of this queue.
- *
- * <P>Clients that depend upon the name are not portable.
- *
- * @return the queue name
- *
- * @exception JMSException if the JMS provider implementation of
- * <CODE>Queue</CODE> fails to return the queue
- * name due to some internal
- * error.
- */
-
String getQueueName() throws JMSException;
-
-
- /** Returns a string representation of this object.
- *
- * @return the provider-specific identity values for this queue
- */
String toString();
}
Index: specs/jms/src/java/javax/jms/QueueBrowser.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueBrowser.java,v
retrieving revision 1.1
diff -u -r1.1 QueueBrowser.java
--- specs/jms/src/java/javax/jms/QueueBrowser.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/QueueBrowser.java 19 Aug 2003 23:12:49
-0000
@@ -64,86 +64,15 @@
import java.util.Enumeration;
-/** A client uses a <CODE>QueueBrowser</CODE> object to look at messages on a
- * queue without removing them.
- *
- * <P>The <CODE>getEnumeration</CODE> method returns a
- * <CODE>java.util.Enumeration</CODE> that is used to scan
- * the queue's messages. It may be an enumeration of the entire content of a
- * queue, or it may contain only the messages matching a message selector.
- *
- * <P>Messages may be arriving and expiring while the scan is done. The JMS API
- * does
- * not require the content of an enumeration to be a static snapshot of queue
- * content. Whether these changes are visible or not depends on the JMS
- * provider.
- *
- *<P>A <CODE>QueueBrowser</CODE> can be created from either a
- * <CODE>Session</CODE> or a <CODE> QueueSession</CODE>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session#createBrowser
- * @see javax.jms.QueueSession#createBrowser
- * @see javax.jms.QueueReceiver
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface QueueBrowser {
-
- /** Gets the queue associated with this queue browser.
- *
- * @return the queue
- *
- * @exception JMSException if the JMS provider fails to get the
- * queue associated with this browser
- * due to some internal error.
- */
-
Queue getQueue() throws JMSException;
-
- /** Gets this queue browser's message selector expression.
- *
- * @return this queue browser's message selector, or null if no
- * message selector exists for the message consumer (that is, if
- * the message selector was not set or was set to null or the
- * empty string)
- *
- * @exception JMSException if the JMS provider fails to get the
- * message selector for this browser
- * due to some internal error.
- */
-
String getMessageSelector() throws JMSException;
-
- /** Gets an enumeration for browsing the current queue messages in the
- * order they would be received.
- *
- * @return an enumeration for browsing the messages
- *
- * @exception JMSException if the JMS provider fails to get the
- * enumeration for this browser
- * due to some internal error.
- */
-
Enumeration getEnumeration() throws JMSException;
-
-
- /** Closes the <CODE>QueueBrowser</CODE>.
- *
- * <P>Since a provider may allocate some resources on behalf of a
- * QueueBrowser outside the Java virtual machine, clients should close them
- * when they
- * are not needed. Relying on garbage collection to eventually reclaim
- * these resources may not be timely enough.
- *
- * @exception JMSException if the JMS provider fails to close this
- * browser due to some internal error.
- */
void close() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/QueueConnection.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueConnection.java,v
retrieving revision 1.1
diff -u -r1.1 QueueConnection.java
--- specs/jms/src/java/javax/jms/QueueConnection.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/QueueConnection.java 19 Aug 2003 23:12:49
-0000
@@ -62,88 +62,17 @@
package javax.jms;
-/** A <CODE>QueueConnection</CODE> object is an active connection to a
- * point-to-point JMS provider. A client uses a <CODE>QueueConnection</CODE>
- * object to create one or more <CODE>QueueSession</CODE> objects
- * for producing and consuming messages.
- *
- *<P>A <CODE>QueueConnection</CODE> can be used to create a
- * <CODE>QueueSession</CODE>, from which specialized queue-related objects
- * can be created.
- * A more general, and recommended, approach is to use the
- * <CODE>Connection</CODE> object.
- *
- *
- * <P>The <CODE>QueueConnection</CODE> object
- * should be used to support existing code that has already used it.
- *
- * <P>A <CODE>QueueConnection</CODE> cannot be used to create objects
- * specific to the publish/subscribe domain. The
- * <CODE>createDurableConnectionConsumer</CODE> method inherits
- * from <CODE>Connection</CODE>, but must throw an
- * <CODE>IllegalStateException</CODE>
- * if used from <CODE>QueueConnection</CODE>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Connection
- * @see javax.jms.ConnectionFactory
- * @see javax.jms.QueueConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface QueueConnection extends Connection {
+ QueueSession createQueueSession(boolean transacted, int acknowledgeMode)
+ throws JMSException;
- /** Creates a <CODE>QueueSession</CODE> object.
- *
- * @param transacted indicates whether the session is transacted
- * @param acknowledgeMode indicates whether the consumer or the
- * client will acknowledge any messages it receives; ignored if the session
- * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
- * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
- * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
- *
- * @return a newly created queue session
- *
- * @exception JMSException if the <CODE>QueueConnection</CODE> object fails
- * to create a session due to some internal error
or
- * lack of support for the specific transaction
- * and acknowledgement mode.
- *
- * @see Session#AUTO_ACKNOWLEDGE
- * @see Session#CLIENT_ACKNOWLEDGE
- * @see Session#DUPS_OK_ACKNOWLEDGE
- */
-
- QueueSession createQueueSession(boolean transacted, int acknowledgeMode)
throws JMSException;
-
-
- /** Creates a connection consumer for this connection (optional operation).
- * This is an expert facility not used by regular JMS clients.
- *
- * @param queue the queue to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param sessionPool the server session pool to associate with this
- * connection consumer
- * @param maxMessages the maximum number of messages that can be
- * assigned to a server session at one time
- *
- * @return the connection consumer
- *
- * @exception JMSException if the <CODE>QueueConnection</CODE> object fails
- * to create a connection consumer due to some
- * internal error or invalid arguments for
- * <CODE>sessionPool</CODE> and
- * <CODE>messageSelector</CODE>.
- * @exception InvalidDestinationException if an invalid queue is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- * @see javax.jms.ConnectionConsumer
- */
-
- ConnectionConsumer createConnectionConsumer(Queue queue, String
messageSelector, ServerSessionPool sessionPool, int maxMessages) throws
JMSException;
+ ConnectionConsumer createConnectionConsumer(
+ Queue queue,
+ String messageSelector,
+ ServerSessionPool sessionPool,
+ int maxMessages)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/QueueConnectionFactory.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueConnectionFactory.java,v
retrieving revision 1.1
diff -u -r1.1 QueueConnectionFactory.java
--- specs/jms/src/java/javax/jms/QueueConnectionFactory.java 16 Aug 2003
02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/QueueConnectionFactory.java 19 Aug 2003
23:12:49 -0000
@@ -62,60 +62,12 @@
package javax.jms;
-/** A client uses a <CODE>QueueConnectionFactory</CODE> object to create
- * <CODE>QueueConnection</CODE> objects with a point-to-point JMS provider.
- *
- * <P><CODE>QueueConnectionFactory</CODE> can be used to create a
- * <CODE>QueueConnection</CODE>, from which specialized queue-related objects
- * can be created. A more general, and recommended, approach
- * is to use the <CODE>ConnectionFactory</CODE> object.
- *
- *<P> The <CODE>QueueConnectionFactory</CODE> object
- * can be used to support existing code that already uses it.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.ConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface QueueConnectionFactory extends ConnectionFactory {
-
- /** Creates a queue connection with the default user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- .
- *
- * @return a newly created queue connection
- *
- * @exception JMSException if the JMS provider fails to create the queue
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
QueueConnection createQueueConnection() throws JMSException;
-
- /** Creates a queue connection with the specified user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @param userName the caller's user name
- * @param password the caller's password
- *
- * @return a newly created queue connection
- *
- * @exception JMSException if the JMS provider fails to create the queue
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
- QueueConnection createQueueConnection(String userName, String password)
throws JMSException;
+ QueueConnection createQueueConnection(String userName, String password)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/QueueReceiver.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueReceiver.java,v
retrieving revision 1.1
diff -u -r1.1 QueueReceiver.java
--- specs/jms/src/java/javax/jms/QueueReceiver.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/QueueReceiver.java 19 Aug 2003 23:12:49
-0000
@@ -62,49 +62,9 @@
package javax.jms;
-
-/** A client uses a <CODE>QueueReceiver</CODE> object to receive messages that
- * have been delivered to a queue.
- *
- * <P>Although it is possible to have multiple <CODE>QueueReceiver</CODE>s
- * for the same queue, the JMS API does not define how messages are
- * distributed between the <CODE>QueueReceiver</CODE>s.
- *
- * <P>If a <CODE>QueueReceiver</CODE> specifies a message selector, the
- * messages that are not selected remain on the queue. By definition, a message
- * selector allows a <CODE>QueueReceiver</CODE> to skip messages. This
- * means that when the skipped messages are eventually read, the total ordering
- * of the reads does not retain the partial order defined by each message
- * producer. Only <CODE>QueueReceiver</CODE>s without a message selector
- * will read messages in message producer order.
- *
- * <P>Creating a <CODE>MessageConsumer</CODE> provides the same features as
- * creating a <CODE>QueueReceiver</CODE>. A <CODE>MessageConsumer</CODE>
object is
- * recommended for creating new code. The <CODE>QueueReceiver</CODE> is
- * provided to support existing code.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session#createConsumer(Destination, String)
- * @see javax.jms.Session#createConsumer(Destination)
- * @see javax.jms.QueueSession#createReceiver(Queue, String)
- * @see javax.jms.QueueSession#createReceiver(Queue)
- * @see javax.jms.MessageConsumer
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface QueueReceiver extends MessageConsumer {
-
- /** Gets the <CODE>Queue</CODE> associated with this queue receiver.
- *
- * @return this receiver's <CODE>Queue</CODE>
- *
- * @exception JMSException if the JMS provider fails to get the queue for
- * this queue receiver
- * due to some internal error.
- */
-
Queue getQueue() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/QueueRequestor.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueRequestor.java,v
retrieving revision 1.1
diff -u -r1.1 QueueRequestor.java
--- specs/jms/src/java/javax/jms/QueueRequestor.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/QueueRequestor.java 19 Aug 2003 23:12:49
-0000
@@ -62,100 +62,74 @@
package javax.jms;
-/** The <CODE>QueueRequestor</CODE> helper class simplifies
- * making service requests.
- *
- * <P>The <CODE>QueueRequestor</CODE> constructor is given a non-transacted
- * <CODE>QueueSession</CODE> and a destination <CODE>Queue</CODE>. It creates a
- * <CODE>TemporaryQueue</CODE> for the responses and provides a
- * <CODE>request</CODE> method that sends the request message and waits
- * for its reply.
- *
- * <P>This is a basic request/reply abstraction that should be sufficient
- * for most uses. JMS providers and clients are free to create more
- * sophisticated versions.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.TopicRequestor
+/**
+ * @version $Revision:$ $Date:$
*/
-
public class QueueRequestor {
+ private QueueSession session;
+ private Queue queue;
+ private TemporaryQueue temporaryQueue;
+ private QueueSender sender;
+ private QueueReceiver receiver;
+
+ public QueueRequestor(QueueSession session, Queue queue)
+ throws JMSException {
+ super();
+ setSession(session);
+ setQueue(queue);
+ setTemporaryQueue(session.createTemporaryQueue());
+ setSender(session.createSender(queue));
+ setReceiver(session.createReceiver(getTemporaryQueue()));
+ }
- QueueSession session; // The queue session the queue belongs to.
- Queue queue; // The queue to perform the request/reply on.
- TemporaryQueue tempQueue;
- QueueSender sender;
- QueueReceiver receiver;
-
-
- /** Constructor for the <CODE>QueueRequestor</CODE> class.
- *
- * <P>This implementation assumes the session parameter to be
non-transacted,
- * with a delivery mode of either <CODE>AUTO_ACKNOWLEDGE</CODE> or
- * <CODE>DUPS_OK_ACKNOWLEDGE</CODE>.
- *
- * @param session the <CODE>QueueSession</CODE> the queue belongs to
- * @param queue the queue to perform the request/reply call on
- *
- * @exception JMSException if the JMS provider fails to create the
- * <CODE>QueueRequestor</CODE> due to some internal
- * error.
- * @exception InvalidDestinationException if an invalid queue is specified.
- */
+ public Message request(Message message) throws JMSException {
+ message.setJMSReplyTo(getTemporaryQueue());
+ getSender().send(message);
+ return getReceiver().receive();
+ }
- public QueueRequestor(QueueSession session, Queue queue) throws
JMSException {
- this.session = session;
+ public void close() throws JMSException {
+ getSession().close();
+ getTemporaryQueue().delete();
+ }
+
+ private void setQueue(Queue queue) {
this.queue = queue;
- tempQueue = session.createTemporaryQueue();
- sender = session.createSender(queue);
- receiver = session.createReceiver(tempQueue);
}
+ private Queue getQueue() {
+ return queue;
+ }
- /** Sends a request and waits for a reply. The temporary queue is used for
- * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
- * is expected.
- *
- * @param message the message to send
- *
- * @return the reply message
- *
- * @exception JMSException if the JMS provider fails to complete the
- * request due to some internal error.
- */
-
- public Message
- request(Message message) throws JMSException {
- message.setJMSReplyTo(tempQueue);
- sender.send(message);
- return (receiver.receive());
+ private void setReceiver(QueueReceiver receiver) {
+ this.receiver = receiver;
}
+ private QueueReceiver getReceiver() {
+ return receiver;
+ }
+
+ private void setSender(QueueSender sender) {
+ this.sender = sender;
+ }
+
+ private QueueSender getSender() {
+ return sender;
+ }
+
+ private void setSession(QueueSession session) {
+ this.session = session;
+ }
+
+ private QueueSession getSession() {
+ return session;
+ }
+
+ private void setTemporaryQueue(TemporaryQueue temporaryQueue) {
+ this.temporaryQueue = temporaryQueue;
+ }
- /** Closes the <CODE>QueueRequestor</CODE> and its session.
- *
- * <P>Since a provider may allocate some resources on behalf of a
- * <CODE>QueueRequestor</CODE> outside the Java virtual machine, clients
- * should close them when they
- * are not needed. Relying on garbage collection to eventually reclaim
- * these resources may not be timely enough.
- *
- * <P>Note that this method closes the <CODE>QueueSession</CODE> object
- * passed to the <CODE>QueueRequestor</CODE> constructor.
- *
- * @exception JMSException if the JMS provider fails to close the
- * <CODE>QueueRequestor</CODE> due to some internal
- * error.
- */
-
- public void
- close() throws JMSException {
-
- // publisher and consumer created by constructor are implicitly closed.
- session.close();
- tempQueue.delete();
+ private TemporaryQueue getTemporaryQueue() {
+ return temporaryQueue;
}
}
Index: specs/jms/src/java/javax/jms/QueueSender.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueSender.java,v
retrieving revision 1.1
diff -u -r1.1 QueueSender.java
--- specs/jms/src/java/javax/jms/QueueSender.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/QueueSender.java 19 Aug 2003 23:12:49
-0000
@@ -62,161 +62,24 @@
package javax.jms;
-/** A client uses a <CODE>QueueSender</CODE> object to send messages to a
queue.
- *
- * <P>Normally, the <CODE>Queue</CODE> is specified when a
- * <CODE>QueueSender</CODE> is created. In this case, an attempt to use
- * the <CODE>send</CODE> methods for an unidentified
- * <CODE>QueueSender</CODE> will throw a
- * <CODE>java.lang.UnsupportedOperationException</CODE>.
- *
- * <P>If the <CODE>QueueSender</CODE> is created with an unidentified
- * <CODE>Queue</CODE>, an attempt to use the <CODE>send</CODE> methods that
- * assume that the <CODE>Queue</CODE> has been identified will throw a
- * <CODE>java.lang.UnsupportedOperationException</CODE>.
- *
- * <P>During the execution of its <CODE>send</CODE> method, a message
- * must not be changed by other threads within the client.
- * If the message is modified, the result of the <CODE>send</CODE> is
- * undefined.
- *
- * <P>After sending a message, a client may retain and modify it
- * without affecting the message that has been sent. The same message
- * object may be sent multiple times.
- *
- * <P>The following message headers are set as part of sending a
- * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
- * <code>JMSExpiration</code>, <code>JMSPriority</code>,
- * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
- * When the message is sent, the values of these headers are ignored.
- * After the completion of the <CODE>send</CODE>, the headers hold the values
- * specified by the method sending the message. It is possible for the
- * <code>send</code> method not to set <code>JMSMessageID</code> and
- * <code>JMSTimeStamp</code> if the
- * setting of these headers is explicitly disabled by the
- * <code>MessageProducer.setDisableMessageID</code> or
- * <code>MessageProducer.setDisableMessageTimestamp</code> method.
- *
- * <P>Creating a <CODE>MessageProducer</CODE> provides the same features as
- * creating a <CODE>QueueSender</CODE>. A <CODE>MessageProducer</CODE> object
is
- * recommended when creating new code. The <CODE>QueueSender</CODE> is
- * provided to support existing code.
- *
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.MessageProducer
- * @see javax.jms.Session#createProducer(Destination)
- * @see javax.jms.QueueSession#createSender(Queue)
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface QueueSender extends MessageProducer {
-
- /** Gets the queue associated with this <CODE>QueueSender</CODE>.
- *
- * @return this sender's queue
- *
- * @exception JMSException if the JMS provider fails to get the queue for
- * this <CODE>QueueSender</CODE>
- * due to some internal error.
- */
-
Queue getQueue() throws JMSException;
-
- /** Sends a message to the queue. Uses the <CODE>QueueSender</CODE>'s
- * default delivery mode, priority, and time to live.
- *
- * @param message the message to send
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with a <CODE>QueueSender</CODE> with
- * an invalid queue.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>QueueSender</CODE> that did
- * not specify a queue at creation time.
- *
- * @see javax.jms.MessageProducer#getDeliveryMode()
- * @see javax.jms.MessageProducer#getTimeToLive()
- * @see javax.jms.MessageProducer#getPriority()
- */
-
void send(Message message) throws JMSException;
-
- /** Sends a message to the queue, specifying delivery mode, priority, and
- * time to live.
- *
- * @param message the message to send
- * @param deliveryMode the delivery mode to use
- * @param priority the priority for this message
- * @param timeToLive the message's lifetime (in milliseconds)
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with a <CODE>QueueSender</CODE> with
- * an invalid queue.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>QueueSender</CODE> that did
- * not specify a queue at creation time.
- */
-
- void send(Message message, int deliveryMode, int priority, long
timeToLive) throws JMSException;
-
- /** Sends a message to a queue for an unidentified message producer.
- * Uses the <CODE>QueueSender</CODE>'s default delivery mode, priority,
- * and time to live.
- *
- * <P>Typically, a message producer is assigned a queue at creation
- * time; however, the JMS API also supports unidentified message producers,
- * which require that the queue be supplied every time a message is
- * sent.
- *
- * @param queue the queue to send this message to
- * @param message the message to send
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with an invalid queue.
- *
- * @see javax.jms.MessageProducer#getDeliveryMode()
- * @see javax.jms.MessageProducer#getTimeToLive()
- * @see javax.jms.MessageProducer#getPriority()
- */
+ void send(Message message, int deliveryMode, int priority, long timeToLive)
+ throws JMSException;
void send(Queue queue, Message message) throws JMSException;
-
- /** Sends a message to a queue for an unidentified message producer,
- * specifying delivery mode, priority and time to live.
- *
- * <P>Typically, a message producer is assigned a queue at creation
- * time; however, the JMS API also supports unidentified message producers,
- * which require that the queue be supplied every time a message is
- * sent.
- *
- * @param queue the queue to send this message to
- * @param message the message to send
- * @param deliveryMode the delivery mode to use
- * @param priority the priority for this message
- * @param timeToLive the message's lifetime (in milliseconds)
- *
- * @exception JMSException if the JMS provider fails to send the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with an invalid queue.
- */
-
- void send(Queue queue, Message message, int deliveryMode, int priority,
long timeToLive) throws JMSException;
+ void send(
+ Queue queue,
+ Message message,
+ int deliveryMode,
+ int priority,
+ long timeToLive)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/QueueSession.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/QueueSession.java,v
retrieving revision 1.1
diff -u -r1.1 QueueSession.java
--- specs/jms/src/java/javax/jms/QueueSession.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/QueueSession.java 19 Aug 2003 23:12:49
-0000
@@ -62,163 +62,23 @@
package javax.jms;
-/** A <CODE>QueueSession</CODE> object provides methods for creating
- * <CODE>QueueReceiver</CODE>, <CODE>QueueSender</CODE>,
- * <CODE>QueueBrowser</CODE>, and <CODE>TemporaryQueue</CODE> objects.
- *
- * <P>If there are messages that have been received but not acknowledged
- * when a <CODE>QueueSession</CODE> terminates, these messages will be retained
- * and redelivered when a consumer next accesses the queue.
- *
- *<P>A <CODE>QueueSession</CODE> is used for creating Point-to-Point specific
- * objects. In general, use the <CODE>Session</CODE> object.
- * The <CODE>QueueSession</CODE> is used to support
- * existing code. Using the <CODE>Session</CODE> object simplifies the
- * programming model, and allows transactions to be used across the two
- * messaging domains.
- *
- * <P>A <CODE>QueueSession</CODE> cannot be used to create objects specific to
the
- * publish/subscribe domain. The following methods inherit from
- * <CODE>Session</CODE>, but must throw an
- * <CODE>IllegalStateException</CODE>
- * if they are used from <CODE>QueueSession</CODE>:
- *<UL>
- * <LI><CODE>createDurableSubscriber</CODE>
- * <LI><CODE>createTemporaryTopic</CODE>
- * <LI><CODE>createTopic</CODE>
- * <LI><CODE>unsubscribe</CODE>
- * </UL>
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session
- * @see javax.jms.QueueConnection#createQueueSession(boolean, int)
- * @see javax.jms.XAQueueSession#getQueueSession()
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface QueueSession extends Session {
+ Queue createQueue(String queueName) throws JMSException;
+
+ QueueReceiver createReceiver(Queue queue) throws JMSException;
+
+ QueueReceiver createReceiver(Queue queue, String messageSelector)
+ throws JMSException;
+
+ QueueSender createSender(Queue queue) throws JMSException;
+
+ QueueBrowser createBrowser(Queue queue) throws JMSException;
- /** Creates a queue identity given a <CODE>Queue</CODE> name.
- *
- * <P>This facility is provided for the rare cases where clients need to
- * dynamically manipulate queue identity. It allows the creation of a
- * queue identity with a provider-specific name. Clients that depend
- * on this ability are not portable.
- *
- * <P>Note that this method is not for creating the physical queue.
- * The physical creation of queues is an administrative task and is not
- * to be initiated by the JMS API. The one exception is the
- * creation of temporary queues, which is accomplished with the
- * <CODE>createTemporaryQueue</CODE> method.
- *
- * @param queueName the name of this <CODE>Queue</CODE>
- *
- * @return a <CODE>Queue</CODE> with the given name
- *
- * @exception JMSException if the session fails to create a queue
- * due to some internal error.
- */
-
- Queue
- createQueue(String queueName) throws JMSException;
-
-
- /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from
the
- * specified queue.
- *
- * @param queue the <CODE>Queue</CODE> to access
- *
- * @exception JMSException if the session fails to create a receiver
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid queue is specified.
- */
-
- QueueReceiver
- createReceiver(Queue queue) throws JMSException;
-
-
- /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from
the
- * specified queue using a message selector.
- *
- * @param queue the <CODE>Queue</CODE> to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- *
- * @exception JMSException if the session fails to create a receiver
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid queue is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- *
- */
-
- QueueReceiver
- createReceiver(Queue queue,
- String messageSelector) throws JMSException;
-
-
- /** Creates a <CODE>QueueSender</CODE> object to send messages to the
- * specified queue.
- *
- * @param queue the <CODE>Queue</CODE> to access, or null if this is an
- * unidentified producer
- *
- * @exception JMSException if the session fails to create a sender
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid queue is specified.
- */
-
- QueueSender
- createSender(Queue queue) throws JMSException;
-
-
- /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
- * the specified queue.
- *
- * @param queue the <CODE>Queue</CODE> to access
- *
- * @exception JMSException if the session fails to create a browser
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid queue is specified.
- */
-
- QueueBrowser
- createBrowser(Queue queue) throws JMSException;
-
-
- /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
- * the specified queue using a message selector.
- *
- * @param queue the <CODE>Queue</CODE> to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- *
- * @exception JMSException if the session fails to create a browser
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid queue is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- */
-
- QueueBrowser
- createBrowser(Queue queue,
- String messageSelector) throws JMSException;
-
-
- /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that
- * of the <CODE>QueueConnection</CODE> unless it is deleted earlier.
- *
- * @return a temporary queue identity
- *
- * @exception JMSException if the session fails to create a temporary queue
- * due to some internal error.
- */
+ QueueBrowser createBrowser(Queue queue, String messageSelector)
+ throws JMSException;
- TemporaryQueue
- createTemporaryQueue() throws JMSException;
+ TemporaryQueue createTemporaryQueue() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/ResourceAllocationException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ResourceAllocationException.java,v
retrieving revision 1.1
diff -u -r1.1 ResourceAllocationException.java
--- specs/jms/src/java/javax/jms/ResourceAllocationException.java 16 Aug
2003 02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/ResourceAllocationException.java 19 Aug
2003 23:12:49 -0000
@@ -63,37 +63,15 @@
package javax.jms;
/**
- * <P>This exception is thrown when a provider is unable to allocate the
- * resources required by a method. For example, this exception should be
- * thrown when a call to
- * <CODE>TopicConnectionFactory.createTopicConnection</CODE> fails due to a
- * lack of JMS provider resources.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class ResourceAllocationException extends JMSException {
-
- /** Constructs a <CODE>ResourceAllocationException</CODE> with the
specified
- * reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public ResourceAllocationException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>ResourceAllocationException</CODE> with the
specified
- * reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public ResourceAllocationException(String reason) {
- super(reason);
+ this(reason, null);
}
}
Index: specs/jms/src/java/javax/jms/ServerSession.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ServerSession.java,v
retrieving revision 1.1
diff -u -r1.1 ServerSession.java
--- specs/jms/src/java/javax/jms/ServerSession.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/ServerSession.java 19 Aug 2003 23:12:49
-0000
@@ -62,77 +62,11 @@
package javax.jms;
-/** A <CODE>ServerSession</CODE> object is an application server object that
- * is used by a server to associate a thread with a JMS session (optional).
- *
- * <P>A <CODE>ServerSession</CODE> implements two methods:
- *
- * <UL>
- * <LI><CODE>getSession</CODE> - returns the <CODE>ServerSession</CODE>'s
- * JMS session.
- * <LI><CODE>start</CODE> - starts the execution of the
- * <CODE>ServerSession</CODE>
- * thread and results in the execution of the JMS session's
- * <CODE>run</CODE> method.
- * </UL>
- *
- * <P>A <CODE>ConnectionConsumer</CODE> implemented by a JMS provider uses a
- * <CODE>ServerSession</CODE> to process one or more messages that have
- * arrived. It does this by getting a <CODE>ServerSession</CODE> from the
- * <CODE>ConnectionConsumer</CODE>'s <CODE>ServerSessionPool</CODE>; getting
- * the <CODE>ServerSession</CODE>'s JMS session; loading it with the messages;
- * and then starting the <CODE>ServerSession</CODE>.
- *
- * <P>In most cases the <CODE>ServerSession</CODE> will register some object
- * it provides as the <CODE>ServerSession</CODE>'s thread run object. The
- * <CODE>ServerSession</CODE>'s <CODE>start</CODE> method will call the
- * thread's <CODE>start</CODE> method, which will start the new thread, and
- * from it, call the <CODE>run</CODE> method of the
- * <CODE>ServerSession</CODE>'s run object. This object will do some
- * housekeeping and then call the <CODE>Session</CODE>'s <CODE>run</CODE>
- * method. When <CODE>run</CODE> returns, the <CODE>ServerSession</CODE>'s run
- * object can return the <CODE>ServerSession</CODE> to the
- * <CODE>ServerSessionPool</CODE>, and the cycle starts again.
- *
- * <P>Note that the JMS API does not architect how the
- * <CODE>ConnectionConsumer</CODE> loads the <CODE>Session</CODE> with
- * messages. Since both the <CODE>ConnectionConsumer</CODE> and
- * <CODE>Session</CODE> are implemented by the same JMS provider, they can
- * accomplish the load using a private mechanism.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.ServerSessionPool
- * @see javax.jms.ConnectionConsumer
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ServerSession {
-
- /** Return the <CODE>ServerSession</CODE>'s <CODE>Session</CODE>. This must
- * be a <CODE>Session</CODE> created by the same <CODE>Connection</CODE>
- * that will be dispatching messages to it. The provider will assign one or
- * more messages to the <CODE>Session</CODE>
- * and then call <CODE>start</CODE> on the <CODE>ServerSession</CODE>.
- *
- * @return the server session's session
- *
- * @exception JMSException if the JMS provider fails to get the associated
- * session for this <CODE>ServerSession</CODE> due
- * to some internal error.
- **/
-
Session getSession() throws JMSException;
-
-
- /** Cause the <CODE>Session</CODE>'s <CODE>run</CODE> method to be called
- * to process messages that were just assigned to it.
- *
- * @exception JMSException if the JMS provider fails to start the server
- * session to process messages due to some internal
- * error.
- */
void start() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/ServerSessionPool.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/ServerSessionPool.java,v
retrieving revision 1.1
diff -u -r1.1 ServerSessionPool.java
--- specs/jms/src/java/javax/jms/ServerSessionPool.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/ServerSessionPool.java 19 Aug 2003 23:12:49
-0000
@@ -62,39 +62,9 @@
package javax.jms;
-/** A <CODE>ServerSessionPool</CODE> object is an object implemented by an
- * application server to provide a pool of <CODE>ServerSession</CODE> objects
- * for processing the messages of a <CODE>ConnectionConsumer</CODE> (optional).
- *
- * <P>Its only method is <CODE>getServerSession</CODE>. The JMS API does not
- * architect how the pool is implemented. It could be a static pool of
- * <CODE>ServerSession</CODE> objects, or it could use a sophisticated
- * algorithm to dynamically create <CODE>ServerSession</CODE> objects as
- * needed.
- *
- * <P>If the <CODE>ServerSessionPool</CODE> is out of
- * <CODE>ServerSession</CODE> objects, the <CODE>getServerSession</CODE> call
- * may block. If a <CODE>ConnectionConsumer</CODE> is blocked, it cannot
- * deliver new messages until a <CODE>ServerSession</CODE> is
- * eventually returned.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.ServerSession
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface ServerSessionPool {
-
- /** Return a server session from the pool.
- *
- * @return a server session from the pool
- *
- * @exception JMSException if an application server fails to
- * return a <CODE>ServerSession</CODE> out of its
- * server session pool.
- */
-
ServerSession getServerSession() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/Session.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/Session.java,v
retrieving revision 1.1
diff -u -r1.1 Session.java
--- specs/jms/src/java/javax/jms/Session.java 16 Aug 2003 02:29:58 -0000
1.1
+++ specs/jms/src/java/javax/jms/Session.java 19 Aug 2003 23:12:49 -0000
@@ -64,734 +64,91 @@
import java.io.Serializable;
-/** <P>A <CODE>Session</CODE> object is a single-threaded context for
producing and consuming
- * messages. Although it may allocate provider resources outside the Java
- * virtual machine (JVM), it is considered a lightweight JMS object.
- *
- * <P>A session serves several purposes:
- *
- * <UL>
- * <LI>It is a factory for its message producers and consumers.
- * <LI>It supplies provider-optimized message factories.
- * <LI>It is a factory for <CODE>TemporaryTopics</CODE> and
- * <CODE>TemporaryQueues</CODE>.
- * <LI> It provides a way to create <CODE>Queue</CODE> or <CODE>Topic</CODE>
- * objects for those clients that need to dynamically manipulate
- * provider-specific destination names.
- * <LI>It supports a single series of transactions that combine work
- * spanning its producers and consumers into atomic units.
- * <LI>It defines a serial order for the messages it consumes and
- * the messages it produces.
- * <LI>It retains messages it consumes until they have been
- * acknowledged.
- * <LI>It serializes execution of message listeners registered with
- * its message consumers.
- * <LI> It is a factory for <CODE>QueueBrowsers</CODE>.
- * </UL>
- *
- * <P>A session can create and service multiple message producers and
- * consumers.
- *
- * <P>One typical use is to have a thread block on a synchronous
- * <CODE>MessageConsumer</CODE> until a message arrives. The thread may then
- * use one or more of the <CODE>Session</CODE>'s <CODE>MessageProducer</CODE>s.
- *
- * <P>If a client desires to have one thread produce messages while others
- * consume them, the client should use a separate session for its producing
- * thread.
- *
- * <P>Once a connection has been started, any session with one or more
- * registered message listeners is dedicated to the thread of control that
- * delivers messages to it. It is erroneous for client code to use this session
- * or any of its constituent objects from another thread of control. The
- * only exception to this rule is the use of the session or connection
- * <CODE>close</CODE> method.
- *
- * <P>It should be easy for most clients to partition their work naturally
- * into sessions. This model allows clients to start simply and incrementally
- * add message processing complexity as their need for concurrency grows.
- *
- * <P>The <CODE>close</CODE> method is the only session method that can be
- * called while some other session method is being executed in another thread.
- *
- * <P>A session may be specified as transacted. Each transacted
- * session supports a single series of transactions. Each transaction groups
- * a set of message sends and a set of message receives into an atomic unit
- * of work. In effect, transactions organize a session's input message
- * stream and output message stream into series of atomic units. When a
- * transaction commits, its atomic unit of input is acknowledged and its
- * associated atomic unit of output is sent. If a transaction rollback is
- * done, the transaction's sent messages are destroyed and the session's input
- * is automatically recovered.
- *
- * <P>The content of a transaction's input and output units is simply those
- * messages that have been produced and consumed within the session's current
- * transaction.
- *
- * <P>A transaction is completed using either its session's <CODE>commit</CODE>
- * method or its session's <CODE>rollback</CODE> method. The completion of a
- * session's current transaction automatically begins the next. The result is
- * that a transacted session always has a current transaction within which its
- * work is done.
- *
- * <P>The Java Transaction Service (JTS) or some other transaction monitor may
- * be used to combine a session's transaction with transactions on other
- * resources (databases, other JMS sessions, etc.). Since Java distributed
- * transactions are controlled via the Java Transaction API (JTA), use of the
- * session's <CODE>commit</CODE> and <CODE>rollback</CODE> methods in
- * this context is prohibited.
- *
- * <P>The JMS API does not require support for JTA; however, it does define
- * how a provider supplies this support.
- *
- * <P>Although it is also possible for a JMS client to handle distributed
- * transactions directly, it is unlikely that many JMS clients will do this.
- * Support for JTA in the JMS API is targeted at systems vendors who will be
- * integrating the JMS API into their application server products.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.QueueSession
- * @see javax.jms.TopicSession
- * @see javax.jms.XASession
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface Session extends Runnable {
-
- /** With this acknowledgment mode, the session automatically acknowledges
- * a client's receipt of a message either when the session has successfully
- * returned from a call to <CODE>receive</CODE> or when the message
- * listener the session has called to process the message successfully
- * returns.
- */
-
static final int AUTO_ACKNOWLEDGE = 1;
- /** With this acknowledgment mode, the client acknowledges a consumed
- * message by calling the message's <CODE>acknowledge</CODE> method.
- * Acknowledging a consumed message acknowledges all messages that the
- * session has consumed.
- *
- * <P>When client acknowledgment mode is used, a client may build up a
- * large number of unacknowledged messages while attempting to process
- * them. A JMS provider should provide administrators with a way to
- * limit client overrun so that clients are not driven to resource
- * exhaustion and ensuing failure when some resource they are using
- * is temporarily blocked.
- *
- * @see javax.jms.Message#acknowledge()
- */
-
static final int CLIENT_ACKNOWLEDGE = 2;
- /** This acknowledgment mode instructs the session to lazily acknowledge
- * the delivery of messages. This is likely to result in the delivery of
- * some duplicate messages if the JMS provider fails, so it should only be
- * used by consumers that can tolerate duplicate messages. Use of this
- * mode can reduce session overhead by minimizing the work the
- * session does to prevent duplicates.
- */
-
static final int DUPS_OK_ACKNOWLEDGE = 3;
- /** This value is returned from the method
- * <CODE>getAcknowledgeMode</CODE> if the session is transacted.
- * If a <CODE>Session</CODE> is transacted, the acknowledgement mode
- * is ignored.
- */
static final int SESSION_TRANSACTED = 0;
- /** Creates a <CODE>BytesMessage</CODE> object. A <CODE>BytesMessage</CODE>
- * object is used to send a message containing a stream of uninterpreted
- * bytes.
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
-
BytesMessage createBytesMessage() throws JMSException;
-
- /** Creates a <CODE>MapMessage</CODE> object. A <CODE>MapMessage</CODE>
- * object is used to send a self-defining set of name-value pairs, where
- * names are <CODE>String</CODE> objects and values are primitive values
- * in the Java programming language.
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
MapMessage createMapMessage() throws JMSException;
-
- /** Creates a <CODE>Message</CODE> object. The <CODE>Message</CODE>
- * interface is the root interface of all JMS messages. A
- * <CODE>Message</CODE> object holds all the
- * standard message header information. It can be sent when a message
- * containing only header information is sufficient.
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
Message createMessage() throws JMSException;
-
- /** Creates an <CODE>ObjectMessage</CODE> object. An
- * <CODE>ObjectMessage</CODE> object is used to send a message
- * that contains a serializable Java object.
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
ObjectMessage createObjectMessage() throws JMSException;
-
- /** Creates an initialized <CODE>ObjectMessage</CODE> object. An
- * <CODE>ObjectMessage</CODE> object is used
- * to send a message that contains a serializable Java object.
- *
- * @param object the object to use to initialize this message
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
ObjectMessage createObjectMessage(Serializable object) throws JMSException;
-
- /** Creates a <CODE>StreamMessage</CODE> object. A
- * <CODE>StreamMessage</CODE> object is used to send a
- * self-defining stream of primitive values in the Java programming
- * language.
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
StreamMessage createStreamMessage() throws JMSException;
-
- /** Creates a <CODE>TextMessage</CODE> object. A <CODE>TextMessage</CODE>
- * object is used to send a message containing a <CODE>String</CODE>
- * object.
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
TextMessage createTextMessage() throws JMSException;
-
- /** Creates an initialized <CODE>TextMessage</CODE> object. A
- * <CODE>TextMessage</CODE> object is used to send
- * a message containing a <CODE>String</CODE>.
- *
- * @param text the string used to initialize this message
- *
- * @exception JMSException if the JMS provider fails to create this message
- * due to some internal error.
- */
-
TextMessage createTextMessage(String text) throws JMSException;
-
- /** Indicates whether the session is in transacted mode.
- *
- * @return true if the session is in transacted mode
- *
- * @exception JMSException if the JMS provider fails to return the
- * transaction mode due to some internal error.
- */
-
boolean getTransacted() throws JMSException;
- /** Returns the acknowledgement mode of the session. The acknowledgement
- * mode is set at the time that the session is created. If the session is
- * transacted, the acknowledgement mode is ignored.
- *
- [EMAIL PROTECTED] If the session is not transacted, returns the
- * current acknowledgement mode for the session.
- * If the session
- * is transacted, returns SESSION_TRANSACTED.
- *
- [EMAIL PROTECTED] JMSException if the JMS provider fails to return the
- * acknowledgment mode due to some internal error.
- *
- [EMAIL PROTECTED] Connection#createSession
- [EMAIL PROTECTED] 1.1
- */
int getAcknowledgeMode() throws JMSException;
-
- /** Commits all messages done in this transaction and releases any locks
- * currently held.
- *
- * @exception JMSException if the JMS provider fails to commit the
- * transaction due to some internal error.
- * @exception TransactionRolledBackException if the transaction
- * is rolled back due to some internal error
- * during commit.
- * @exception IllegalStateException if the method is not called by a
- * transacted session.
- */
-
void commit() throws JMSException;
-
- /** Rolls back any messages done in this transaction and releases any locks
- * currently held.
- *
- * @exception JMSException if the JMS provider fails to roll back the
- * transaction due to some internal error.
- * @exception IllegalStateException if the method is not called by a
- * transacted session.
- *
- */
-
void rollback() throws JMSException;
-
- /** Closes the session.
- *
- * <P>Since a provider may allocate some resources on behalf of a session
- * outside the JVM, clients should close the resources when they are not
- * needed.
- * Relying on garbage collection to eventually reclaim these resources
- * may not be timely enough.
- *
- * <P>There is no need to close the producers and consumers
- * of a closed session.
- *
- * <P> This call will block until a <CODE>receive</CODE> call or message
- * listener in progress has completed. A blocked message consumer
- * <CODE>receive</CODE> call returns <CODE>null</CODE> when this session
- * is closed.
- *
- * <P>Closing a transacted session must roll back the transaction
- * in progress.
- *
- * <P>This method is the only <CODE>Session</CODE> method that can
- * be called concurrently.
- *
- * <P>Invoking any other <CODE>Session</CODE> method on a closed session
- * must throw a <CODE>JMSException.IllegalStateException</CODE>. Closing a
- * closed session must <I>not</I> throw an exception.
- *
- * @exception JMSException if the JMS provider fails to close the
- * session due to some internal error.
- */
-
void close() throws JMSException;
-
- /** 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 all
- * messages that have been delivered to the client.
- *
- * <P>Restarting a session causes it to take the following actions:
- *
- * <UL>
- * <LI>Stop message delivery
- * <LI>Mark all messages that might have been delivered but not
- * acknowledged as "redelivered"
- * <LI>Restart the delivery sequence including all unacknowledged
- * messages that had been previously delivered. Redelivered messages
- * do not have to be delivered in
- * exactly their original delivery order.
- * </UL>
- *
- * @exception JMSException if the JMS provider fails to stop and restart
- * message delivery due to some internal error.
- * @exception IllegalStateException if the method is called by a
- * transacted session.
- */
-
void recover() throws JMSException;
-
- /** Returns the session's distinguished message listener (optional).
- *
- * @return the message listener associated with this session
- *
- * @exception JMSException if the JMS provider fails to get the message
- * listener due to an internal error.
- *
- * @see javax.jms.Session#setMessageListener
- * @see javax.jms.ServerSessionPool
- * @see javax.jms.ServerSession
- */
-
MessageListener getMessageListener() throws JMSException;
-
- /** Sets the session's distinguished message listener (optional).
- *
- * <P>When the distinguished message listener is set, no other form of
- * message receipt in the session can
- * be used; however, all forms of sending messages are still supported.
- *
- * <P>This is an expert facility not used by regular JMS clients.
- *
- * @param listener the message listener to associate with this session
- *
- * @exception JMSException if the JMS provider fails to set the message
- * listener due to an internal error.
- *
- * @see javax.jms.Session#getMessageListener
- * @see javax.jms.ServerSessionPool
- * @see javax.jms.ServerSession
- */
-
void setMessageListener(MessageListener listener) throws JMSException;
- /**
- * Optional operation, intended to be used only by Application Servers,
- * not by ordinary JMS clients.
- *
- * @see javax.jms.ServerSession
- */
public void run();
- /** Creates a <CODE>MessageProducer</CODE> to send messages to the
specified
- * destination.
- *
- * <P>A client uses a <CODE>MessageProducer</CODE> object to send
- * messages to a destination. Since <CODE>Queue</CODE> and
<CODE>Topic</CODE>
- * both inherit from <CODE>Destination</CODE>, they can be used in
- * the destination parameter to create a <CODE>MessageProducer</CODE>
object.
- *
- * @param destination the <CODE>Destination</CODE> to send to,
- * or null if this is a producer which does not have a specified
- * destination.
- *
- * @exception JMSException if the session fails to create a MessageProducer
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid destination
- * is specified.
- *
- * @since 1.1
- *
- */
-
- MessageProducer createProducer(Destination destination) throws
JMSException;
-
-
- /** Creates a <CODE>MessageConsumer</CODE> for the specified destination.
- * Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
- * both inherit from <CODE>Destination</CODE>, they can be used in
- * the destination parameter to create a <CODE>MessageConsumer</CODE>.
- *
- * @param destination the <CODE>Destination</CODE> to access.
- *
- * @exception JMSException if the session fails to create a consumer
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid destination
- * is specified.
- *
- * @since 1.1
- */
-
- MessageConsumer createConsumer(Destination destination) throws
JMSException;
-
- /** Creates a <CODE>MessageConsumer</CODE> for the specified destination,
- * using a message selector.
- * Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
- * both inherit from <CODE>Destination</CODE>, they can be used in
- * the destination parameter to create a <CODE>MessageConsumer</CODE>.
- *
- * <P>A client uses a <CODE>MessageConsumer</CODE> object to receive
- * messages that have been sent to a destination.
- *
- *
- * @param destination the <CODE>Destination</CODE> to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- *
- *
- * @exception JMSException if the session fails to create a MessageConsumer
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid destination
- * is specified.
-
- * @exception InvalidSelectorException if the message selector is invalid.
- *
- * @since 1.1
- */
- MessageConsumer createConsumer(Destination destination, java.lang.String
messageSelector) throws JMSException;
-
-
- /** Creates <CODE>MessageConsumer</CODE> for the specified destination,
using a
- * message selector. This method can specify whether messages published by
- * its own connection should be delivered to it, if the destination is a
- * topic.
- *<P> Since <CODE>Queue</CODE> and <CODE>Topic</CODE>
- * both inherit from <CODE>Destination</CODE>, they can be used in
- * the destination parameter to create a <CODE>MessageConsumer</CODE>.
- * <P>A client uses a <CODE>MessageConsumer</CODE> object to receive
- * messages that have been published to a destination.
- *
- * <P>In some cases, a connection may both publish and subscribe to a
- * topic. The consumer <CODE>NoLocal</CODE> attribute allows a consumer
- * to inhibit the delivery of messages published by its own connection.
- * The default value for this attribute is False. The <CODE>noLocal</CODE>
- * value must be supported by destinations that are topics.
- *
- * @param destination the <CODE>Destination</CODE> to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param NoLocal - if true, and the destination is a topic,
- * inhibits the delivery of messages published
- * by its own connection. The behavior for
- * <CODE>NoLocal</CODE> is
- * not specified if the destination is a queue.
- *
- * @exception JMSException if the session fails to create a MessageConsumer
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid destination
- * is specified.
-
- * @exception InvalidSelectorException if the message selector is invalid.
- *
- * @since 1.1
- *
- */
- MessageConsumer createConsumer(Destination destination, java.lang.String
messageSelector, boolean NoLocal) throws JMSException;
-
-
- /** Creates a queue identity given a <CODE>Queue</CODE> name.
- *
- * <P>This facility is provided for the rare cases where clients need to
- * dynamically manipulate queue identity. It allows the creation of a
- * queue identity with a provider-specific name. Clients that depend
- * on this ability are not portable.
- *
- * <P>Note that this method is not for creating the physical queue.
- * The physical creation of queues is an administrative task and is not
- * to be initiated by the JMS API. The one exception is the
- * creation of temporary queues, which is accomplished with the
- * <CODE>createTemporaryQueue</CODE> method.
- *
- * @param queueName the name of this <CODE>Queue</CODE>
- *
- * @return a <CODE>Queue</CODE> with the given name
- *
- * @exception JMSException if the session fails to create a queue
- * due to some internal error.
- * @since 1.1
- */
+ MessageProducer createProducer(Destination destination)
+ throws JMSException;
- Queue createQueue(String queueName) throws JMSException;
+ MessageConsumer createConsumer(Destination destination)
+ throws JMSException;
- /** Creates a topic identity given a <CODE>Topic</CODE> name.
- *
- * <P>This facility is provided for the rare cases where clients need to
- * dynamically manipulate topic identity. This allows the creation of a
- * topic identity with a provider-specific name. Clients that depend
- * on this ability are not portable.
- *
- * <P>Note that this method is not for creating the physical topic.
- * The physical creation of topics is an administrative task and is not
- * to be initiated by the JMS API. The one exception is the
- * creation of temporary topics, which is accomplished with the
- * <CODE>createTemporaryTopic</CODE> method.
- *
- * @param topicName the name of this <CODE>Topic</CODE>
- *
- * @return a <CODE>Topic</CODE> with the given name
- *
- * @exception JMSException if the session fails to create a topic
- * due to some internal error.
- * @since 1.1
- */
+ MessageConsumer createConsumer(
+ Destination destination,
+ java.lang.String messageSelector)
+ throws JMSException;
+
+ MessageConsumer createConsumer(
+ Destination destination,
+ java.lang.String messageSelector,
+ boolean NoLocal)
+ throws JMSException;
- Topic createTopic(String topicName) throws JMSException;
+ Queue createQueue(String queueName) throws JMSException;
- /** Creates a durable subscriber to the specified topic.
- *
- * <P>If a client needs to receive all the messages published on a
- * topic, including the ones published while the subscriber is inactive,
- * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
- * retains a record of this
- * durable subscription and insures that all messages from the topic's
- * publishers are retained until they are acknowledged by this
- * durable subscriber or they have expired.
- *
- * <P>Sessions with durable subscribers must always provide the same
- * client identifier. In addition, each client must specify a name that
- * uniquely identifies (within client identifier) each durable
- * subscription it creates. Only one session at a time can have a
- * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
- *
- * <P>A client can change an existing durable subscription by creating
- * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
- * topic and/or
- * message selector. Changing a durable subscriber is equivalent to
- * unsubscribing (deleting) the old one and creating a new one.
- *
- * <P>In some cases, a connection may both publish and subscribe to a
- * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
- * to inhibit the delivery of messages published by its own connection.
- * The default value for this attribute is false.
- *
- * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
- * @param name the name used to identify this subscription
- *
- * @exception JMSException if the session fails to create a subscriber
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- *
- * @since 1.1
- */
-
- TopicSubscriber createDurableSubscriber(Topic topic,
- String name) throws JMSException;
-
-
- /** Creates a durable subscriber to the specified topic, using a
- * message selector and specifying whether messages published by its
- * own connection should be delivered to it.
- *
- * <P>If a client needs to receive all the messages published on a
- * topic, including the ones published while the subscriber is inactive,
- * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
- * retains a record of this
- * durable subscription and insures that all messages from the topic's
- * publishers are retained until they are acknowledged by this
- * durable subscriber or they have expired.
- *
- * <P>Sessions with durable subscribers must always provide the same
- * client identifier. In addition, each client must specify a name which
- * uniquely identifies (within client identifier) each durable
- * subscription it creates. Only one session at a time can have a
- * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
- * An inactive durable subscriber is one that exists but
- * does not currently have a message consumer associated with it.
- *
- * <P>A client can change an existing durable subscription by creating
- * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
- * topic and/or
- * message selector. Changing a durable subscriber is equivalent to
- * unsubscribing (deleting) the old one and creating a new one.
- *
- * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
- * @param name the name used to identify this subscription
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param noLocal if set, inhibits the delivery of messages published
- * by its own connection
- *
- * @exception JMSException if the session fails to create a subscriber
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- *
- * @since 1.1
- */
-
- TopicSubscriber createDurableSubscriber(Topic topic, String name, String
messageSelector, boolean noLocal) throws JMSException;
-
- /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
- * the specified queue.
- *
- * @param queue the <CODE>queue</CODE> to access
- *
- *
- * @exception JMSException if the session fails to create a browser
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid destination
- * is specified
- *
- * @since 1.1
- */
- QueueBrowser createBrowser(Queue queue) throws JMSException;
+ Topic createTopic(String topicName) throws JMSException;
+ TopicSubscriber createDurableSubscriber(Topic topic, String name)
+ throws JMSException;
- /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
- * the specified queue using a message selector.
- *
- * @param queue the <CODE>queue</CODE> to access
- *
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- *
- * @exception JMSException if the session fails to create a browser
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid destination
- * is specified
- * @exception InvalidSelectorException if the message selector is invalid.
- *
- * @since 1.1
- */
-
- QueueBrowser createBrowser(Queue queue, String messageSelector) throws
JMSException;
-
-
- /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that
- * of the <CODE>Connection</CODE> unless it is deleted earlier.
- *
- * @return a temporary queue identity
- *
- * @exception JMSException if the session fails to create a temporary queue
- * due to some internal error.
- *
- [EMAIL PROTECTED] 1.1
- */
+ TopicSubscriber createDurableSubscriber(
+ Topic topic,
+ String name,
+ String messageSelector,
+ boolean noLocal)
+ throws JMSException;
- TemporaryQueue createTemporaryQueue() throws JMSException;
+ QueueBrowser createBrowser(Queue queue) throws JMSException;
+ QueueBrowser createBrowser(Queue queue, String messageSelector)
+ throws JMSException;
- /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that
- * of the <CODE>Connection</CODE> unless it is deleted earlier.
- *
- * @return a temporary topic identity
- *
- * @exception JMSException if the session fails to create a temporary
- * topic due to some internal error.
- *
- * @since 1.1
- */
+ TemporaryQueue createTemporaryQueue() throws JMSException;
TemporaryTopic createTemporaryTopic() throws JMSException;
-
- /** Unsubscribes a durable subscription that has been created by a client.
- *
- * <P>This method deletes the state being maintained on behalf of the
- * subscriber by its provider.
- *
- * <P>It is erroneous for a client to delete a durable subscription
- * while there is an active <CODE>MessageConsumer</CODE>
- * or <CODE>TopicSubscriber</CODE> for the
- * subscription, or while a consumed message is part of a pending
- * transaction or has not been acknowledged in the session.
- *
- * @param name the name used to identify this subscription
- *
- * @exception JMSException if the session fails to unsubscribe to the
- * durable subscription due to some internal error.
- * @exception InvalidDestinationException if an invalid subscription name
- * is specified.
- *
- * @since 1.1
- */
-
void unsubscribe(String name) throws JMSException;
-
}
Index: specs/jms/src/java/javax/jms/StreamMessage.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/StreamMessage.java,v
retrieving revision 1.1
diff -u -r1.1 StreamMessage.java
--- specs/jms/src/java/javax/jms/StreamMessage.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/StreamMessage.java 19 Aug 2003 23:12:49
-0000
@@ -62,500 +62,55 @@
package javax.jms;
-/** A <CODE>StreamMessage</CODE> object is used to send a stream of primitive
- * types in the Java programming language. It is filled and read sequentially.
- * It inherits from the <CODE>Message</CODE> interface
- * and adds a stream message body. Its methods are based largely on those
- * found in <CODE>java.io.DataInputStream</CODE> and
- * <CODE>java.io.DataOutputStream</CODE>.
- *
- * <P>The primitive types can be read or written explicitly using methods
- * for each type. They may also be read or written generically as objects.
- * For instance, a call to <CODE>StreamMessage.writeInt(6)</CODE> is
- * equivalent to <CODE>StreamMessage.writeObject(new Integer(6))</CODE>.
- * Both forms are provided, because the explicit form is convenient for
- * static programming, and the object form is needed when types are not known
- * at compile time.
- *
- * <P>When the message is first created, and when <CODE>clearBody</CODE>
- * is called, the body of the message is in write-only mode. After the
- * first call to <CODE>reset</CODE> has been made, the message body is in
- * read-only mode.
- * After a message has been sent, the client that sent it can retain and
- * modify it without affecting the message that has been sent. The same message
- * object can be sent multiple times.
- * When a message has been received, the provider has called
- * <CODE>reset</CODE> so that the message body is in read-only mode for the
client.
- *
- * <P>If <CODE>clearBody</CODE> is called on a message in read-only mode,
- * the message body is cleared and the message body is in write-only mode.
- *
- * <P>If a client attempts to read a message in write-only mode, a
- * <CODE>MessageNotReadableException</CODE> is thrown.
- *
- * <P>If a client attempts to write a message in read-only mode, a
- * <CODE>MessageNotWriteableException</CODE> is thrown.
- *
- * <P><CODE>StreamMessage</CODE> objects support the following conversion
- * table. The marked cases must be supported. The unmarked cases must throw a
- * <CODE>JMSException</CODE>. The <CODE>String</CODE>-to-primitive conversions
- * may throw a runtime exception if the primitive's <CODE>valueOf()</CODE>
- * method does not accept it as a valid <CODE>String</CODE> representation of
- * the primitive.
- *
- * <P>A value written as the row type can be read as the column type.
- *
- * <PRE>
- * | | boolean byte short char int long float double String byte[]
- * |----------------------------------------------------------------------
- * |boolean | X X
- * |byte | X X X X X
- * |short | X X X X
- * |char | X X
- * |int | X X X
- * |long | X X
- * |float | X X X
- * |double | X X
- * |String | X X X X X X X X
- * |byte[] | X
- * |----------------------------------------------------------------------
- * </PRE>
- *
- * <P>Attempting to read a null value as a primitive type must be treated
- * as calling the primitive's corresponding <code>valueOf(String)</code>
- * conversion method with a null value. Since <code>char</code> does not
- * support a <code>String</code> conversion, attempting to read a null value
- * as a <code>char</code> must throw a <code>NullPointerException</code>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.Session#createStreamMessage()
- * @see javax.jms.BytesMessage
- * @see javax.jms.MapMessage
- * @see javax.jms.Message
- * @see javax.jms.ObjectMessage
- * @see javax.jms.TextMessage
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface StreamMessage extends Message {
-
-
- /** Reads a <code>boolean</code> from the stream message.
- *
- * @return the <code>boolean</code> value read
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
boolean readBoolean() throws JMSException;
-
- /** Reads a <code>byte</code> value from the stream message.
- *
- * @return the next byte from the stream message as a 8-bit
- * <code>byte</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
byte readByte() throws JMSException;
-
- /** Reads a 16-bit integer from the stream message.
- *
- * @return a 16-bit integer from the stream message
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
short readShort() throws JMSException;
-
- /** Reads a Unicode character value from the stream message.
- *
- * @return a Unicode character from the stream message
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
char readChar() throws JMSException;
-
- /** Reads a 32-bit integer from the stream message.
- *
- * @return a 32-bit integer value from the stream message, interpreted
- * as an <code>int</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
int readInt() throws JMSException;
-
- /** Reads a 64-bit integer from the stream message.
- *
- * @return a 64-bit integer value from the stream message, interpreted as
- * a <code>long</code>
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
long readLong() throws JMSException;
-
- /** Reads a <code>float</code> from the stream message.
- *
- * @return a <code>float</code> value from the stream message
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
float readFloat() throws JMSException;
-
- /** Reads a <code>double</code> from the stream message.
- *
- * @return a <code>double</code> value from the stream message
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
double readDouble() throws JMSException;
-
- /** Reads a <CODE>String</CODE> from the stream message.
- *
- * @return a Unicode string from the stream message
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- */
-
String readString() throws JMSException;
-
- /** Reads a byte array field from the stream message into the
- * specified <CODE>byte[]</CODE> object (the read buffer).
- *
- * <P>To read the field value, <CODE>readBytes</CODE> should be
- * successively called
- * until it returns a value less than the length of the read buffer.
- * The value of the bytes in the buffer following the last byte
- * read is undefined.
- *
- * <P>If <CODE>readBytes</CODE> returns a value equal to the length of the
- * buffer, a subsequent <CODE>readBytes</CODE> call must be made. If there
- * are no more bytes to be read, this call returns -1.
- *
- * <P>If the byte array field value is null, <CODE>readBytes</CODE>
- * returns -1.
- *
- * <P>If the byte array field value is empty, <CODE>readBytes</CODE>
- * returns 0.
- *
- * <P>Once the first <CODE>readBytes</CODE> call on a <CODE>byte[]</CODE>
- * field value has been made,
- * the full value of the field must be read before it is valid to read
- * the next field. An attempt to read the next field before that has
- * been done will throw a <CODE>MessageFormatException</CODE>.
- *
- * <P>To read the byte field value into a new <CODE>byte[]</CODE> object,
- * use the <CODE>readObject</CODE> method.
- *
- * @param value the buffer into which the data is read
- *
- * @return the total number of bytes read into the buffer, or -1 if
- * there is no more data because the end of the byte field has been
- * reached
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- *
- * @see #readObject()
- */
-
int readBytes(byte[] value) throws JMSException;
-
- /** Reads an object from the stream message.
- *
- * <P>This method can be used to return, in objectified format,
- * an object in the Java programming language ("Java object") that has
- * been written to the stream with the equivalent
- * <CODE>writeObject</CODE> method call, or its equivalent primitive
- * <CODE>write<I>type</I></CODE> method.
- *
- * <P>Note that byte values are returned as <CODE>byte[]</CODE>, not
- * <CODE>Byte[]</CODE>.
- *
- * <P>An attempt to call <CODE>readObject</CODE> to read a byte field
- * value into a new <CODE>byte[]</CODE> object before the full value of the
- * byte field has been read will throw a
- * <CODE>MessageFormatException</CODE>.
- *
- * @return a Java object from the stream message, in objectified
- * format (for example, if the object was written as an <CODE>int</CODE>,
- * an <CODE>Integer</CODE> is returned)
- *
- * @exception JMSException if the JMS provider fails to read the message
- * due to some internal error.
- * @exception MessageEOFException if unexpected end of message stream has
- * been reached.
- * @exception MessageFormatException if this type conversion is invalid.
- * @exception MessageNotReadableException if the message is in write-only
- * mode.
- *
- * @see #readBytes(byte[] value)
- */
-
Object readObject() throws JMSException;
-
- /** Writes a <code>boolean</code> to the stream message.
- * The value <code>true</code> is written as the value
- * <code>(byte)1</code>; the value <code>false</code> is written as
- * the value <code>(byte)0</code>.
- *
- * @param value the <code>boolean</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeBoolean(boolean value) throws JMSException;
-
- /** Writes a <code>byte</code> to the stream message.
- *
- * @param value the <code>byte</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeByte(byte value) throws JMSException;
-
- /** Writes a <code>short</code> to the stream message.
- *
- * @param value the <code>short</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeShort(short value) throws JMSException;
-
- /** Writes a <code>char</code> to the stream message.
- *
- * @param value the <code>char</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeChar(char value) throws JMSException;
-
- /** Writes an <code>int</code> to the stream message.
- *
- * @param value the <code>int</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeInt(int value) throws JMSException;
-
- /** Writes a <code>long</code> to the stream message.
- *
- * @param value the <code>long</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeLong(long value) throws JMSException;
-
- /** Writes a <code>float</code> to the stream message.
- *
- * @param value the <code>float</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeFloat(float value) throws JMSException;
-
- /** Writes a <code>double</code> to the stream message.
- *
- * @param value the <code>double</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeDouble(double value) throws JMSException;
-
- /** Writes a <code>String</code> to the stream message.
- *
- * @param value the <code>String</code> value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeString(String value) throws JMSException;
-
- /** Writes a byte array field to the stream message.
- *
- * <P>The byte array <code>value</code> is written to the message
- * as a byte array field. Consecutively written byte array fields are
- * treated as two distinct fields when the fields are read.
- *
- * @param value the byte array value to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeBytes(byte[] value) throws JMSException;
-
- /** Writes a portion of a byte array as a byte array field to the stream
- * message.
- *
- * <P>The a portion of the byte array <code>value</code> is written to the
- * message as a byte array field. Consecutively written byte
- * array fields are treated as two distinct fields when the fields are
- * read.
- *
- * @param value the byte array value to be written
- * @param offset the initial offset within the byte array
- * @param length the number of bytes to use
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeBytes(byte[] value, int offset, int length) throws JMSException;
-
- /** Writes an object to the stream message.
- *
- * <P>This method works only for the objectified primitive
- * object types (<code>Integer</code>, <code>Double</code>,
- * <code>Long</code> ...), <code>String</code> objects, and byte
- * arrays.
- *
- * @param value the Java object to be written
- *
- * @exception JMSException if the JMS provider fails to write the message
- * due to some internal error.
- * @exception MessageFormatException if the object is invalid.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void writeObject(Object value) throws JMSException;
-
-
- /** Puts the message body in read-only mode and repositions the stream
- * to the beginning.
- *
- * @exception JMSException if the JMS provider fails to reset the message
- * due to some internal error.
- * @exception MessageFormatException if the message has an invalid
- * format.
- */
void reset() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TemporaryQueue.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TemporaryQueue.java,v
retrieving revision 1.1
diff -u -r1.1 TemporaryQueue.java
--- specs/jms/src/java/javax/jms/TemporaryQueue.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TemporaryQueue.java 19 Aug 2003 23:12:49
-0000
@@ -62,35 +62,9 @@
package javax.jms;
-/** A <CODE>TemporaryQueue</CODE> object is a unique <CODE>Queue</CODE> object
- * created for the duration of a <CODE>Connection</CODE>. It is a
- * system-defined queue that can be consumed only by the
- * <CODE>Connection</CODE> that created it.
- *
- *<P>A <CODE>TemporaryQueue</CODE> object can be created at either the
- * <CODE>Session</CODE> or <CODE>QueueSession</CODE> level. Creating it at the
- * <CODE>Session</CODE> level allows to the <CODE>TemporaryQueue</CODE> to
- * participate in transactions with objects from the Pub/Sub domain.
- * If it is created at the <CODE>QueueSession</CODE>, it will only
- * be able participate in transactions with objects from the PTP domain.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see Session#createTemporaryQueue()
- * @see QueueSession#createTemporaryQueue()
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TemporaryQueue extends Queue {
-
- /** Deletes this temporary queue. If there are existing receivers
- * still using it, a <CODE>JMSException</CODE> will be thrown.
- *
- * @exception JMSException if the JMS provider fails to delete the
- * temporary queue due to some internal error.
- */
-
void delete() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TemporaryTopic.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TemporaryTopic.java,v
retrieving revision 1.1
diff -u -r1.1 TemporaryTopic.java
--- specs/jms/src/java/javax/jms/TemporaryTopic.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TemporaryTopic.java 19 Aug 2003 23:12:49
-0000
@@ -62,36 +62,9 @@
package javax.jms;
-/** A <CODE>TemporaryTopic</CODE> object is a unique <CODE>Topic</CODE> object
- * created for the duration of a <CODE>Connection</CODE>. It is a
- * system-defined topic that can be consumed only by the
- * <CODE>Connection</CODE> that created it.
- *
- *<P>A <CODE>TemporaryTopic</CODE> object can be created either at the
- * <CODE>Session</CODE> or <CODE>TopicSession</CODE> level. Creating it at the
- * <CODE>Session</CODE> level allows the <CODE>TemporaryTopic</CODE> to
participate
- * in the same transaction with objects from the PTP domain.
- * If a <CODE>TemporaryTopic</CODE> is created at the
- * <CODE>TopicSession</CODE>, it will only
- * be able participate in transactions with objects from the Pub/Sub domain.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see Session#createTemporaryTopic()
- * @see TopicSession#createTemporaryTopic()
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TemporaryTopic extends Topic {
-
- /** Deletes this temporary topic. If there are existing subscribers
- * still using it, a <CODE>JMSException</CODE> will be thrown.
- *
- * @exception JMSException if the JMS provider fails to delete the
- * temporary topic due to some internal error.
- */
-
void delete() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TextMessage.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TextMessage.java,v
retrieving revision 1.1
diff -u -r1.1 TextMessage.java
--- specs/jms/src/java/javax/jms/TextMessage.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TextMessage.java 19 Aug 2003 23:12:49
-0000
@@ -62,58 +62,11 @@
package javax.jms;
-/** A <CODE>TextMessage</CODE> object is used to send a message containing a
- * <CODE>java.lang.String</CODE>.
- * It inherits from the <CODE>Message</CODE> interface and adds a text message
- * body.
- *
- * <P>This message type can be used to transport text-based messages, including
- * those with XML content.
- *
- * <P>When a client receives a <CODE>TextMessage</CODE>, it is in read-only
- * mode. If a client attempts to write to the message at this point, a
- * <CODE>MessageNotWriteableException</CODE> is thrown. If
- * <CODE>clearBody</CODE> is
- * called, the message can now be both read from and written to.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session#createTextMessage()
- * @see javax.jms.Session#createTextMessage(String)
- * @see javax.jms.BytesMessage
- * @see javax.jms.MapMessage
- * @see javax.jms.Message
- * @see javax.jms.ObjectMessage
- * @see javax.jms.StreamMessage
- * @see java.lang.String
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TextMessage extends Message {
-
- /** Sets the string containing this message's data.
- *
- * @param string the <CODE>String</CODE> containing the message's data
- *
- * @exception JMSException if the JMS provider fails to set the text due to
- * some internal error.
- * @exception MessageNotWriteableException if the message is in read-only
- * mode.
- */
-
void setText(String string) throws JMSException;
-
-
- /** Gets the string containing this message's data. The default
- * value is null.
- *
- * @return the <CODE>String</CODE> containing the message's data
- *
- * @exception JMSException if the JMS provider fails to get the text due to
- * some internal error.
- */
String getText() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/Topic.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/Topic.java,v
retrieving revision 1.1
diff -u -r1.1 Topic.java
--- specs/jms/src/java/javax/jms/Topic.java 16 Aug 2003 02:29:58 -0000
1.1
+++ specs/jms/src/java/javax/jms/Topic.java 19 Aug 2003 23:12:49 -0000
@@ -62,66 +62,11 @@
package javax.jms;
-
-/** A <CODE>Topic</CODE> object encapsulates a provider-specific topic name.
- * It is the way a client specifies the identity of a topic to JMS API methods.
- * For those methods that use a <CODE>Destination</CODE> as a parameter, a
- * <CODE>Topic</CODE> object may used as an argument . For
- * example, a Topic can be used to create a <CODE>MessageConsumer</CODE>
- * and a <CODE>MessageProducer</CODE>
- * by calling:
- *<UL>
- *<LI> <CODE>Session.CreateConsumer(Destination destination)</CODE>
- *<LI> <CODE>Session.CreateProducer(Destination destination)</CODE>
- *
- *</UL>
- *
- * <P>Many publish/subscribe (pub/sub) providers group topics into hierarchies
- * and provide various options for subscribing to parts of the hierarchy. The
- * JMS API places no restriction on what a <CODE>Topic</CODE> object
- * represents. It may be a leaf in a topic hierarchy, or it may be a larger
- * part of the hierarchy.
- *
- * <P>The organization of topics and the granularity of subscriptions to
- * them is an important part of a pub/sub application's architecture. The JMS
- * API
- * does not specify a policy for how this should be done. If an application
- * takes advantage of a provider-specific topic-grouping mechanism, it
- * should document this. If the application is installed using a different
- * provider, it is the job of the administrator to construct an equivalent
- * topic architecture and create equivalent <CODE>Topic</CODE> objects.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see Session#createConsumer(Destination)
- * @see Session#createProducer(Destination)
- * @see javax.jms.TopicSession#createTopic(String)
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface Topic extends Destination {
-
- /** Gets the name of this topic.
- *
- * <P>Clients that depend upon the name are not portable.
- *
- * @return the topic name
- *
- * @exception JMSException if the JMS provider implementation of
- * <CODE>Topic</CODE> fails to return the topic
- * name due to some internal
- * error.
- */
-
String getTopicName() throws JMSException;
-
-
- /** Returns a string representation of this object.
- *
- * @return the provider-specific identity values for this topic
- */
String toString();
}
Index: specs/jms/src/java/javax/jms/TopicConnection.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TopicConnection.java,v
retrieving revision 1.1
diff -u -r1.1 TopicConnection.java
--- specs/jms/src/java/javax/jms/TopicConnection.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TopicConnection.java 19 Aug 2003 23:12:49
-0000
@@ -62,110 +62,25 @@
package javax.jms;
-/** A <CODE>TopicConnection</CODE> object is an active connection to a
- * publish/subscribe JMS provider. A client uses a <CODE>TopicConnection</CODE>
- * object to create one or more <CODE>TopicSession</CODE> objects
- * for producing and consuming messages.
- *
- *<P>A <CODE>TopicConnection</CODE> can be used to create a
- *<CODE>TopicSession</CODE>, from which
- * specialized topic-related objects can be created.
- * A more general, and recommended approach is to use the
- * <CODE>Connection</CODE> object.
- *
- *
- * <P>The <CODE>TopicConnection</CODE> object
- * should be used to support existing code.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Connection
- * @see javax.jms.ConnectionFactory
- * @see javax.jms.TopicConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TopicConnection extends Connection {
+ TopicSession createTopicSession(boolean transacted, int acknowledgeMode)
+ throws JMSException;
- /** Creates a <CODE>TopicSession</CODE> object.
- *
- * @param transacted indicates whether the session is transacted
- * @param acknowledgeMode indicates whether the consumer or the
- * client will acknowledge any messages it receives; ignored if the session
- * is transacted. Legal values are <code>Session.AUTO_ACKNOWLEDGE</code>,
- * <code>Session.CLIENT_ACKNOWLEDGE</code>, and
- * <code>Session.DUPS_OK_ACKNOWLEDGE</code>.
- *
- * @return a newly created topic session
- *
- * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
- * to create a session due to some internal error
or
- * lack of support for the specific transaction
- * and acknowledgement mode.
- *
- * @see Session#AUTO_ACKNOWLEDGE
- * @see Session#CLIENT_ACKNOWLEDGE
- * @see Session#DUPS_OK_ACKNOWLEDGE
- */
-
- TopicSession createTopicSession(boolean transacted, int acknowledgeMode)
throws JMSException;
-
-
- /** Creates a connection consumer for this connection (optional operation).
- * This is an expert facility not used by regular JMS clients.
- *
- * @param topic the topic to access
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param sessionPool the server session pool to associate with this
- * connection consumer
- * @param maxMessages the maximum number of messages that can be
- * assigned to a server session at one time
- *
- * @return the connection consumer
- *
- * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
- * to create a connection consumer due to some
- * internal error or invalid arguments for
- * <CODE>sessionPool</CODE> and
- * <CODE>messageSelector</CODE>.
- * @exception InvalidDestinationException if an invalid topic is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- * @see javax.jms.ConnectionConsumer
- */
-
- ConnectionConsumer createConnectionConsumer(Topic topic, String
messageSelector, ServerSessionPool sessionPool, int maxMessages) throws
JMSException;
-
-
- /** Create a durable connection consumer for this connection (optional
operation).
- * This is an expert facility not used by regular JMS clients.
- *
- * @param topic the topic to access
- * @param subscriptionName durable subscription name
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param sessionPool the server session pool to associate with this
- * durable connection consumer
- * @param maxMessages the maximum number of messages that can be
- * assigned to a server session at one time
- *
- * @return the durable connection consumer
- *
- * @exception JMSException if the <CODE>TopicConnection</CODE> object fails
- * to create a connection consumer due to some
- * internal error or invalid arguments for
- * <CODE>sessionPool</CODE> and
- * <CODE>messageSelector</CODE>.
- * @exception InvalidDestinationException if an invalid topic is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- * @see javax.jms.ConnectionConsumer
- */
-
- ConnectionConsumer createDurableConnectionConsumer(Topic topic, String
subscriptionName, String messageSelector, ServerSessionPool sessionPool, int
maxMessages) throws JMSException;
+ ConnectionConsumer createConnectionConsumer(
+ Topic topic,
+ String messageSelector,
+ ServerSessionPool sessionPool,
+ int maxMessages)
+ throws JMSException;
+
+ ConnectionConsumer createDurableConnectionConsumer(
+ Topic topic,
+ String subscriptionName,
+ String messageSelector,
+ ServerSessionPool sessionPool,
+ int maxMessages)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TopicConnectionFactory.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TopicConnectionFactory.java,v
retrieving revision 1.1
diff -u -r1.1 TopicConnectionFactory.java
--- specs/jms/src/java/javax/jms/TopicConnectionFactory.java 16 Aug 2003
02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/TopicConnectionFactory.java 19 Aug 2003
23:12:49 -0000
@@ -62,58 +62,12 @@
package javax.jms;
-/** A client uses a <CODE>TopicConnectionFactory</CODE> object to create
- * <CODE>TopicConnection</CODE> objects with a publish/subscribe JMS provider.
- *
- * <P>A<CODE> TopicConnectionFactory</CODE> can be used to create a
- * <CODE>TopicConnection</CODE>, from which specialized topic-related objects
- * can be created. A more general, and recommended approach
- * is to use the <CODE>ConnectionFactory</CODE> object.
- *
- * <P> The <CODE>TopicConnectionFactory</CODE> object
- * should be used to support existing code.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.ConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TopicConnectionFactory extends ConnectionFactory {
-
- /** Creates a topic connection with the default user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @return a newly created topic connection
- *
- * @exception JMSException if the JMS provider fails to create a topic
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
TopicConnection createTopicConnection() throws JMSException;
-
- /** Creates a topic connection with the specified user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @param userName the caller's user name
- * @param password the caller's password
- *
- * @return a newly created topic connection
- *
- * @exception JMSException if the JMS provider fails to create a topic
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
- TopicConnection createTopicConnection(String userName, String password)
throws JMSException;
+ TopicConnection createTopicConnection(String userName, String password)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TopicPublisher.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TopicPublisher.java,v
retrieving revision 1.1
diff -u -r1.1 TopicPublisher.java
--- specs/jms/src/java/javax/jms/TopicPublisher.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TopicPublisher.java 19 Aug 2003 23:12:49
-0000
@@ -62,172 +62,25 @@
package javax.jms;
-/** A client uses a <CODE>TopicPublisher</CODE> object to publish messages on a
- * topic. A <CODE>TopicPublisher</CODE> object is the publish-subscribe form
- * of a message producer.
- *
- * <P>Normally, the <CODE>Topic</CODE> is specified when a
- * <CODE>TopicPublisher</CODE> is created. In this case, an attempt to use
- * the <CODE>publish</CODE> methods for an unidentified
- * <CODE>TopicPublisher</CODE> will throw a
- * <CODE>java.lang.UnsupportedOperationException</CODE>.
- *
- * <P>If the <CODE>TopicPublisher</CODE> is created with an unidentified
- * <CODE>Topic</CODE>, an attempt to use the <CODE>publish</CODE> methods that
- * assume that the <CODE>Topic</CODE> has been identified will throw a
- * <CODE>java.lang.UnsupportedOperationException</CODE>.
- *
- * <P>During the execution of its <CODE>publish</CODE> method,
- * a message must not be changed by other threads within the client.
- * If the message is modified, the result of the <CODE>publish</CODE> is
- * undefined.
- *
- * <P>After publishing a message, a client may retain and modify it
- * without affecting the message that has been published. The same message
- * object may be published multiple times.
- *
- * <P>The following message headers are set as part of publishing a
- * message: <code>JMSDestination</code>, <code>JMSDeliveryMode</code>,
- * <code>JMSExpiration</code>, <code>JMSPriority</code>,
- * <code>JMSMessageID</code> and <code>JMSTimeStamp</code>.
- * When the message is published, the values of these headers are ignored.
- * After completion of the <CODE>publish</CODE>, the headers hold the values
- * specified by the method publishing the message. It is possible for the
- * <CODE>publish</CODE> method not to set <code>JMSMessageID</code> and
- * <code>JMSTimeStamp</code> if the
- * setting of these headers is explicitly disabled by the
- * <code>MessageProducer.setDisableMessageID</code> or
- * <code>MessageProducer.setDisableMessageTimestamp</code> method.
- *
- *<P>Creating a <CODE>MessageProducer</CODE> provides the same features as
- * creating a <CODE>TopicPublisher</CODE>. A <CODE>MessageProducer</CODE>
object is
- * recommended when creating new code. The <CODE>TopicPublisher</CODE> is
- * provided to support existing code.
-
- *
- *<P>Because <CODE>TopicPublisher</CODE> inherits from
- * <CODE>MessageProducer</CODE>, it inherits the
- * <CODE>send</CODE> methods that are a part of the
<CODE>MessageProducer</CODE>
- * interface. Using the <CODE>send</CODE> methods will have the same
- * effect as using the
- * <CODE>publish</CODE> methods: they are functionally the same.
- *
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see Session#createProducer(Destination)
- * @see TopicSession#createPublisher(Topic)
- */
-
public interface TopicPublisher extends MessageProducer {
-
- /** Gets the topic associated with this <CODE>TopicPublisher</CODE>.
- *
- * @return this publisher's topic
- *
- * @exception JMSException if the JMS provider fails to get the topic for
- * this <CODE>TopicPublisher</CODE>
- * due to some internal error.
- */
-
Topic getTopic() throws JMSException;
-
- /** Publishes a message to the topic.
- * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode, priority,
- * and time to live.
- *
- * @param message the message to publish
- *
- * @exception JMSException if the JMS provider fails to publish the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses this method
- * with a <CODE>TopicPublisher</CODE> with
- * an invalid topic.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>TopicPublisher</CODE> that
- * did not specify a topic at creation time.
- *
- * @see javax.jms.MessageProducer#getDeliveryMode()
- * @see javax.jms.MessageProducer#getTimeToLive()
- * @see javax.jms.MessageProducer#getPriority()
- */
-
void publish(Message message) throws JMSException;
-
- /** Publishes a message to the topic, specifying delivery mode,
- * priority, and time to live.
- *
- * @param message the message to publish
- * @param deliveryMode the delivery mode to use
- * @param priority the priority for this message
- * @param timeToLive the message's lifetime (in milliseconds)
- *
- * @exception JMSException if the JMS provider fails to publish the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses this method
- * with a <CODE>TopicPublisher</CODE> with
- * an invalid topic.
- * @exception java.lang.UnsupportedOperationException if a client uses this
- * method with a <CODE>TopicPublisher</CODE> that
- * did not specify a topic at creation time.
- */
-
- void publish(Message message, int deliveryMode, int priority, long
timeToLive) throws JMSException;
-
-
- /** Publishes a message to a topic for an unidentified message producer.
- * Uses the <CODE>TopicPublisher</CODE>'s default delivery mode,
- * priority, and time to live.
- *
- * <P>Typically, a message producer is assigned a topic at creation
- * time; however, the JMS API also supports unidentified message producers,
- * which require that the topic be supplied every time a message is
- * published.
- *
- * @param topic the topic to publish this message to
- * @param message the message to publish
- *
- * @exception JMSException if the JMS provider fails to publish the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with an invalid topic.
- *
- * @see javax.jms.MessageProducer#getDeliveryMode()
- * @see javax.jms.MessageProducer#getTimeToLive()
- * @see javax.jms.MessageProducer#getPriority()
- */
+ void publish(
+ Message message,
+ int deliveryMode,
+ int priority,
+ long timeToLive)
+ throws JMSException;
void publish(Topic topic, Message message) throws JMSException;
-
- /** Publishes a message to a topic for an unidentified message
- * producer, specifying delivery mode, priority and time to live.
- *
- * <P>Typically, a message producer is assigned a topic at creation
- * time; however, the JMS API also supports unidentified message producers,
- * which require that the topic be supplied every time a message is
- * published.
- *
- * @param topic the topic to publish this message to
- * @param message the message to publish
- * @param deliveryMode the delivery mode to use
- * @param priority the priority for this message
- * @param timeToLive the message's lifetime (in milliseconds)
- *
- * @exception JMSException if the JMS provider fails to publish the message
- * due to some internal error.
- * @exception MessageFormatException if an invalid message is specified.
- * @exception InvalidDestinationException if a client uses
- * this method with an invalid topic.
- */
-
- void publish(Topic topic, Message message, int deliveryMode, int priority,
long timeToLive) throws JMSException;
+ void publish(
+ Topic topic,
+ Message message,
+ int deliveryMode,
+ int priority,
+ long timeToLive)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TopicRequestor.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TopicRequestor.java,v
retrieving revision 1.1
diff -u -r1.1 TopicRequestor.java
--- specs/jms/src/java/javax/jms/TopicRequestor.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TopicRequestor.java 19 Aug 2003 23:12:49
-0000
@@ -62,101 +62,74 @@
package javax.jms;
-/** The <CODE>TopicRequestor</CODE> helper class simplifies
- * making service requests.
- *
- * <P>The <CODE>TopicRequestor</CODE> constructor is given a non-transacted
- * <CODE>TopicSession</CODE> and a destination <CODE>Topic</CODE>. It creates a
- * <CODE>TemporaryTopic</CODE> for the responses and provides a
- * <CODE>request</CODE> method that sends the request message and waits
- * for its reply.
- *
- * <P>This is a basic request/reply abstraction that should be sufficient
- * for most uses. JMS providers and clients are free to create more
- * sophisticated versions.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- *
- * @see javax.jms.QueueRequestor
+/**
+ * @version $Revision:$ $Date:$
*/
-
public class TopicRequestor {
+ private TopicSession session;
+ private Topic topic;
+ private TemporaryTopic temporaryTopic;
+ private TopicPublisher publisher;
+ private TopicSubscriber subscriber;
+
+ public TopicRequestor(TopicSession session, Topic topic)
+ throws JMSException {
+ super();
+ setSession(session);
+ setTopic(topic);
+ setTemporaryTopic(session.createTemporaryTopic());
+ setPublisher(session.createPublisher(topic));
+ setSubscriber(session.createSubscriber(getTemporaryTopic()));
+ }
+
+ public Message request(Message message) throws JMSException {
+ message.setJMSReplyTo(getTemporaryTopic());
+ getPublisher().publish(message);
+ return (getSubscriber().receive());
+ }
+
+ public void close() throws JMSException {
+ getSession().close();
+ getTemporaryTopic().delete();
+ }
- TopicSession session; // The topic session the topic belongs to.
- Topic topic; // The topic to perform the request/reply on.
- TemporaryTopic tempTopic;
- TopicPublisher publisher;
- TopicSubscriber subscriber;
-
-
- /** Constructor for the <CODE>TopicRequestor</CODE> class.
- *
- * <P>This implementation assumes the session parameter to be
non-transacted,
- * with a delivery mode of either <CODE>AUTO_ACKNOWLEDGE</CODE> or
- * <CODE>DUPS_OK_ACKNOWLEDGE</CODE>.
- *
- * @param session the <CODE>TopicSession</CODE> the topic belongs to
- * @param topic the topic to perform the request/reply call on
- *
- * @exception JMSException if the JMS provider fails to create the
- * <CODE>TopicRequestor</CODE> due to some internal
- * error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- */
+ private void setPublisher(TopicPublisher publisher) {
+ this.publisher = publisher;
+ }
- public
- TopicRequestor(TopicSession session, Topic topic) throws
JMSException {
+ private TopicPublisher getPublisher() {
+ return publisher;
+ }
+
+ private void setSession(TopicSession session) {
this.session = session;
- this.topic = topic;
- tempTopic = session.createTemporaryTopic();
- publisher = session.createPublisher(topic);
- subscriber = session.createSubscriber(tempTopic);
}
+ private TopicSession getSession() {
+ return session;
+ }
+
+ private void setSubscriber(TopicSubscriber subscriber) {
+ this.subscriber = subscriber;
+ }
+
+ private TopicSubscriber getSubscriber() {
+ return subscriber;
+ }
- /** Sends a request and waits for a reply. The temporary topic is used for
- * the <CODE>JMSReplyTo</CODE> destination; the first reply is returned,
- * and any following replies are discarded.
- *
- * @param message the message to send
- *
- * @return the reply message
- *
- * @exception JMSException if the JMS provider fails to complete the
- * request due to some internal error.
- */
-
- public Message
- request(Message message) throws JMSException {
- message.setJMSReplyTo(tempTopic);
- publisher.publish(message);
- return (subscriber.receive());
+ private void setTemporaryTopic(TemporaryTopic temporaryTopic) {
+ this.temporaryTopic = temporaryTopic;
}
+ private TemporaryTopic getTemporaryTopic() {
+ return temporaryTopic;
+ }
+
+ private void setTopic(Topic topic) {
+ this.topic = topic;
+ }
- /** Closes the <CODE>TopicRequestor</CODE> and its session.
- *
- * <P>Since a provider may allocate some resources on behalf of a
- * <CODE>TopicRequestor</CODE> outside the Java virtual machine, clients
- * should close them when they
- * are not needed. Relying on garbage collection to eventually reclaim
- * these resources may not be timely enough.
- *
- * <P>Note that this method closes the <CODE>TopicSession</CODE> object
- * passed to the <CODE>TopicRequestor</CODE> constructor.
- *
- * @exception JMSException if the JMS provider fails to close the
- * <CODE>TopicRequestor</CODE> due to some internal
- * error.
- */
-
- public void
- close() throws JMSException {
-
- // publisher and consumer created by constructor are implicitly closed.
- session.close();
- tempTopic.delete();
+ private Topic getTopic() {
+ return topic;
}
}
Index: specs/jms/src/java/javax/jms/TopicSession.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TopicSession.java,v
retrieving revision 1.1
diff -u -r1.1 TopicSession.java
--- specs/jms/src/java/javax/jms/TopicSession.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TopicSession.java 19 Aug 2003 23:12:49
-0000
@@ -62,256 +62,33 @@
package javax.jms;
-/** A <CODE>TopicSession</CODE> object provides methods for creating
- * <CODE>TopicPublisher</CODE>, <CODE>TopicSubscriber</CODE>, and
- * <CODE>TemporaryTopic</CODE> objects. It also provides a method for
- * deleting its client's durable subscribers.
- *
- *<P>A <CODE>TopicSession</CODE> is used for creating Pub/Sub specific
- * objects. In general, use the <CODE>Session</CODE> object, and
- * use <CODE>TopicSession</CODE> only to support
- * existing code. Using the <CODE>Session</CODE> object simplifies the
- * programming model, and allows transactions to be used across the two
- * messaging domains.
- *
- * <P>A <CODE>TopicSession</CODE> cannot be used to create objects specific to
the
- * point-to-point domain. The following methods inherit from
- * <CODE>Session</CODE>, but must throw an
- * <CODE>IllegalStateException</CODE>
- * if used from <CODE>TopicSession</CODE>:
- *<UL>
- * <LI><CODE>createBrowser</CODE>
- * <LI><CODE>createQueue</CODE>
- * <LI><CODE>createTemporaryQueue</CODE>
- *</UL>
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session
- * @see javax.jms.Connection#createSession(boolean, int)
- * @see javax.jms.TopicConnection#createTopicSession(boolean, int)
- * @see javax.jms.XATopicSession#getTopicSession()
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TopicSession extends Session {
-
- /** Creates a topic identity given a <CODE>Topic</CODE> name.
- *
- * <P>This facility is provided for the rare cases where clients need to
- * dynamically manipulate topic identity. This allows the creation of a
- * topic identity with a provider-specific name. Clients that depend
- * on this ability are not portable.
- *
- * <P>Note that this method is not for creating the physical topic.
- * The physical creation of topics is an administrative task and is not
- * to be initiated by the JMS API. The one exception is the
- * creation of temporary topics, which is accomplished with the
- * <CODE>createTemporaryTopic</CODE> method.
- *
- * @param topicName the name of this <CODE>Topic</CODE>
- *
- * @return a <CODE>Topic</CODE> with the given name
- *
- * @exception JMSException if the session fails to create a topic
- * due to some internal error.
- */
-
Topic createTopic(String topicName) throws JMSException;
-
- /** Creates a nondurable subscriber to the specified topic.
- *
- * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive
- * messages that have been published to a topic.
- *
- * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable.
- * They receive only messages that are published while they are active.
- *
- * <P>In some cases, a connection may both publish and subscribe to a
- * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
- * to inhibit the delivery of messages published by its own connection.
- * The default value for this attribute is false.
- *
- * @param topic the <CODE>Topic</CODE> to subscribe to
- *
- * @exception JMSException if the session fails to create a subscriber
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- */
-
TopicSubscriber createSubscriber(Topic topic) throws JMSException;
-
- /** Creates a nondurable subscriber to the specified topic, using a
- * message selector or specifying whether messages published by its
- * own connection should be delivered to it.
- *
- * <P>A client uses a <CODE>TopicSubscriber</CODE> object to receive
- * messages that have been published to a topic.
- *
- * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable.
- * They receive only messages that are published while they are active.
- *
- * <P>Messages filtered out by a subscriber's message selector will
- * never be delivered to the subscriber. From the subscriber's
- * perspective, they do not exist.
- *
- * <P>In some cases, a connection may both publish and subscribe to a
- * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
- * to inhibit the delivery of messages published by its own connection.
- * The default value for this attribute is false.
- *
- * @param topic the <CODE>Topic</CODE> to subscribe to
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param noLocal if set, inhibits the delivery of messages published
- * by its own connection
- *
- * @exception JMSException if the session fails to create a subscriber
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- */
-
- TopicSubscriber createSubscriber(Topic topic, String messageSelector,
boolean noLocal) throws JMSException;
-
-
- /** Creates a durable subscriber to the specified topic.
- *
- * <P>If a client needs to receive all the messages published on a
- * topic, including the ones published while the subscriber is inactive,
- * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
- * retains a record of this
- * durable subscription and insures that all messages from the topic's
- * publishers are retained until they are acknowledged by this
- * durable subscriber or they have expired.
- *
- * <P>Sessions with durable subscribers must always provide the same
- * client identifier. In addition, each client must specify a name that
- * uniquely identifies (within client identifier) each durable
- * subscription it creates. Only one session at a time can have a
- * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
- *
- * <P>A client can change an existing durable subscription by creating
- * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
- * topic and/or
- * message selector. Changing a durable subscriber is equivalent to
- * unsubscribing (deleting) the old one and creating a new one.
- *
- * <P>In some cases, a connection may both publish and subscribe to a
- * topic. The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber
- * to inhibit the delivery of messages published by its own connection.
- * The default value for this attribute is false.
- *
- * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
- * @param name the name used to identify this subscription
- *
- * @exception JMSException if the session fails to create a subscriber
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- */
-
- TopicSubscriber createDurableSubscriber(Topic topic, String name) throws
JMSException;
-
-
- /** Creates a durable subscriber to the specified topic, using a
- * message selector or specifying whether messages published by its
- * own connection should be delivered to it.
- *
- * <P>If a client needs to receive all the messages published on a
- * topic, including the ones published while the subscriber is inactive,
- * it uses a durable <CODE>TopicSubscriber</CODE>. The JMS provider
- * retains a record of this
- * durable subscription and insures that all messages from the topic's
- * publishers are retained until they are acknowledged by this
- * durable subscriber or they have expired.
- *
- * <P>Sessions with durable subscribers must always provide the same
- * client identifier. In addition, each client must specify a name which
- * uniquely identifies (within client identifier) each durable
- * subscription it creates. Only one session at a time can have a
- * <CODE>TopicSubscriber</CODE> for a particular durable subscription.
- * An inactive durable subscriber is one that exists but
- * does not currently have a message consumer associated with it.
- *
- * <P>A client can change an existing durable subscription by creating
- * a durable <CODE>TopicSubscriber</CODE> with the same name and a new
- * topic and/or
- * message selector. Changing a durable subscriber is equivalent to
- * unsubscribing (deleting) the old one and creating a new one.
- *
- * @param topic the non-temporary <CODE>Topic</CODE> to subscribe to
- * @param name the name used to identify this subscription
- * @param messageSelector only messages with properties matching the
- * message selector expression are delivered. A value of null or
- * an empty string indicates that there is no message selector
- * for the message consumer.
- * @param noLocal if set, inhibits the delivery of messages published
- * by its own connection
- *
- * @exception JMSException if the session fails to create a subscriber
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- * @exception InvalidSelectorException if the message selector is invalid.
- */
-
- TopicSubscriber createDurableSubscriber(Topic topic, String name, String
messageSelector, boolean noLocal) throws JMSException;
-
-
- /** Creates a publisher for the specified topic.
- *
- * <P>A client uses a <CODE>TopicPublisher</CODE> object to publish
- * messages on a topic.
- * Each time a client creates a <CODE>TopicPublisher</CODE> on a topic, it
- * defines a
- * new sequence of messages that have no ordering relationship with the
- * messages it has previously sent.
- *
- * @param topic the <CODE>Topic</CODE> to publish to, or null if this is an
- * unidentified producer
- *
- * @exception JMSException if the session fails to create a publisher
- * due to some internal error.
- * @exception InvalidDestinationException if an invalid topic is specified.
- */
+ TopicSubscriber createSubscriber(
+ Topic topic,
+ String messageSelector,
+ boolean noLocal)
+ throws JMSException;
+
+ TopicSubscriber createDurableSubscriber(Topic topic, String name)
+ throws JMSException;
+
+ TopicSubscriber createDurableSubscriber(
+ Topic topic,
+ String name,
+ String messageSelector,
+ boolean noLocal)
+ throws JMSException;
TopicPublisher createPublisher(Topic topic) throws JMSException;
-
- /** Creates a <CODE>TemporaryTopic</CODE> object. Its lifetime will be that
- * of the <CODE>TopicConnection</CODE> unless it is deleted earlier.
- *
- * @return a temporary topic identity
- *
- * @exception JMSException if the session fails to create a temporary
- * topic due to some internal error.
- */
-
TemporaryTopic createTemporaryTopic() throws JMSException;
-
-
- /** Unsubscribes a durable subscription that has been created by a client.
- *
- * <P>This method deletes the state being maintained on behalf of the
- * subscriber by its provider.
- *
- * <P>It is erroneous for a client to delete a durable subscription
- * while there is an active <CODE>TopicSubscriber</CODE> for the
- * subscription, or while a consumed message is part of a pending
- * transaction or has not been acknowledged in the session.
- *
- * @param name the name used to identify this subscription
- *
- * @exception JMSException if the session fails to unsubscribe to the
- * durable subscription due to some internal error.
- * @exception InvalidDestinationException if an invalid subscription name
- * is specified.
- */
void unsubscribe(String name) throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TopicSubscriber.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TopicSubscriber.java,v
retrieving revision 1.1
diff -u -r1.1 TopicSubscriber.java
--- specs/jms/src/java/javax/jms/TopicSubscriber.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/TopicSubscriber.java 19 Aug 2003 23:12:49
-0000
@@ -62,100 +62,11 @@
package javax.jms;
-/** A client uses a <CODE>TopicSubscriber</CODE> object to receive messages
that
- * have been published to a topic. A <CODE>TopicSubscriber</CODE> object is the
- * publish/subscribe form of a message consumer. A <CODE>MessageConsumer</CODE>
- * can be created by using <CODE>Session.createConsumer</CODE>.
- *
- * <P>A <CODE>TopicSession</CODE> allows the creation of multiple
- * <CODE>TopicSubscriber</CODE> objects per topic. It will deliver each
- * message for a topic to each
- * subscriber eligible to receive it. Each copy of the message
- * is treated as a completely separate message. Work done on one copy has
- * no effect on the others; acknowledging one does not acknowledge the
- * others; one message may be delivered immediately, while another waits
- * for its subscriber to process messages ahead of it.
- *
- * <P>Regular <CODE>TopicSubscriber</CODE> objects are not durable. They
- * receive only messages that are published while they are active.
- *
- * <P>Messages filtered out by a subscriber's message selector will never
- * be delivered to the subscriber. From the subscriber's perspective, they
- * do not exist.
- *
- * <P>In some cases, a connection may both publish and subscribe to a topic.
- * The subscriber <CODE>NoLocal</CODE> attribute allows a subscriber to inhibit
- * the
- * delivery of messages published by its own connection.
- *
- * <P>If a client needs to receive all the messages published on a topic,
- * including the ones published while the subscriber is inactive, it uses
- * a durable <CODE>TopicSubscriber</CODE>. The JMS provider retains a record of
- * this durable
- * subscription and insures that all messages from the topic's publishers
- * are retained until they are acknowledged by this durable
- * subscriber or they have expired.
- *
- * <P>Sessions with durable subscribers must always provide the same client
- * identifier. In addition, each client must specify a name that uniquely
- * identifies (within client identifier) each durable subscription it creates.
- * Only one session at a time can have a <CODE>TopicSubscriber</CODE> for a
- * particular durable subscription.
- *
- * <P>A client can change an existing durable subscription by creating a
- * durable <CODE>TopicSubscriber</CODE> with the same name and a new topic
- * and/or message
- * selector. Changing a durable subscription is equivalent to unsubscribing
- * (deleting) the old one and creating a new one.
- *
- * <P>The <CODE>unsubscribe</CODE> method is used to delete a durable
- * subscription. The <CODE>unsubscribe</CODE> method can be used at the
- * <CODE>Session</CODE> or <CODE>TopicSession</CODE> level.
- * This method deletes the state being
- * maintained on behalf of the subscriber by its provider.
- *
- * <P>Creating a <CODE>MessageConsumer</CODE> provides the same features as
- * creating a <CODE>TopicSubscriber</CODE>. To create a durable subscriber,
- * use of <CODE>Session.CreateDurableSubscriber</CODE> is recommended. The
- * <CODE>TopicSubscriber</CODE> is provided to support existing code.
- *
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session#createConsumer
- * @see javax.jms.Session#createDurableSubscriber
- * @see javax.jms.TopicSession
- * @see javax.jms.TopicSession#createSubscriber
- * @see javax.jms.MessageConsumer
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface TopicSubscriber extends MessageConsumer {
-
- /** Gets the <CODE>Topic</CODE> associated with this subscriber.
- *
- * @return this subscriber's <CODE>Topic</CODE>
- *
- * @exception JMSException if the JMS provider fails to get the topic for
- * this topic subscriber
- * due to some internal error.
- */
-
Topic getTopic() throws JMSException;
-
-
- /** Gets the <CODE>NoLocal</CODE> attribute for this subscriber.
- * The default value for this attribute is false.
- *
- * @return true if locally published messages are being inhibited
- *
- * @exception JMSException if the JMS provider fails to get the
- * <CODE>NoLocal</CODE> attribute for
- * this topic subscriber
- * due to some internal error.
- */
boolean getNoLocal() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/TransactionInProgressException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TransactionInProgressException.java,v
retrieving revision 1.1
diff -u -r1.1 TransactionInProgressException.java
--- specs/jms/src/java/javax/jms/TransactionInProgressException.java 16 Aug
2003 02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/TransactionInProgressException.java 19 Aug
2003 23:12:49 -0000
@@ -63,37 +63,14 @@
package javax.jms;
/**
- * <P> This exception is thrown when an
- * operation is invalid because a transaction is in progress.
- * For instance, an attempt to call <CODE>Session.commit</CODE> when a
- * session is part of a distributed transaction should throw a
- * <CODE>TransactionInProgressException</CODE>.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class TransactionInProgressException extends JMSException {
-
- /** Constructs a <CODE>TransactionInProgressException</CODE> with the
- * specified reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public TransactionInProgressException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>TransactionInProgressException</CODE> with the
- * specified reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public TransactionInProgressException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/TransactionRolledBackException.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/TransactionRolledBackException.java,v
retrieving revision 1.1
diff -u -r1.1 TransactionRolledBackException.java
--- specs/jms/src/java/javax/jms/TransactionRolledBackException.java 16 Aug
2003 02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/TransactionRolledBackException.java 19 Aug
2003 23:12:49 -0000
@@ -63,35 +63,14 @@
package javax.jms;
/**
- * <P> This exception must be thrown when a
- * call to <CODE>Session.commit</CODE> results in a rollback of the current
- * transaction.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Rahul Sharma
- **/
-
+ * @version $Revision:$ $Date:$
+ */
public class TransactionRolledBackException extends JMSException {
-
- /** Constructs a <CODE>TransactionRolledBackException</CODE> with the
- * specified reason and error code.
- *
- * @param reason a description of the exception
- * @param errorCode a string specifying the vendor-specific
- * error code
- *
- **/
public TransactionRolledBackException(String reason, String errorCode) {
super(reason, errorCode);
}
- /** Constructs a <CODE>TransactionRolledBackException</CODE> with the
- * specified reason. The error code defaults to null.
- *
- * @param reason a description of the exception
- **/
public TransactionRolledBackException(String reason) {
- super(reason);
+ this(reason, null);
}
-
}
Index: specs/jms/src/java/javax/jms/XAConnection.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XAConnection.java,v
retrieving revision 1.1
diff -u -r1.1 XAConnection.java
--- specs/jms/src/java/javax/jms/XAConnection.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/XAConnection.java 19 Aug 2003 23:12:49
-0000
@@ -62,52 +62,12 @@
package javax.jms;
-/** The <CODE>XAConnection</CODE> interface extends the capability of
- * <CODE>Connection</CODE> by providing an <CODE>XASession</CODE> (optional).
- *
- *<P>The <CODE>XAConnection</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.XAQueueConnection
- * @see javax.jms.XATopicConnection
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XAConnection extends Connection {
-
- /** Creates an <CODE>XASession</CODE> object.
- *
- * @return a newly created <CODE>XASession</CODE>
- *
- * @exception JMSException if the <CODE>XAConnection</CODE> object
- * fails to create an <CODE>XASession</CODE> due to
- * some internal error.
- *
- * @since 1.1
- */
-
XASession createXASession() throws JMSException;
- /** Creates an <CODE>Session</CODE> object.
- *
- * @param transacted usage undefined
- * @param acknowledgeMode usage undefined
- *
- * @return a <CODE>Session</CODE> object
- *
- * @exception JMSException if the <CODE>XAConnection</CODE> object
- * fails to create an <CODE>Session</CODE> due to
- * some internal error.
- *
- * @since 1.1
- */
- Session createSession(boolean transacted, int acknowledgeMode) throws
JMSException;
+ Session createSession(boolean transacted, int acknowledgeMode)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XAConnectionFactory.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XAConnectionFactory.java,v
retrieving revision 1.1
diff -u -r1.1 XAConnectionFactory.java
--- specs/jms/src/java/javax/jms/XAConnectionFactory.java 16 Aug 2003
02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/XAConnectionFactory.java 19 Aug 2003
23:12:49 -0000
@@ -62,75 +62,12 @@
package javax.jms;
-/** The <CODE>XAConnectionFactory</CODE> interface is a base interface for the
- * <CODE>XAQueueConnectionFactory</CODE> and
- * <CODE>XATopicConnectionFactory</CODE> interfaces.
- *
- * <P>Some application servers provide support for grouping JTS capable
- * resource use into a distributed transaction (optional). To include JMS API
transactions
- * in a JTS transaction, an application server requires a JTS aware JMS
- * provider. A JMS provider exposes its JTS support using an
- * <CODE>XAConnectionFactory</CODE> object, which an application server uses
- * to create <CODE>XAConnection</CODE> objects.
- *
- * <P><CODE>XAConnectionFactory</CODE> objects are JMS administered objects,
- * just like <CODE>ConnectionFactory</CODE> objects. It is expected that
- * application servers will find them using the Java Naming and Directory
- * Interface (JNDI) API.
- *
- *<P>The <CODE>XAConnectionFactory</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.XAQueueConnectionFactory
- * @see javax.jms.XATopicConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XAConnectionFactory {
-
- /** Creates an <CODE>XAConnection</CODE> with the default user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @return a newly created <CODE>XAConnection</CODE>
- *
- * @exception JMSException if the JMS provider fails to create an XA
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- *
- * @since 1.1
- */
-
XAConnection createXAConnection() throws JMSException;
-
- /** Creates an XA connection with the specified user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @param userName the caller's user name
- * @param password the caller's password
- *
- * @return a newly created XA connection
- *
- * @exception JMSException if the JMS provider fails to create an XA
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- *
- * @since 1.1
- */
-
- XAConnection createXAConnection(String userName, String password) throws
JMSException;
+ XAConnection createXAConnection(String userName, String password)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XAQueueConnection.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XAQueueConnection.java,v
retrieving revision 1.1
diff -u -r1.1 XAQueueConnection.java
--- specs/jms/src/java/javax/jms/XAQueueConnection.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/XAQueueConnection.java 19 Aug 2003 23:12:49
-0000
@@ -62,50 +62,12 @@
package javax.jms;
-/** An <CODE>XAQueueConnection</CODE> provides the same create options as
- * <CODE>QueueConnection</CODE> (optional).
- * The only difference is that an <CODE>XAConnection</CODE> is by definition
- * transacted.
- *
- *<P>The <CODE>XAQueueConnection</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.XAConnection
+/**
+ * @version $Revision:$ $Date:$
*/
-
-public interface XAQueueConnection
- extends XAConnection, QueueConnection {
-
- /** Creates an <CODE>XAQueueSession</CODE> object.
- *
- * @return a newly created <CODE>XAQueueSession</CODE>
- *
- * @exception JMSException if the <CODE>XAQueueConnection</CODE> object
- * fails to create an XA queue session due to some
- * internal error.
- */
-
+public interface XAQueueConnection extends XAConnection, QueueConnection {
XAQueueSession createXAQueueSession() throws JMSException;
- /** Creates an <CODE>XAQueueSession</CODE> object.
- *
- * @param transacted usage undefined
- * @param acknowledgeMode usage undefined
- *
- * @return a newly created <CODE>XAQueueSession</CODE>
- *
- * @exception JMSException if the <CODE>XAQueueConnection</CODE> object
- * fails to create an XA queue session due to some
- * internal error.
- */
- QueueSession createQueueSession(boolean transacted, int acknowledgeMode)
throws JMSException;
+ QueueSession createQueueSession(boolean transacted, int acknowledgeMode)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XAQueueConnectionFactory.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XAQueueConnectionFactory.java,v
retrieving revision 1.1
diff -u -r1.1 XAQueueConnectionFactory.java
--- specs/jms/src/java/javax/jms/XAQueueConnectionFactory.java 16 Aug 2003
02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/XAQueueConnectionFactory.java 19 Aug 2003
23:12:49 -0000
@@ -62,59 +62,13 @@
package javax.jms;
-/** An <CODE>XAQueueConnectionFactory</CODE> provides the same create options
as
- * a <CODE>QueueConnectionFactory</CODE> (optional).
- *
- * <P>The <CODE>XATopicConnectionFactory</CODE> interface is optional. JMS
providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.QueueConnectionFactory
- * @see javax.jms.XAConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XAQueueConnectionFactory
- extends XAConnectionFactory, QueueConnectionFactory {
-
- /** Creates an XA queue connection with the default user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @return a newly created XA queue connection
- *
- * @exception JMSException if the JMS provider fails to create an XA queue
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
+ extends XAConnectionFactory, QueueConnectionFactory {
XAQueueConnection createXAQueueConnection() throws JMSException;
-
- /** Creates an XA queue connection with the specified user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @param userName the caller's user name
- * @param password the caller's password
- *
- * @return a newly created XA queue connection
- *
- * @exception JMSException if the JMS provider fails to create an XA queue
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
- XAQueueConnection createXAQueueConnection(String userName, String
password) throws JMSException;
+ XAQueueConnection createXAQueueConnection(String userName, String password)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XAQueueSession.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XAQueueSession.java,v
retrieving revision 1.1
diff -u -r1.1 XAQueueSession.java
--- specs/jms/src/java/javax/jms/XAQueueSession.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/XAQueueSession.java 19 Aug 2003 23:12:49
-0000
@@ -62,34 +62,9 @@
package javax.jms;
-/** An <CODE>XAQueueSession</CODE> provides a regular
<CODE>QueueSession</CODE>,
- * which can be used to
- * create <CODE>QueueReceiver</CODE>, <CODE>QueueSender</CODE>, and
- *<CODE>QueueBrowser</CODE> objects (optional).
- *
- * <P>The <CODE>XAQueueSession</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.XASession
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XAQueueSession extends XASession {
-
- /** Gets the queue session associated with this
<CODE>XAQueueSession</CODE>.
- *
- * @return the queue session object
- *
- * @exception JMSException if an internal error occurs.
- */
-
QueueSession getQueueSession() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XASession.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XASession.java,v
retrieving revision 1.1
diff -u -r1.1 XASession.java
--- specs/jms/src/java/javax/jms/XASession.java 16 Aug 2003 02:29:58 -0000
1.1
+++ specs/jms/src/java/javax/jms/XASession.java 19 Aug 2003 23:12:50 -0000
@@ -64,94 +64,17 @@
import javax.transaction.xa.XAResource;
-/** The <CODE>XASession</CODE> interface extends the capability of
- * <CODE>Session</CODE> by adding access to a JMS provider's support for the
- * Java Transaction API (JTA) (optional). This support takes the form of a
- * <CODE>javax.transaction.xa.XAResource</CODE> object. The functionality of
- * this object closely resembles that defined by the standard X/Open XA
- * Resource interface.
- *
- * <P>An application server controls the transactional assignment of an
- * <CODE>XASession</CODE> by obtaining its <CODE>XAResource</CODE>. It uses
- * the <CODE>XAResource</CODE> to assign the session to a transaction, prepare
- * and commit work on the transaction, and so on.
- *
- * <P>An <CODE>XAResource</CODE> provides some fairly sophisticated facilities
- * for interleaving work on multiple transactions, recovering a list of
- * transactions in progress, and so on. A JTA aware JMS provider must fully
- * implement this functionality. This could be done by using the services
- * of a database that supports XA, or a JMS provider may choose to implement
- * this functionality from scratch.
- *
- * <P>A client of the application server is given what it thinks is a
- * regular JMS <CODE>Session</CODE>. Behind the scenes, the application server
- * controls the transaction management of the underlying
- * <CODE>XASession</CODE>.
- *
- * <P>The <CODE>XASession</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.Session
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XASession extends Session {
-
- /** Gets the session associated with this <CODE>XASession</CODE>.
- *
- * @return the session object
- *
- * @exception JMSException if an internal error occurs.
- *
- * @since 1.1
- */
-
Session getSession() throws JMSException;
- /** Returns an XA resource to the caller.
- *
- * @return an XA resource to the caller
- */
-
XAResource getXAResource();
- /** Indicates whether the session is in transacted mode.
- *
- * @return true
- *
- * @exception JMSException if the JMS provider fails to return the
- * transaction mode due to some internal error.
- */
-
boolean getTransacted() throws JMSException;
-
- /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
- * not be called for an <CODE>XASession</CODE> object.
- *
- * @exception TransactionInProgressException if the method is called on
- * an <CODE>XASession</CODE>.
- *
- */
-
void commit() throws JMSException;
-
-
- /** Throws a <CODE>TransactionInProgressException</CODE>, since it should
- * not be called for an <CODE>XASession</CODE> object.
- *
- * @exception TransactionInProgressException if the method is called on
- * an <CODE>XASession</CODE>.
- *
- */
void rollback() throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XATopicConnection.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XATopicConnection.java,v
retrieving revision 1.1
diff -u -r1.1 XATopicConnection.java
--- specs/jms/src/java/javax/jms/XATopicConnection.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/XATopicConnection.java 19 Aug 2003 23:12:50
-0000
@@ -62,50 +62,12 @@
package javax.jms;
-/** An <CODE>XATopicConnection</CODE> provides the same create options as
- * <CODE>TopicConnection</CODE> (optional). The Topic connections created are
- * transactional.
- *
- * <P>The <CODE>XATopicConnection</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.XAConnection
+/**
+ * @version $Revision:$ $Date:$
*/
-
-public interface XATopicConnection
- extends XAConnection, TopicConnection {
-
- /** Creates an <CODE>XATopicSession</CODE> object.
- *
- * @return a newly created XA topic session
- *
- * @exception JMSException if the <CODE>XATopicConnection</CODE> object
- * fails to create an XA topic session due to some
- * internal error.
- */
-
+public interface XATopicConnection extends XAConnection, TopicConnection {
XATopicSession createXATopicSession() throws JMSException;
- /** Creates an <CODE>XATopicSession</CODE> object.
- *
- * @param transacted usage undefined
- * @param acknowledgeMode usage undefined
- *
- * @return a newly created XA topic session
- *
- * @exception JMSException if the <CODE>XATopicConnection</CODE> object
- * fails to create an XA topic session due to some
- * internal error.
- */
-
- TopicSession createTopicSession(boolean transacted, int acknowledgeMode)
throws JMSException;
+ TopicSession createTopicSession(boolean transacted, int acknowledgeMode)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XATopicConnectionFactory.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XATopicConnectionFactory.java,v
retrieving revision 1.1
diff -u -r1.1 XATopicConnectionFactory.java
--- specs/jms/src/java/javax/jms/XATopicConnectionFactory.java 16 Aug 2003
02:29:58 -0000 1.1
+++ specs/jms/src/java/javax/jms/XATopicConnectionFactory.java 19 Aug 2003
23:12:50 -0000
@@ -62,59 +62,13 @@
package javax.jms;
-/** An <CODE>XATopicConnectionFactory</CODE> provides the same create options
as
- * a <CODE>TopicConnectionFactory</CODE> (optional).
- *
- * <P>The <CODE>XATopicConnectionFactory</CODE> interface is optional. JMS
providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than use these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.TopicConnectionFactory
- * @see javax.jms.XAConnectionFactory
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XATopicConnectionFactory
- extends XAConnectionFactory, TopicConnectionFactory {
-
- /** Creates an XA topic connection with the default user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @return a newly created XA topic connection
- *
- * @exception JMSException if the JMS provider fails to create an XA topic
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
+ extends XAConnectionFactory, TopicConnectionFactory {
XATopicConnection createXATopicConnection() throws JMSException;
-
- /** Creates an XA topic connection with the specified user identity.
- * The connection is created in stopped mode. No messages
- * will be delivered until the <code>Connection.start</code> method
- * is explicitly called.
- *
- * @param userName the caller's user name
- * @param password the caller's password
- *
- * @return a newly created XA topic connection
- *
- * @exception JMSException if the JMS provider fails to create an XA topic
- * connection due to some internal error.
- * @exception JMSSecurityException if client authentication fails due to
- * an invalid user name or password.
- */
-
- XATopicConnection createXATopicConnection(String userName, String
password) throws JMSException;
+ XATopicConnection createXATopicConnection(String userName, String password)
+ throws JMSException;
}
Index: specs/jms/src/java/javax/jms/XATopicSession.java
===================================================================
RCS file:
/home/cvspublic/incubator-geronimo/specs/jms/src/java/javax/jms/XATopicSession.java,v
retrieving revision 1.1
diff -u -r1.1 XATopicSession.java
--- specs/jms/src/java/javax/jms/XATopicSession.java 16 Aug 2003 02:29:58
-0000 1.1
+++ specs/jms/src/java/javax/jms/XATopicSession.java 19 Aug 2003 23:12:50
-0000
@@ -62,34 +62,9 @@
package javax.jms;
-/** An <CODE>XATopicSession</CODE> provides a regular
<CODE>TopicSession</CODE>.
- * which can be used to create <CODE>TopicSubscriber</CODE> and
- * <CODE>TopicPublisher</CODE> objects (optional).
- *
- * <P>The <CODE>XATopicSession</CODE> interface is optional. JMS providers
- * are not required to support this interface. This interface is for
- * use by JMS providers to support transactional environments.
- * Client programs are strongly encouraged to use the transactional support
- * available in their environment, rather than using these XA
- * interfaces directly.
- *
- * @version $Revision: 1.1 $ $Date: 2003/08/16 02:29:58 $
- * @author Mark Hapner
- * @author Rich Burridge
- * @author Kate Stout
- *
- * @see javax.jms.XASession
- * @see javax.jms.TopicSession
+/**
+ * @version $Revision:$ $Date:$
*/
-
public interface XATopicSession extends XASession {
-
- /** Gets the topic session associated with this
<CODE>XATopicSession</CODE>.
- *
- * @return the topic session object
- *
- * @exception JMSException if an internal error occurs.
- */
-
TopicSession getTopicSession() throws JMSException;
}
