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    }