001: /*
002: * $Id: MuleSession.java 10961 2008-02-22 19:01:02Z dfeist $
003: * --------------------------------------------------------------------------------------
004: * Copyright (c) MuleSource, Inc. All rights reserved. http://www.mulesource.com
005: *
006: * The software in this package is published under the terms of the CPAL v1.0
007: * license, a copy of which has been included with this distribution in the
008: * LICENSE.txt file.
009: */
010:
011: package org.mule.api;
012:
013: import org.mule.api.endpoint.InboundEndpoint;
014: import org.mule.api.endpoint.OutboundEndpoint;
015: import org.mule.api.security.SecurityContext;
016: import org.mule.api.service.Service;
017:
018: import java.io.Serializable;
019: import java.util.Iterator;
020:
021: /**
022: * <code>MuleSession</code> is the context in which a request is executed. The
023: * session manages the marshalling of events to and from components This object is
024: * not usually referenced by client code directly. If needed Components should manage
025: * events via the <code>MuleEventContext</code> which is obtainable via the
026: * <code>UMOManager</code> or by implementing
027: * <code>org.mule.api.lifecycle.Callable</code>.
028: */
029:
030: public interface MuleSession extends Serializable {
031: /**
032: * Returns the Service associated with the session in its current execution
033: *
034: * @return the Service associated with the session in its current execution
035: * @see org.mule.api.service.Service
036: */
037: Service getService();
038:
039: /**
040: * This will send an event via the configured outbound endpoint on the service
041: * for this session
042: *
043: * @param message the message to send
044: * @return the result of the send if any
045: * @throws org.mule.api.MuleException if there is no outbound endpoint configured
046: * on the service or the events fails during dispatch
047: */
048: MuleMessage sendEvent(MuleMessage message) throws MuleException;
049:
050: /**
051: * Depending on the session state this methods either Passes an event
052: * synchronously to the next available Mule UMO in the pool or via the endpoint
053: * configured for the event
054: *
055: * @param event the event to process
056: * @return the return Message from the call or null if there was no result
057: * @throws MuleException if the event fails to be processed by the service or
058: * the transport for the endpoint
059: */
060: MuleMessage sendEvent(MuleEvent event) throws MuleException;
061:
062: /**
063: * Depending on the session state this methods either Passes an event
064: * synchronously to the next available Mule UMO in the pool or via the endpoint
065: * configured for the event
066: *
067: * @param message the event message payload to send
068: * @param endpoint The endpoint to disptch the event through
069: * @return the return Message from the call or null if there was no result
070: * @throws MuleException if the event fails to be processed by the service or
071: * the transport for the endpoint
072: */
073: MuleMessage sendEvent(MuleMessage message, OutboundEndpoint endpoint)
074: throws MuleException;
075:
076: /**
077: * Depending on the session state this methods either Passes an event
078: * synchronously to the next available Mule UMO in the pool or via the endpoint
079: * configured for the event
080: *
081: * @param message the event message payload to send
082: * @param endpointName The endpoint name to disptch the event through. This will
083: * be looked up first on the service configuration and then on the
084: * mule manager configuration
085: * @return the return Message from the call or null if there was no result
086: * @throws MuleException if the event fails to be processed by the service or
087: * the transport for the endpoint
088: */
089: MuleMessage sendEvent(MuleMessage message, String endpointName)
090: throws MuleException;
091:
092: /**
093: * This will dispatch an event asynchronously via the configured outbound
094: * endpoint on the service for this session
095: *
096: * @param message the message to send
097: * @throws MuleException if there is no outbound endpoint configured on the
098: * service or the events fails during dispatch
099: */
100: void dispatchEvent(MuleMessage message) throws MuleException;
101:
102: /**
103: * Depending on the session state this methods either Passes an event
104: * asynchronously to the next available Mule UMO in the pool or via the endpoint
105: * configured for the event
106: *
107: * @param event the event message payload to send first on the service
108: * configuration and then on the mule manager configuration
109: * @throws MuleException if the event fails to be processed by the service or
110: * the transport for the endpoint
111: */
112: void dispatchEvent(MuleEvent event) throws MuleException;
113:
114: /**
115: * Depending on the session state this methods either Passes an event
116: * asynchronously to the next available Mule UMO in the pool or via the endpoint
117: * configured for the event
118: *
119: * @param message the event message payload to send
120: * @param endpoint The endpoint name to disptch the event through
121: * @throws MuleException if the event fails to be processed by the service or
122: * the transport for the endpoint
123: */
124: void dispatchEvent(MuleMessage message, OutboundEndpoint endpoint)
125: throws MuleException;
126:
127: /**
128: * Depending on the session state this methods either Passes an event
129: * asynchronously to the next available Mule UMO in the pool or via the endpoint
130: * configured for the event
131: *
132: * @param message the event message payload to send
133: * @param endpointName The endpoint name to disptch the event through. This will
134: * be looked up first on the service configuration and then on the
135: * mule manager configuration
136: * @throws MuleException if the event fails to be processed by the service or
137: * the transport for the endpoint
138: */
139: void dispatchEvent(MuleMessage message, String endpointName)
140: throws MuleException;
141:
142: /**
143: * Requests a synchronous receive of an event on the service
144: *
145: * @param endpoint the endpoint identifing the endpointUri on ewhich the event
146: * will be received
147: * @param timeout time in milliseconds before the request timesout
148: * @return The requested event or null if the request times out
149: * @throws MuleException if the request operation fails
150: */
151: MuleMessage requestEvent(InboundEndpoint endpoint, long timeout)
152: throws MuleException;
153:
154: /**
155: * Requests a synchronous receive of an event on the service
156: *
157: * @param endpointName the endpoint name identifing the endpointUri on ewhich the
158: * event will be received
159: * @param timeout time in milliseconds before the request timesout
160: * @return The requested event or null if the request times out
161: * @throws MuleException if the request operation fails
162: */
163: MuleMessage requestEvent(String endpointName, long timeout)
164: throws MuleException;
165:
166: /**
167: * Determines if this session is valid. A session becomes invalid if an exception
168: * occurs while processing
169: *
170: * @return true if the service is functioning properly, false otherwise
171: */
172: boolean isValid();
173:
174: /**
175: * Determines if this session is valid. A session becomes invalid if an exception
176: * occurs while processing
177: *
178: * @param value true if the service is functioning properly, false otherwise
179: */
180: void setValid(boolean value);
181:
182: /**
183: * Creates an outbound event for this session
184: *
185: * @param message the event messgae payload
186: * @param endpoint the endpoint to send/dispatch through
187: * @param previousEvent the previous event (if any) on this session
188: * @return the event to send/dispatch
189: * @throws MuleException if the evnet cannot be created
190: */
191: MuleEvent createOutboundEvent(MuleMessage message,
192: OutboundEndpoint endpoint, MuleEvent previousEvent)
193: throws MuleException;
194:
195: /**
196: * Returns the unique id for this session
197: *
198: * @return the unique id for this session
199: */
200: String getId();
201:
202: /**
203: * The security context for this session. If not null outbound, inbound and/or
204: * method invocations will be authenticated using this context
205: *
206: * @param context the context for this session or null if the request is not
207: * secure.
208: */
209: void setSecurityContext(SecurityContext context);
210:
211: /**
212: * The security context for this session. If not null outbound, inbound and/or
213: * method invocations will be authenticated using this context
214: *
215: * @return the context for this session or null if the request is not secure.
216: */
217: SecurityContext getSecurityContext();
218:
219: /**
220: * Will set a session level property. These will either be stored and retrieved
221: * using the underlying transport mechanism of stored using a default mechanism
222: *
223: * @param key the key for the object data being stored on the session
224: * @param value the value of the session data
225: */
226: void setProperty(Object key, Object value);
227:
228: /**
229: * Will retrieve a session level property.
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 getProperty(Object key);
235:
236: /**
237: * Will retrieve a session level property and remove it from the session
238: *
239: * @param key the key for the object data being stored on the session
240: * @return the value of the session data or null if the property does not exist
241: */
242: Object removeProperty(Object key);
243:
244: /**
245: * Returns an iterater of property keys for the session properties on this
246: * session
247: *
248: * @return an iterater of property keys for the session properties on this
249: * session
250: */
251: Iterator getPropertyNames();
252:
253: }
|