View Javadoc

1   /*
2    * $Id: MuleSession.java 10961 2008-02-22 19:01:02Z dfeist $
3    * --------------------------------------------------------------------------------------
4    * Copyright (c) MuleSource, Inc.  All rights reserved.  http://www.mulesource.com
5    *
6    * The software in this package is published under the terms of the CPAL v1.0
7    * license, a copy of which has been included with this distribution in the
8    * LICENSE.txt file.
9    */
10  
11  package org.mule.api;
12  
13  import org.mule.api.endpoint.InboundEndpoint;
14  import org.mule.api.endpoint.OutboundEndpoint;
15  import org.mule.api.security.SecurityContext;
16  import org.mule.api.service.Service;
17  
18  import java.io.Serializable;
19  import java.util.Iterator;
20  
21  /**
22   * <code>MuleSession</code> is the context in which a request is executed. The
23   * session manages the marshalling of events to and from components This object is
24   * not usually referenced by client code directly. If needed Components should manage
25   * events via the <code>MuleEventContext</code> which is obtainable via the
26   * <code>UMOManager</code> or by implementing
27   * <code>org.mule.api.lifecycle.Callable</code>.
28   */
29  
30  public interface MuleSession extends Serializable
31  {
32      /**
33       * Returns the Service associated with the session in its current execution
34       * 
35       * @return the Service associated with the session in its current execution
36       * @see org.mule.api.service.Service
37       */
38      Service getService();
39  
40      /**
41       * This will send an event via the configured outbound endpoint on the service
42       * for this session
43       * 
44       * @param message the message to send
45       * @return the result of the send if any
46       * @throws org.mule.api.MuleException if there is no outbound endpoint configured
47       *             on the service or the events fails during dispatch
48       */
49      MuleMessage sendEvent(MuleMessage message) throws MuleException;
50  
51      /**
52       * Depending on the session state this methods either Passes an event
53       * synchronously to the next available Mule UMO in the pool or via the endpoint
54       * configured for the event
55       * 
56       * @param event the event to process
57       * @return the return Message from the call or null if there was no result
58       * @throws MuleException if the event fails to be processed by the service or
59       *             the transport for the endpoint
60       */
61      MuleMessage sendEvent(MuleEvent event) throws MuleException;
62  
63      /**
64       * Depending on the session state this methods either Passes an event
65       * synchronously to the next available Mule UMO in the pool or via the endpoint
66       * configured for the event
67       * 
68       * @param message the event message payload to send
69       * @param endpoint The endpoint to disptch the event through
70       * @return the return Message from the call or null if there was no result
71       * @throws MuleException if the event fails to be processed by the service or
72       *             the transport for the endpoint
73       */
74      MuleMessage sendEvent(MuleMessage message, OutboundEndpoint endpoint) throws MuleException;
75  
76      /**
77       * Depending on the session state this methods either Passes an event
78       * synchronously to the next available Mule UMO in the pool or via the endpoint
79       * configured for the event
80       * 
81       * @param message the event message payload to send
82       * @param endpointName The endpoint name to disptch the event through. This will
83       *            be looked up first on the service configuration and then on the
84       *            mule manager configuration
85       * @return the return Message from the call or null if there was no result
86       * @throws MuleException if the event fails to be processed by the service or
87       *             the transport for the endpoint
88       */
89      MuleMessage sendEvent(MuleMessage message, String endpointName) throws MuleException;
90  
91      /**
92       * This will dispatch an event asynchronously via the configured outbound
93       * endpoint on the service for this session
94       * 
95       * @param message the message to send
96       * @throws MuleException if there is no outbound endpoint configured on the
97       *             service or the events fails during dispatch
98       */
99      void dispatchEvent(MuleMessage message) throws MuleException;
100 
101     /**
102      * Depending on the session state this methods either Passes an event
103      * asynchronously to the next available Mule UMO in the pool or via the endpoint
104      * configured for the event
105      * 
106      * @param event the event message payload to send first on the service
107      *            configuration and then on the mule manager configuration
108      * @throws MuleException if the event fails to be processed by the service or
109      *             the transport for the endpoint
110      */
111     void dispatchEvent(MuleEvent event) throws MuleException;
112 
113     /**
114      * Depending on the session state this methods either Passes an event
115      * asynchronously to the next available Mule UMO in the pool or via the endpoint
116      * configured for the event
117      * 
118      * @param message the event message payload to send
119      * @param endpoint The endpoint name to disptch the event through
120      * @throws MuleException if the event fails to be processed by the service or
121      *             the transport for the endpoint
122      */
123     void dispatchEvent(MuleMessage message, OutboundEndpoint endpoint) throws MuleException;
124 
125     /**
126      * Depending on the session state this methods either Passes an event
127      * asynchronously to the next available Mule UMO in the pool or via the endpoint
128      * configured for the event
129      * 
130      * @param message the event message payload to send
131      * @param endpointName The endpoint name to disptch the event through. This will
132      *            be looked up first on the service configuration and then on the
133      *            mule manager configuration
134      * @throws MuleException if the event fails to be processed by the service or
135      *             the transport for the endpoint
136      */
137     void dispatchEvent(MuleMessage message, String endpointName) throws MuleException;
138 
139     /**
140      * Requests a synchronous receive of an event on the service
141      * 
142      * @param endpoint the endpoint identifing the endpointUri on ewhich the event
143      *            will be received
144      * @param timeout time in milliseconds before the request timesout
145      * @return The requested event or null if the request times out
146      * @throws MuleException if the request operation fails
147      */
148     MuleMessage requestEvent(InboundEndpoint endpoint, long timeout) throws MuleException;
149 
150     /**
151      * Requests a synchronous receive of an event on the service
152      * 
153      * @param endpointName the endpoint name identifing the endpointUri on ewhich the
154      *            event will be received
155      * @param timeout time in milliseconds before the request timesout
156      * @return The requested event or null if the request times out
157      * @throws MuleException if the request operation fails
158      */
159     MuleMessage requestEvent(String endpointName, long timeout) throws MuleException;
160 
161     /**
162      * Determines if this session is valid. A session becomes invalid if an exception
163      * occurs while processing
164      * 
165      * @return true if the service is functioning properly, false otherwise
166      */
167     boolean isValid();
168 
169     /**
170      * Determines if this session is valid. A session becomes invalid if an exception
171      * occurs while processing
172      * 
173      * @param value true if the service is functioning properly, false otherwise
174      */
175     void setValid(boolean value);
176 
177     /**
178      * Creates an outbound event for this session
179      * 
180      * @param message the event messgae payload
181      * @param endpoint the endpoint to send/dispatch through
182      * @param previousEvent the previous event (if any) on this session
183      * @return the event to send/dispatch
184      * @throws MuleException if the evnet cannot be created
185      */
186     MuleEvent createOutboundEvent(MuleMessage message, OutboundEndpoint endpoint, MuleEvent previousEvent)
187         throws MuleException;
188 
189     /**
190      * Returns the unique id for this session
191      * 
192      * @return the unique id for this session
193      */
194     String getId();
195 
196     /**
197      * The security context for this session. If not null outbound, inbound and/or
198      * method invocations will be authenticated using this context
199      * 
200      * @param context the context for this session or null if the request is not
201      *            secure.
202      */
203     void setSecurityContext(SecurityContext context);
204 
205     /**
206      * The security context for this session. If not null outbound, inbound and/or
207      * method invocations will be authenticated using this context
208      * 
209      * @return the context for this session or null if the request is not secure.
210      */
211     SecurityContext getSecurityContext();
212 
213     /**
214      * Will set a session level property. These will either be stored and retrieved
215      * using the underlying transport mechanism of stored using a default mechanism
216      * 
217      * @param key the key for the object data being stored on the session
218      * @param value the value of the session data
219      */
220     void setProperty(Object key, Object value);
221 
222     /**
223      * Will retrieve a session level property.
224      * 
225      * @param key the key for the object data being stored on the session
226      * @return the value of the session data or null if the property does not exist
227      */
228     Object getProperty(Object key);
229 
230     /**
231      * Will retrieve a session level property and remove it from the session
232      * 
233      * @param key the key for the object data being stored on the session
234      * @return the value of the session data or null if the property does not exist
235      */
236     Object removeProperty(Object key);
237 
238     /**
239      * Returns an iterater of property keys for the session properties on this
240      * session
241      * 
242      * @return an iterater of property keys for the session properties on this
243      *         session
244      */
245     Iterator getPropertyNames();
246 
247 }