A short user guide of the Le Client system.
Le Client Summary
Le Client, named after the middleware application Le Select, is a front-end for the NAWDI system. NAWDI provides a central location and standard for registering scientific applications and scientific data. A scientist wanting to publish her data or application may do so without losing control of that data – she can put the data on a web server and remove that data at any time. Le Client allows an easy way to do the most common NAWDI tasks: register hosts and programs, create program configurations, run programs, and register data.
Running Le Client
Le Client can be run on any system with JDK 1.3.1 or above running an operating system with a graphical interface (for example, Windows or Linux with X). Le Client can be downloaded from http://kermit.evergreen.edu/VRVClient/LCDistro.zip. After downloading, unzip the contents of the file into any directory of your choosing. Then open that directory and open “winrun.bat” if your are using windows or “unixrun” if you are using unix (java must be in your classpath). You will be prompted for a password. To get a password, contact mureme12@evergreen.edu. The Main Le Client Window should open after a few moments while retrieving initial NAWDI information, depending on the speed of the connection to the Central Database.
Registering a Host
A Host is a computer running Le Select server and is accessible though the Internet. A Host can be registered by pressing the “register host” button on the main Le Client window. The only information required of a host is the “Host IP and Port” field. It should be in the form “//host:port”, e.g. “//192.211.16.43:3055”. To make sure the host.domain is running Le Select, visit //host:3080 and make sure the HTTP interface is running. The port that needs to be registered is the Le Select JDBC port, 3055 by default. It is essential that the host’s port is accessible to the outside word, e.g., if the host is behind a firewall, it should have an external IP and open port. All other fields in the Register Host window are optional. After a host is registered, the NAWDI system does not currently verify that the Host is accessible. Hosts show up in the main Le Client window as the second level of the Tree.
Registering a Program
A Program is any application packaged in a Le Select wrapper published on a host. Registering a program should not be taken lightly; running a Job with a Program will only succeed if a wrapper is successfully written on a Host and the Program registration matches the wrapper specification exactly. Since writing a wrapper for a Program is no small task, registering a program will be done only on rare occasions. A Programs can be registered by choosing a Host on which the Program is installed and pressing the “register program” button on the main Le Client window.” “Name” and “Parameters” are required fields, the rest are optional metadata. The “Name” much match the Program name exactly, given by the wrapper on the Host. There must be at least one input parameter for each Program. To add a parameter, choose a parameter from the combo box and click “Add.” “Remove” will remove one parameter from the list of parameter. If the Program is order dependent, or if the wrapper is expecting the inputs in a certain order, then use “Up” or “Down” to adjust the order. Additionally, one can choose a parameter and click the “Make Variable” button to make the parameter variable. If a parameter is not variable (by default) then you must choose one registered data source when creating a Configuration. If a parameter is variable, then you may choose 1 to n data sources when creating a Configuration. The NAWDI system does not currently verify that a registered Program is accessible after registration. Programs are visible in the main Le Client window as the third level of the Tree.
Associating a Program
If a registered Program and its wrapper are installed on two different registered Hosts, it is not necessary to register two identical Programs. Instead, choose the “Associate Program” button on the main Le Client window. It will present two drop down boxes, one for registered Programs, one for registered Hosts. A third text for information about the association can be included optionally. Again, an association is not verified upon registration and will be visible when in the main Le Client window’s Tree.
Creating a Configuration
A Configuration is an instantiation of a Program that consists of a set of inputs. This set of inputs corresponds directly to the set of parameters specified when a Program was registered. To create a configuration, select a Program from the main Le Client window’s Tree and click “Create Configuration.” You must specify a name and at least one input for each parameter. The button to the left of each parameter drop down specifies either (1), meaning choose 1 input, or (1..n), meaning choose a variable number of inputs. To choose each input(s) for the Configuration, click a leftmost button for a respective input. A Query Viewer will pop up with only the Types of data that are available for that input. If the Program Signature requires only 1 data source for that input, choose one data source and click “ok.” If 1..n are required, then you can choose 1..n data sources. Once each input has an instance of a Type, then you can click “ok” to create the configuration. The configuration will be visible in the Main Le Client Window under the originally selected program.
Running a Configuration
Running a Configuration means taking an actual set of inputs (the Configuration) and executing a Program with them. To run a Program, choose a configuration and then press “Run Configuration.” This operation, although automated, may take some time, as a user-defined routine is being executed in the central database, which contacts the Host, which in turn executes the Program. When this operation is complete, the Tree in the main window will refresh. Navigate to the Configuration chosen originally and open up the next level on the Tree. There should be at least one or more results, called a Job, the most recent of which was the Job you ran (note: Theoretically, all the Jobs under one configuration should be identical since they were run on the same host with the same inputs. However, in practice, since NAWDI allows free reign of all data, hosts, and programs, any of these may have changed during the course of their lives as registered NAWDI objects. This could affect the outcome of any program run without the knowledge of a NAWDI user). In the Metadata Window, the status of the Job is visible. The status should be set by the wrapper. When the wrapper publishes Results, they will be visible in the next level down in the Tree. If a Host or Program has been registered incorrectly, the problem will become apparent at this stage. If a registered Host or Program was inaccessible or nonexistent, a Le Select exception within an SQL exception will be thrown. If any inputs were inaccessible or nonexistant (and thus a configuration invalid), a wrapper error will be thrown. To correct for these errors, the Host, Program, or Configuration will need to be Edited. When a Job is completed, you can download its Results.
Registering Data
Registered Data is information sources that are known to the Central Database and are accessible through a URL. Currently, only the HTTP protocol is supported. Like Programs, the Data must be accessible to the Central Database and to all Clients who wish to use the data. Data can be registered in two ways. First, you can click “Register Data” from the main Le Client Window. Second, you can click “New” from the Query Viewer Window. In either case, you will be presented with a Register Data window with five fields. Type, URL, and Format are all that are required. In the Type field, NAWDI lists all the Types it knows about. Select the type of the data you wish to register. In the URL field, enter the HTTP address of the Data you wish to register. In the Format field, enter the Format that the Data is stored in. In most cases, the Format is Generic, but in some cases, you may have a choice. For instance, if you are registering a binary file of some Type and was created on an SGI, then the format might be Big Endian 32. In most cases, you will want the Format to match how the data was created or on what machine the data was created, not the Format that corresponds to the machine that data is being stored in. For example, if the binary file was being stored on an Intel 32 machine but created on an SGI, then the file should be still be registered as Big Endian 32. Author and Info are not required. Once Data is registered with a properly formed URL (the only test run on the Data at this point), it is available for use in Configurations of Programs that have a Program Signature containing that type.
Refreshing
Refreshing is an action performed on the Tree in the Main Le Client window. Refreshing retrieves all Hosts, Programs, Configurations, Jobs, and Results from the Central Database. Depending on the connection speed, this action may take anywhere from less than a second to a few minutes. Refreshing is done automatically whenever a new Entity is added to NAWDI, such as when you register a Host or create a Configuration. A refresh can be done manually by clicking the “Refresh” button on the Main Le Client Window.
Browsing Data
Browsing Data is an advanced feature of Le Client not intended for most users. It allows you to view and execute queries on most of the Central Database. Click “Browse Data” to view the Central Database. A window will appear that shows all the available tables. Choose the table you wish to view and click “View Table.” This will allow you to view the contents of most tables. Alternatively, you can choose “Make Query” to make a custom SQL query, although this is NOT RECOMMENDED. Very few safeguards have been incorporated in to Le Client – you will not be warned if you make attempt to make a destructive query.
Downloading Results
After a Configuration has been run and a Job has completed, results will be published by the wrapper. Each Result will be available in the Tree of the Main Le Client Window under the Job which produced it. To Download a result, press the “Download Result” button in the Main Le Client Window. A window will be shown identical to the window shown while Registering Data. In this case, you may only choose which format you would like to download it in. Choose the format, then click ok. You will be presented with a dialog box to choose where you want to save the data on your computer and what you want to name it. Select a location and choose ok. Now the result has been downloaded to your local machine for viewing and use.
Getting Help
Help can be obtained by clicking “Help” on the Main Le Client Window or by going to http://kermit.evergreen.edu/VRVClient/ .
Editing Entities
After an Entity has been created, it may be desirable to edit it. The only Entities which can be edited are Hosts, Programs, and Configurations. This can be done in the Main Le Client Window by selecting the Entity you wish to edit and clicking the “Edit” button. Certain restrictions have been placed on what parts of an Entity that can be edited. For example, if a Configuration has been Run, the Program name, Host name, and Configuration Signature for that Job cannot be edited. Since any such change would alter the semantics of that job, Le Client disallows harmful changes.
Dropping Entries
In some cases, it may be desirable to remove Hosts, Programs, Configurations or Jobs. These Entities can only be dropped if (1) they are leaves of the Main Le Client Window’s Tree and (2) if they don’t have Results. Drops should be done with care, however.
Main Le Client Window The Main Le Client Window is the starting point for all Le Client activities. It contains three main parts: Tree – The Tree is a hierarchical view of the NAWDI system. To navigate down levels of the Tree, click the handle to the left of the Entity you wish to expand. At the top level, there is always a root, labeled “Hosts”, that has no functionality. The second level, all registered Hosts are visible. At the third level, Programs that are Associated with each Host are shown. At the fourth level, you will find Configurations that were Created for each Program. At the fifth level, you will find Jobs that were Run for each Configuration. And finally, the sixth level contains all Results for each job. After an automatic or manual Refresh, the tree will collapse. Clicking on an Entity will display information about it in the MetaData Window. MetaData – This frame appears just below the Tree frame and contains all available information about a selected Entity. Some Entities can be dropped or have their information edited. Between the Tree and the MetaData frame, there is an adjustable Slider that allows you to adjust the size of the MetaData and Tree frames by dragging it. Clicking the up arrow completely moves the divider up and down moves it down. Buttons – A toolbar with buttons appears on the right and provides access to most Le Client Functionality. Table Viewer The Table Viewer simply shows what tables are available on the Central Database. Not all tables are viewable – some have UDT’s which Le Client is not prepared to display. From this window, you can Execute a Query and View Tables.
Publishing Data
Publishing data using the NAWDI system is fairly straightforward. Most importantly, you must have access to a web server, such as one running IIS or Apache. First, copy your data on the web server. Make sure the data is accessible through the internet by opening a web browser and finding your file. For example, if your file is ‘myfile.txt and is published on ‘scidb.evergreen.edu’, you might enter ‘http://scidb.evergreen.edu/myfile.txt’ into your web browser. Once you have access to your file through your browser, you may Register your data.
Publishing Programs
Publishing Programs with the NAWDI system is no small task, although it is within the grasp of most Java programmers. First, you must Set Up Le Select. Second, you must Write a Wrapper. Finally, you must Register your Host and Register your Program.
Setting Up Le Select
Le Select is easy to set up on most Windows and Unix machines once java is installed (see http://java.sun.com/j2se/1.3/download.html for more information). The computer that uses Le Select must be accessible through the internet (that is, not protected by a firewall) and must have open ports 3080 and 3055. Download Le Select 2.0 from http://kermit.evergreen.edu/VRVClient/LeSelect-2.1.D017.zip) and unzip it into a director of your choice, call it ‘mydir.’ Inside mydir, run the shell script LSServerStart if you are using Linux or the batch file LSServerStart.bat if you are running Windows. If all is well, you should be able to visit http://localhost:3080/ in your web browser and see the Le Select HTTP interface. Click on ‘NAWDI' to view the contents of the Central Database. If there are any problems, consult http://www-caravel.inria.fr/Eaction_Le_Select.html.
Writing a Wrapper
Once Le Select is up and running, it’s time to write the wrapper for your program. The easiest way is to copy one of the existing wrappers. For our purposes, copy the mydir/PinCWrapper directory to mydir/myWrapper and delete all the class files. Now change all the instances of PinC in the filenames and in the java files to a name of your choice; we’ll use ‘my’. For example, PinCWrapper.java changes to MyWrapper.java and it’s contents are changed from:
package PinCWrapper;
import LeSelect.WrapperInterface.*;
import LeSelect.Common.LeSelectException;
import java.io.Serializable;public class PinCWrapper implements ProgramWrapper {
public PinCWrapper(InfoNode wrapperInfo) {
}public ProgramInstance newInstance() throws LeSelectException {
return new PinCInstance();
}public void close() {
}public ProgramInstance restoreInstance(Serializable serializable) throws LeSelectException {
return null;
}
}to
package MyWrapper;
import LeSelect.WrapperInterface.*;
import LeSelect.Common.LeSelectException;
import java.io.Serializable;public class MyWrapper implements ProgramWrapper {
public MyWrapper(InfoNode wrapperInfo) {
}public ProgramInstance newInstance() throws LeSelectException {
return new MyInstance();
}public void close() {
}public ProgramInstance restoreInstance(Serializable serializable) throws LeSelectException {
return null;
}
}
Now do this for all java files. VRVCConstants and WrapperMethods only need to have their package renamed. Now compile all the files in the directory, something like:
javac -classpath ..\extlib\ifxjdbc.jar;..\oldclass\classes.jar;. *.java
Now, open either of the LSServerStart or LSServerStart.bat and add MyWrapper to the classpath. In the myDir/Wrappers directory, copy PinC.wd (the XML wrapper) to My.wd and change the line
< ProgramWrapper WrapperClass="PinCWrapper.PinCWrapperFactory" >
to
< ProgramWrapper WrapperClass="MyWrapper.MyWrapperFactory" >
Now start the server (running LSServerStart or LSServerStart.bat). Click programs from the top bar and you should see “My” as a registered program. At this point, you can actually write your program wrapper, or more accurately, modify the one you just copied.
Fortunately, the only file that needs to be edited is myDir\myWrapper\MyInstance.java. Inside that file, only the runPass2 method must change. First, some of the environmental variables need to be set. Specifically, pgmname, host, and owner need to be modified. The rest of the variables’ uses should become apparent after reading runPass1 and runPass2.
Instead of explicitly saying what each part of runPass2 does, it will be sufficient to say what needs to be done in general in it. Basically, does the actual work of executing the program. All that the wrapper knows when its enters runPass2 is the name of a configuration. Traditionally, it has been done in a number of steps: get the ID’s for each input file based on the configuration, download the physical files through the database based on the ID’s, execute the program and give it the inputs, wait for the program to finish, set the status of the program in the Central Database to “Complete,” put the outputs on a web server, and register the outputs with the database. Although we’ve use this process in the past, runPass2 could be used to execute an application in any way Java allows.