001 /**
002 *
003 * Copyright 2005 LogicBlaze, Inc.
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 *
017 **/
018 package org.logicblaze.lingo.jms;
019
020 import javax.jms.Connection;
021 import javax.jms.Destination;
022 import javax.jms.JMSException;
023 import javax.jms.Message;
024 import javax.jms.MessageProducer;
025 import javax.jms.Session;
026
027 /**
028 * Represents a JMS based requestor which is capable of performing various
029 * Message Exchange Patterns such as one-way, synchronous request-response,
030 * receive etc.
031 *
032 * @version $Revision: 1.6 $
033 */
034 public interface Requestor {
035
036 /**
037 * Sends a one way message, not waiting for the response.
038 *
039 * @param destination
040 * the server side destination
041 * @param message
042 * the message to send
043 */
044 void send(Destination destination, Message message) throws JMSException;
045
046 /**
047 * Sends a message to the given destination in a way that can be implemented
048 * in JMS 1.0.2b as well as using the JMS 1.1 send() method on
049 * {@link MessageProducer}
050 *
051 * @throws JMSException
052 * if the message could not be sent
053 */
054 public void send(Destination destination, Message message, int deliveryMode, int priority, long timeToLive) throws JMSException;
055
056 /**
057 * Sends a request and waits for a reply. The temporary queue is used for
058 * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
059 * is expected.
060 *
061 * @param destination
062 * the server side destination
063 * @param message
064 * the message to send
065 * @return the reply message
066 * @throws javax.jms.JMSException
067 * if the JMS provider fails to complete the request due to some
068 * internal error.
069 */
070 Message request(Destination destination, Message message) throws JMSException;
071
072 /**
073 * Sends a request and waits for a reply up to a maximum timeout. The
074 * temporary queue is used for the <CODE>JMSReplyTo</CODE> destination,
075 * and only one reply per request is expected.
076 *
077 * @param destination
078 * the server side destination
079 * @param message
080 * the message to send
081 * @return the reply message
082 * @throws javax.jms.JMSException
083 * if the JMS provider fails to complete the request due to some
084 * internal error.
085 */
086 Message request(Destination destination, Message message, long timeout) throws JMSException;
087
088 /**
089 * Receives a message waiting for a maximum timeout if the timeout value is >
090 * 0 ir waiting forever if the timeout is < 0 or not waiting at all if the
091 * timeout is zero
092 */
093 Message receive(long timeout) throws JMSException;
094
095 /**
096 * Sends a request and provides a handler for all responses until the
097 * request is considered dead (or it is timed out).
098 */
099 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 }