001: /*
002: * @(#)QueueSession.java 1.26 02/04/09
003: *
004: * Copyright 1997-2002 Sun Microsystems, Inc. All Rights Reserved.
005: *
006: * SUN PROPRIETARY/CONFIDENTIAL.
007: * This software is the proprietary information of Sun Microsystems, Inc.
008: * Use is subject to license terms.
009: *
010: */
011:
012: package javax.jms;
013:
014: /** A <CODE>QueueSession</CODE> object provides methods for creating
015: * <CODE>QueueReceiver</CODE>, <CODE>QueueSender</CODE>,
016: * <CODE>QueueBrowser</CODE>, and <CODE>TemporaryQueue</CODE> objects.
017: *
018: * <P>If there are messages that have been received but not acknowledged
019: * when a <CODE>QueueSession</CODE> terminates, these messages will be retained
020: * and redelivered when a consumer next accesses the queue.
021: *
022: *<P>A <CODE>QueueSession</CODE> is used for creating Point-to-Point specific
023: * objects. In general, use the <CODE>Session</CODE> object.
024: * The <CODE>QueueSession</CODE> is used to support
025: * existing code. Using the <CODE>Session</CODE> object simplifies the
026: * programming model, and allows transactions to be used across the two
027: * messaging domains.
028: *
029: * <P>A <CODE>QueueSession</CODE> cannot be used to create objects specific to the
030: * publish/subscribe domain. The following methods inherit from
031: * <CODE>Session</CODE>, but must throw an
032: * <CODE>IllegalStateException</CODE>
033: * if they are used from <CODE>QueueSession</CODE>:
034: *<UL>
035: * <LI><CODE>createDurableSubscriber</CODE>
036: * <LI><CODE>createTemporaryTopic</CODE>
037: * <LI><CODE>createTopic</CODE>
038: * <LI><CODE>unsubscribe</CODE>
039: * </UL>
040: *
041: * @version 1.1 - April 2, 2002
042: * @author Mark Hapner
043: * @author Rich Burridge
044: * @author Kate Stout
045: *
046: * @see javax.jms.Session
047: * @see javax.jms.QueueConnection#createQueueSession(boolean, int)
048: * @see javax.jms.XAQueueSession#getQueueSession()
049: */
050:
051: public interface QueueSession extends Session {
052:
053: /** Creates a queue identity given a <CODE>Queue</CODE> name.
054: *
055: * <P>This facility is provided for the rare cases where clients need to
056: * dynamically manipulate queue identity. It allows the creation of a
057: * queue identity with a provider-specific name. Clients that depend
058: * on this ability are not portable.
059: *
060: * <P>Note that this method is not for creating the physical queue.
061: * The physical creation of queues is an administrative task and is not
062: * to be initiated by the JMS API. The one exception is the
063: * creation of temporary queues, which is accomplished with the
064: * <CODE>createTemporaryQueue</CODE> method.
065: *
066: * @param queueName the name of this <CODE>Queue</CODE>
067: *
068: * @return a <CODE>Queue</CODE> with the given name
069: *
070: * @exception JMSException if the session fails to create a queue
071: * due to some internal error.
072: */
073:
074: Queue createQueue(String queueName) throws JMSException;
075:
076: /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
077: * specified queue.
078: *
079: * @param queue the <CODE>Queue</CODE> to access
080: *
081: * @exception JMSException if the session fails to create a receiver
082: * due to some internal error.
083: * @exception InvalidDestinationException if an invalid queue is specified.
084: */
085:
086: QueueReceiver createReceiver(Queue queue) throws JMSException;
087:
088: /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
089: * specified queue using a message selector.
090: *
091: * @param queue the <CODE>Queue</CODE> to access
092: * @param messageSelector only messages with properties matching the
093: * message selector expression are delivered. A value of null or
094: * an empty string indicates that there is no message selector
095: * for the message consumer.
096: *
097: * @exception JMSException if the session fails to create a receiver
098: * due to some internal error.
099: * @exception InvalidDestinationException if an invalid queue is specified.
100: * @exception InvalidSelectorException if the message selector is invalid.
101: *
102: */
103:
104: QueueReceiver createReceiver(Queue queue, String messageSelector)
105: throws JMSException;
106:
107: /** Creates a <CODE>QueueSender</CODE> object to send messages to the
108: * specified queue.
109: *
110: * @param queue the <CODE>Queue</CODE> to access, or null if this is an
111: * unidentified producer
112: *
113: * @exception JMSException if the session fails to create a sender
114: * due to some internal error.
115: * @exception InvalidDestinationException if an invalid queue is specified.
116: */
117:
118: QueueSender createSender(Queue queue) throws JMSException;
119:
120: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
121: * the specified queue.
122: *
123: * @param queue the <CODE>Queue</CODE> to access
124: *
125: * @exception JMSException if the session fails to create a browser
126: * due to some internal error.
127: * @exception InvalidDestinationException if an invalid queue is specified.
128: */
129:
130: QueueBrowser createBrowser(Queue queue) throws JMSException;
131:
132: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
133: * the specified queue using a message selector.
134: *
135: * @param queue the <CODE>Queue</CODE> to access
136: * @param messageSelector only messages with properties matching the
137: * message selector expression are delivered. A value of null or
138: * an empty string indicates that there is no message selector
139: * for the message consumer.
140: *
141: * @exception JMSException if the session fails to create a browser
142: * due to some internal error.
143: * @exception InvalidDestinationException if an invalid queue is specified.
144: * @exception InvalidSelectorException if the message selector is invalid.
145: */
146:
147: QueueBrowser createBrowser(Queue queue, String messageSelector)
148: throws JMSException;
149:
150: /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that
151: * of the <CODE>QueueConnection</CODE> unless it is deleted earlier.
152: *
153: * @return a temporary queue identity
154: *
155: * @exception JMSException if the session fails to create a temporary queue
156: * due to some internal error.
157: */
158:
159: TemporaryQueue createTemporaryQueue() throws JMSException;
160: }
|