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

Platform Symphony 4.1 Java API Reference

com.platform.symphony.soam
Interface Connection


public interface Connection

Represents a physical connection between the client and the SOA middleware for an application. The client can communicate with the services of an application through this physical connection.

The Connection object can be created by invoking SoamFactory.connect.

After a connection has been established, a Session object can be created to manage the workload. Create a Session by invoking Connection.createSession.

See Also:
SoamFactory.connect(String), SoamFactory.connect(String, ConnectionSecurityCallback), SoamFactory.connect(String, String), SoamFactory.connect(String, String, ConnectionSecurityCallback), Session

Method Summary
 void close()
          Closes this Connection (mandatory).
 Session createSession()
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 Session createSession(SessionCreationAttributes attributes)
          Creates a Session on this Connection with the provided attributes.
 Session createSession(java.lang.String sessionName)
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 Session createSession(java.lang.String sessionName, java.lang.String sessionType)
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 Session createSession(java.lang.String sessionName, java.lang.String sessionType, long sessionFlags)
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 Session createSession(java.lang.String sessionName, java.lang.String sessionType, long sessionFlags, SessionCallback callback)
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 Session createSession(java.lang.String sessionName, java.lang.String sessionType, long sessionFlags, SessionCallback callback, Message commonData)
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 Session createSession(java.lang.String sessionName, java.lang.String sessionType, long sessionFlags, SessionCallback callback, java.io.Serializable commonData)
          Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)
 java.lang.String getId()
          Returns the identifier for this Connection.
 Session openSession(SessionOpenAttributes attributes)
          Opens an existing session with the provided attributes, and associates it with this connection.
 Session openSession(java.lang.String sessionId)
          Deprecated. As of Symphony 3.1, replaced by openSession(SessionOpenAttributes)
 Session openSession(java.lang.String sessionId, long sessionFlags)
          Deprecated. As of Symphony 3.1, replaced by openSession(SessionOpenAttributes)
 Session openSession(java.lang.String sessionId, long sessionFlags, SessionCallback callback)
          Deprecated. As of Symphony 3.1, replaced by openSession(SessionOpenAttributes)
 

Method Detail

getId

java.lang.String getId()
                       throws SoamException
Returns the identifier for this Connection.

Returns:
The connection identifier for this Connection
Throws:
SoamException

createSession

Session createSession(SessionCreationAttributes attributes)
                      throws SoamException
Creates a Session on this Connection with the provided attributes.

Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

Parameters:
attributes - The attributes to apply to the session upon creation.
Returns:
The created Session
Throws:
SoamException
See Also:
SessionCreationAttributes

createSession

Session createSession()
                      throws SoamException
Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

Creates a Session on this Connection with the default attributes.
  • session name - This is just a name for your session, so that the session 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. Symphony also defines a system default session type with the name "".
  • 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.


  • Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Returns:
    The created Session
    Throws:
    SoamException

    createSession

    Session createSession(java.lang.String sessionName)
                          throws SoamException
    Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

    Creates a Session on this Connection with the provided attributes. In addition, the following default attributes are applied:
  • 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. Symphony also defines a system default session type with the name "".
  • 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.


  • Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.
    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Parameters:
    sessionName - This is just a name for your session, so that the session can be easily identified. Maximum 1024 characters.
    Returns:
    The created Session
    Throws:
    SoamException

    createSession

    Session createSession(java.lang.String sessionName,
                          java.lang.String sessionType)
                          throws SoamException
    Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

    Creates a Session on this Connection with the provided attributes. In addition, the following default attributes are applied:
  • 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.


  • Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Parameters:
    sessionName - This is just a name for your session, so that the session can be easily identified. Maximum 1024 characters.
    sessionType - This argument tells Symphony which type of session to create. In the application profile, you can define different types of sessions with different attributes. Symphony also defines a system default session type with the name "". For this argument, specify the name of the session type you would like to use. An exception will be thrown if a session type is specified that is not defined.
    Returns:
    The created Session
    Throws:
    SoamException

    createSession

    Session createSession(java.lang.String sessionName,
                          java.lang.String sessionType,
                          long sessionFlags)
                          throws SoamException
    Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

    Creates a Session on this Connection with the provided attributes. In addition, the following default attributes are applied:
  • 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.


  • Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Parameters:
    sessionName - This is just a name for your session, so that the session can be easily identified.
    sessionType - This argument tells Symphony which type of session to create. In the application profile, you can define different types of sessions with different attributes. Symphony also defines a system default session type with the name "". For this argument, specify the name of the session type you would like to use. An exception will be thrown if a session type is specified that is not defined.
    sessionFlags - This argument tells Symphony how you would like to receive task results for the session. See the com.platform.symphony.soam.Session object for explanation of flags and their usage.
    Returns:
    The created Session
    Throws:
    SoamException
    See Also:
    Session

    createSession

    Session createSession(java.lang.String sessionName,
                          java.lang.String sessionType,
                          long sessionFlags,
                          SessionCallback callback)
                          throws SoamException
    Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

    Creates a Session on this Connection with the provided attributes. In addition, the following default attributes are applied:
  • 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.


  • Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Parameters:
    sessionName - This is just a name for your session, so that the session can be easily identified.
    sessionType - This argument tells Symphony which type of session to create. In the application profile, you can define different types of sessions with different attributes. Symphony also defines a system default session type with the name "". For this argument, specify the name of the session type you would like to use. An exception will be thrown if a session type is specified that is not defined.
    sessionFlags - This argument tells Symphony how you would like to receive task results for the session. See the com.platform.symphony.soam.Session object for explanation of flags and their usage.
    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.
    Returns:
    The created Session
    Throws:
    SoamException
    See Also:
    Session

    createSession

    Session createSession(java.lang.String sessionName,
                          java.lang.String sessionType,
                          long sessionFlags,
                          SessionCallback callback,
                          Message commonData)
                          throws SoamException
    Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

    Creates a Session on this Connection with the provided attributes.

    Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Parameters:
    sessionName - This is just a name for your session, so that your session can be easily identified.
    sessionType - This argument tells Symphony which type of session to create. In the application profile, you can define different types of sessions with different attributes. Symphony also defines a system default session type with the name "". For this argument, specify the name of the session type you would like to use. An exception will be thrown if a session type is specified that is not defined.
    sessionFlags - This argument tells Symphony how you would like to receive task results for the session. See the com.platform.symphony.soam.Session object for explanation of flags and their usage.
    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.
    commonData - 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.

    IMPORTANT NOTE:
    This createSession overload uses Symphony Serialization. That is, it sends your common data to the service as a com.platform.symphony.soam.Message. If you send your common data using this overload, you must retrieve your common data on the service with the SessionContext.populateCommonData(Message) method.

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

    For more details, please refer to the Application Development Guide.
    Returns:
    The created Session
    Throws:
    SoamException
    See Also:
    SessionContext.populateCommonData(com.platform.symphony.soam.Message), Session

    createSession

    Session createSession(java.lang.String sessionName,
                          java.lang.String sessionType,
                          long sessionFlags,
                          SessionCallback callback,
                          java.io.Serializable commonData)
                          throws SoamException
    Deprecated. As of Symphony 3.1, replaced by createSession(SessionCreationAttributes)

    Creates a Session on this Connection with the provided attributes.

    Note: For recoverable sessions, all submissions will wait for a special confirmation from the middleware that the submission has been stored in a manner that it can be recovered. This means that the submission times may be longer than those of non-recoverable sessions.

    Create a recoverable session by setting the recoverable flag "true" in the Application Profile.

    Parameters:
    sessionName - This is just a name for your session, so that your session can be easily identified.
    sessionType - This argument tells Symphony which type of session to create. In the application profile, you can define different types of sessions with different attributes. Symphony also defines a system default session type with the name "". For this argument, specify the name of the session type you would like to use. An exception will be thrown if a session type is specified that is not defined.
    sessionFlags - This argument tells Symphony how you would like to receive task results for the session. See the com.platform.symphony.soam.Session object for explanation of flags and their usage.
    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.
    commonData - 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.

    IMPORTANT NOTE:
    This createSession overload uses Native Serialization. That is, it sends your common data to the service as a java.io.Serializable. If you send your common data using this overload, you must retrieve your common data on the service with the SessionContext.getCommonData() method.

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

    For more details, please refer to the Application Development Guide.
    Returns:
    The created Session
    Throws:
    SoamException
    See Also:
    SessionContext.getCommonData(), Session

    openSession

    Session openSession(SessionOpenAttributes attributes)
                        throws SoamException
    Opens an existing session with the provided attributes, and associates it with this connection.

    IMPORANT NOTE: Since a session can only be associated with one connection at a time, if the session being opened is already associated with a different connection, the open request will succeed and the session will now be associated with the new connection. The client which had the session opened prior to this new open request will be disconnected from the session and an exception will be returned to that client indicating the transfer of the association.

    Parameters:
    attributes - The attributes to apply to the session upon opening.
    Returns:
    The Session.
    Throws:
    SoamException
    See Also:
    SessionOpenAttributes, SoamFactory.connect(String), SoamFactory.connect(String, ConnectionSecurityCallback), SoamFactory.connect(String, String), SoamFactory.connect(String, String, ConnectionSecurityCallback)

    openSession

    Session openSession(java.lang.String sessionId)
                        throws SoamException
    Deprecated. As of Symphony 3.1, replaced by openSession(SessionOpenAttributes)

    Opens an existing session with the default attributes.
  • 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.


  • The session will be associated with this Connection

    IMPORANT NOTE: Since a session can only be associated with one connection at a time, if the session being opened is already associated with a different connection, the open request will succeed and the session will now be associated with the new connection. The client which had the session opened prior to this new open request will be disconnected from the session and an exception will be returned to that client indicating the transfer of the association.

    Parameters:
    sessionId - The session identifier.
    Returns:
    The Session.
    Throws:
    SoamException
    See Also:
    SoamFactory.connect(String), SoamFactory.connect(String, ConnectionSecurityCallback), SoamFactory.connect(String, String), SoamFactory.connect(String, String, ConnectionSecurityCallback)

    openSession

    Session openSession(java.lang.String sessionId,
                        long sessionFlags)
                        throws SoamException
    Deprecated. As of Symphony 3.1, replaced by openSession(SessionOpenAttributes)

    Opens an existing session with the provided attributes. In addition, the following default attributes are applied:
  • 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.


  • The session will be associated with this Connection

    IMPORANT NOTE: Since a session can only be associated with one connection at a time, if the session being opened is already associated with a different connection, the open request will succeed and the session will now be associated with the new connection. The client which had the session opened prior to this new open request will be disconnected from the session and an exception will be returned to that client indicating the transfer of the association.

    Parameters:
    sessionId - The session identifier.
    sessionFlags - This argument tells Symphony how you would like to receive task results for the session. See the com.platform.symphony.soam.Session object for explanation of flags and their usage.
    Returns:
    The Session.
    Throws:
    SoamException
    See Also:
    SoamFactory.connect(String), SoamFactory.connect(String, ConnectionSecurityCallback), SoamFactory.connect(String, String), SoamFactory.connect(String, String, ConnectionSecurityCallback), Session

    openSession

    Session openSession(java.lang.String sessionId,
                        long sessionFlags,
                        SessionCallback callback)
                        throws SoamException
    Deprecated. As of Symphony 3.1, replaced by openSession(SessionOpenAttributes)

    Opens an existing session with the provided attributes.

    The session will be associated with this Connection

    Parameters:
    sessionId - The session identifier.
    sessionFlags - This argument tells Symphony how you would like to receive task results for the session. See the com.platform.symphony.soam.Session object for explanation of flags and their usage.
    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.
    Returns:
    The Session.
    Throws:
    SoamException
    See Also:
    SoamFactory.connect(String), SoamFactory.connect(String, ConnectionSecurityCallback), SoamFactory.connect(String, String), SoamFactory.connect(String, String, ConnectionSecurityCallback), SessionCallback

    close

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

    Closing the connection will result in the the logical connection between the client and the middleware to become broken. Once a connection is closed no further operations can be performed on the connection and all open sessions will be aborted by the middleware. ** 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 connection, you will introduce a resource leak.

    Throws:
    SoamException

    Version 4.1
    Date Modified: -DREL_DATE=Nov 03 2008
    Platform Computing. Accelerating Intelligence(TM).
    Copyright (C) 2001-2008 Platform Computing Corporation. All rights reserved.