apache/synapse/MessageContext.java

/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 */

package org.apache.synapse;


import org.apache.axiom.soap.SOAPEnvelope;
import org.apache.axis2.AxisFault;
import org.apache.axis2.addressing.EndpointReference;
import org.apache.axis2.addressing.RelatesTo;
import org.apache.synapse.config.SynapseConfiguration;
import org.apache.synapse.core.SynapseEnvironment;
import org.apache.synapse.endpoints.Endpoint;
import org.apache.commons.logging.Log;

import java.util.Set;
import java.util.Stack;
import java.util.Map;


/**
 * The Synapse Message Context is available to all mediators through which it flows. It
 * allows one to call to the underlying SynapseEnvironment (i.e. the SOAP engine
 * - such as Axis2) where required. It also allows one to access the current
 * SynapseConfiguration. Additionally it holds per message properties (i.e. local
 * properties valid for the lifetime of the message), and the current SOAPEnvelope
 */
public interface MessageContext {

    /**
     * Get a reference to the current SynapseConfiguration
     *
     * @return the current synapse configuration
     */
    public SynapseConfiguration getConfiguration();

    /**
     * Set or replace the Synapse Configuration instance to be used. May be used to
     * programatically change the configuration at runtime etc.
     *
     * @param cfg The new synapse configuration instance
     */
    public void setConfiguration(SynapseConfiguration cfg);

    /**
     * Returns a reference to the host Synapse Environment
     * @return the Synapse Environment
     */
    public SynapseEnvironment getEnvironment();

    /**
     * Sets the SynapseEnvironment reference to this context
     * @param se the reference to the Synapse Environment
     */
    public void setEnvironment(SynapseEnvironment se);

    /**
     * Return all the entries which are in the MessageContext. This does not represent
     * all the declared entries in the configuration, rather only the entries that the
     * context has already used. This will not lookup for the entries in the Configuration.
     * @return the set of local entries in the context
     */
    public Map<String, Object> getContextEntries();

    /**
     * Sets the entries to the current context and not to the configuration. This can be
     * used to forcibly override an existing set of resources in the configuration, because
     * the resource lookup will look for the context first. But this only sets the entries
     * to the current context
     * @param entries the set of local entries to be set
     */
    public void setContextEntries(Map<String, Object> entries);

    /**
     * Return the main sequence from the configuration, or the local message context
     * This method looks up for the sequence named Constants.MAIN_SEQUENCE_KEY from
     * the local message context to make this look up transactional - i.e. a request and
     * response message pair will not see a difference in the main sequence if the main
     * sequence was dynamic and changed in between at the registry
     * @return the main sequence to be used for mediation
     */
    public Mediator getMainSequence();

    /**
     * Return the fault sequence from the configuration, or the local message context
     * This method looks up for the sequence named Constants.FAULT_SEQUENCE_KEY from
     * the local message context to make this look up transactional - i.e. a request and
     * response message pair will not see a difference in the fault sequence if the fault
     * sequence was dynamic and changed in between at the registry
     * @return the fault sequence to be used for mediation
     */
    public Mediator getFaultSequence();

    /**
     * Return the sequence with the given key from the configuration, or the local message
     * context. This method looks up for the sequence with the given key from the local
     * message context to make this look up transactional - i.e. a request and response
     * message pair will not see a difference in the said sequence if it was dynamic and
     * changed in between at the registry
     * @param key the sequence key to be looked up
     * @return the sequence mediator mapped to the key
     */
    public Mediator getSequence(String key);

    /**
     * Return the endpoint with the given key from the configuration, or the local message
     * context. This method looks up for the endpoint with the given key from the local
     * message context to make this look up transactional - i.e. a request and response
     * message pair will not see a difference in the said endpoint if it was dynamic and
     * changed in between at the registry
     * @param key the endpoint key to be looked up
     * @return the endpoint mapped to the key
     */
    public Endpoint getEndpoint(String key);

    /**
     * Get the value of a custom (local) property set on the message instance
     * @param key key to look up property
     * @return value for the given key
     */
    public Object getProperty(String key);

    /**
     * Get the value of a property set on the message instance, from the local registry
     * or the remote registry - by cascading through
     * @param key key to look up property
     * @return value for the given key
     */
    public Object getEntry(String key);

    /**
     * Set a custom (local) property with the given name on the message instance
     * @param key key to be used
     * @param value value to be saved
     */
    public void setProperty(String key, Object value);

    /**
     * Returns the Set of keys over the properties on this message context
     * @return a Set of keys over message properties
     */
    public Set getPropertyKeySet();

    /**
     * Get the SOAP envelope of this message
     * @return the SOAP envelope of the message
     */
    public SOAPEnvelope getEnvelope();

    /**
     * Sets the given envelope as the current SOAPEnvelope for this message
     * @param envelope the envelope to be set
     * @throws org.apache.axis2.AxisFault on exception
     */
    public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;

    // --- SOAP Message related methods ------
    /**
     * Get the faultTo EPR if available
     * @return FaultTo epr if available
     */
    public EndpointReference getFaultTo();

    /**
     * Set the faultTo EPR
     * @param reference epr representing the FaultTo address
     */
    public void setFaultTo(EndpointReference reference);

    /**
     * Get the from EPR if available
     * @return From epr if available
     */
    public EndpointReference getFrom();

    /**
     * Set the from EPR
     * @param reference epr representing the From address
     */
    public void setFrom(EndpointReference reference);

    /**
     * Get the message id if available
     * @return message id if available
     */
    public String getMessageID();

    /**
     * Set the message id
     * @param string message id to be set
     */
    public void setMessageID(String string);

    /**
     * Get the relatesTo of this message
     * @return RelatesTo of the message if available
     */
    public RelatesTo getRelatesTo();

    /**
     * Sets the relatesTo references for this message
     * @param reference the relatesTo references array
     */
    public void setRelatesTo(RelatesTo[] reference);

    /**
     * Get the replyTo EPR if available
     * @return ReplyTo epr of the message if available
     */
    public EndpointReference getReplyTo();

    /**
     * Set the replyTo EPR
     * @param reference epr representing the ReplyTo address
     */
    public void setReplyTo(EndpointReference reference);

    /**
     * Get the To EPR
     * @return To epr of the message if available
     */
    public EndpointReference getTo();

     /**
     * Set the To EPR
     * @param reference the To EPR
     */
    public void setTo(EndpointReference reference);

    /**
     * Sets the WSAAction
     * @param actionURI the WSAAction
     */
    public void setWSAAction(String actionURI);

    /**
     * Returns the WSAAction
     * @return the WSAAction
     */
    public String getWSAAction();

    /**
     * Returns the SOAPAction of the message
     * @return the SOAPAction
     */
    public String getSoapAction();

    /**
     * Set the SOAPAction
     * @param string the SOAP Action
     */
    public void setSoapAction(String string);

    /**
     * Set the message
     * @param messageID message id to be set
     */
    public void setWSAMessageID(String messageID);

    /**
     * Gets the message name
     * @return the WSA MessageID
     */
    public String getWSAMessageID();

    /**
     * If this message using MTOM?
     * @return true if using MTOM
     */
    public boolean isDoingMTOM();

    /**
     * If this message using SWA?
     * @return true if using SWA
     */
    public boolean isDoingSWA();

    /**
     * Marks as using MTOM
     * @param b true to mark as using MTOM
     */
    public void setDoingMTOM(boolean b);

    /**
     * Marks as using SWA
     * @param b true to mark as using SWA
     */
    public void setDoingSWA(boolean b);

    /**
     * Is this message over POX?
     * @return true if over POX
     */
    public boolean isDoingPOX();

    /**
     * Marks this message as over POX
     * @param b true to mark as POX
     */
    public void setDoingPOX(boolean b);

    /**
     * Is this message over GET?
     * @return true if over GET
     */
    public boolean isDoingGET();

    /**
     * Marks this message as over REST/GET
     * @param b true to mark as REST/GET
     */
    public void setDoingGET(boolean b);

    /**
     * Is this message a SOAP 1.1 message?
     * @return true if this is a SOAP 1.1 message
     */
    public boolean isSOAP11();

    /**
     * Mark this message as a response or not.
     * @see org.apache.synapse.MessageContext#isResponse()
     * @param b true to set this as a response
     */
    public void setResponse(boolean b);

    /**
     * Is this message a response to a synchronous message sent out through Synapse?
     * @return true if this message is a response message
     */
    public boolean isResponse();

    /**
     * Marks this message as a fault response
     * @see org.apache.synapse.MessageContext#isFaultResponse()
     * @param b true to mark this as a fault response
     */
    public void setFaultResponse(boolean b);

    /**
     * Is this message a response to a fault message?
     * @return true if this is a response to a fault message
     */
    public boolean isFaultResponse();

    /**
     * This is used to check whether the tracing should be enabled on the current mediator or not
     * @return indicate whether tracing is on, off or unset
     */
    public int getTracingState();

    /**
     * This is used to set the value of tracing enable variable
     * @param tracingState Set whether the tracing is enabled or not
     */
    public void setTracingState(int tracingState);

    public Stack<FaultHandler> getFaultStack();

    public void pushFaultHandler(FaultHandler fault);

    /**
     * Return the service level Log for this message context or null
     * @return the service level Log for the message
     */
    public Log getServiceLog();
}
1	/*
2	* Licensed to the Apache Software Foundation (ASF) under one
3	* or more contributor license agreements. See the NOTICE file
4	* distributed with this work for additional information
5	* regarding copyright ownership. The ASF licenses this file
6	* to you under the Apache License, Version 2.0 (the
7	* "License"); you may not use this file except in compliance
8	* with the License. You may obtain a copy of the License at
9	*
10	* http://www.apache.org/licenses/LICENSE-2.0
11	*
12	* Unless required by applicable law or agreed to in writing,
13	* software distributed under the License is distributed on an
14	* * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15	* KIND, either express or implied. See the License for the
16	* specific language governing permissions and limitations
17	* under the License.
18	*/
19
20	package org.apache.synapse;
21
22
23	import org.apache.axiom.soap.SOAPEnvelope;
24	import org.apache.axis2.AxisFault;
25	import org.apache.axis2.addressing.EndpointReference;
26	import org.apache.axis2.addressing.RelatesTo;
27	import org.apache.synapse.config.SynapseConfiguration;
28	import org.apache.synapse.core.SynapseEnvironment;
29	import org.apache.synapse.endpoints.Endpoint;
30	import org.apache.commons.logging.Log;
31
32	import java.util.Set;
33	import java.util.Stack;
34	import java.util.Map;
35
36
37	/**
38	* The Synapse Message Context is available to all mediators through which it flows. It
39	* allows one to call to the underlying SynapseEnvironment (i.e. the SOAP engine
40	* - such as Axis2) where required. It also allows one to access the current
41	* SynapseConfiguration. Additionally it holds per message properties (i.e. local
42	* properties valid for the lifetime of the message), and the current SOAPEnvelope
43	*/
44	public interface MessageContext {
45
46	/**
47	* Get a reference to the current SynapseConfiguration
48	*
49	* @return the current synapse configuration
50	*/
51	public SynapseConfiguration getConfiguration();
52
53	/**
54	* Set or replace the Synapse Configuration instance to be used. May be used to
55	* programatically change the configuration at runtime etc.
56	*
57	* @param cfg The new synapse configuration instance
58	*/
59	public void setConfiguration(SynapseConfiguration cfg);
60
61	/**
62	* Returns a reference to the host Synapse Environment
63	* @return the Synapse Environment
64	*/
65	public SynapseEnvironment getEnvironment();
66
67	/**
68	* Sets the SynapseEnvironment reference to this context
69	* @param se the reference to the Synapse Environment
70	*/
71	public void setEnvironment(SynapseEnvironment se);
72
73	/**
74	* Return all the entries which are in the MessageContext. This does not represent
75	* all the declared entries in the configuration, rather only the entries that the
76	* context has already used. This will not lookup for the entries in the Configuration.
77	* @return the set of local entries in the context
78	*/
79	public Map<String, Object> getContextEntries();
80
81	/**
82	* Sets the entries to the current context and not to the configuration. This can be
83	* used to forcibly override an existing set of resources in the configuration, because
84	* the resource lookup will look for the context first. But this only sets the entries
85	* to the current context
86	* @param entries the set of local entries to be set
87	*/
88	public void setContextEntries(Map<String, Object> entries);
89
90	/**
91	* Return the main sequence from the configuration, or the local message context
92	* This method looks up for the sequence named Constants.MAIN_SEQUENCE_KEY from
93	* the local message context to make this look up transactional - i.e. a request and
94	* response message pair will not see a difference in the main sequence if the main
95	* sequence was dynamic and changed in between at the registry
96	* @return the main sequence to be used for mediation
97	*/
98	public Mediator getMainSequence();
99
100	/**
101	* Return the fault sequence from the configuration, or the local message context
102	* This method looks up for the sequence named Constants.FAULT_SEQUENCE_KEY from
103	* the local message context to make this look up transactional - i.e. a request and
104	* response message pair will not see a difference in the fault sequence if the fault
105	* sequence was dynamic and changed in between at the registry
106	* @return the fault sequence to be used for mediation
107	*/
108	public Mediator getFaultSequence();
109
110	/**
111	* Return the sequence with the given key from the configuration, or the local message
112	* context. This method looks up for the sequence with the given key from the local
113	* message context to make this look up transactional - i.e. a request and response
114	* message pair will not see a difference in the said sequence if it was dynamic and
115	* changed in between at the registry
116	* @param key the sequence key to be looked up
117	* @return the sequence mediator mapped to the key
118	*/
119	public Mediator getSequence(String key);
120
121	/**
122	* Return the endpoint with the given key from the configuration, or the local message
123	* context. This method looks up for the endpoint with the given key from the local
124	* message context to make this look up transactional - i.e. a request and response
125	* message pair will not see a difference in the said endpoint if it was dynamic and
126	* changed in between at the registry
127	* @param key the endpoint key to be looked up
128	* @return the endpoint mapped to the key
129	*/
130	public Endpoint getEndpoint(String key);
131
132	/**
133	* Get the value of a custom (local) property set on the message instance
134	* @param key key to look up property
135	* @return value for the given key
136	*/
137	public Object getProperty(String key);
138
139	/**
140	* Get the value of a property set on the message instance, from the local registry
141	* or the remote registry - by cascading through
142	* @param key key to look up property
143	* @return value for the given key
144	*/
145	public Object getEntry(String key);
146
147	/**
148	* Set a custom (local) property with the given name on the message instance
149	* @param key key to be used
150	* @param value value to be saved
151	*/
152	public void setProperty(String key, Object value);
153
154	/**
155	* Returns the Set of keys over the properties on this message context
156	* @return a Set of keys over message properties
157	*/
158	public Set getPropertyKeySet();
159
160	/**
161	* Get the SOAP envelope of this message
162	* @return the SOAP envelope of the message
163	*/
164	public SOAPEnvelope getEnvelope();
165
166	/**
167	* Sets the given envelope as the current SOAPEnvelope for this message
168	* @param envelope the envelope to be set
169	* @throws org.apache.axis2.AxisFault on exception
170	*/
171	public void setEnvelope(SOAPEnvelope envelope) throws AxisFault;
172
173	// --- SOAP Message related methods ------
174	/**
175	* Get the faultTo EPR if available
176	* @return FaultTo epr if available
177	*/
178	public EndpointReference getFaultTo();
179
180	/**
181	* Set the faultTo EPR
182	* @param reference epr representing the FaultTo address
183	*/
184	public void setFaultTo(EndpointReference reference);
185
186	/**
187	* Get the from EPR if available
188	* @return From epr if available
189	*/
190	public EndpointReference getFrom();
191
192	/**
193	* Set the from EPR
194	* @param reference epr representing the From address
195	*/
196	public void setFrom(EndpointReference reference);
197
198	/**
199	* Get the message id if available
200	* @return message id if available
201	*/
202	public String getMessageID();
203
204	/**
205	* Set the message id
206	* @param string message id to be set
207	*/
208	public void setMessageID(String string);
209
210	/**
211	* Get the relatesTo of this message
212	* @return RelatesTo of the message if available
213	*/
214	public RelatesTo getRelatesTo();
215
216	/**
217	* Sets the relatesTo references for this message
218	* @param reference the relatesTo references array
219	*/
220	public void setRelatesTo(RelatesTo[] reference);
221
222	/**
223	* Get the replyTo EPR if available
224	* @return ReplyTo epr of the message if available
225	*/
226	public EndpointReference getReplyTo();
227
228	/**
229	* Set the replyTo EPR
230	* @param reference epr representing the ReplyTo address
231	*/
232	public void setReplyTo(EndpointReference reference);
233
234	/**
235	* Get the To EPR
236	* @return To epr of the message if available
237	*/
238	public EndpointReference getTo();
239
240	/**
241	* Set the To EPR
242	* @param reference the To EPR
243	*/
244	public void setTo(EndpointReference reference);
245
246	/**
247	* Sets the WSAAction
248	* @param actionURI the WSAAction
249	*/
250	public void setWSAAction(String actionURI);
251
252	/**
253	* Returns the WSAAction
254	* @return the WSAAction
255	*/
256	public String getWSAAction();
257
258	/**
259	* Returns the SOAPAction of the message
260	* @return the SOAPAction
261	*/
262	public String getSoapAction();
263
264	/**
265	* Set the SOAPAction
266	* @param string the SOAP Action
267	*/
268	public void setSoapAction(String string);
269
270	/**
271	* Set the message
272	* @param messageID message id to be set
273	*/
274	public void setWSAMessageID(String messageID);
275
276	/**
277	* Gets the message name
278	* @return the WSA MessageID
279	*/
280	public String getWSAMessageID();
281
282	/**
283	* If this message using MTOM?
284	* @return true if using MTOM
285	*/
286	public boolean isDoingMTOM();
287
288	/**
289	* If this message using SWA?
290	* @return true if using SWA
291	*/
292	public boolean isDoingSWA();
293
294	/**
295	* Marks as using MTOM
296	* @param b true to mark as using MTOM
297	*/
298	public void setDoingMTOM(boolean b);
299
300	/**
301	* Marks as using SWA
302	* @param b true to mark as using SWA
303	*/
304	public void setDoingSWA(boolean b);
305
306	/**
307	* Is this message over POX?
308	* @return true if over POX
309	*/
310	public boolean isDoingPOX();
311
312	/**
313	* Marks this message as over POX
314	* @param b true to mark as POX
315	*/
316	public void setDoingPOX(boolean b);
317
318	/**
319	* Is this message over GET?
320	* @return true if over GET
321	*/
322	public boolean isDoingGET();
323
324	/**
325	* Marks this message as over REST/GET
326	* @param b true to mark as REST/GET
327	*/
328	public void setDoingGET(boolean b);
329
330	/**
331	* Is this message a SOAP 1.1 message?
332	* @return true if this is a SOAP 1.1 message
333	*/
334	public boolean isSOAP11();
335
336	/**
337	* Mark this message as a response or not.
338	* @see org.apache.synapse.MessageContext#isResponse()
339	* @param b true to set this as a response
340	*/
341	public void setResponse(boolean b);
342
343	/**
344	* Is this message a response to a synchronous message sent out through Synapse?
345	* @return true if this message is a response message
346	*/
347	public boolean isResponse();
348
349	/**
350	* Marks this message as a fault response
351	* @see org.apache.synapse.MessageContext#isFaultResponse()
352	* @param b true to mark this as a fault response
353	*/
354	public void setFaultResponse(boolean b);
355
356	/**
357	* Is this message a response to a fault message?
358	* @return true if this is a response to a fault message
359	*/
360	public boolean isFaultResponse();
361
362	/**
363	* This is used to check whether the tracing should be enabled on the current mediator or not
364	* @return indicate whether tracing is on, off or unset
365	*/
366	public int getTracingState();
367
368	/**
369	* This is used to set the value of tracing enable variable
370	* @param tracingState Set whether the tracing is enabled or not
371	*/
372	public void setTracingState(int tracingState);
373
374	public Stack<FaultHandler> getFaultStack();
375
376	public void pushFaultHandler(FaultHandler fault);
377
378	/**
379	* Return the service level Log for this message context or null
380	* @return the service level Log for the message
381	*/
382	public Log getServiceLog();
383	}