1 /*
2 * JBoss, Home of Professional Open Source
3 * Copyright 2005, JBoss Inc., and individual contributors as indicated
4 * by the @authors tag. See the copyright.txt in the distribution for a
5 * full listing of individual contributors.
6 *
7 * This is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU Lesser General Public License as
9 * published by the Free Software Foundation; either version 2.1 of
10 * the License, or (at your option) any later version.
11 *
12 * This software is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this software; if not, write to the Free
19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21 */
22 package javax.jms;
23
24 /** A <CODE>QueueSession</CODE> object provides methods for creating
25 * <CODE>QueueReceiver</CODE>, <CODE>QueueSender</CODE>,
26 * <CODE>QueueBrowser</CODE>, and <CODE>TemporaryQueue</CODE> objects.
27 *
28 * <P>If there are messages that have been received but not acknowledged
29 * when a <CODE>QueueSession</CODE> terminates, these messages will be retained
30 * and redelivered when a consumer next accesses the queue.
31 *
32 *<P>A <CODE>QueueSession</CODE> is used for creating Point-to-Point specific
33 * objects. In general, use the <CODE>Session</CODE> object.
34 * The <CODE>QueueSession</CODE> is used to support
35 * existing code. Using the <CODE>Session</CODE> object simplifies the
36 * programming model, and allows transactions to be used across the two
37 * messaging domains.
38 *
39 * <P>A <CODE>QueueSession</CODE> cannot be used to create objects specific to the
40 * publish/subscribe domain. The following methods inherit from
41 * <CODE>Session</CODE>, but must throw an
42 * <CODE>IllegalStateException</CODE>
43 * if they are used from <CODE>QueueSession</CODE>:
44 *<UL>
45 * <LI><CODE>createDurableSubscriber</CODE>
46 * <LI><CODE>createTemporaryTopic</CODE>
47 * <LI><CODE>createTopic</CODE>
48 * <LI><CODE>unsubscribe</CODE>
49 * </UL>
50 *
51 * @see javax.jms.Session
52 * @see javax.jms.QueueConnection#createQueueSession(boolean, int)
53 * @see javax.jms.XAQueueSession#getQueueSession()
54 */
55
56 public interface QueueSession extends Session
57 {
58
59 /** Creates a queue identity given a <CODE>Queue</CODE> name.
60 *
61 * <P>This facility is provided for the rare cases where clients need to
62 * dynamically manipulate queue identity. It allows the creation of a
63 * queue identity with a provider-specific name. Clients that depend
64 * on this ability are not portable.
65 *
66 * <P>Note that this method is not for creating the physical queue.
67 * The physical creation of queues is an administrative task and is not
68 * to be initiated by the JMS API. The one exception is the
69 * creation of temporary queues, which is accomplished with the
70 * <CODE>createTemporaryQueue</CODE> method.
71 *
72 * @param queueName the name of this <CODE>Queue</CODE>
73 *
74 * @return a <CODE>Queue</CODE> with the given name
75 *
76 * @exception JMSException if the session fails to create a queue
77 * due to some internal error.
78 */
79
80 Queue createQueue(String queueName) throws JMSException;
81
82 /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
83 * specified queue.
84 *
85 * @param queue the <CODE>Queue</CODE> to access
86 *
87 * @exception JMSException if the session fails to create a receiver
88 * due to some internal error.
89 * @exception InvalidDestinationException if an invalid queue is specified.
90 */
91
92 QueueReceiver createReceiver(Queue queue) throws JMSException;
93
94 /** Creates a <CODE>QueueReceiver</CODE> object to receive messages from the
95 * specified queue using a message selector.
96 *
97 * @param queue the <CODE>Queue</CODE> to access
98 * @param messageSelector only messages with properties matching the
99 * message selector expression are delivered. A value of null or
100 * an empty string indicates that there is no message selector
101 * for the message consumer.
102 *
103 * @exception JMSException if the session fails to create a receiver
104 * due to some internal error.
105 * @exception InvalidDestinationException if an invalid queue is specified.
106 * @exception InvalidSelectorException if the message selector is invalid.
107 *
108 */
109
110 QueueReceiver createReceiver(Queue queue, String messageSelector) 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) throws JMSException;
153
154 /** Creates a <CODE>TemporaryQueue</CODE> object. Its lifetime will be that
155 * of the <CODE>QueueConnection</CODE> unless it is deleted earlier.
156 *
157 * @return a temporary queue identity
158 *
159 * @exception JMSException if the session fails to create a temporary queue
160 * due to some internal error.
161 */
162
163 TemporaryQueue createTemporaryQueue() throws JMSException;
164 }