001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. 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 package javax.jbi.messaging;
018
019 import javax.jbi.servicedesc.ServiceEndpoint;
020
021 import javax.xml.namespace.QName;
022
023 /**
024 * Bi-directional communication channel used to interact with the Normalized
025 * Message Service.
026 *
027 * @author JSR208 Expert Group
028 */
029 public interface DeliveryChannel
030 {
031 /**
032 * Closes the delivery channel, halting all message traffic.
033 *
034 * @throws MessagingException fatal error while closing channel.
035 */
036 void close() throws MessagingException;
037
038 /**
039 * Create a message exchange factory. This factory will create exchange
040 * instances with all appropriate properties set to null.
041 *
042 * @return a message exchange factory
043 */
044 MessageExchangeFactory createExchangeFactory();
045
046 /**
047 * Create a message exchange factory for the given interface name.
048 *
049 * @param interfaceName name of the interface for which all exchanges
050 * created by the returned factory will be set
051 * @return an exchange factory that will create exchanges for the given
052 * interface; must be non-null
053 */
054 MessageExchangeFactory createExchangeFactory(QName interfaceName);
055
056 /**
057 * Create a message exchange factory for the given service name.
058 *
059 * @param serviceName name of the service for which all exchanges
060 * created by the returned factory will be set
061 * @return an exchange factory that will create exchanges for the given
062 * service; must be non-null
063 */
064 MessageExchangeFactory createExchangeFactoryForService(QName serviceName);
065
066 /**
067 * Create a message exchange factory for the given endpoint.
068 *
069 * @param endpoint endpoint for which all exchanges created by the
070 * returned factory will be set for
071 * @return an exchange factory that will create exchanges for the
072 * given endpoint
073 */
074 MessageExchangeFactory createExchangeFactory(ServiceEndpoint endpoint);
075
076 /**
077 * Blocking call used to service a MessageExchange instance which has
078 * been initiated by another component. This method supports concurrent
079 * invocation for multi-threaded environments.
080 *
081 * @return mesage exchange instance
082 * @throws MessagingException failed to accept
083 */
084 MessageExchange accept() throws MessagingException;
085
086 /**
087 * Identical to accept(), but returns after specified interval even if
088 * a message exchange is unavailable.
089 *
090 * @param timeout time to wait in milliseconds
091 * @return mesage exchange instance or null if timeout is reached
092 * @throws MessagingException failed to accept
093 */
094 MessageExchange accept(long timeout) throws MessagingException;
095
096 /**
097 * Routes a MessageExchange instance through the Normalized Message Service
098 * to the appropriate servicing component. This method supports concurrent
099 * invocation for multi-threaded environments.
100 *
101 * @param exchange message exchange to send
102 * @throws MessagingException unable to send exchange
103 */
104 void send(MessageExchange exchange) throws MessagingException;
105
106 /**
107 * Routes a MessageExchange instance through the Normalized Message Service
108 * to the appropriate servicing component, blocking until the exchange is
109 * returned. This method supports concurrent invocation for multi-threaded
110 * environments.
111 *
112 * @param exchange message exchange to send
113 * @return true if the exchange has been processed and returned by the
114 * servicing component, false otherwise.
115 * @throws MessagingException unable to send exchange
116 */
117 boolean sendSync(MessageExchange exchange) throws MessagingException;
118
119 /**
120 * Routes a MessageExchange instance through the Normalized Message Service
121 * to the appropriate servicing component, blocking until the specified
122 * timeout is reached. This method supports concurrent invocation for
123 * multi-threaded environments.
124 *
125 * @param exchange message exchange to send
126 * @param timeout time to wait in milliseconds
127 * @return true if the exchange has been processed and returned by the
128 * servicing component, false in the case of timeout.
129 * @throws MessagingException unable to send exchange
130 */
131 boolean sendSync(MessageExchange exchange, long timeout) throws MessagingException;
132
133 }