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    }