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 org.apache.camel;
018    
019    import java.util.Map;
020    
021    /**
022     * The base message exchange interface providing access to the request, response
023     * and fault {@link Message} instances. Different providers such as JMS, JBI,
024     * CXF and HTTP can provide their own derived API to expose the underlying
025     * transport semantics to avoid the leaky abstractions of generic APIs.
026     * 
027     * @version $Revision: 563607 $
028     */
029    public interface Exchange {
030    
031        /**
032         * Returns the exchange id
033         * 
034         * @return the unique id of the exchange
035         */
036        String getExchangeId();
037    
038        /**
039         * Set the exchange id
040         * 
041         * @param id
042         */
043        void setExchangeId(String id);
044    
045        /**
046         * Returns a property associated with this exchange by name
047         * 
048         * @param name the name of the property
049         * @return the value of the given header or null if there is no property for
050         *         the given name
051         */
052        Object getProperty(String name);
053    
054        /**
055         * Returns a property associated with this exchange by name and specifying
056         * the type required
057         * 
058         * @param name the name of the property
059         * @param type the type of the property
060         * @return the value of the given header or null if there is no property for
061         *         the given name or null if it cannot be converted to the given
062         *         type
063         */
064        <T> T getProperty(String name, Class<T> type);
065    
066        /**
067         * Sets a property on the exchange
068         * 
069         * @param name of the property
070         * @param value to associate with the name
071         */
072        void setProperty(String name, Object value);
073    
074        /**
075         * Returns all of the properties associated with the exchange
076         * 
077         * @return all the headers in a Map
078         */
079        Map<String, Object> getProperties();
080    
081        /**
082         * Returns the inbound request message
083         * 
084         * @return the message
085         */
086        Message getIn();
087    
088        /**
089         * Returns the outbound message, lazily creating one if one has not already
090         * been associated with this exchange. If you want to inspect this property
091         * but not force lazy creation then invoke the {@link #getOut(boolean)}
092         * method passing in null
093         * 
094         * @return the response
095         */
096        Message getOut();
097    
098        /**
099         * Returns the outbound message; optionally lazily creating one if one has
100         * not been associated with this exchange
101         * 
102         * @return the response
103         */
104        Message getOut(boolean lazyCreate);
105    
106        /**
107         * Returns the fault message
108         * 
109         * @return the fault
110         */
111        Message getFault();
112    
113        /**
114         * Returns the exception associated with this exchange
115         * 
116         * @return the exception (or null if no faults)
117         */
118        Throwable getException();
119    
120        /**
121         * Sets the exception associated with this exchange
122         * 
123         * @param e
124         */
125        void setException(Throwable e);
126    
127        /**
128         * Returns the container so that a processor can resolve endpoints from URIs
129         * 
130         * @return the container which owns this exchange
131         */
132        CamelContext getContext();
133    
134        /**
135         * Creates a copy of the current message exchange so that it can be
136         * forwarded to another destination
137         */
138        Exchange copy();
139    
140        /**
141         * Copies the data into this exchange from the given exchange
142         * 
143         * #param source is the source from which headers and messages will be
144         * copied
145         */
146        void copyFrom(Exchange source);
147    }