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 }