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

Platform Symphony 5.0 Java API Reference

com.platform.symphony.soam
Interface Session


public interface Session

Acts as a conduit for tasks being submitted to the service instances. Enables the client to manage its workload.

Created by invoking Connection.createSession. You can specify the following attributes when creating your Session:

  • session name - This is just a name for your session, so that it can be easily identified. Maximum 1024 characters. Default session name is "".
  • session type - This argument tells Symphony which type of session to create. In the application profile, you can define different types of sessions with different attributes. For this argument, specify the name of the session type you would like to use. Default value is "".
  • session flags - This argument tells Symphony how you would like to send and receive task results for the session. Default value is Session.RECEIVE_SYNC, which means that you will send and receive your task results synchronously.
  • session callback - This argument allows you to provide a SessionCallback object, which is a handler that allows you to process your session's task results asynchronously. This argument should only be provided when you have set the appropriate session flag argument to indicate that you will be receiving task results asynchronously. Default value is null - no session callback.
  • common data - This argument allows you do provide common data to the session. Common data is any data that is common to all of the tasks in your session. You can send common data rather than sending duplicate data to each task, and thus save on network overhead. Default value is null - no common data.
  • See Also:
    Connection, Connection.createSession(SessionCreationAttributes)

    Field Summary
    static long FETCH_RESULTS_DIRECTLY
              This informs the API that the client expects that results will only be returned to the middleware upon the explicit request of the client.
    static long PARTIAL_ASYNC
              Flag to indicate that the Session will send its input synchronously, but receive its output asynchronously.
    static long RECEIVE_ASYNC
              Flag to indicate that the client expects the result of its computation to be returned to the client in an asynchronous manner.
    static long RECEIVE_SYNC
              Flag to indicate that the client expects the result of its computation to be returned in a synchronous manner.
    static long SEND_OVERLAPPED
              Flag to indicate that the client requires the submission of input to be in an overlapped manner.
    static long SEND_SYNC
              Flag to indicate that the client requires the submission of input to be in a synchonous manner.
    static long SYNC
              Flag to indicate that the Session will send its input and receive its output synchronously.
     
    Method Summary
     void close()
              Closes this Session (mandatory).
     void close(long closeFlags)
              Closes this Session (mandatory).
     EnumItems fetchTaskOutput(long countMax)
              Blocks indefinitely until countMax task responses are ready.
     EnumItems fetchTaskOutput(long countMax, int timeoutInSeconds)
              If countMax task responses are ready before the timeout occurs, this method will return with all countMax responses as soon as they are available; otherwise, this method will block for up to timeoutInSeconds seconds and return with the responses that are available at timeout (will be between 0 and countMax responses, inclusive).
     EnumItems fetchTaskOutput(TaskOutputFilter filter)
              Retrieves the task outputs that match the specified filter.
     EnumItems fetchTaskOutput(TaskOutputFilter filter, int timeoutInSeconds)
              Retrieves the task outputs that match the specified filter.
     java.lang.String getId()
              Returns the identier for this Session.
     TaskInputHandle sendTaskInput(Message taskInput)
              Delivers the provided task input message to the middleware.
     TaskInputHandle sendTaskInput(Message taskInput, boolean hasPriority)
              Delivers the provided task input message to the middleware.
     TaskInputHandle sendTaskInput(java.io.Serializable inputObj)
              Delivers the provided task input object to the middleware.
     TaskInputHandle sendTaskInput(java.io.Serializable inputObj, boolean hasPriority)
              Delivers the provided task input object to the middleware.
     TaskInputHandle sendTaskInput(TaskSubmissionAttributes attributes)
              Delivers the provided task input attributes to the middleware.
     void update(SessionUpdateAttributes attributes)
              \brief Updates the session with the provided attributes.
     void updatePriority(int priority)
              Updates the session with the provided priority.
     

    Field Detail

    SEND_SYNC

    static final long SEND_SYNC
    Flag to indicate that the client requires the submission of input to be in a synchonous manner. This means that the call to Session.sendTaskInput() will block the client's thread until it recieves a confirmation from the middleware that the input has been safely received.

    See Also:
    Constant Field Values

    SEND_OVERLAPPED

    static final long SEND_OVERLAPPED
    Flag to indicate that the client requires the submission of input to be in an overlapped manner. This means that the call to Session.sendTaskInput will *not* block the client's thread. The client is then free send the next task immediately and get the status of the submission of the input at a later time from the returned TaskInputHandle object.

    See Also:
    Constant Field Values

    FETCH_RESULTS_DIRECTLY

    static final long FETCH_RESULTS_DIRECTLY
    This informs the API that the client expects that results will only be returned to the middleware upon the explicit request of the client. By default the API will cache results as they are returned from the Symphony Session Manager to boost the performance of results retrieval. Developers are strongly encouraged to fetch their results in small increments once this flag is enabled to reduce any impact to the overall performance of the Middleware during the handling of the fetch request. Note that this flag is intended for usage with the RECEIVE_SYNC flag.
    e.g. you may create a session which will retrieve results synchronously as follows;

         // Set up session creation attributes
         SessionCreationAttributes attributes = new SessionCreationAttributes();
         attributes.setSessionName("mySession");
         attributes.setSessionType("ShortRunningTasks");
         attributes.setSessionFlags(RECEIVE_SYNC | FETCH_RESULTS_DIRECTLY);

         // Now create session
         session = connection.createSession(attributes);

    See Also:
    fetchTaskOutput(long), Constant Field Values

    RECEIVE_SYNC

    static final long RECEIVE_SYNC
    Flag to indicate that the client expects the result of its computation to be returned in a synchronous manner. This means that the client is expected to use the Session.fetchTaskOutput() method to retrieve the output.

    See Also:
    Constant Field Values

    RECEIVE_ASYNC

    static final long RECEIVE_ASYNC
    Flag to indicate that the client expects the result of its computation to be returned to the client in an asynchronous manner. This means that the client is expected to provide a callback object which will be invoked each time a result is available.

    See Also:
    Constant Field Values

    SYNC

    static final long SYNC
    Flag to indicate that the Session will send its input and receive its output synchronously.

    See Also:
    Constant Field Values

    PARTIAL_ASYNC

    static final long PARTIAL_ASYNC
    Flag to indicate that the Session will send its input synchronously, but receive its output asynchronously.

    See Also:
    Constant Field Values
    Method Detail

    getId

    java.lang.String getId()
                           throws SoamException
    Returns the identier for this Session. This identifier can be used to allow another client to attach to this Session.

    Returns:
    The identier for this Session
    Throws:
    SoamException

    sendTaskInput

    TaskInputHandle sendTaskInput(TaskSubmissionAttributes attributes)
                                  throws SoamException
    Delivers the provided task input attributes to the middleware. This method will block until the client receives acknowledgement from the middleware that the input attributes has been safely accepted. Upon receiving this acknowledgement, a task ID will be returned through a TaskInputHandle.

    For more details, please refer to the Application Development Guide.

    Parameters:
    attributes - The task input attributes to be sent through Symphony to the service.
    Returns:
    A handle to the submitted task input object
    Throws:
    SoamException
    See Also:
    TaskInputHandle

    sendTaskInput

    TaskInputHandle sendTaskInput(java.io.Serializable inputObj)
                                  throws SoamException
    Delivers the provided task input object to the middleware. This method will block until the client receives acknowledgement from the middleware that the input object has been safely accepted. Upon receiving this acknowledgement, a task ID will be returned through a TaskInputHandle.

    IMPORTANT NOTE:
    This sendTaskInput overload uses Native Serialization. That is, it sends your task input to the service as a java.io.Serializable. If you send your task input using this overload, you must retrieve your task input on the service with the TaskContext.getTaskInput() method.

    If you are concerned with performance or memory usage, do not use this method to send your task input. Instead, use another sendTaskInput overload to send your task input as a com.platform.symphony.soam.Message using Symphony Serialization.

    For more details, please refer to the Application Development Guide.

    Parameters:
    inputObj - The task input object to be sent through Symphony to the service.
    Returns:
    A handle to the submitted task input object
    Throws:
    SoamException
    See Also:
    TaskInputHandle, TaskContext.getTaskInput()

    sendTaskInput

    TaskInputHandle sendTaskInput(Message taskInput)
                                  throws SoamException
    Delivers the provided task input message to the middleware. This method will block until the client receives acknowledgement from the middleware that the input message has been safely accepted. Upon receiving this acknowledgement, a task ID will be returned through a TaskInputHandle.

    IMPORTANT NOTE:
    This sendTaskInput overload uses Symphony Serialization. That is, it sends your task input to the service as a com.platform.symphony.soam.Message. If you send your task input using this overload, you must retrieve your task input on the service with the TaskContext.populateTaskInput(Message) method.

    By using Symphony Serialization, this overload provides best performance and memory usage for sending task input.

    For more details, please refer to the Application Development Guide.

    Parameters:
    taskInput - The input message to be sent through Symphony to the service.
    Returns:
    A handle to the submitted task input
    Throws:
    SoamException
    See Also:
    TaskInputHandle, TaskContext.populateTaskInput(com.platform.symphony.soam.Message)

    sendTaskInput

    TaskInputHandle sendTaskInput(java.io.Serializable inputObj,
                                  boolean hasPriority)
                                  throws SoamException
    Delivers the provided task input object to the middleware. This method will block until the client receives acknowledgement from the middleware that the input object has been safely accepted. Upon receiving this acknowledgement, a task ID will be returned through a TaskInputHandle.

    IMPORTANT NOTE:
    This sendTaskInput overload uses Native Serialization. That is, it sends your task input to the service as a java.io.Serializable. If you send your task input using this overload, you must retrieve your task input on the service with the TaskContext.getTaskInput() method.

    If you are concerned with performance or memory usage, do not use this method to send your task input. Instead, use another sendTaskInput overload to send your task input as a com.platform.symphony.soam.Message using Symphony Serialization.

    For more details, please refer to the Application Development Guide.

    Parameters:
    inputObj - The task input object to be sent through Symphony to the service.
    hasPriority - This is used to indicate to the Middleware if the message being submitted should take priority in the current session. When set to "true" the message will be used to create a task which will be placed at the front of the dispatch queue. When set to "false" the newly created task will be placed at the rear of the dispatch queue (this is the default behavior when the overloaded form of the method is used without specifying this parameter).
    Returns:
    A handle to the submitted task input object
    Throws:
    SoamException
    See Also:
    TaskInputHandle, TaskContext.getTaskInput()

    sendTaskInput

    TaskInputHandle sendTaskInput(Message taskInput,
                                  boolean hasPriority)
                                  throws SoamException
    Delivers the provided task input message to the middleware. This method will block until the client receives acknowledgement from the middleware that the input message has been safely accepted. Upon receiving this acknowledgement, a task ID will be returned through a TaskInputHandle.

    IMPORTANT NOTE:
    This sendTaskInput overload uses Symphony Serialization. That is, it sends your task input to the service as a com.platform.symphony.soam.Message. If you send your task input using this overload, you must retrieve your task input on the service with the TaskContext.populateTaskInput(Message) method.

    By using Symphony Serialization, this overload provides best performance and memory usage for sending task input.

    For more details, please refer to the Application Development Guide.

    Parameters:
    taskInput - The message to be sent through Symphony to the service.
    hasPriority - This is used to indicate to the Middleware if the message being submitted should take priority in the current session. When set to "true" the message will be used to create a task which will be placed at the front of the dispatch queue. When set to "false" the newly created task will be placed at the rear of the dispatch queue (this is the default behavior when the overloaded form of the method is used without specifying this parameter).
    Returns:
    A handle to the submitted task input
    Throws:
    SoamException
    See Also:
    TaskInputHandle, TaskContext.populateTaskInput(com.platform.symphony.soam.Message)

    fetchTaskOutput

    EnumItems fetchTaskOutput(long countMax)
                              throws SoamException
    Blocks indefinitely until countMax task responses are ready. The task responses will be returned as an enumeration.

    IMPORTANT NOTE:
    If your session was created using the FETCH_RESULTS_DIRECTLY flag then this method will not block indefinitely but instead will return with 0 - N items as soon as they are recieved from the Symphony Session Manager. The number of items returned will depend on the amount of available results in the Symphony Session Manager at the time of the call. Also, when the Session::FetchResultsDirectly flag is used, developers are strongly encouraged to fetch their results in small increments once this flag is enabled to reduce any impact to the overall performance of the Middleware during the handling of the fetch request.

    Parameters:
    countMax - The maximum number of task responses to be returned by Symphony. It must greater than or equal to 0.
    Returns:
    An EnumItems object, which contains exactly countMax task responses
    Throws:
    SoamException
    See Also:
    EnumItems

    fetchTaskOutput

    EnumItems fetchTaskOutput(TaskOutputFilter filter)
                              throws SoamException
    Retrieves the task outputs that match the specified filter. Blocks indefinitely until the fetch request is satisfied. The task responses will be returned as an enumeration. Any matched tasks in the resulting EnumItems will be removed from the filter once this method call returns.

    NOTE: This method is for use only if your session is created with the FETCH_RESULTS_DIRECTLY and RECEIVE_SYNC session flags.

    Parameters:
    filter - Describes which task outputs to retrieve.
    Returns:
    An EnumItems object that contains the returned task outputs.
    Throws:
    SoamException
    See Also:
    EnumItems, TaskOutputFilter

    fetchTaskOutput

    EnumItems fetchTaskOutput(TaskOutputFilter filter,
                              int timeoutInSeconds)
                              throws SoamException
    Retrieves the task outputs that match the specified filter. If a timeout of 0 seconds is specified and the full result set is not ready when the timeout interval expires, this method will return with a subset of the requested items. This subset can contain 0 or more items. Any matched tasks in the resulting EnumItems will be removed from the filter once this method call returns.

    NOTE: This method is for use only if your session is created with the FETCH_RESULTS_DIRECTLY and RECEIVE_SYNC session flags.

    Parameters:
    filter - Describes which task outputs to retrieve.
    timeoutInSeconds - Time to wait before giving up on trying to fulfill the request. Valid values are:
  • 0 : Return with the specified task outputs that are available right now.
  • Returns:
    An EnumItems object that contains the returned task outputs.
    Throws:
    SoamException
    See Also:
    EnumItems, TaskOutputFilter

    fetchTaskOutput

    EnumItems fetchTaskOutput(long countMax,
                              int timeoutInSeconds)
                              throws SoamException
    If countMax task responses are ready before the timeout occurs, this method will return with all countMax responses as soon as they are available; otherwise, this method will block for up to timeoutInSeconds seconds and return with the responses that are available at timeout (will be between 0 and countMax responses, inclusive).
    The task responses will be presented as an enumeration.

    IMPORTANT NOTE:
    If your session was created using the FETCH_RESULTS_DIRECTLY flag then the timeout will be ignored and the method will return with 0 - N items as soon as they are recieved from the Symphony Session Manager. The number of items returned will depend on the amount of available results in the Symphony Session Manager at the time of the call. Also, when the Session::FetchResultsDirectly flag is used, developers are strongly encouraged to fetch their results in small increments once this flag is enabled to reduce any impact to the overall performance of the Middleware during the handling of the fetch request.

    Parameters:
    countMax - The maximum number of task responses to be returned by Symphony. It must greater than or equal to 0.
    timeoutInSeconds - How much time should pass before giving up on trying to fulfill the request. Value must be between 0 and 31556926 seconds inclusive.
    Returns:
    An EnumItems object, which contains up to countMax task responses
    Throws:
    SoamException
    See Also:
    EnumItems

    close

    void close()
               throws SoamException
    Closes this Session (mandatory).

    Closing the session will result in the session being terminated within the middleware. Once a session is closed, no further operations can be performed on the session and all outstanding results will be discarded. ** NOTE : Never call close(...) during the execution of a callback method. This will result in a deadlock.

    IMPORTANT NOTE:

    This call is mandatory. If you do not close the session, you will introduce a resource leak.

    Throws:
    SoamException

    close

    void close(long closeFlags)
               throws SoamException
    Closes this Session (mandatory).

    IMPORTANT NOTE:

    This call is mandatory. If you do not close the session, you will introduce a resource leak. ** NOTE : Never call close(...) during the execution of a callback method. This will result in a deadlock.

    Parameters:
    closeFlags - This flag allows the client to specify explicitly what action to take during the closing of the session. The supported flags are as follows:
    • SessionCloseFlags.DESTROY_ON_CLOSE This informs the API that the client no longer intends to use the session. This is the default behaviour if the Session.close() overload is used. Closing the session in this way will result in the session being terminated within the middleware. All outstanding results will be discarded.
    • SessionCloseFlags.DETACH_ON_CLOSE 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. A client must call Connection.openSession to gain access to this session once it has been closed with this flag.
    Throws:
    SoamException
    See Also:
    SessionCloseFlags, Connection.openSession(SessionOpenAttributes)

    update

    void update(SessionUpdateAttributes attributes)
                throws SoamException
    \brief Updates the session with the provided attributes.

    Throws:
    SoamException

    updatePriority

    void updatePriority(int priority)
                        throws SoamException
    Updates the session with the provided priority.

    Note: The session priority can be any number between 1 and 10,000 (highest priority) inclusive.

    Parameters:
    priority - The priority to apply to the session upon update.
    Throws:
    SoamException

    Version 5.0
    Date Modified: -DREL_DATE=Nov 11 2009
    Platform Computing. Accelerating Intelligence(TM).
    Copyright (C) 2001-2009 Platform Computing Corporation. All rights reserved.