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 }