001 /*
002 * Copyright 1999-2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.apache.commons.messenger;
017
018 import java.io.Serializable;
019
020 import javax.jms.BytesMessage;
021 import javax.jms.Connection;
022 import javax.jms.ConnectionConsumer;
023 import javax.jms.Destination;
024 import javax.jms.JMSException;
025 import javax.jms.MapMessage;
026 import javax.jms.Message;
027 import javax.jms.MessageConsumer;
028 import javax.jms.MessageListener;
029 import javax.jms.ObjectMessage;
030 import javax.jms.QueueBrowser;
031 import javax.jms.ServerSessionPool;
032 import javax.jms.Session;
033 import javax.jms.StreamMessage;
034 import javax.jms.TextMessage;
035
036 /** <p><code>Messenger</code> a facade over the JMS API making it easy to use JMS
037 * and hiding much of the complexity of threading and configuration.
038 * A Messenger will internally associate a JMS Session with the calling thread
039 * so that all methods called in the same thread (such as inside a Servlet or
040 * taglib) will use the same JMS Session.</p>
041 *
042 * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
043 * @version $Revision: 155459 $
044 */
045 public interface Messenger {
046
047 /** Temporary hack - this method has been added so that Messenger works better with the digester */
048 public String getName();
049
050 /** Returns the destination for the given subject name */
051 public Destination getDestination(String subject) throws JMSException;
052
053 /** Returns a new temporary destination */
054 public Destination createTemporaryDestination() throws JMSException;
055
056 /** Sends a message on the given destination */
057 public void send(Destination destination, Message message) throws JMSException;
058
059 /** Sends a message on the given destination and blocks until a response is returned */
060 public Message call(Destination destination, Message message)
061 throws JMSException;
062
063 /** Sends a message on the given destination and blocks until a response is returned or the given timeout period expires */
064 public Message call(
065 Destination destination,
066 Message message,
067 long timeoutMillis)
068 throws JMSException;
069
070 /** Receives a message on the given destination, blocking until one is returned */
071 public Message receive(Destination destination) throws JMSException;
072
073 /** Receives a message on the given destination and message selector, blocking until one is returned */
074 public Message receive(Destination destination, String selector)
075 throws JMSException;
076
077 /** Receives a message on the given destination, blocking for the specified timeout */
078 public Message receive(Destination destination, long timeoutMillis)
079 throws JMSException;
080
081 /** Receives a message on the given destination and selector, blocking for the specified timeout */
082 public Message receive(
083 Destination destination,
084 String selector,
085 long timeoutMillis)
086 throws JMSException;
087
088 /** Receives a message on the given destination without blocking or returns null */
089 public Message receiveNoWait(Destination destination) throws JMSException;
090
091 /** Receives a message on the given destination and selector without blocking or returns null */
092 public Message receiveNoWait(Destination destination, String selector)
093 throws JMSException;
094
095 /** Creates a MessageConsumer for the given JMS Desintation
096 */
097 public MessageConsumer createConsumer(Destination destination)
098 throws JMSException;
099
100 /** Creates a MessageConsumer for the given JMS Desintation and JMS selector
101 */
102 public MessageConsumer createConsumer(Destination destination, String selector)
103 throws JMSException;
104
105
106 /**
107 * Creates a QueueBrowser for the given Queue
108 */
109 public QueueBrowser createBrowser(Destination destination) throws JMSException;
110
111
112 /** Allows this current thread to be given to the JMS connection to process messages. This
113 * method can be useful for creating background processing threads
114 */
115 public void run();
116
117 /** Returns the underlying JMS connection that this Messenger is using */
118 public Connection getConnection() throws JMSException;
119
120 /**
121 * Returns the underlying JMS session that this thread is using for
122 * synchronous operations such as send() and receive() for synchronous operation
123 */
124 public Session getSession() throws JMSException;
125
126 /**
127 * Returns the underlying JMS session that this thread is using for
128 * this Messenger for asynchronous operation such as addMessageListener() operations
129 */
130 public Session getAsyncSession() throws JMSException;
131
132
133 /** Creates a ConnectionConsumer which is useful if used inside an application server
134 * to associate multiple threads with consuming from a JMS destination */
135 public ConnectionConsumer createConnectionConsumer(
136 Destination destination,
137 ServerSessionPool sessionPool,
138 int maxMessages)
139 throws JMSException;
140
141 /** Creates a ConnectionConsumer which is useful if used inside an application server
142 * to associate multiple threads with consuming from a JMS destination */
143 public ConnectionConsumer createConnectionConsumer(
144 Destination destination,
145 String selector,
146 ServerSessionPool sessionPool,
147 int maxMessages)
148 throws JMSException;
149
150 /** Creates a new ServerSessionPool implementation with a given maximum number of threads
151 * for use by a ConnectionConsumer
152 */
153 public ServerSessionPool createServerSessionPool(
154 MessageListener messageListener,
155 int maxThreads)
156 throws JMSException;
157
158 // Listener API
159 //-------------------------------------------------------------------------
160
161 /** Adds a message listener on the given destination */
162 public void addListener(Destination destination, MessageListener listener)
163 throws JMSException;
164
165 public void addListener(
166 Destination destination,
167 String selector,
168 MessageListener listener)
169 throws JMSException;
170
171 public void removeListener(Destination destination, MessageListener listener)
172 throws JMSException;
173
174 public void removeListener(
175 Destination destination,
176 String selector,
177 MessageListener listener)
178 throws JMSException;
179
180
181 // Message factory methods
182 //-------------------------------------------------------------------------
183
184 public BytesMessage createBytesMessage() throws JMSException;
185
186 public MapMessage createMapMessage() throws JMSException;
187
188 public Message createMessage() throws JMSException;
189
190 public ObjectMessage createObjectMessage() throws JMSException;
191
192 public ObjectMessage createObjectMessage(Serializable object)
193 throws JMSException;
194
195 public StreamMessage createStreamMessage() throws JMSException;
196
197 public TextMessage createTextMessage() throws JMSException;
198
199 public TextMessage createTextMessage(String text) throws JMSException;
200
201
202 // Transaction related methods
203 //-------------------------------------------------------------------------
204 /** Commits all messages done in this thread and releases any locks */
205 public void commit() throws JMSException;
206
207 /** Rolls back any messages done in this thread and releases any locks */
208 public void rollback() throws JMSException;
209
210 /** Closes the underlying JMS connection */
211 public void close() throws JMSException;
212
213
214 // Extra configuration methods available in JMS
215 //-------------------------------------------------------------------------
216
217 /**
218 * Returns the SessionFactory used to create new JMS sessions
219 * and Connections. This allows things like transaction mode to be
220 * configured before sessions are created.
221 */
222 public SessionFactory getSessionFactory() throws JMSException;
223
224
225 public int getDeliveryMode(Destination destination) throws JMSException;
226
227 public boolean getDisableMessageID(Destination destination)
228 throws JMSException;
229
230 public boolean getDisableMessageTimestamp(Destination destination)
231 throws JMSException;
232
233 public int getPriority(Destination destination) throws JMSException;
234
235 public long getTimeToLive(Destination destination) throws JMSException;
236
237 public void setDeliveryMode(Destination destination, int deliveryMode)
238 throws JMSException;
239
240 public void setDisableMessageID(Destination destination, boolean value)
241 throws JMSException;
242
243 public void setDisableMessageTimestamp(Destination destination, boolean value)
244 throws JMSException;
245
246 public void setPriority(Destination destination, int defaultPriority)
247 throws JMSException;
248
249 public void setTimeToLive(Destination destination, long timeToLive)
250 throws JMSException;
251 }