001: /*
002: * JBoss, Home of Professional Open Source.
003: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
004: * as indicated by the @author tags. See the copyright.txt file in the
005: * distribution for a full listing of individual contributors.
006: *
007: * This is free software; you can redistribute it and/or modify it
008: * under the terms of the GNU Lesser General Public License as
009: * published by the Free Software Foundation; either version 2.1 of
010: * the License, or (at your option) any later version.
011: *
012: * This software is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this software; if not, write to the Free
019: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
021: */
022: package javax.jms;
023:
024: /** A <CODE>QueueSession</CODE> object provides methods for creating
025: * <CODE>QueueReceiver</CODE>, <CODE>QueueSender</CODE>,
026: * <CODE>QueueBrowser</CODE>, and <CODE>TemporaryQueue</CODE> objects.
027: *
028: * <P>If there are messages that have been received but not acknowledged
029: * when a <CODE>QueueSession</CODE> terminates, these messages will be retained
030: * and redelivered when a consumer next accesses the queue.
031: *
032: *<P>A <CODE>QueueSession</CODE> is used for creating Point-to-Point specific
033: * objects. In general, use the <CODE>Session</CODE> object.
034: * The <CODE>QueueSession</CODE> is used to support
035: * existing code. Using the <CODE>Session</CODE> object simplifies the
036: * programming model, and allows transactions to be used across the two
037: * messaging domains.
038: *
039: * <P>A <CODE>QueueSession</CODE> cannot be used to create objects specific to the
040: * publish/subscribe domain. The following methods inherit from
041: * <CODE>Session</CODE>, but must throw an
042: * <CODE>IllegalStateException</CODE>
043: * if they are used from <CODE>QueueSession</CODE>:
044: *<UL>
045: * <LI><CODE>createDurableSubscriber</CODE>
046: * <LI><CODE>createTemporaryTopic</CODE>
047: * <LI><CODE>createTopic</CODE>
048: * <LI><CODE>unsubscribe</CODE>
049: * </UL>
050: *
051: * @see javax.jms.Session
052: * @see javax.jms.QueueConnection#createQueueSession(boolean, int)
053: * @see javax.jms.XAQueueSession#getQueueSession()
054: */
055:
056: public interface QueueSession extends Session {
057:
058: /** Creates a queue identity given a <CODE>Queue</CODE> name.
059: *
060: * <P>This facility is provided for the rare cases where clients need to
061: * dynamically manipulate queue identity. It allows the creation of a
062: * queue identity with a provider-specific name. Clients that depend
063: * on this ability are not portable.
064: *
065: * <P>Note that this method is not for creating the physical queue.
066: * The physical creation of queues is an administrative task and is not
067: * to be initiated by the JMS API. The one exception is the
068: * creation of temporary queues, which is accomplished with the
069: * <CODE>createTemporaryQueue</CODE> method.
070: *
071: * @param queueName the name of this <CODE>Queue</CODE>
072: *
073: * @return a <CODE>Queue</CODE> with the given name
074: *
075: * @exception JMSException if the session fails to create a queue
076: * due to some internal error.
077: */
078:
079: Queue createQueue(String queueName) throws JMSException;
080:
081: /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
082: * specified queue.
083: *
084: * @param queue the <CODE>Queue</CODE> to access
085: *
086: * @exception JMSException if the session fails to create a receiver
087: * due to some internal error.
088: * @exception InvalidDestinationException if an invalid queue is specified.
089: */
090:
091: QueueReceiver createReceiver(Queue queue) throws JMSException;
092:
093: /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
094: * specified queue using a message selector.
095: *
096: * @param queue the <CODE>Queue</CODE> to access
097: * @param messageSelector only messages with properties matching the
098: * message selector expression are delivered. A value of null or
099: * an empty string indicates that there is no message selector
100: * for the message consumer.
101: *
102: * @exception JMSException if the session fails to create a receiver
103: * due to some internal error.
104: * @exception InvalidDestinationException if an invalid queue is specified.
105: * @exception InvalidSelectorException if the message selector is invalid.
106: *
107: */
108:
109: QueueReceiver createReceiver(Queue queue, String messageSelector)
110: throws JMSException;
111:
112: /** Creates a <CODE>QueueSender</CODE> object to send messages to the
113: * specified queue.
114: *
115: * @param queue the <CODE>Queue</CODE> to access, or null if this is an
116: * unidentified producer
117: *
118: * @exception JMSException if the session fails to create a sender
119: * due to some internal error.
120: * @exception InvalidDestinationException if an invalid queue is specified.
121: */
122:
123: QueueSender createSender(Queue queue) throws JMSException;
124:
125: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
126: * the specified queue.
127: *
128: * @param queue the <CODE>Queue</CODE> to access
129: *
130: * @exception JMSException if the session fails to create a browser
131: * due to some internal error.
132: * @exception InvalidDestinationException if an invalid queue is specified.
133: */
134:
135: QueueBrowser createBrowser(Queue queue) throws JMSException;
136:
137: /** Creates a <CODE>QueueBrowser</CODE> object to peek at the messages on
138: * the specified queue using a message selector.
139: *
140: * @param queue the <CODE>Queue</CODE> to access
141: * @param messageSelector only messages with properties matching the
142: * message selector expression are delivered. A value of null or
143: * an empty string indicates that there is no message selector
144: * for the message consumer.
145: *
146: * @exception JMSException if the session fails to create a browser
147: * due to some internal error.
148: * @exception InvalidDestinationException if an invalid queue is specified.
149: * @exception InvalidSelectorException if the message selector is invalid.
150: */
151:
152: QueueBrowser createBrowser(Queue queue, String messageSelector)
153: throws JMSException;
154:
155: /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that
156: * of the <CODE>QueueConnection</CODE> unless it is deleted earlier.
157: *
158: * @return a temporary queue identity
159: *
160: * @exception JMSException if the session fails to create a temporary queue
161: * due to some internal error.
162: */
163:
164: TemporaryQueue createTemporaryQueue() throws JMSException;
165: }
|