Visit Platform at http://www.platform.com

Main Page   Compound List   Compound Members  

ISoamSession Interface Reference

An object to enable the client to manage its workload. More...

List of all members.


Public Types

enum  SessionCloseFlags { DestroyOnClose = 1, DetachOnClose = 2 }
enum  SessionFlags { SendSync = 1, ReceiveSync = 4, AliasSync = 5 }

Public Methods

HRESULT SendTaskInput ([in] ISoamMessage *message,[out, retval] ISoamTaskInputHandle **InputHandle)
 Send task inputs.

HRESULT FetchTaskOutput ([in] LONG countMax,[out, retval] ISoamEnum **Tasks)
 Get response from SOAM.

HRESULT Close ()
 Close the session.

HRESULT Id ([out, retval] BSTR *pVal)
 Get an ID of a ISoamSession.

HRESULT FetchTaskOutputWithTimeOut ([in] LONG countMax,[in] LONG maxTimeOut,[out, retval] ISoamEnum **Tasks)
 Get response from SOAM.


Detailed Description

An object to enable the client to manage its workload.

Created by the connection object to enable the client to manage its workload and can be considered as a conduit for tasks being submitted to the service instances.

See also:
Connection


Member Enumeration Documentation

enum SessionCloseFlags
 

SessionCloseFlags Flags used to indicate how the session is to be closed. series of elements, one at a time. Successive calls to the getNext method return successive elements of the series.

See also:
ISoamSession
Enumeration values:
DestroyOnClose  This informs the API that the client no longer intends to use the session. This is the default behaviour if this parameter is ignored. Closing the session in this way will result in the session being terminated within the middleware. All outstanding results will be discarded.
DetachOnClose  This informs the API that the client no longer intends to use the session locally, but intends for the workload to continue running within the middleware. In effect, this session will become available to any client wishing to access it. A client must call Connection::openSession to gain access to this session once it has been closed in this manner.

enum SessionFlags
 

Flags used to inform the API of any extended behavior to associate with the session.

Enumeration values:
SendSync  This informs the API that the client requires the submission of input to be in a "synchonous" manner. This means that the call to ISoamSession::sendTaskInput() will block the client's thread until it receives a confirmation from the middleware that the input has been safely received. This is the default sending behaviour (if no "Send" flag is specified).
ReceiveSync  This informs the API that the client is expecting that the result of its computation will be returned in a synchronous manner. This means that the client will use the ISoamSession::fetchTaskOutput() method to retrieve the output.
AliasSync  This alias can be used instead of the following combination "SendSync | ReceiveSync"

Member Function Documentation

HRESULT SendTaskInput [in] ISoamMessage   message,
[out, retval] ISoamTaskInputHandle **    InputHandle
 

Send task inputs.

This method will deliver the provided input message to the system. For synchronous (created with flag ISoamSession::Sync) session, this method will wait for acknowledgement from the Symphony Session Manager that the message has been safely accepted and will be processed as soon as possible, in which case a task ID will be returned. For fully asynchronous mode, the acknowledgement will return on the callback and the method call will not be blocked.

IMPORTANT NOTE:
The sendTaskInput(....) method always returns a TaskInputHandle object. This means that even if the developer has no intention of using the returned object, the returned object should always be assigned to a smartpointer to ensure that there is no memory leaked from the client. e.g.

     // send it
     TaskInputHandlePtr input = sesPtr->sendTaskInput(msg);

Parameters:
taskInput  [IN] - a message to be sent to SOAM.
hasPriority  [IN] - this is an optional parameter that indicates to the Middleware that the message being submitted should take priority in the current session. This means that it will be used to create a task that will be placed at the front of the dispatch queue. The default value for this parameter is false if not specified, in which case the newly created task will be placed at the rear of the dispatch queue.
Returns:
a pointer of a TaskInputHandle object.
Exceptions:
ISoamException 
See also:
Connection::createSession , TaskInputHandle

HRESULT FetchTaskOutput [in] LONG    countMax,
[out, retval] ISoamEnum **    Tasks
 

Get response from SOAM.

Attempts to retrieve the number of specified output messages currently ready and waiting that were produced by the service instance. The replies will be presented as an enumeration.The method will return with a subset of the requested items. This subset can be 0 to countMax.

Parameters:
countMax  [IN] - maximum output items to be returned by SOAM.
Returns:
a pointer to an EnumItems object.
Exceptions:
ISoamException 
See also:
EnumItems

HRESULT Close  
 

Close the session.

Once a session is closed no further operations can be performed on the session within the client.

Parameters:
closeFlags  [IN] - This flag allows the client to specify explicitly which ISoamSession::SessionCloseFlag to use when closing the session.
Exceptions:
ISoamException 
See also:
Connection::openSession , ISoamSession::SessionCloseFlags

HRESULT Id [out, retval] BSTR *    pVal
 

Get an ID of a ISoamSession.

Retrieve the ID associated with the session. This ID can be used to allow another client to attach to this session.

Returns:
a ISoamSession ID.
Exceptions:
ISoamException 

HRESULT FetchTaskOutputWithTimeOut [in] LONG    countMax,
[in] LONG    maxTimeOut,
[out, retval] ISoamEnum **    Tasks
 

Get response from SOAM.

Attempts to retrieve the number of specified output messages currently ready and waiting that were produced by the service instance. The replies will be presented as an enumeration.If a timeout within the range of 0 - 31556926 seconds is specified, then if there is less than the specified amount of output messages ready when the timeout interval is exceeded, the method will return with a subset of the requested items. This subset can be 0 to countMax.

Parameters:
countMax  [IN] - maximum output items to be returned by SOAM.
timeoutInSeconds  [IN] - how much time should pass before giving up on trying to fulfill the request. The maximum number of seconds allowed is 31556926 seconds.
Returns:
a pointer to an EnumItems object.
Exceptions:
ISoamException 
See also:
EnumItems


     
Date Modified: 28 Apr 2011
Platform Support: support@platform.com
Platform Information Development: doc@platform.com

Platform Computing. Accelerating Intelligence(TM).
Copyright © 2001-2009 Platform Computing Corporation. All rights reserved.