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 java.net.URI;
020    
021    import javax.xml.namespace.QName;
022    
023    /**
024     * A message exchange factory is used used to create new instances of
025     * MessageExchange. Service consumers use these factories to create
026     * message exchanges when initiating a new service request. Message
027     * exchange factories are created using the
028     * {@link javax.jbi.component.ComponentContext} given to the component
029     * during its initialization (see
030     * {@link javax.jbi.component.ComponentLifeCycle}). There are a variety
031     * of ways to creating such factories, each of which creates a context
032     * that is used to provide some of the default properties of
033     * MessageExchange instances created by the factory instances. For example,
034     * a factory can be created for a particular endpoint, ensuring that all exchanges
035     * created by the factory have that endpoint set as the default endpoint property
036     * of the exchange. This allows components to retain factories as a way of aligning
037     * internal processing context with the context contained in the factory, ensuring
038     * that the exchanges created consistently reflect that context.
039     */
040    public interface MessageExchangeFactory {
041    
042        /**
043         * Creates a new MessageExchange instance used to initiate a service
044         * invocation. JBI defines a set of four basic message exchange types,
045         * corresponding to the predefined in-* WSDL 2.0 Message Exchange Patterns.
046         *
047         * @param serviceName name of the service to be invoked
048         * @param operationName name of the operation to be invoked
049         * @return new message exchange, initialized for invoking the given service and operation
050         * @throws MessagingException if the given service or operation are not registered
051         *                            with the NMR or the factory was created for a particular
052         *                            interface, and the given serviceName does not implement
053         *                            that interface.
054         */
055        MessageExchange createExchange(QName serviceName, QName operationName) throws MessagingException;
056    
057        /**
058         * Creates a new MessageExchange instance used to initiate a service invocation.
059         * JBI defines a set of eight fundamental message exchange types which are created
060         * using binding and engine delivery channels. This base method is provided for
061         * extensibility, to satisfy the need for vendor-specific message exchange patterns.
062         * The registration and administration of these patterns is not addressed by JBI.
063         *
064         * @param pattern message exchange pattern
065         * @return new message exchange
066         * @throws MessagingException specified pattern is not registered to a message exchange type
067         */
068        MessageExchange createExchange(URI pattern) throws MessagingException;
069    
070        /**
071         * Convenience method that creates an In-Only message exchange.
072         * 
073         * @return new In-Only message exchange
074         * @throws MessagingException failed to create exchange
075         */
076        InOnly createInOnlyExchange() throws MessagingException;
077    
078        /**
079         * Convenience method that creates an In-Optional-Out message exchange.
080         *
081         * @return new In-Optional-Out message exchange
082         * @throws MessagingException failed to create exchange
083         */
084        InOptionalOut createInOptionalOutExchange() throws MessagingException;
085    
086        /**
087         * Convenience method that creates an In-Out message exchange.
088         *
089         * @return new In-Out message exchange
090         * @throws MessagingException failed to create exchange
091         */
092        InOut createInOutExchange() throws MessagingException;
093    
094        /**
095         * Convenience method that creates an Robust-In-Only message exchange.
096         *
097         * @return new Robust-In-Only message exchange
098         * @throws MessagingException failed to create exchange
099         */
100        RobustInOnly createRobustInOnlyExchange() throws MessagingException;
101    
102    }