Session Objects

Subclass of 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.

s.close()

Closes this session. This automatically interrupts any task currently running, closes any current Stream and invalidates any other objects created by this session.

s.connect(serverDescriptor)

serverDescriptor (ServerConnectionDescriptor) : identifies a remote data mining server

Connects this session to the remote server identified by the specified server descriptor.

Exceptions:

ServerConnectionException : if a connection to the server cannot be established or if the Session already has a connection

s.connect()

Connects this session to a local server instance. Spawns a new local server process.

Exceptions:

ServerConnectionException : if a local server instance cannot be created or if the session already has a connection

s.connect(stream)

stream (Stream) : the stream to be connected

Connects the stream to the session's server.

Exceptions:

ServerConnectionException : if the Session is not connected or if the stream is already connected

OwnerException : if the stream was not created by this session

s.createServerDatabaseConnection(datasourceName, credentialName, catalogName) : 
  ServerDatabaseConnection

datasourceName (string) : the datasource name

credentialName (string) : the stored credential name

catalogName (string) : the catalog name

Creates a ServerDatabaseConnection. The datasource name must visible to the data mining server.

Exceptions:

ServerConnectionException : if the session is not connected to a server

ServerResourceException : if the connection task fails.

s.createServerDatabaseConnection(datasourceName, userName, password, catalogName) : 
  ServerDatabaseConnection

datasourceName (string) : the datasource name

userName (string) : the user name

password (string) : the password

catalogName (string) : the catalog name

Creates a ServerDatabaseConnection. The datasource name must visible to the data mining server.

Exceptions:

ServerConnectionException : if the session is not connected to a server

ServerResourceException : if the connection task fails.

s.getASCredentialDescriptor() : ASCredentialDescriptor

Returns the credential descriptor used to log in to the Analytic Server.

s.getAttribute(name) : Object

name (string) : an attribute name

Returns the value of the specified attribute in this session, or None if there is no such attribute. Attributes are created by the application, not by the Modeler API.

s.getAttributeNames() : Collection

Returns the names of the attributes defined in this session.

s.getParameters() : ParameterProvider

Returns the parameter provider for this session. The parameter provider provides access to session parameters.

s.getParser() : Parser

Returns the shared parser for this session.

s.getRepository() : Repository

Returns the repository object that provides simple mechanisms for storing and retrieving objects.

s.getRepositoryConnectionDescriptor() : RepositoryConnectionDescriptor

Returns the repository connection descriptor.

s.getServerConnectionDescriptor() : ServerConnectionDescriptor

Returns the ServerConnectionDescriptor used to connect this session to a remote server. Returns None if the session is connected to a local server or has not yet been connected.

s.getServerDataSourceNames() : RowSet

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.

Exceptions:

ServerConnectionException : if the session is not connected to a server

ServerResourceException : if access to the server data sources was denied

s.getServerFileSystem() : ServerFileSystem

Returns the server file system.

Exceptions:

ServerConnectionException : if the session is not connected to a server

ServerResourceException : if access to the server file system was denied

s.getServerVersionInfo() : ServerVersionInfo

Returns information about the connected server version or None if the session is not connected.

s.getTaskFactory() : TaskFactory

Returns the TaskFactory for this session.

s.getTaskRunner() : TaskRunner

Returns the TaskRunner for this session.

s.getUIResources() : UIResources

Returns the interface that provides access to UI-related resources.

s.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.

s.isBusy() : boolean

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.

s.isClosed() : boolean

Returns True if this has been closed.

s.isConnected() : boolean

Returns True if this session has a server connection.

s.isValidASCredentialDescriptor(asConnectionDescriptor) : boolean

asConnectionDescriptor (ASCredentialDescriptor) : the credential descriptor

Check whether the credential descriptor is a valid.

s.isValidRepositoryConnectionDescriptor(descriptor) : boolean

descriptor (RepositoryConnectionDescriptor) : the repository connection descriptor

Returns True if the supplied repository connection descriptor is valid i.e. can connect to a content repository.

s.publish(node) : ExecutionHandle

node (DataWriter) : the DataWriter to be published

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.

Exceptions:

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

s.publish(node, inline) : ExecutionHandle

node (TerminalNode) : the TerminalNode to be published. Must be a DataWriter if not publishing inline

inline (boolean) : True to prepare the image for inline scoring

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.

Exceptions:

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

s.removeAttribute(name)

name (string) : an attribute name

Deletes the specified attribute from this session. If there is no such attribute, the call has no effect.

s.run(stream, results) : ExecutionHandle

stream (Stream) : the Stream to be executed

results (Collection) : an empty collection that will contain any built objects once execution has completed

Executes the supplied stream 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.

Exceptions:

OwnerException : if the stream was not created by this session

ObjectLockedException : if the stream is locked

ServerConnectionException : if the 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

s.run(nodes, results) : ExecutionHandle

nodes (Node[]) : the array of Node objects to be executed

results (Collection) : an empty collection that will contain any built objects once execution has completed

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.

Exceptions:

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

IllegalArgumentException : if the array is empty

s.runTask(task) : ExecutionHandle

task (Task) : the Task to be executed

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.

Exceptions:

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

s.setASCredentialDescriptor(asConnectionDescriptor)

asConnectionDescriptor (ASCredentialDescriptor) : the credential descriptor

Sets the credential descriptor used to log in Analytic Server.

s.setAttribute(name, value)

name (string) : an attribute name

value (Object) : the attribute 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 None, the attribute is deleted from the session.

s.setRepositoryConnectionDescriptor(descriptor)

descriptor (RepositoryConnectionDescriptor) : the new repository connection descriptor

Sets the repository connection descriptor to be used when a connection to a content repository is required. Any existing connection is closed although a new connection will not be created until it is required.

s.spawn(stream, results) : ExecutionHandle

stream (Stream) : the Stream to be executed

results (Collection) : an empty collection that will contain any built objects once execution has completed

Executes the supplied stream asynchronously. Returns an ExecutionHandle which can be used to monitor and control the progress of the task.

Exceptions:

OwnerException : if the stream was not created by this session

ObjectLockedException : if the stream is locked

ServerConnectionException : if the stream is not connected to a server

s.spawn(nodes, builtObjects) : ExecutionHandle

nodes (Node[]) : the array of Node objects to be executed

builtObjects (Collection) : an empty collection that will be populated by built objects created by the execution

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.

Exceptions:

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

IllegalArgumentException : if the array is empty

s.spawnPublish(node) : ExecutionHandle

node (DataWriter) : the DataWriter to be published

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.

Exceptions:

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

s.spawnPublish(node, inline) : ExecutionHandle

node (TerminalNode) : the TerminalNode to be published. Must be a DataWriter if not publishing inline

inline (boolean) : True to prepare the image for inline scoring

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.

Exceptions:

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

s.spawnTask(task) : ExecutionHandle

task (Task) : the Task to be executed

Executes the supplied task asynchronously. Returns an ExecutionHandle which can be used to monitor and control the progress of the task.

Exceptions:

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

s.waitForAllTasksToFinish()

Waits for all tasks in progress on this session to complete.