1 /***
2 *
3 * Copyright 2005 LogicBlaze, Inc.
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 *
17 **/
18 package org.logicblaze.lingo.jms;
19
20 import javax.jms.Connection;
21 import javax.jms.Destination;
22 import javax.jms.JMSException;
23 import javax.jms.Message;
24 import javax.jms.MessageProducer;
25 import javax.jms.Session;
26
27 /***
28 * Represents a JMS based requestor which is capable of performing various
29 * Message Exchange Patterns such as one-way, synchronous request-response,
30 * receive etc.
31 *
32 * @version $Revision: 1.6 $
33 */
34 public interface Requestor {
35
36 /***
37 * Sends a one way message, not waiting for the response.
38 *
39 * @param destination
40 * the server side destination
41 * @param message
42 * the message to send
43 */
44 void send(Destination destination, Message message) throws JMSException;
45
46 /***
47 * Sends a message to the given destination in a way that can be implemented
48 * in JMS 1.0.2b as well as using the JMS 1.1 send() method on
49 * {@link MessageProducer}
50 *
51 * @throws JMSException
52 * if the message could not be sent
53 */
54 public void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
55
56 /***
57 * Sends a request and waits for a reply. The temporary queue is used for
58 * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
59 * is expected.
60 *
61 * @param destination
62 * the server side destination
63 * @param message
64 * the message to send
65 * @return the reply message
66 * @throws javax.jms.JMSException
67 * if the JMS provider fails to complete the request due to some
68 * internal error.
69 */
70 Message request(Destination destination, Message message) throws JMSException;
71
72 /***
73 * Sends a request and waits for a reply up to a maximum timeout. The
74 * temporary queue is used for the <CODE>JMSReplyTo</CODE> destination,
75 * and only one reply per request is expected.
76 *
77 * @param destination
78 * the server side destination
79 * @param message
80 * the message to send
81 * @return the reply message
82 * @throws javax.jms.JMSException
83 * if the JMS provider fails to complete the request due to some
84 * internal error.
85 */
86 Message request(Destination destination, Message message, long timeout) throws JMSException;
87
88 /***
89 * Receives a message waiting for a maximum timeout if the timeout value is >
90 * 0 ir waiting forever if the timeout is < 0 or not waiting at all if the
91 * timeout is zero
92 */
93 Message receive(long timeout) throws JMSException;
94
95 /***
96 * Sends a request and provides a handler for all responses until the
97 * request is considered dead (or it is timed out).
98 */
99 void request(Destination destination, Message requestMessage, ReplyHandler handler, long timeout) throws JMSException;
100
101 /***
102 * Returns the underying producer
103 */
104 public MessageProducer getMessageProducer();
105
106 /***
107 * Provides access to the underlying Connection this requestor is using
108 */
109 Connection getConnection();
110
111 /***
112 * Provides access to the underlying JMS session so that you can create
113 * messages.
114 */
115 Session getSession();
116
117 /***
118 * Closes the <CODE>Requestor</CODE> and its session. <p/>
119 * <P>
120 * Since a provider may allocate some resources on behalf of a <CODE>Requestor</CODE>
121 * outside the Java virtual machine, clients should close them when they are
122 * not needed. Relying on garbage collection to eventually reclaim these
123 * resources may not be timely enough. <p/>
124 * <P>
125 * Note that this method closes the <CODE>Session</CODE> object passed to
126 * the <CODE>Requestor</CODE> constructor.
127 *
128 * @throws javax.jms.JMSException
129 * if the JMS provider fails to close the <CODE>Requestor</CODE>
130 * due to some internal error.
131 */
132 void close() throws JMSException;
133
134 /***
135 * Creates a new correlation ID. Note that because the correlationID is used
136 * on a per-temporary destination basis, it does not need to be unique
137 * across more than one destination. So a simple counter will suffice.
138 *
139 * @return
140 */
141 String createCorrelationID();
142 }