View Javadoc

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.Destination;
21  import javax.jms.JMSException;
22  import javax.jms.Message;
23  import javax.jms.Session;
24  
25  /***
26   * Represents a JMS based requestor which is capable of performing various
27   * Message Exchange Patterns such as one-way, synchronous request-response,
28   * receive etc.
29   *
30   * @version $Revision: 1.1 $
31   */
32  public interface Requestor {
33  
34      /***
35       * Sends a one way message, not waiting for the response.
36       *
37       * @param destination the server side destination
38       * @param message     the message to send
39       */
40      void oneWay(Destination destination, Message message) throws JMSException;
41  
42      /***
43       * Sends a request and waits for a reply. The temporary queue is used for
44       * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
45       * is expected.
46       *
47       * @param destination the server side destination
48       * @param message     the message to send
49       * @return the reply message
50       * @throws javax.jms.JMSException if the JMS provider fails to complete the
51       *                                request due to some internal error.
52       */
53      Message request(Destination destination, Message message) throws JMSException;
54  
55      /***
56       * Sends a request and waits for a reply up to a maximum timeout. The temporary queue is used for
57       * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
58       * is expected.
59       *
60       * @param destination the server side destination
61       * @param message     the message to send
62       * @return the reply message
63       * @throws javax.jms.JMSException if the JMS provider fails to complete the
64       *                                request due to some internal error.
65       */
66      Message request(Destination destination, Message message, long timeout) throws JMSException;
67  
68      /***
69       * Receives a message waiting for a maximum timeout if the timeout value
70       * is > 0 ir waiting forever if the timeout is < 0 or not waiting at all
71       * if the timeout is zero
72       */
73      Message receive(long timeout) throws JMSException;
74  
75      /***
76       * Provides access to the underlying JMS session so that you can
77       * create messages.
78       */
79      Session getSession();
80  
81      /***
82       * Closes the <CODE>Requestor</CODE> and its session.
83       * <p/>
84       * <P>Since a provider may allocate some resources on behalf of a
85       * <CODE>Requestor</CODE> outside the Java virtual machine, clients
86       * should close them when they
87       * are not needed. Relying on garbage collection to eventually reclaim
88       * these resources may not be timely enough.
89       * <p/>
90       * <P>Note that this method closes the <CODE>Session</CODE> object
91       * passed to the <CODE>Requestor</CODE> constructor.
92       *
93       * @throws javax.jms.JMSException if the JMS provider fails to close the
94       *                                <CODE>Requestor</CODE> due to some internal
95       *                                error.
96       */
97      void close() throws JMSException;
98  
99      /***
100      * Creates a new correlation ID. Note that because the correlationID is used
101      * on a per-temporary destination basis, it does not need to be unique across
102      * more than one destination. So a simple counter will suffice.
103      *
104      * @return
105      */
106     String createCorrelationID();
107 }