javax.jbi.messaging.DeliveryChannel Maven / Gradle / Ivy
Show all versions of petals-jbi Show documentation
/**
* @(#) DeliveryChannel.java
*
* PETALS - PETALS Services Platform.
* Copyright (c) 2005 Fossil E-Commerce, http://www.fossilec.com/
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* -------------------------------------------------------------------------
* $Id: DeliveryChannel.java 221 2006-04-14 12:45:33Z alouis $
* -------------------------------------------------------------------------
*/
//
// This source code implements specifications defined by the Java
// Community Process. In order to remain compliant with the specification
// DO NOT add / change / or delete method signatures!
//
package javax.jbi.messaging;
/**
* Bi-directional communication channel used by engines and bindings (hereafter
* called JBI components) to interact with the Normalized Message Router. Each
* JBI component has one DeliveryChannel associated with it.
* Using the delivery channel, a component may:
*
* - Receive message exchanges routed to the component (optionally, with a
* time-out).
*
- Send a message asynchronously (that is, without waiting for a response
* or status change acknowledging that the exchange was received).
*
- Send a message synchronously, blocking the thread of execution until
* the result is received. Optionally, this can be done with a time-out.
*
*
* @author JSR208 Expert Group
*/
public interface DeliveryChannel {
/**
* TODO accept check multi thread
* Blocking call used to service a MessageExchange instance which has been
* initiated by another component. This method supports concurrent
* invocation for multi-threaded environments. This must be interruptable
* (Thread.interrupt()).
*
* @return message exchange instance; must be non-null
* @throws MessagingException
* failed to accept
* @throws MessagingException
* when the blocked thread is interrupted
*/
public javax.jbi.messaging.MessageExchange accept()
throws MessagingException;
/**
* TODO accept check multi thread
* Blocking call used to service a MessageExchange instance which has been
* initiated by another component, within the given timeout period. This
* method supports concurrent invocation for multi-threaded environments.
*
* @param timeoutMS
* timeout period, in milliseconds (0 means no timeout); must be
* greater than or equal to zero
* @return message exchange instance, or null if timed out
* @throws java.lang.IllegalArgumentException
* if timeoutMS < 0
* @throws MessagingException
* failed to accept
* @throws MessagingException
* when the blocked thread is interrupted
*/
public javax.jbi.messaging.MessageExchange accept(long timeoutMS)
throws MessagingException, IllegalArgumentException;
/**
* TODO close pending messages, remove endpoint entries ?
* Closes the delivery channel, halting all message traffic.
*
* @throws MessagingException
* fatal error while closing channel
*/
public void close() throws MessagingException;
/**
* Create a message exchange factory. This factory will create exchange
* instances with all appropriate properties set to null.
*
* @return a message exchange factory; must be non-null
*/
public javax.jbi.messaging.MessageExchangeFactory createExchangeFactory();
/**
* Create a message exchange factory for the given interface name.
*
* @param interfaceName
* name of the interface for which all exchanges created by the
* returned factory will be set for; may be null
* @return an exchange factory that will create exchanges for the the given
* interface; must be non-null
*/
public javax.jbi.messaging.MessageExchangeFactory createExchangeFactory(
javax.xml.namespace.QName interfaceName);
/**
* Create a message exchange factory for the given endpoint.
*
* @param endpoint
* endpoint for which all exchanges created by the returned
* factory will be set for; may be null
* @return an exchange factory that will create exchanges for the given
* endpoint; must be non-null
*/
public javax.jbi.messaging.MessageExchangeFactory createExchangeFactory(
javax.jbi.servicedesc.ServiceEndpoint endpoint);
/**
* Create a message exchange factory for the given service name.
*
* @param serviceName
* name of the service for which all exchanges created by the
* returned factory will be set for; may be null
* @return an exchange factory that will create exchanges for the the given
* service; must be non-null
*/
public javax.jbi.messaging.MessageExchangeFactory createExchangeFactoryForService(
javax.xml.namespace.QName serviceName);
/**
* TODO send resolve jbi logical endpoint
* Routes a MessageExchange instance through the Normalized Message Router
* to the appropriate servicing component. This method supports concurrent
* invocation for multi-threaded environments.
*
* This is used not only to send the initial message in an exchange, but
* also for the servicer to "return" the exchange with the appropriate
* response (response, fault, or ExchangeStatus). In more
* complex message exchange patterns, a single MessageExchange
* can be sent back-and-forth via send() several times, but
* always terminating with the MessageExchange instance being sent with a
* terminal ExchangeStatus.
*
* @param exchange
* message exchange to send; must be non-null
* @throws MessagingException
* unable to send exchange
*/
public void send(javax.jbi.messaging.MessageExchange exchange)
throws MessagingException;
/**
* TODO sendSync check multithread
* Routes a MessageExchange instance through the Normalized Message Router
* to the appropriate servicing component, and blocks until the exchange is
* returned (that is, the other participant sends the message exchange
* back). This method supports concurrent invocation for multi-threaded
* environments.
*
* If the thread making this call is interrupted, the message exchange is
* treated in the same fashion as a timed-out sendSync call; see
* {@link DeliveryChannel#sendSync(MessageExchange, long)}.
*
* Note that the "returned" message exchange (the instance returned by the
* other participant in the exchange) is the same instance referred to by
* the parameter exchange.
*
* @param exchange
* message exchange to send; must be non-null
* @return true if the exchange has been returned (always)
* @throws MessagingException
* unable to send exchange, or no response is expected from the
* send() operation (i.e., the
* MessageExchange is being used to convey an
* ExchangeStatus)
* @throws MessagingException
* when the blocked thread is interrupted
*/
public boolean sendSync(javax.jbi.messaging.MessageExchange exchange)
throws MessagingException;
/**
* TODO sendSync check multithread
* Routes a MessageExchange instance through the Normalized Message Router
* to the appropriate servicing component, and blocks until the exchange is
* returned (that is, the other participant sends the message exchange
* back), or the specified timeout interval elapses. This method supports
* concurrent invocation for multi-threaded environments.
*
* If the thread making this call is interrupted while this method is
* blocked, the message exchange is treated as if the time out occurred.
*
* If this method returns false (indicating that timeout occurred), the
* message exchange must be marked by the implementation as being in the
* {@link ExchangeStatus#ERROR} state. Attempts by the service provider to
* send a MessageExchange in such an ERROR state must result in the send (or
* sendSync) method called ending abruptly with an appropriate
* MessagingException.
*
* Note that the "returned" message exchange (the instance returned by the
* other participant in the exchange) is the same instance referred to by
* the parameter exchange.
*
* @param exchange
* message exchange to send; must be non-null
* @param timeoutMS
* timeout period, in milliseconds (0 means no timeout); must be
* greater than or equal to zero
* @return true if the exchange has been returned, or
* false if the method timed out while waiting
* @throws java.lang.IllegalArgumentException
* if timeoutMS < 0
* @throws MessagingException
* unable to send exchange, or no response is expected from the
* send() operation (i.e., the
* MessageExchange is being used to convey an
* ExchangeStatus)
* @throws MessagingException
* when the blocked thread is interrupted
*/
public boolean sendSync(javax.jbi.messaging.MessageExchange exchange,
long timeoutMS) throws MessagingException;
}