com.spss.psapi.session

Interface Session

  • All Superinterfaces:
    SystemSession


    public interface Session
    extends SystemSession
    A session is the main interface through which users of the Modeler API access the API features. Each session has its own connection to a data mining server.

    A data mining server is typically a remote server identified by a ServerConnectionDescriptor. From Modeler API 2.0 a server can also be a local server instance spawned as a child process of the Modeler API host process (see connect()). This local server mode requires a local server installation, such as a Modeler client installation, on the local machine. The installation directory is located through the system property

     com.spss.psapi.session.serverInstallationDirectory
     
    This property must point to a valid installation directory and must be set before the session factory is instantiated otherwise connections to the local server will fail.
    Since:
    PSAPI 1.0
    Version:
    1.2
    Author:
    Julian Clinton, Rob Duncan
    Specification Status:
    Under Development
    • Method Detail

      • close

        void close()
        Closes this session. This automatically interrupts any task currently running, closes any current ProcessorStream and invalidates any other objects created by this session.
        See Also:
        isClosed()
      • isClosed

        boolean isClosed()
        Returns true if this has been closed.
        Returns:
        true if this has been closed
        See Also:
        close()
      • connect

        void connect(ServerConnectionDescriptor serverDescriptor)
                     throws ServerConnectionException
        Connects this session to the remote server identified by the specified server descriptor.
        Parameters:
        serverDescriptor - identifies a remote data mining server
        Throws:
        ServerConnectionException - if a connection to the server cannot be established or if the Session already has a connection
      • connect

        void connect()
                     throws ServerConnectionException
        Connects this session to a local server instance. Spawns a new local server process.
        Throws:
        ServerConnectionException - if a local server instance cannot be created or if the session already has a connection
        Since:
        PSAPI 2.0
      • isConnected

        boolean isConnected()
        Returns true if this session has a server connection.
        Returns:
        true if this session has a server connection
      • getServerConnectionDescriptor

        ServerConnectionDescriptor getServerConnectionDescriptor()
        Returns the ServerConnectionDescriptor used to connect this session to a remote server. Returns null if the session is connected to a local server or has not yet been connected.
        Returns:
        the ServerConnectionDescriptor used to connect this session to a remote server or null
      • createProcessorStream

        ProcessorStream createProcessorStream(java.lang.String name)
                                              throws ServerConnectionException
        Deprecated. 
        Creates and returns a new ProcessorStream. If the session is connected to a server then the stream will also be connected to the server. This is the same as calling createProcessorStream(name, autoConnect) with the autoConnect set to true.

        This method is deprecated, please use TaskRunner.createStream().

        Parameters:
        name - the object's name
        Returns:
        a new ProcessorStream
        Throws:
        ServerConnectionException - if the Session is already connected but a new connection could not be created for the stream
        See Also:
        TaskRunner.createStream(String, boolean, boolean), getTaskRunner()
      • runTask

        ExecutionHandle runTask(Task task)
                                throws OwnerException,
                                       ObjectLockedException,
                                       SessionException
        Executes the supplied task synchronously and waits for it to complete. Returns an ExecutionHandle which can be used to access the exit status and any result from the task.
        Parameters:
        task - the Task to be executed
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the task was not created by this session's TaskFactory
        ObjectLockedException - if the task is already executing or any object referenced by the task is locked for updating
        SessionException - if the session cannot execute the task or if execution completes in a state other than SUCCESS
        Since:
        PSAPI 1.2
      • spawnTask

        ExecutionHandle spawnTask(Task task)
                                  throws OwnerException,
                                         ObjectLockedException
        Executes the supplied task asynchronously. Returns an ExecutionHandle which can be used to monitor and control the progress of the task.
        Parameters:
        task - the Task to be executed
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the task was not created by this session's TaskFactory
        ObjectLockedException - if the task is already executing or any object referenced by the task is locked for updating
      • run

        ExecutionHandle run(Processor[] nodes,
                          java.util.Collection results)
                            throws OwnerException,
                                   ObjectLockedException,
                                   ServerConnectionException,
                                   SessionException
        Executes the supplied array of nodes synchronously and waits for them to complete. There must be at least one node in the array. Returns an ExecutionHandle which can be used to access the exit status and any result from the task.
        Parameters:
        nodes - the array of Processor objects to be executed
        results - an empty collection that will contain any built objects once execution has completed
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the nodes' stream was not created by this session or the nodes are not all owned by the same stream
        ObjectLockedException - if the nodes' owner stream is locked
        ServerConnectionException - if the nodes' stream is not connected to a server
        SessionException - if the session is already running another task, cannot execute the task or if execution completes in a state other than SUCCESS
        java.lang.IllegalArgumentException - if the array is empty
        Since:
        PSAPI 1.2
      • spawn

        ExecutionHandle spawn(Processor[] nodes,
                            java.util.Collection builtObjects)
                              throws OwnerException,
                                     ObjectLockedException,
                                     ServerConnectionException
        Executes the supplied array of nodes asynchronously. Returns an ExecutionHandle which can be used to monitor and control the progress of the task. There must be at least one node in the array.
        Parameters:
        nodes - the array of Processor objects to be executed
        builtObjects - an empty collection that will be populated by built objects created by the execution
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the nodes' stream was not created by this session or the nodes are not all owned by the same stream
        ObjectLockedException - if the nodes' stream is locked
        ServerConnectionException - if the nodes' stream is not connected to a server
        java.lang.IllegalArgumentException - if the array is empty
      • publish

        ExecutionHandle publish(DataWriter node)
                                throws OwnerException,
                                       ObjectLockedException,
                                       ServerConnectionException,
                                       SessionException
        Executes the specified DataWriter in publish mode to obtain a PublishedImage. This overrides the execution mode set in the node and retrieves the published image from the server on completion. Execution is synchronous. The result is an ExecutionHandle which can be used to determine the exit status of the task and, if the task completes successfully, to obtain the result of the task which is a PublishedImage.
        Parameters:
        node - the DataWriter to be published
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the node was not created by this session
        ObjectLockedException - if the node or its containing stream is locked
        ServerConnectionException - if the stream is not connected to a server
        SessionException - if the session is already running another task, or cannot execute the task for some other reason, or if execution completes in a state other than SUCCESS
        Since:
        PSAPI 12.0
      • spawnPublish

        ExecutionHandle spawnPublish(DataWriter node)
                                     throws OwnerException,
                                            ObjectLockedException,
                                            ServerConnectionException
        Executes the specified DataWriter asynchronously in publish mode to obtain a PublishedImage. This overrides the execution mode set in the node and retrieves the published image from the server on completion. Returns an ExecutionHandle which can be used to monitor and control the progress of the publishing task and, if it completes successfully, to obtain the task result which is a PublishedImage.
        Parameters:
        node - the DataWriter to be published
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the node was not created by this session
        ObjectLockedException - if the node or its containing stream is locked
        ServerConnectionException - if the stream is not connected to a server
        Since:
        PSAPI 13.0.4
      • publish

        ExecutionHandle publish(TerminalProcessor node,
                              boolean inline)
                                throws OwnerException,
                                       ObjectLockedException,
                                       ServerConnectionException,
                                       SessionException
        Executes the specified node in publish mode to obtain a PublishedImage ready for inline scoring.

        If inline is false, this is equivalent to calling publish(DataWriter) and the node must be a data writer. Otherwise, the node may be any terminal node and the stream is modified in place to replace the input and output nodes with ones suitable for inline scoring.

        Execution is synchronous. The result is an ExecutionHandle which can be used to determine the exit status of the publishing task and, if the task completes successfully, to obtain the result of the task which is a PublishedImage.

        Parameters:
        node - the TerminalProcessor to be published. Must be a DataWriter if not publishing inline
        inline - true to prepare the image for inline scoring
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the node was not created by this session
        ObjectLockedException - if the node or its containing stream is locked
        ServerConnectionException - if the stream is not connected to a server
        SessionException - if the session is already running another task, or cannot execute the task for some other reason, or if the stream cannot be prepared for inline scoring, or if execution completes in a state other than SUCCESS
        Since:
        PSAPI 13.0
      • spawnPublish

        ExecutionHandle spawnPublish(TerminalProcessor node,
                                   boolean inline)
                                     throws OwnerException,
                                            ObjectLockedException,
                                            ServerConnectionException,
                                            SessionException
        Executes the specified node asynchronously in publish mode to obtain a PublishedImage ready for inline scoring.

        If inline is false, this is equivalent to calling publish(DataWriter) and the node must be a data writer. Otherwise, the node may be any terminal node and the stream is modified in place to replace the input and output nodes with ones suitable for inline scoring.

        Returns an ExecutionHandle which can be used to monitor and control the progress of the publishing task and, if it completes successfully, to obtain the task result which is a PublishedImage.

        Parameters:
        node - the TerminalProcessor to be published. Must be a DataWriter if not publishing inline
        inline - true to prepare the image for inline scoring
        Returns:
        a handle on the execution task
        Throws:
        OwnerException - if the node was not created by this session
        ObjectLockedException - if the node or its containing stream is locked
        ServerConnectionException - if the stream is not connected to a server
        SessionException - if the stream cannot be prepared for inline scoring
        Since:
        PSAPI 13.0.4
      • getServerDataSourceNames

        RowSet getServerDataSourceNames()
                                        throws ServerConnectionException,
                                               ServerResourceException
        Returns a row set that lists the available system DSNs visible on the data mining server host. The list is returned in the form of a row set where the first column contains the data source name as a string and the second column contains a string description.
        Returns:
        the set of system DSNs visible on data mining server host
        Throws:
        ServerConnectionException - if the session is not connected to a server
        ServerResourceException - if access to the server data sources was denied
      • createServerDatabaseConnection

        ServerDatabaseConnection createServerDatabaseConnection(java.lang.String datasourceName,
                                                              java.lang.String credentialName,
                                                              java.lang.String catalogName)
                                                                throws ServerConnectionException,
                                                                       ServerResourceException
        Creates a ServerDatabaseConnection. The datasource name must visible to the data mining server.
        Parameters:
        datasourceName - the datasource name
        credentialName - the stored credential name
        catalogName - the catalog name
        Returns:
        a ServerDatabaseConnection
        Throws:
        ServerConnectionException - if the session is not connected to a server
        ServerResourceException - if the connection task fails.
      • createServerDatabaseConnection

        ServerDatabaseConnection createServerDatabaseConnection(java.lang.String datasourceName,
                                                              java.lang.String userName,
                                                              java.lang.String password,
                                                              java.lang.String catalogName)
                                                                throws ServerConnectionException,
                                                                       ServerResourceException
        Creates a ServerDatabaseConnection. The datasource name must visible to the data mining server.
        Parameters:
        datasourceName - the datasource name
        userName - the user name
        password - the password
        catalogName - the catalog name
        Returns:
        a ServerDatabaseConnection
        Throws:
        ServerConnectionException - if the session is not connected to a server
        ServerResourceException - if the connection task fails.
      • addExecutionStateListener

        void addExecutionStateListener(ExecutionStateListener listener)
        Adds the specified execution state listener to this session.
        Parameters:
        listener - the listener to be added
      • removeExecutionStateListener

        void removeExecutionStateListener(ExecutionStateListener listener)
        Removes the specified execution state listener from this session.
        Parameters:
        listener - the listener to be removed
      • addExecutionFeedbackListener

        void addExecutionFeedbackListener(ExecutionFeedbackListener listener)
        Adds the specified execution feedback listener to this session.
        Parameters:
        listener - the listener to be added
      • removeExecutionFeedbackListener

        void removeExecutionFeedbackListener(ExecutionFeedbackListener listener)
        Removes the specified execution feedback listener from this session.
        Parameters:
        listener - the listener to be removed
      • isBusy

        boolean isBusy()
        Returns true if this session is currently executing a synchronous task (even if the task is in the process of being interrupted).

        This method may be called from any thread.

        Returns:
        true if this session is executing a synchronous task
        See Also:
        interrupt()
      • interrupt

        void interrupt()
        Interrupts any synchronous task which is currently executing. The call returns immediately while the task is interrupted. It has no effect if the session is not busy.

        This method may be called from any thread.

        See Also:
        isBusy()
      • getRowSetFactory

        RowSetFactory getRowSetFactory()
        Returns the RowSetFactory for this session.
        Returns:
        the RowSetFactory
        See Also:
        RowSetFactory
      • getTaskFactory

        TaskFactory getTaskFactory()
        Returns the TaskFactory for this session.
        Returns:
        the TaskFactory
        See Also:
        TaskFactory
      • getTaskRunner

        TaskRunner getTaskRunner()
        Returns the TaskRunner for this session.
        Returns:
        the TaskRunner
        See Also:
        TaskRunner
      • getOutputFactory

        OutputFactory getOutputFactory()
        Returns the OutputFactory for this session.
        Returns:
        the OutputFactory
        Since:
        PSAPI 2.0
        See Also:
        OutputFactory
      • getServerCatalogManager

        ServerCatalogManager getServerCatalogManager()
        Returns the server catalog manager for this session
        Returns:
        the server catalog manager
      • getAttribute

        java.lang.Object getAttribute(java.lang.String name)
        Returns the value of the specified attribute in this session, or null if there is no such attribute. Attributes are created by the application, not by the Modeler API.
        Parameters:
        name - an attribute name
        Returns:
        the attribute value
        Since:
        PSAPI 13.0.4
      • setAttribute

        void setAttribute(java.lang.String name,
                        java.lang.Object value)
        Assigns a value to the specified attribute in this session. If the attribute already has a value, it is replaced. If the value is null, the attribute is deleted from the session.
        Parameters:
        name - an attribute name
        value - the attribute value
        Since:
        PSAPI 13.0.4
      • removeAttribute

        void removeAttribute(java.lang.String name)
        Deletes the specified attribute from this session. If there is no such attribute, the call has no effect.
        Parameters:
        name - an attribute name
        Since:
        PSAPI 13.0.4
      • getAttributeNames

        java.util.Collection<java.lang.String> getAttributeNames()
        Returns the names of the attributes defined in this session.
        Returns:
        a collection of attribute names
        Since:
        PSAPI 13.0.4
      • waitForAllTasksToFinish

        void waitForAllTasksToFinish()
        Waits for all tasks in progress on this session to complete.
      • getUIResources

        UIResources getUIResources()
        Returns the interface that provides access to UI-related resources.
        Returns:
        the UI resources
        Since:
        PSAPI 15.0.0.1
      • getServerVersionInfo

        ServerVersionInfo getServerVersionInfo()
        Returns information about the connected server version or null if the session is not connected.
        Returns:
        the server version
        Since:
        PSAPI 15.0.0.1
      • getRepository

        Repository getRepository()
        Returns the repository object that provides simple mechanisms for storing and retrieving objects.
        Returns:
        the repository
        Since:
        PSAPI 16.0
      • getParameters

        ParameterProvider getParameters()
        Returns the parameter provider for this session. The parameter provider provides access to session parameters.
        Returns:
        the session parameter provider
        Since:
        PSAPI 16.0
      • getParser

        Parser getParser()
        Returns the shared parser for this session
        Returns:
        the parser
        Since:
        PSAPI 17.0

Copyright © 2014 Integral Solutions Ltd. All Rights Reserved.