001: /*
002: * BEGIN_HEADER - DO NOT EDIT
003: *
004: * The contents of this file are subject to the terms
005: * of the Common Development and Distribution License
006: * (the "License"). You may not use this file except
007: * in compliance with the License.
008: *
009: * You can obtain a copy of the license at
010: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
011: * See the License for the specific language governing
012: * permissions and limitations under the License.
013: *
014: * When distributing Covered Code, include this CDDL
015: * HEADER in each file and include the License file at
016: * https://open-esb.dev.java.net/public/CDDLv1.0.html.
017: * If applicable add the following below this CDDL HEADER,
018: * with the fields enclosed by brackets "[]" replaced with
019: * your own identifying information: Portions Copyright
020: * [year] [name of copyright owner]
021: */
022:
023: /*
024: * @(#)MessageExchange.java
025: * Copyright 2004-2007 Sun Microsystems, Inc. All Rights Reserved.
026: *
027: * END_HEADER - DO NOT EDIT
028: */
029: package javax.jbi.messaging;
030:
031: import java.net.URI;
032:
033: import javax.jbi.servicedesc.ServiceEndpoint;
034:
035: import javax.transaction.Transaction;
036:
037: import javax.xml.namespace.QName;
038:
039: /** MessageExchange represents a container for normalized messages which are
040: * described by an exchange pattern. The exchange pattern defines the
041: * names, sequence, and cardinality of messages in an exchange.
042: *
043: * @author JSR208 Expert Group
044: */
045: public interface MessageExchange {
046: /** JTA transaction context property name. */
047: String JTA_TRANSACTION_PROPERTY_NAME = "javax.jbi.transaction.jta";
048:
049: /** Returns the URI of the pattern for this exchange.
050: * @return pattern URI for this exchange
051: */
052: URI getPattern();
053:
054: /** Returns the unique identifier assigned by the NMS for this exchange.
055: * @return unique id for this exchange
056: */
057: String getExchangeId();
058:
059: /** Returns the processing status of the exchange.
060: * @return status of the exchange
061: */
062: ExchangeStatus getStatus();
063:
064: /** Sets the processing status of the exchange.
065: * @param status exchange status
066: * @throws MessagingException failed to set status, possibly due to an
067: * invalid state transition.
068: */
069: void setStatus(ExchangeStatus status) throws MessagingException;
070:
071: /** Used to specify the source of a failure status. Invoking this method
072: * automatically adjusts the status of the ME to ExchangeStatus.ERROR.
073: * @param error error cause
074: */
075: void setError(Exception error);
076:
077: /** Retrieves the Exception describing the exchanges error status.
078: * @return exception associated with this exchange
079: */
080: Exception getError();
081:
082: /** Retrieves the fault message for this exchange, if one exists. A
083: * fault/message reference is unnecessary, since an exchange can carry
084: * at most one fault, and it is always the final message in an exchange.
085: * @return fault associated with the exchange, or null if not present
086: */
087: Fault getFault();
088:
089: /** Specifies the fault message for this exchange, if one exists. A
090: * fault/message reference is unnecessary, since an exchange can carry
091: * at most one fault, and it is always the final message in an exchange.
092: * @param fault fault
093: * @throws MessagingException operation not permitted in the current exchange state
094: */
095: void setFault(Fault fault) throws MessagingException;
096:
097: /** Creates a normalized message based on the specified message reference.
098: * The pattern governing this exchange must contain a definition for the
099: * reference name supplied.
100: * @return a new normalized message
101: * @throws MessagingException failed to create message
102: */
103: NormalizedMessage createMessage() throws MessagingException;
104:
105: /** Generic factory method for Fault objects.
106: * @return a new fault
107: * @throws MessagingException failed to create fault
108: */
109: Fault createFault() throws MessagingException;
110:
111: /** Retrieves a normalized message based on the specified message reference.
112: * @param name message reference
113: * @return message with the specified reference name
114: */
115: NormalizedMessage getMessage(String name);
116:
117: /** Sets a normalized message with the specified message reference.
118: * The pattern governing this exchange must contain a definition for the
119: * reference name supplied.
120: * @param msg normalized message
121: * @param name message reference
122: * @throws MessagingException operation not permitted in the current exchange state
123: */
124: void setMessage(NormalizedMessage msg, String name)
125: throws MessagingException;
126:
127: /** Retrieves the specified property from the exchange.
128: * @param name property name
129: * @return property value
130: */
131: Object getProperty(String name);
132:
133: /** Specifies a property for the exchange.
134: * @param name property name
135: * @param obj property value
136: */
137: void setProperty(String name, Object obj);
138:
139: /** Specifies the endpoint used by this exchange.
140: * @param endpoint endpoint address
141: */
142: void setEndpoint(ServiceEndpoint endpoint);
143:
144: /** Specifies the service used by this exchange.
145: * @param service service address
146: */
147: void setService(QName service);
148:
149: /** Specifies the interface name used by this exchange.
150: * @param interfaceName interface name
151: */
152: void setInterfaceName(QName interfaceName);
153:
154: /** Specifies the operation used by this exchange.
155: * @param name operation name
156: */
157: void setOperation(QName name);
158:
159: /** Retrieves the endpoint used by this exchange.
160: * @return endpoint address for this message exchange
161: */
162: ServiceEndpoint getEndpoint();
163:
164: /** Retrieves the interface name used by this exchange.
165: * @return interface used for this message exchange
166: */
167: QName getInterfaceName();
168:
169: /** Retrieves the service used by this exchange.
170: * @return service address for this message exchange
171: */
172: QName getService();
173:
174: /** Retrieves the operation used by this exchange.
175: * @return operation name for this message exchange
176: */
177: QName getOperation();
178:
179: /** Queries the existence of a transaction context.
180: * @return boolean transactional state of the exchange
181: */
182: boolean isTransacted();
183:
184: /** Queries the role that the caller plays in the exchange.
185: * @return Role expected of caller.
186: */
187: Role getRole();
188:
189: /** Returns the name of all properties for this exchange.
190: * @return a set of all the property names, as Strings.
191: */
192: java.util.Set getPropertyNames();
193:
194: /** Typesafe enum containing the roles a component can play in a service.
195: */
196: public static final class Role {
197: /** Service provider. */
198: public static final Role PROVIDER = new Role();
199: /** Service consumer. */
200: public static final Role CONSUMER = new Role();
201:
202: /** Prevent direct instantiation. */
203: private Role() {
204: }
205: }
206: }
|