View Javadoc

1   /*
2    * Copyright 1999-2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  package org.apache.commons.messenger;
17  
18  import java.io.Serializable;
19  
20  import javax.jms.BytesMessage;
21  import javax.jms.Connection;
22  import javax.jms.ConnectionConsumer;
23  import javax.jms.Destination;
24  import javax.jms.JMSException;
25  import javax.jms.MapMessage;
26  import javax.jms.Message;
27  import javax.jms.MessageConsumer;
28  import javax.jms.MessageListener;
29  import javax.jms.ObjectMessage;
30  import javax.jms.QueueBrowser;
31  import javax.jms.ServerSessionPool;
32  import javax.jms.Session;
33  import javax.jms.StreamMessage;
34  import javax.jms.TextMessage;
35  
36  /** <p><code>Messenger</code> a facade over the JMS API making it easy to use JMS
37    * and hiding much of the complexity of threading and configuration.
38    * A Messenger will internally associate a JMS Session with the calling thread
39    * so that all methods called in the same thread (such as inside a Servlet or 
40    * taglib) will use the same JMS Session.</p>
41    *
42    * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>
43    * @version $Revision: 155459 $
44    */
45  public interface Messenger {
46  
47      /** Temporary hack - this method has been added so that Messenger works better with the digester */
48      public String getName();
49  
50      /** Returns the destination for the given subject name */
51      public Destination getDestination(String subject) throws JMSException;
52  
53      /** Returns a new temporary destination */
54      public Destination createTemporaryDestination() throws JMSException;
55  
56      /** Sends a message on the given destination */
57      public void send(Destination destination, Message message) throws JMSException;
58  
59      /** Sends a message on the given destination and blocks until a response is returned */
60      public Message call(Destination destination, Message message)
61          throws JMSException;
62  
63      /** Sends a message on the given destination and blocks until a response is returned or the given timeout period expires */
64      public Message call(
65          Destination destination,
66          Message message,
67          long timeoutMillis)
68          throws JMSException;
69  
70      /** Receives a message on the given destination, blocking until one is returned */
71      public Message receive(Destination destination) throws JMSException;
72  
73      /** Receives a message on the given destination and message selector, blocking until one is returned */
74      public Message receive(Destination destination, String selector)
75          throws JMSException;
76  
77      /** Receives a message on the given destination, blocking for the specified timeout */
78      public Message receive(Destination destination, long timeoutMillis)
79          throws JMSException;
80  
81      /** Receives a message on the given destination and selector, blocking for the specified timeout */
82      public Message receive(
83          Destination destination,
84          String selector,
85          long timeoutMillis)
86          throws JMSException;
87  
88      /** Receives a message on the given destination without blocking or returns null */
89      public Message receiveNoWait(Destination destination) throws JMSException;
90  
91      /** Receives a message on the given destination and selector without blocking or returns null */
92      public Message receiveNoWait(Destination destination, String selector)
93          throws JMSException;
94  
95      /** Creates a MessageConsumer for the given JMS Desintation
96       */
97      public MessageConsumer createConsumer(Destination destination)
98          throws JMSException;
99  
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 }