newSessionContext
Synopsis
SessionId newSessionContext( SessionId sessionId,
SessionContextData? ContextData)
throws SessionServiceFault;
struct SessionContextData {
UUID? projectKey; // attribute
}
See also: SessionId, SessionServiceFault, UUID
Session contexts are a mechanism to to allow clients to pass implicit parameters to (web service) operations that are required by most operations. As of now, the only such parameter is the project key (a kind of handle for an in-memory instance of a project).
To use a session context, a client will create a session context, set the implicit parameters stored in the session context, and use the session context ID instead of the session ID as the sessionId argument of web service operations. The implementations of these operations will then use the session ID stored in the session context as the actual session ID, and use implicit parameters stored in the session context if and when needed (in other words, an operation which does not require a project should not fail just because the session context contains a project key which does not reference one of the session’s open projects).
Once no longer needed, a client may dispose a session context. All session contexts of a session are automatically disposed when the session is closed.
In general, and unless explicitly specified otherwise, all operations which take a session ID as their first argument may be invoked with a session context ID. If so, the session ID stored in the session context will be used as the actual session ID.
Furthermore, if the operation requires a project, the project key stored in the session context will be used to identify the project to operate on. The operation will fail if the project key does not identify one of the projects currently held open by the session. On the other hand, if the project key of the session context is not specified, the operation will operate on the session’s current project (the same project as used with operations invoked with an actual session ID).
The operation newSessionContext creates a new session context for the session specified by the first argument.
Depending on whether argument sessionId is a session ID or a session context ID, the default value for the project key stored in the new session context is either the key of the session’s current project, or the project key from the original session context, or unspecified if the original session context does not specify a project key (in which case operations on the session context will operate on the session’s current project unless a project key has been set for the session context).
The optional contextData argument, if specified, is used to initialize the session context. See operation updateSessionContext for more information.
The operation returns a session context ID which can be used as the sessionId argument of most EAIWS web service operations until the context is disposed, either explicitly with operation disposeSessionContext, or implicitly when the session is closed.