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 }