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