Context Manager

1. Introduction
2. How to use the Contex Manager
3. Gateway Contexts
4. Context Properties
5. Gateway contexts are persistent
6. Context Manager methods
7. How to obtain a handle of a context

Source

ContextManagerImp.java
ContextManager.idl
Example WebFlow configuration file
Example Makefile

 

1. Introduction

This module provides a set of utility methods that simplify manipulation of WebFlow contexts. Most of the methods of the Context Manager just aggregate basic methods on the WebFlowContexts class. The advantage of using the Context Manager is that it reduces number of requests to be send from a client to a remote server.

At this time the functionality of the Context Manager is focused to provide support for the Gateway System.

2. How to use the Context Manager

The context manager does not uses directly methods of ORB (for performance sake, and to hide low level CORBA from the developer). The server-side WebFlow objects are accessed through object handles, and not IORs. In a typical use within the Gateway system, the handle of the user context must be provided. Handles of all other objects can be obtained by using WebFlowContext methods. In most cases, this functionality is put into Context Manager methods.

The Context Manager makes use of SaveContext and RemoteFile modules. At this time, handles to these modules must be expliticly passed to the ContextManager (probably in the next releases this will be not necessary). For details, see an example Contex Manager client code.

The Context Manager maintains a conversional state: it is initialized once (by providing handles to the UserContext, SaveContext and RemoteFile) and can be used as long as the UserContext is alive. To simplify navigation, the Contex Manager maintains handles (transparently to the client) to current Problem, Session and Application (those can be null, if never set or selected).

3. Gateway contexts

The Gateway system uses the following object hierearchy. The root of the hierarchy is a Master Server. Each Gateway user is represented by the UserContext (a slave server - a WebFlow context running as a separate process).

Each user creates one or more ProblemContext(s) that correspond to the PSE Problem Descriptor(s):

Each instance of the problem solution (selected code, method, input file, job, output file, etc.) is represented by a SessionContext:

Finally, each SessionContext comprises one or more ApplicationContext(s):

Each ApplicationContext represent a single job. At this time, the Gateway system allows to associate only a single code with a seesion. Therefore the distiction between the session and application objects is not well justified. The situation will change dramatically as soon as we provide support for multiple codes (e.g., dataflow chain) associated with the session.

The ContextManager provides means for controlling Problem, Session, and Application contexts. The Master Server and the UserContexts are managed differently.

4. Contexts properties (ContextData module)

Each WebFlow context within the Gateway system has the ContextData module attached to it. The ContextData is a CORBA wrapper of the java.util.hashtable class, restricted to String objects only. The ContextData is used to store the context properties. Each context has several default properties:

The default properties are controlled by the Context Manager. There is no restriction on adding new properties to any context in addition to the default ones. New properties can be added in persistent or non persitent way.

The default properties often provide redundant information. This is done deliberately to improve performance of the Gateway system.

5. Gateway contexts are persistent

Another WebFlow module, SaveContext, attached to the UserContext, provide capability to save the context properties. In the Gateway system we use file system to store the data (and we provide JDBC/Oracle8 support on demand). Each context data is saved as a separate file. The files are organized as a tree that mimic context hierarchy.

The root of the file system (here: user1) is defined in the UserContext context data. The Context Manager provides methods for setting the context properties in a persistent way. These methods create directories and files as needed starting from the preexisting root (using methods of the RemoteFile module attached to the UserContext).

6. Context Manager methods

6.1 Creation of a new context
There is a dedicated method to set the user context and a family of methods to set other contexts (Problem, Session, and Application). The difference is that the user context WebFlowContext is created during the login procedure (see GatewayPortal servlet), while all other context are actually created by invoking any of the "newContext" methods.

So why do we need to address the user context here? We need to restore context data (for existing users) or set default values (for new users).

public boolean setUserContextData(WebFlowContext uc, String userDirectory, String userName)
returns true if stored user context data is not found. If the userDirectory is found, default values of the user context prooperties are set and stored. It does nothing (just prints an error message to sterr) if the directory does not exist.
returns false, if file userDirectory/userName/ContextData.txt exists. It does not fetches the stored properties, though!
userDirectory is the root of users directories.
usage:
(fragment of GatewayPortal servlet):
ServerServlet.setContextManager(userName,cm); //get user Context Manager
if(!cm.setUserContextData(userContext,userDir,userName)) {
 // file ContextData.txt exists, so read it!
 String rootDir = userDir + "/" + userName; //it's where the file is
 sc.readContextData(userContext,rootDir); //use SaveContext module for that
 restoreChildren(userContext); //restore all children contexts, if any
}
// otherwise setUserContextData filled the new user's context data
// with defaults
Problem, Session, and Application Contexts

Threre are two types of methods to create a new context: setContext and addContext.

 
public boolean setNewProblem(WebFlowContext uc, String ProblemContextName)
public boolean setNewSession(WebFlowContext pc, String SessionContextName)
public boolean setNewApplication(WebFlowContext sc, String ApplContextName)
replaces spaces in the string ContextName by underscore character, creates the context, attaches ContextData module, creates directory to save the context data, and persistently sets its default properties.
It expects uc to be not null (existing UserContext) with valid value of Directory property.
Returns false if creation of the context, or saving the ContextData failed.
 
 
public boolean addNewProblem(String ProblemContextName)
public boolean addNewSession(String project, String SessionContextName)
public boolean addNewApplication(String project, String session, String ApplContextName)
the semantic of these methods is indentical to setNewContext above ; instead of the handle to the parent context, it accepts only name of the contexts (including suffix: .PC, .SC, .AC, respectively).
 
public boolean addProblem(String ProblemContextName)
public boolean addSession(String SessionContextName)
public boolean addApplication(String ApplContextName)
the semantic of these methods is indentical to setNewContext above ; instead of the handle to the parent context, it accepts only name of the contexts (including suffix: .PC, .SC, .AC, respectively). It adds the new context to the current one.
 

6.2 Removing Context

public void stopSession()
removes user context data
public boolean removeContext(WebFlowContext c);
removes specified context. This operation includes: updating Children and CurrentChild properties of the parent contexts, deleting directory and its contents, and removing the context itself with all its children (modules and contexts). If this context is selected as the current child of its parent, the CurrentChild property is set to string "null"; otherwise it is left unchanged. Warning: no attempt to update current contexts is made!
 
public boolean removeCurrentProblem();
removes the current problem context (and all its dependants). The current problem, current session, and current application context handles are set to null;
public boolean removeCurrentSession();
removes the current session context (and all its dependants). The current session, and current application context handles are set to null;
public boolean removeCurrentApplication();
removes the current application context. The current application context handle is set to null;
 
public boolean removeProblem(String problem);
removes named problem context (and all its dependants). The current problem, current session, and current application context handles are set to null;
public boolean removeCurrentProblemChild(String session);
removes the named session context (and all its dependants) of the current problem. The current session, and current application context handles are set to null;
public boolean removeCurrentSessionChild(String application);
removes the named application context of the current session. The current application context handle is set to null;
 

6.3 Selecting Context

The following 9 methods return lists of contexts organized as array of strings. If a list of contexts is empty (or an error occured while processing the request), the methods return an array of size 1, with the first (and only) element set to string "null".

public String[] listChildren(WebFlowContext c);
returns names of all children of the selected context;
public String[] listChildrenContexts(WebFlowContext c);
returns context names of all children of the selected context (e.g., session.SC);
public String[] listProblems();
returns names of all problems defined by the user;
public String[] listSessions();
returns names of all sessions of the current problem;
public String[] listApplications();
returns names of all applications of the current session;
public String[] listProjectSessions(String problem);
returns names of all sessions of the named problem;
public String[] listSessionApplications(String session);
returns names of all applications of the named session of the current problem;
public String[] listAllSessions();
returns names of all sessions of all problems; format: problem/session;
public String[] listAllApplications();
returns names of all applications of all sessions of all problems; format: problem/session/application;
 
public boolean setCurrentProblem(String problem);
public boolean setCurrentSession(String session);
public boolean setCurrentApplication(String application);
sets the named context as the current context and updates CurrentChild property of its parent (e.g., once the current project is set, setCurrentSession method allows to change the current session within the current project);
setCurrentProject sets currentSession and current Application to null; setCurrentSession sets current Application to null;
 
public boolean selectProblem(String problem);
public boolean selectSession(String project, String session);
public boolean selectApplication(String project, String session, String application);
sets the named contexts as the current contexts and recursively updates CurrentChild property of its ancestors;
selectProject sets currentSession and current Application to null; selectSession sets current Application to null;
(note: there is no difference between setCurrentProject and selectProject);
 
public boolean isCurrentProblem();
public boolean isCurrentSession();
public boolean isCurrentApplication();
returns false is the current context is null; note: when these methods returns true, it means that the handle to the respective current context is not null and that DOES NOT mean that the handle is valid!
 

6.4 Access to ContextData

There are 7 methods to set context data and 7 methods to get the context data. "Generic methods" require the context handle as an argument, while "Gateway specific" do not: they access context data of the current context, or a context specified by its name (project/session/application - as needed).

The Gateway specific methods set the context data persistently. The generic set of methods includes both persistent and nonperistent setting of context properties.

6.4.1 Generic Methods:

public void setContextData(WebFlowContext c, String name, String value)
obtains reference for the ContextData module attached to the context c, and adds name-value pair to the hashtable. The data stored this way is not persistent: it will dissapear as soon as the context is deleted.
 
public void setContextMData(WebFlowContext c, String[] name, String[] value)
as setContextData, allowing mutiple name-value pairs to be set with a single call
 
public void setSessionData(WebFlowContext c, String name, String value)
obtains reference for the ContextData module attached to the context c, and adds name-value pair to the hashtable. Saves it to a file, and updates the LastTime property. The data are persistent.
 
public void setSessionMData(WebFlowContext c, String[] name, String[] value)
as setSessionData, allowing mutiple name-value pairs to be set with a single call
 
public String getContextData(WebFlowContext c, String name)
retrieves value of the property name of the context c
 

6.4.2 Gateway Specific Methods

public boolean setCurrentProblemProperty(String name, String value);
public boolean setCurrentSessionProperty(String name, String value);
public boolean setCurrentApplicationProperty(String name, String value);
sets the named property of the current context to value. Returns false if the current context is null. The semantic of these method is identical to that of setSessionData (data are stored persistently).
 
public String getCurrentProblemProperty(String name);
public String getCurrentSessionProperty(String name);
public String getCurrentApplicationProperty(String name);
returns the value of the named property of the current context. If the property has been never set, it returns string "null". If the current context is null, it returns string "nocurrentcontext".
 
public String getProblemProperty(String problem, String name);
public String getSessionProperty(String problem, String session, String name);
public String getApplicationProperty(String problem, String session, String application, String name);
returns the value of the named property of the contex defined by (problem/session/application) names. If the property has been never set, it returns string "null". If the context does not exist, it returns string "nocontextfound".

 7. How to obtain a handle of a context

UserContext is simple. Any client must have handle to the UserContext in order to connect to it. It can be obtained from IOR read from a Web Server, or it is returned by the login procedure.

A handle of any object in the WebFlow object hierarchy can be obtained using the WebFlowContext method: getContext(ObjectID). The ObjectID is a string obtained by concatenation of the object name and names of all its parents, separated by a slash ("/"). For example, osprey4.npac.syr.edu/Tom/project02.PC/session01.SC is the ObjectID of the SessionContext named session01.SC, added to ProblemContext project02.PC, added to UserContext of Tom, registered to the MasterServer named osprey4.npac.syr.edu (the name of the master server is specified in its configuration file). Consequently, you can obtain the handle to session01.SC using

org.omg.CORBA.Object o = uc.getContext("osprey4.npac.syr.edu/Tom/project02.PC/session01.SC");
WebFlowContext s = WebFlowContextHelper.narrow(o);

In this example we used method of the UserContext uc. Any context can be used to obtain the object handle as long as it is highier in the object hierarchy than that specified by the objectID: the getContext methods searches for object only down the tree. For example,

org.omg.CORBA.Object o = s.getContext("osprey4.npac.syr.edu/Tom");

will return null, because s is a grandchild of the UserContext named Tom.

You can use the getObjectID() method of any WebFlow object to retrieve its ObjectID. Hence you do not have to look at the master configuration file to use the getContext(ObjectID) method. The above example may be thus rewritten as

String ObjectID = uc.getObjectID();  //returns "osprey4.npac.syr.edu/Tom"
ObjectID += "/project02.PC/session01.SC";
org.omg.CORBA.Object o = uc.getContext(ObjectID);
WebFlowContext s = WebFlowContextHelper.narrow(o);

The same result can be obtained by using the following method of the ContextManager:

WebFlowContext getContext(String ObjectID);