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.Destination;
021    import javax.jms.JMSException;
022    import javax.jms.Message;
023    import javax.jms.Session;
024    
025    /**
026     * Represents a JMS based requestor which is capable of performing various
027     * Message Exchange Patterns such as one-way, synchronous request-response,
028     * receive etc.
029     *
030     * @version $Revision: 1.1 $
031     */
032    public interface Requestor {
033    
034        /**
035         * Sends a one way message, not waiting for the response.
036         *
037         * @param destination the server side destination
038         * @param message     the message to send
039         */
040        void oneWay(Destination destination, Message message) throws JMSException;
041    
042        /**
043         * Sends a request and waits for a reply. The temporary queue is used for
044         * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
045         * is expected.
046         *
047         * @param destination the server side destination
048         * @param message     the message to send
049         * @return the reply message
050         * @throws javax.jms.JMSException if the JMS provider fails to complete the
051         *                                request due to some internal error.
052         */
053        Message request(Destination destination, Message message) throws JMSException;
054    
055        /**
056         * Sends a request and waits for a reply up to a maximum timeout. The temporary queue is used for
057         * the <CODE>JMSReplyTo</CODE> destination, and only one reply per request
058         * is expected.
059         *
060         * @param destination the server side destination
061         * @param message     the message to send
062         * @return the reply message
063         * @throws javax.jms.JMSException if the JMS provider fails to complete the
064         *                                request due to some internal error.
065         */
066        Message request(Destination destination, Message message, long timeout) throws JMSException;
067    
068        /**
069         * Receives a message waiting for a maximum timeout if the timeout value
070         * is > 0 ir waiting forever if the timeout is < 0 or not waiting at all
071         * if the timeout is zero
072         */
073        Message receive(long timeout) throws JMSException;
074    
075        /**
076         * Provides access to the underlying JMS session so that you can
077         * create messages.
078         */
079        Session getSession();
080    
081        /**
082         * Closes the <CODE>Requestor</CODE> and its session.
083         * <p/>
084         * <P>Since a provider may allocate some resources on behalf of a
085         * <CODE>Requestor</CODE> outside the Java virtual machine, clients
086         * should close them when they
087         * are not needed. Relying on garbage collection to eventually reclaim
088         * these resources may not be timely enough.
089         * <p/>
090         * <P>Note that this method closes the <CODE>Session</CODE> object
091         * passed to the <CODE>Requestor</CODE> constructor.
092         *
093         * @throws javax.jms.JMSException if the JMS provider fails to close the
094         *                                <CODE>Requestor</CODE> due to some internal
095         *                                error.
096         */
097        void close() throws JMSException;
098    
099        /**
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    }