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 }