Lincoln D. Stein, lstein@genome.wi.mit.edu
This document describes the steps required to install Jade over an ACEDB database.
Because only the Unix version of the ACEDB server is currently supported, you must have a Unix machine available to install the database itself. The Web server, netclient and Jade layer should run on any Unix or Windows system, although only Unix systems have been tested so far. The MacIntosh can be used to view the data, but not to install the aceserver or the netclient, because this platforms does not support the rpc protocol.
In addition to the software and documents in this file, you'll need a Java-capable Web browser. Browsers include:
| OS | Site |
|---|---|
| Solaris | http://java.sun.com/ |
| Windows NT | http://java.sun.com/ |
| Macintosh | http://java.sun.com/ |
| Linux | http://www.blackdown.org/ |
| DEC Unix (OSF/1) | http://www.osf.org/mall/web/JDK/ |
| Hewlett Packard HPUX | http://www.osf.org/mall/web/JDK/ |
| AIX | http://www.osf.org/mall/web/JDK/ |
with documentation in:http://alpha.crbm.cnrs-mop.fr/jade/distrib/jade.tar.Zftp://ftp.crbm.cnrs-mop.fr/pub/unix/jade/jade.tar.Zftp://ftp-genome.wi.mit.edu/pub/software/jade/jade.tar.Z
http://alpha.crbm.cnrs-mop.fr/jade/distrib/programming.doc.tar.Z
If you are using an FTP (as opposed to a Web-based client), be sure to
use binary mode to download.
jade.tar.Z to a directory with at least 20 MB of
free space, uncompress and untar it with the command:
This will create a directory jade.version_number containing:zcat jade.tar.Z | tar xf -
<applet codebase="." code="jade.maps.Welcome.class" width=400 height=150>indicates that the main browser applet can be found in the file Welcome.class in the directory ./jade/maps relative to the .html document. If you move the location of the jade directory, you'll need to alter the codebase attribute to point to the correct location.
<param name="netclient" value="alpha.crbm.cnrs-mop.fr">must be modified. You should indicate in the value attribute the full name of the machine on which the netclient program is installed. Often this will be the same machine as the Web server.
<param name="port" value="20100">must be modified to indicate the correct value for netclient's network port, as defined in Installing the netclient.
Aceserver is fast. The speed and quantity of data that can be handled has been increasing every year. Running on a Linux portable 486 pc, aceserver can handle fifty thousand objects; on a workstation, several hundred thousands; using a high-end DEC server, Otto Ritter has conducted very successful tests on a database of 3 million objects.
ftp://ncbi.nlm.nih.gov/repository/acedb
ftp://ftp.crbm.cnrs-mop.fr/pub/acedb/aceserver
If you do not find the server/client in precompiled form, you should
recompile as follows:
zcat source.*.tar.Z | tar xf - setenv ACEDB_SRC `pwd` make tace aceserver netclientThe system will complain that ACEDB_MACHINE is undefined, and prompt you with a list of known platforms. Select the one that's correct for you with a command like
setenv ACEDB_MACHINE SOLARIS_4_OPT
(Solaris 4.X, optimized) and make again. Note that the makefile
system is layered. If the make command
fails and you want to change the compiler or library flags, please edit
one of the files wmake/*_DEF, do not touch
makefile or truemake.
tace is a command-line (text-only) client for ACEDB. It should be used to initialise the database and to load the initial data set. To create an empty database in the directory $ACEDB, type
mkdir $ACEDB/database cp -r wspec $ACEDB #cp, because you may want to edit these files bin.$ACEDB_MACHINE/tace $ACEDB yes // to accept initialisation quit // to quit tace (the // is the acedb comment delimiter)
At the other end of the socket, Jade expects to find a simple program which can reply to a limited set of requests by returning in specially formatted lists the set of objects matching a query, the content of an object expressed as a tree, or named data tables with parameters.
In our present implementation, this functionality is provided by netclient a C program derived from aceclient. In turn, netclient communicates with aceserver using the RPC protocol. Aceserver can be located on the same machine or a distant one. With simple modifications, netclient could communicate with other type of servers. In this section we explain how to install netclient. The next section covers aceserver.
For security reasons, a Java applet can only connect to the machine from which the applet was received. Hence, you must install netclient on the same machine on which the Web server is running. Fortunately netclient is a small program that will not excessively tax your Web server's CPU. Aceserver, on the other hand, is big and should preferably be installed on the machine physically controlling the disks where your ACEDB database is located.
Netclient runs under the control of the inetd "super daemon". This means that it is launched when necessary and exits when done. A new netclient is launched every time a Java client requests a new ACEDB connection. This means that there may be several copies of netclient running simultaneously.
To install netclient,
su root cd /etc
The name and number must be unique to the file. The number indicates the port to use for incoming connections to netclient and must be the same port indicated in the browser applet's HTML document (see Editing and installing jade.html).my.netclient 20100/tcp
my.netclient stream tcp nowait mieg /usr/local/bin/netclient netclient -host beta -port 20000100
kill -HUP `ps -aux | grep inetd | grep -v grep | perl -nae 'print $F[1]'`
To surrender root access.exit
Like netclient, aceserver is started by the inetd super daemon. The main difference is that only a single copy of aceserver is allowed to run at any time. It handles incoming requests from multiple clients (including netclient clients) and services them. When a certain amount of time has gone by without any additional requests, aceserver times out and exits. It will be launched again by inetd if needed. Because aceserver uses Sun's RPC (Remote Procedure Call) mechanism, its inetd.conf configuration line has a certain baroque quality to it.
To install aceserver:
su root
cd /etc
cd bin.$ACEDB_MACHINE; ln -s aceserver /usr/local/bin/rpc.acedbd
The name and number should be unique. This number is the port number indicated in netclient's invocation line in inetd.conf (see above).my.aceserver 20000100/tcp
my.aceserver/1 stream rpc/tcp wait mieg /usr/local/bin/rpc.acedbd rpc.acedbd /net/beta/local1/worm 20000100 1200:1200:0
/1 (a
program version number) appended.
20000100/1 stream rpc/tcp wait mieg /usr/local/bin/rpc.acedbd rpc.acedbd /net/beta/local1/worm 20000100 1200:1200:0
my.aceserver 20000100 rpc.acedbd
kill -HUP `ps -aux | grep portmap | grep -v grep | perl -nae 'print $F[1]'`
kill -HUP `ps -aux | grep inetd | grep -v grep | perl -nae 'print $F[1]'`
On some machines we've found that it's necessary to reboot in
order to convince the portmap program to recognize the new
aceserver server.
exit (abandon root access)
Note that several services running on different databases can run in parallel on the same machine, all of them serving the same Jade interface, a feature used in the USDA grass multimap demo. For each one, declare in the same way a netclient and a corresponding aceserver, each with its own port number and database directory. Remember that all the netclients must run on the Web host, but that the various servers may be on a different machines.
To implement these features, although the Jade communication layer can import whole objetcs, we have chosen to import all the data driving our graphic displays in the form of simple tables declared by name on the server side. The tables are essentially simplified "views" on the more complex object-oriented ACEDB schema. This system has the following advantages:
At any time, data retrieved from the first server can indicate the address of some other server to which Jade can establish independent connections (see below). Depending on the applications, the data retrieved from different servers can be merged or maintained separately.
Jade is also capable of representing and retrieving ACEDB objects in their full object-oriented tree form, translating ACEDB pointers into Java-style references. We use this possibility in the plain Tree-display of the objects, which implements hypertext facility. However, to write a graphic display, like a genetic map, in the object-oriented form, sacrifices some of Jade's portability, because it assumes a certain database structure and schema.
Jade can access any preexisting ACEDB database. However, to use table-oriented views effectively you must do some work:
This file is self documented, but you must edit it if you want to limit read access to your data to netclient. In that case,and if netclient and aceserver run on different machines, /tmp is not a correct choice for PUBLIC_DIRECTORY since you must choose a directory visible from both machines. You must choose a directory that is cross-mounted using NFS or other transparent network file system.
You need to add in your models the declaration of the Jade Class It may be part of the distributed models.wrm file, and will later be precompiled in the server source code. As of August 1996 the Jade class is defined as:
?Jade Display Text Text Text UNIQUE Text
StandAloneDisplay Text
bin.$ACEDB_MACHINE/tace $ACEDB read-models parse meta.jade.ace parse tables.jade.ace save quit
cp /dev/null $ACEDB/server.log
These lines associate the names ricegenes, maizedb... to the ports number 20211 and 20212... corresponding on the same host to the netclient services of the rice, maize... servers.<applet code=jade.maps.Welcome.class width=400 height=150> <param name="title" value="Grass@beta"> <param name="netclient" value="alpha.crbm.cnrs-mop.fr"> <param name="port" value="20210"> <param name="otherdbs" value="ricegenes 20211 maizedb 20213 graingenes 20212 sorghumdb 20214">
The first connection is established with the web host on the principal port, 20210 in this example. Later on, the display may require additional connections to other servers. Inside the Java display code, the need to call the secondary servers is hard coded, including a name recognition system, and results in a call:
jade.db.MultiAccess.display("ricegenes", "Map", locus.name)
The relevant point is that although the need to call the rice server is part of the display code, the actual location of the server is part of the configuration of the main server. The grass demo is running at //alpha.crbm.cnrs-mop.fr/jade/grass.html,
This declaration is used to add a new display in the Jade interface. The class jade.grassplot.MapSetPick implements the interface Displayable and the method:Jade : default StandAloneDisplay jade.grassplot.MapSetPick
public String nickName () { return "Oxford Grid Selector" ; }
The second line implies that chromosomes are displayed using the Vmap display code, a standard genetic map display. This code imports its data in several tables, one of which is map.interval.Jade : default Display Chromosome jade.maps.Vmap Display Sequence jade.maps.Vmap map.interval link.interval
The third line is more interesting. In the dace database, we wanted to reuse the same Vmap display for a new purpose. This displays is now also associated to the Sequence class, but when used on a Sequence object, this table name map.interval is remapped to link.interval. The two tables have a very different definition on the server side, but export semantically equivalent tables to the display code.
The important feature on the server side is to be able to answer a request of the form:
by the export of the relevant table using the Object-Name as run time parameter. (this section will be developped later) .Table -n Table_name Object_Name
The ACEDB definition file Jade.tables.ace is self documented.In a few words, that probably only make sense for acedb users, these definitions were constructed using the acedb xace graphic interface, starting the Table-Maker from the main menu, and saving the definition as an ace object via the new "Save Def" button. Unfortunatelly, the current ace.4_3 interface does not correctly allows the handling of parameters and one must finish the preparation by editing in tree-update mode the resulting Table class object, and finally exporting them as ace files.
This document and software may be redistributed as long as it is distributed in full and the above copyright statement remains intact. Any additions or modifications should be expressly labeled as such.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.