diff options
Diffstat (limited to 'plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src')
58 files changed, 9675 insertions, 0 deletions
diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/BytesMessage.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/BytesMessage.java new file mode 100644 index 0000000000..669d1b3891 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/BytesMessage.java @@ -0,0 +1,577 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +import java.io.InputStream; +import java.io.OutputStream; + +/** 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 1.1 April 2, 2002 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Connection.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Connection.java new file mode 100644 index 0000000000..93e1361bd0 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Connection.java @@ -0,0 +1,414 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 - February 1, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.ConnectionFactory + * @see javax.jms.QueueConnection + * @see javax.jms.TopicConnection + */ + +public interface Connection { + + /** 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; +} + diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionConsumer.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionConsumer.java new file mode 100644 index 0000000000..d6876fbaac --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionConsumer.java @@ -0,0 +1,85 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 February 8, 2002 + * @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 + */ + +public interface ConnectionConsumer { + + /** 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionFactory.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionFactory.java new file mode 100644 index 0000000000..9916d5c3d6 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionFactory.java @@ -0,0 +1,126 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 - February 1, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.Connection + * @see javax.jms.QueueConnectionFactory + * @see javax.jms.TopicConnectionFactory + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionMetaData.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionMetaData.java new file mode 100644 index 0000000000..8fb3d50964 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ConnectionMetaData.java @@ -0,0 +1,133 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +import java.util.Enumeration; + +/** A <CODE>ConnectionMetaData</CODE> object provides information describing the + * <CODE>Connection</CODE> object. + * + * @version 1.0 - 13 March 1998 + * @author Mark Hapner + * @author Rich Burridge + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/DeliveryMode.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/DeliveryMode.java new file mode 100644 index 0000000000..b5cab804c1 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/DeliveryMode.java @@ -0,0 +1,79 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 7 August 1998 + * @author Mark Hapner + * @author Rich Burridge + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Destination.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Destination.java new file mode 100644 index 0000000000..a7bec1ae86 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Destination.java @@ -0,0 +1,97 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 3 August 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.Queue + * @see javax.jms.Topic + */ + +public interface Destination { +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ExceptionListener.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ExceptionListener.java new file mode 100644 index 0000000000..24904bb097 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ExceptionListener.java @@ -0,0 +1,57 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 9 March 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.Connection#setExceptionListener(ExceptionListener) + */ + +public interface ExceptionListener { + + /** Notifies user of a JMS exception. + * + * @param exception the JMS exception + */ + + void + onException(JMSException exception); +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/IllegalStateException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/IllegalStateException.java new file mode 100644 index 0000000000..5c80831a90 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/IllegalStateException.java @@ -0,0 +1,48 @@ +/* + * Copyright 2004-2005 Sun Microsystems, Inc. All rights reserved. + * Use is subject to license terms. + */ + + +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 April 9, 2002 + * @author Rahul Sharma + * @author Kate Stout + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidClientIDException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidClientIDException.java new file mode 100644 index 0000000000..0c4aae3f7e --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidClientIDException.java @@ -0,0 +1,60 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidDestinationException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidDestinationException.java new file mode 100644 index 0000000000..410b5b1339 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidDestinationException.java @@ -0,0 +1,61 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidSelectorException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidSelectorException.java new file mode 100644 index 0000000000..3f55c62c6d --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/InvalidSelectorException.java @@ -0,0 +1,61 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/JMSException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/JMSException.java new file mode 100644 index 0000000000..38230dbabf --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/JMSException.java @@ -0,0 +1,110 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 5 Oct 1998 + * @author Mark Hapner + * @author Rich Burridge + **/ + +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; + linkedException = null; + } + + /** Gets the vendor-specific error code. + * @return a string specifying the vendor-specific + * error code + **/ + public + String getErrorCode() { + return this.errorCode; + } + + /** + * Gets the exception linked to this one. + * + * @return the linked <CODE>Exception</CODE>, null if none + **/ + public + Exception getLinkedException() { + return (linkedException); + } + + /** + * Adds a linked <CODE>Exception</CODE>. + * + * @param ex the linked <CODE>Exception</CODE> + **/ + public + synchronized void setLinkedException(Exception ex) { + linkedException = ex; + } +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/JMSSecurityException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/JMSSecurityException.java new file mode 100644 index 0000000000..61377aca20 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/JMSSecurityException.java @@ -0,0 +1,61 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MapMessage.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MapMessage.java new file mode 100644 index 0000000000..faada144d1 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MapMessage.java @@ -0,0 +1,529 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +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 1.1 February 2, 002 + * @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 + */ + +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; + + + /** 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Message.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Message.java new file mode 100644 index 0000000000..e3148ee859 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Message.java @@ -0,0 +1,1511 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +import java.util.Enumeration; +import java.util.Properties; + +/** 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 + * {@link javax.jms.QueueReceiver QueueReceiver} and + * {@link 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 1.1 April 2, 2002 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageConsumer.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageConsumer.java new file mode 100644 index 0000000000..f6e7664b6e --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageConsumer.java @@ -0,0 +1,191 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.0 - 13 March 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.QueueReceiver + * @see javax.jms.TopicSubscriber + * @see javax.jms.Session + */ + +public interface MessageConsumer { + + /** 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. + */ + + void + close() throws JMSException; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageEOFException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageEOFException.java new file mode 100644 index 0000000000..1006ebd816 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageEOFException.java @@ -0,0 +1,61 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageFormatException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageFormatException.java new file mode 100644 index 0000000000..50b685cf03 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageFormatException.java @@ -0,0 +1,69 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageListener.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageListener.java new file mode 100644 index 0000000000..a35fa42b4f --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageListener.java @@ -0,0 +1,51 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 13 March 1998 + * @author Mark Hapner + * @author Rich Burridge + */ + +public interface MessageListener { + + /** Passes a message to the listener. + * + * @param message the message passed to the listener + */ + + void + onMessage(Message message); +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageNotReadableException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageNotReadableException.java new file mode 100644 index 0000000000..95c90b5352 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageNotReadableException.java @@ -0,0 +1,60 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +/** + * <P> This exception must be thrown when a JMS client attempts to read a + * write-only message. + * + * @version 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageNotWriteableException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageNotWriteableException.java new file mode 100644 index 0000000000..b8852c9905 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageNotWriteableException.java @@ -0,0 +1,60 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +/** + * <P> This exception must be thrown when a JMS client attempts to write to a + * read-only message. + * + * @version 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageProducer.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageProducer.java new file mode 100644 index 0000000000..a9658bb771 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/MessageProducer.java @@ -0,0 +1,389 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.TopicPublisher + * @see javax.jms.QueueSender + * @see javax.jms.Session#createProducer + */ + +public interface MessageProducer { + + /** 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. + *@since 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; + + + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ObjectMessage.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ObjectMessage.java new file mode 100644 index 0000000000..8c0fff03de --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ObjectMessage.java @@ -0,0 +1,90 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +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 1.0 - 6 August 1998 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Queue.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Queue.java new file mode 100644 index 0000000000..0a9ec202cd --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Queue.java @@ -0,0 +1,81 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 February 2 - 2000 + * @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) + */ + +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(); +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueBrowser.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueBrowser.java new file mode 100644 index 0000000000..0bb06ffb55 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueBrowser.java @@ -0,0 +1,115 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +package javax.jms; + +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 1.1 April 9, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.Session#createBrowser + * @see javax.jms.QueueSession#createBrowser + * @see javax.jms.QueueReceiver + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueConnection.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueConnection.java new file mode 100644 index 0000000000..ef21a6db56 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueConnection.java @@ -0,0 +1,118 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - April 9, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.Connection + * @see javax.jms.ConnectionFactory + * @see javax.jms.QueueConnectionFactory + */ + +public interface QueueConnection extends Connection { + + /** 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueConnectionFactory.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueConnectionFactory.java new file mode 100644 index 0000000000..dd1d570c82 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueConnectionFactory.java @@ -0,0 +1,87 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.ConnectionFactory + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueReceiver.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueReceiver.java new file mode 100644 index 0000000000..20d3300b82 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueReceiver.java @@ -0,0 +1,73 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 February 2, 2002 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueRequestor.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueRequestor.java new file mode 100644 index 0000000000..68860de448 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueRequestor.java @@ -0,0 +1,124 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 8 July 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.TopicRequestor + */ + +public class QueueRequestor { + + 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 + QueueRequestor(QueueSession session, Queue queue) throws JMSException { + this.session = session; + this.queue = queue; + tempQueue = session.createTemporaryQueue(); + sender = session.createSender(queue); + receiver = session.createReceiver(tempQueue); + } + + + /** 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()); + } + + + /** 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(); + } +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueSender.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueSender.java new file mode 100644 index 0000000000..57035f7a6e --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueSender.java @@ -0,0 +1,197 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @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) + */ + +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(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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueSession.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueSession.java new file mode 100644 index 0000000000..1c9399205e --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/QueueSession.java @@ -0,0 +1,187 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + + +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 1.1 - April 2, 2002 + * @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() + */ + +public interface QueueSession extends Session { + + /** 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. + */ + + TemporaryQueue + createTemporaryQueue() throws JMSException; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ResourceAllocationException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ResourceAllocationException.java new file mode 100644 index 0000000000..9a865d2752 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ResourceAllocationException.java @@ -0,0 +1,63 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ServerSession.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ServerSession.java new file mode 100644 index 0000000000..85a224e1fd --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ServerSession.java @@ -0,0 +1,102 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 9 March 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.ServerSessionPool + * @see javax.jms.ConnectionConsumer + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ServerSessionPool.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ServerSessionPool.java new file mode 100644 index 0000000000..858b937a2a --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/ServerSessionPool.java @@ -0,0 +1,63 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 9 March 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.ServerSession + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Session.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Session.java new file mode 100644 index 0000000000..c71cddfd48 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Session.java @@ -0,0 +1,807 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + + +package javax.jms; + +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 1.1 February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.QueueSession + * @see javax.jms.TopicSession + * @see javax.jms.XASession + */ + +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. + * + *@return If the session is not transacted, returns the + * current acknowledgement mode for the session. + * If the session + * is transacted, returns SESSION_TRANSACTED. + * + *@exception JMSException if the JMS provider fails to return the + * acknowledgment mode due to some internal error. + * + *@see Connection#createSession + *@since 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 + */ + + Queue + createQueue(String queueName) 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 + */ + + Topic + createTopic(String topicName) 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 InvalidDestinationException if an invalid destination + * is specified + * + * @since 1.1 + */ + + + /** 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; + + + /** 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. + * + *@since 1.1 + */ + + TemporaryQueue + createTemporaryQueue() 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 + */ + + 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; + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/StreamMessage.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/StreamMessage.java new file mode 100644 index 0000000000..d3de3eeb0d --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/StreamMessage.java @@ -0,0 +1,550 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.0 - 6 August 1998 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TemporaryQueue.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TemporaryQueue.java new file mode 100644 index 0000000000..1de79ef678 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TemporaryQueue.java @@ -0,0 +1,58 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see Session#createTemporaryQueue() + * @see QueueSession#createTemporaryQueue() + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TemporaryTopic.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TemporaryTopic.java new file mode 100644 index 0000000000..cf56d565f6 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TemporaryTopic.java @@ -0,0 +1,60 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see Session#createTemporaryTopic() + * @see TopicSession#createTemporaryTopic() + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TextMessage.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TextMessage.java new file mode 100644 index 0000000000..0ee45a0df1 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TextMessage.java @@ -0,0 +1,82 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 - February 2, 2002 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Topic.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Topic.java new file mode 100644 index 0000000000..37db768ce5 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/Topic.java @@ -0,0 +1,90 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see Session#createConsumer(Destination) + * @see Session#createProducer(Destination) + * @see javax.jms.TopicSession#createTopic(String) + */ + +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(); +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicConnection.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicConnection.java new file mode 100644 index 0000000000..15d9a9f605 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicConnection.java @@ -0,0 +1,146 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.Connection + * @see javax.jms.ConnectionFactory + * @see javax.jms.TopicConnectionFactory + */ + +public interface TopicConnection extends Connection { + + /** 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicConnectionFactory.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicConnectionFactory.java new file mode 100644 index 0000000000..68376b3a53 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicConnectionFactory.java @@ -0,0 +1,84 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.ConnectionFactory + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicPublisher.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicPublisher.java new file mode 100644 index 0000000000..b7dbb9fc69 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicPublisher.java @@ -0,0 +1,207 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 February 2, 2002 + * @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(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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicRequestor.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicRequestor.java new file mode 100644 index 0000000000..0ef194b428 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicRequestor.java @@ -0,0 +1,123 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.0 - 8 July 1998 + * @author Mark Hapner + * @author Rich Burridge + * + * @see javax.jms.QueueRequestor + */ + +public class TopicRequestor { + + 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. + */ + + public + TopicRequestor(TopicSession session, Topic topic) throws JMSException { + this.session = session; + this.topic = topic; + tempTopic = session.createTemporaryTopic(); + publisher = session.createPublisher(topic); + subscriber = session.createSubscriber(tempTopic); + } + + + /** 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()); + } + + + /** 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(); + } +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicSession.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicSession.java new file mode 100644 index 0000000000..d42dc5fb94 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicSession.java @@ -0,0 +1,293 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - April 9, 2002 + * @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() + */ + +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. + */ + + 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicSubscriber.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicSubscriber.java new file mode 100644 index 0000000000..9a1337c5cb --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TopicSubscriber.java @@ -0,0 +1,125 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @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 + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TransactionInProgressException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TransactionInProgressException.java new file mode 100644 index 0000000000..010bb58c2b --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TransactionInProgressException.java @@ -0,0 +1,62 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TransactionRolledBackException.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TransactionRolledBackException.java new file mode 100644 index 0000000000..d23a9f70a5 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/TransactionRolledBackException.java @@ -0,0 +1,60 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 26 August 1998 + * @author Rahul Sharma + **/ + +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); + } + +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAConnection.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAConnection.java new file mode 100644 index 0000000000..cd308aaa4e --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAConnection.java @@ -0,0 +1,78 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.XAQueueConnection + * @see javax.jms.XATopicConnection + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAConnectionFactory.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAConnectionFactory.java new file mode 100644 index 0000000000..bf4dc2393f --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAConnectionFactory.java @@ -0,0 +1,101 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 April 4, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.XAQueueConnectionFactory + * @see javax.jms.XATopicConnectionFactory + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueConnection.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueConnection.java new file mode 100644 index 0000000000..691c7fdd46 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueConnection.java @@ -0,0 +1,75 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 February 2 - 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.XAConnection + */ + +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. + */ + + 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueConnectionFactory.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueConnectionFactory.java new file mode 100644 index 0000000000..5978e54d12 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueConnectionFactory.java @@ -0,0 +1,85 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - 8 April 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.QueueConnectionFactory + * @see javax.jms.XAConnectionFactory + */ + +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. + */ + + 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueSession.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueSession.java new file mode 100644 index 0000000000..d524162a6a --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XAQueueSession.java @@ -0,0 +1,58 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.XASession + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XASession.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XASession.java new file mode 100644 index 0000000000..31689cf49c --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XASession.java @@ -0,0 +1,123 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +package javax.jms; + +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 1.1 February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.Session + */ + +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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicConnection.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicConnection.java new file mode 100644 index 0000000000..5f6b218fff --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicConnection.java @@ -0,0 +1,76 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 - February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.XAConnection + */ + +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. + */ + + 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicConnectionFactory.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicConnectionFactory.java new file mode 100644 index 0000000000..6f589d1493 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicConnectionFactory.java @@ -0,0 +1,85 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + + +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 1.1 February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.TopicConnectionFactory + * @see javax.jms.XAConnectionFactory + */ + +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. + */ + + 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; +} diff --git a/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicSession.java b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicSession.java new file mode 100644 index 0000000000..091e391438 --- /dev/null +++ b/plugins/org.eclipse.net4j.examples.installer/examples/org.eclipse.net4j.jms.api/src/javax/jms/XATopicSession.java @@ -0,0 +1,57 @@ +/* + * The contents of this file are subject to the terms + * of the Common Development and Distribution License + * (the License). You may not use this file except in + * compliance with the License. + * + * You can obtain a copy of the license at + * https://glassfish.dev.java.net/public/CDDLv1.0.html or + * glassfish/bootstrap/legal/CDDLv1.0.txt. + * See the License for the specific language governing + * permissions and limitations under the License. + * + * When distributing Covered Code, include this CDDL + * Header Notice in each file and include the License file + * at glassfish/bootstrap/legal/CDDLv1.0.txt. + * If applicable, add the following below the CDDL Header, + * with the fields enclosed by brackets [] replaced by + * you own identifying information: + * "Portions Copyrighted [year] [name of copyright owner]" + * + * Copyright 2006 Sun Microsystems, Inc. All rights reserved. + */ + +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 1.1 February 2, 2002 + * @author Mark Hapner + * @author Rich Burridge + * @author Kate Stout + * + * @see javax.jms.XASession + * @see javax.jms.TopicSession + */ + +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; +} |