/*

  * Copyright 1999-2004 The Apache Software Foundation.

  * 

  * Licensed under the Apache License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  * 

  *      http://www.apache.org/licenses/LICENSE-2.0

  * 

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.messenger;

 import java.io.Serializable;

 import javax.jms.BytesMessage;

 import javax.jms.Connection;

 import javax.jms.ConnectionConsumer;

 import javax.jms.Destination;

 import javax.jms.JMSException;

 import javax.jms.MapMessage;

 import javax.jms.Message;

 import javax.jms.MessageConsumer;

 import javax.jms.MessageListener;

 import javax.jms.ObjectMessage;

 import javax.jms.QueueBrowser;

 import javax.jms.ServerSessionPool;

 import javax.jms.Session;

 import javax.jms.StreamMessage;

 import javax.jms.TextMessage;

 /** <p><code>Messenger</code> a facade over the JMS API making it easy to use JMS

   * and hiding much of the complexity of threading and configuration.

   * A Messenger will internally associate a JMS Session with the calling thread

   * so that all methods called in the same thread (such as inside a Servlet or 

   * taglib) will use the same JMS Session.</p>

   *

   * @author <a href="mailto:jstrachan@apache.org">James Strachan</a>

   * @version $Revision: 155459 $

   */

 public interface Messenger {

     /** Temporary hack - this method has been added so that Messenger works better with the digester */

     public String getName();

     /** Returns the destination for the given subject name */

     public Destination getDestination(String subject) throws JMSException;

     /** Returns a new temporary destination */

     public Destination createTemporaryDestination() throws JMSException;

     /** Sends a message on the given destination */

     public void send(Destination destination, Message message) throws JMSException;

     /** Sends a message on the given destination and blocks until a response is returned */

     public Message call(Destination destination, Message message)

         throws JMSException;

     /** Sends a message on the given destination and blocks until a response is returned or the given timeout period expires */

     public Message call(

         Destination destination,

         Message message,

         long timeoutMillis)

         throws JMSException;

     /** Receives a message on the given destination, blocking until one is returned */

     public Message receive(Destination destination) throws JMSException;

     /** Receives a message on the given destination and message selector, blocking until one is returned */

     public Message receive(Destination destination, String selector)

         throws JMSException;

     /** Receives a message on the given destination, blocking for the specified timeout */

     public Message receive(Destination destination, long timeoutMillis)

         throws JMSException;

     /** Receives a message on the given destination and selector, blocking for the specified timeout */

     public Message receive(

         Destination destination,

         String selector,

         long timeoutMillis)

         throws JMSException;

     /** Receives a message on the given destination without blocking or returns null */

     public Message receiveNoWait(Destination destination) throws JMSException;

     /** Receives a message on the given destination and selector without blocking or returns null */

     public Message receiveNoWait(Destination destination, String selector)

         throws JMSException;

     /** Creates a MessageConsumer for the given JMS Desintation

      */

     public MessageConsumer createConsumer(Destination destination)

         throws JMSException;

     /** Creates a MessageConsumer for the given JMS Desintation and JMS selector

      */

     public MessageConsumer createConsumer(Destination destination, String selector)

         throws JMSException;

     /**

      * Creates a QueueBrowser for the given Queue

      */    

     public QueueBrowser createBrowser(Destination destination) throws JMSException;

     /** Allows this current thread to be given to the JMS connection to process messages. This

      * method can be useful for creating background processing threads

      */

     public void run();

     /** Returns the underlying JMS connection that this Messenger is using */

     public Connection getConnection() throws JMSException;

     /** 

      * Returns the underlying JMS session that this thread is using for

      * synchronous operations such as send() and receive() for synchronous operation

      */ 

     public Session getSession() throws JMSException;

     /** 

      * Returns the underlying JMS session that this thread is using for

      * this Messenger for asynchronous operation such as addMessageListener() operations

      */ 

     public Session getAsyncSession() throws JMSException;

     /** Creates a ConnectionConsumer which is useful if used inside an application server

      * to associate multiple threads with consuming from a JMS destination */

     public ConnectionConsumer createConnectionConsumer(

         Destination destination,

         ServerSessionPool sessionPool,

         int maxMessages)

         throws JMSException;

     /** Creates a ConnectionConsumer which is useful if used inside an application server

      * to associate multiple threads with consuming from a JMS destination */

     public ConnectionConsumer createConnectionConsumer(

         Destination destination,

         String selector,

         ServerSessionPool sessionPool,

         int maxMessages)

         throws JMSException;

     /** Creates a new ServerSessionPool implementation with a given maximum number of threads

      * for use by a ConnectionConsumer

      */

     public ServerSessionPool createServerSessionPool(

         MessageListener messageListener,

         int maxThreads)

         throws JMSException;

     // Listener API

     //-------------------------------------------------------------------------    

     /** Adds a message listener on the given destination */

     public void addListener(Destination destination, MessageListener listener)

         throws JMSException;

     public void addListener(

         Destination destination,

         String selector,

         MessageListener listener)

         throws JMSException;

     public void removeListener(Destination destination, MessageListener listener)

         throws JMSException;

     public void removeListener(

         Destination destination,

         String selector,

         MessageListener listener)

         throws JMSException;

     // Message factory methods

     //-------------------------------------------------------------------------    

     public BytesMessage createBytesMessage() throws JMSException;

     public MapMessage createMapMessage() throws JMSException;

     public Message createMessage() throws JMSException;

     public ObjectMessage createObjectMessage() throws JMSException;

     public ObjectMessage createObjectMessage(Serializable object)

         throws JMSException;

     public StreamMessage createStreamMessage() throws JMSException;

     public TextMessage createTextMessage() throws JMSException;

     public TextMessage createTextMessage(String text) throws JMSException;

     // Transaction related methods

     //-------------------------------------------------------------------------    

     /** Commits all messages done in this thread and releases any locks */

     public void commit() throws JMSException;

     /** Rolls back any messages done in this thread and releases any locks */

     public void rollback() throws JMSException;

     /** Closes the underlying JMS connection */

     public void close() throws JMSException;

     // Extra configuration methods available in JMS

     //-------------------------------------------------------------------------        

     /** 

      * Returns the SessionFactory used to create new JMS sessions 

      * and Connections. This allows things like transaction mode to be

      * configured before sessions are created. 

      */

     public SessionFactory getSessionFactory() throws JMSException;

     public int getDeliveryMode(Destination destination) throws JMSException;

     public boolean getDisableMessageID(Destination destination)

         throws JMSException;

     public boolean getDisableMessageTimestamp(Destination destination)

         throws JMSException;

     public int getPriority(Destination destination) throws JMSException;

     public long getTimeToLive(Destination destination) throws JMSException;

     public void setDeliveryMode(Destination destination, int deliveryMode)

         throws JMSException;

     public void setDisableMessageID(Destination destination, boolean value)

         throws JMSException;

     public void setDisableMessageTimestamp(Destination destination, boolean value)

         throws JMSException;

     public void setPriority(Destination destination, int defaultPriority)

         throws JMSException;

     public void setTimeToLive(Destination destination, long timeToLive)

         throws JMSException;

 }