View Javadoc

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