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.jbi.servicedesc.ServiceEndpoint;
022
023 import javax.xml.namespace.QName;
024
025 /**
026 * MessageExchange represents a container for normalized messages which
027 * are described by an exchange pattern. The exchange pattern defines the
028 * names, sequence, and cardinality of messages in an exchange.
029 *
030 * @author JSR208 Expert Group
031 */
032 public interface MessageExchange {
033
034 /**
035 * JTA transaction context property name.
036 */
037 String JTA_TRANSACTION_PROPERTY_NAME = "javax.jbi.transaction.jta";
038
039 /**
040 * Returns the URI of the pattern for this exchange.
041 *
042 * @return pattern URI for this exchange
043 */
044 URI getPattern();
045
046 /**
047 * Returns the unique identifier assigned by the NMS for this exchange.
048 *
049 * @return unique id for this exchange
050 */
051 String getExchangeId();
052
053 /**
054 * Returns the processing status of the exchange.
055 *
056 * @return status of the exchange
057 */
058 ExchangeStatus getStatus();
059
060 /**
061 * Sets the processing status of the exchange.
062 *
063 * @param status exchange status
064 * @throws MessagingException failed to set status, possibly due to
065 * an invalid state transition.
066 */
067 void setStatus(ExchangeStatus status) throws MessagingException;
068
069 /**
070 * Used to specify the source of a failure status. Invoking this method
071 * automatically adjusts the status of the ME to {@link ExchangeStatus#ERROR}.
072 *
073 * @param error error cause
074 */
075 void setError(Exception error);
076
077 /**
078 * Retrieves the Exception describing the exchanges error status.
079 *
080 * @return exception associated with this exchange
081 */
082 Exception getError();
083
084 /**
085 * Retrieves the fault message for this exchange, if one exists. A fault/message
086 * reference is unnecessary, since an exchange can carry at most one fault, and
087 * it is always the final message in an exchange.
088 *
089 * @return fault associated with the exchange, or null if not present
090 */
091 Fault getFault();
092
093 /**
094 * Specifies the fault message for this exchange, if one exists. A fault/message
095 * reference is unnecessary, since an exchange can carry at most one fault, and
096 * it is always the final message in an exchange.
097 *
098 * @param fault fault
099 * @throws MessagingException operation not permitted in the current exchange state
100 */
101 void setFault(Fault fault) throws MessagingException;
102
103 /**
104 * Creates a normalized message based on the specified message reference. The pattern
105 * governing this exchange must contain a definition for the reference name supplied.
106 *
107 * @return a new normalized message
108 * @throws MessagingException failed to create message
109 */
110 NormalizedMessage createMessage() throws MessagingException;
111
112 /**
113 * Generic factory method for Fault objects.
114 *
115 * @return a new fault
116 * @throws MessagingException failed to create fault
117 */
118 Fault createFault() throws MessagingException;
119
120 /**
121 * Retrieves a normalized message based on the specified message reference.
122 *
123 * @param name message reference
124 * @return message with the specified reference name
125 */
126 NormalizedMessage getMessage(String name);
127
128 /**
129 * Sets a normalized message with the specified message reference. The pattern
130 * governing this exchange must contain a definition for the reference name
131 * supplied.
132 *
133 * @param msg normalized message
134 * @param name message reference
135 * @throws MessagingException operation not permitted in the current exchange state
136 */
137 void setMessage(NormalizedMessage msg, String name) throws MessagingException;
138
139 /**
140 * Retrieves the specified property from the exchange.
141 *
142 * @param name property name
143 * @return property value
144 */
145 Object getProperty(String name);
146
147 /**
148 * Specifies a property for the exchange.
149 *
150 * @param name property name
151 * @param obj property value
152 */
153 void setProperty(String name, Object obj);
154
155 /**
156 * Specifies the endpoint used by this exchange.
157 *
158 * @param endpoint endpoint address
159 */
160 void setEndpoint(ServiceEndpoint endpoint);
161
162 /**
163 * Specifies the service used by this exchange.
164 *
165 * @param service service address
166 */
167 void setService(QName service);
168
169 /**
170 * Specifies the interface name used by this exchange.
171 *
172 * @param interfaceName interface name
173 */
174 void setInterfaceName(QName interfaceName);
175
176 /**
177 * Specifies the operation used by this exchange.
178 *
179 * @param name operation name
180 */
181 void setOperation(QName name);
182
183 /**
184 * Retrieves the endpoint used by this exchange.
185 *
186 * @return endpoint address for this message exchange
187 */
188 ServiceEndpoint getEndpoint();
189
190 /**
191 * Retrieves the interface name used by this exchange.
192 *
193 * @return interface used for this message exchange
194 */
195 QName getInterfaceName();
196
197 /**
198 * Retrieves the service used by this exchange.
199 *
200 * @return service address for this message exchange
201 */
202 QName getService();
203
204 /**
205 * Retrieves the operation used by this exchange.
206 *
207 * @return operation name for this message exchange
208 */
209 QName getOperation();
210
211 /**
212 * Queries the existence of a transaction context.
213 *
214 * @return boolean transactional state of the exchange
215 */
216 boolean isTransacted();
217
218 /**
219 * Queries the role that the caller plays in the exchange.
220 *
221 * @return Role expected of caller.
222 */
223 Role getRole();
224
225 /**
226 * Returns the name of all properties for this exchange.
227 *
228 * @return a set of all the property names, as Strings.
229 */
230 java.util.Set getPropertyNames();
231
232 /**
233 * Typesafe enum containing the roles a component can play in a service.
234 *
235 */
236 public static final class Role {
237
238 /**
239 * Service provider.
240 */
241 public static final Role PROVIDER = new Role();
242
243 /**
244 * Service Consumer.
245 */
246 public static final Role CONSUMER = new Role();
247
248 /**
249 * Prevent direct instantiation.
250 */
251 private Role() {
252 }
253 }
254 }