Installing Gmaj



Gmaj can be run in two different modes: as a stand-alone application (for viewing local data files yourself) or as an applet over the world-wide web (to display your data on a server for viewing by others). Both forms of the program are distributed together, so the initial download and unpacking instructions are the same. Setting it up as an applet, however, requires some additional steps: ensuring that Gmaj and the data files you want to display are accessible to your web server, and building a web page to run the applet.


Gmaj is available for download as a compressed zip archive, This was created with the Java jar tool, but the format is compatible with PKUnzip and many other unzip programs. Unzipping the archive will produce gmaj.jar (a jar file containing the program itself) and a docs subdirectory containing some documentation files in HTML format. If your unzipper program does not preserve the directory structure and complete file names from the archive, you may need to move and/or rename the documentation files manually in order for the "Help - Manual" function to work. Note that the gmaj.jar file does not need a second round of unzipping -- Java will access it "as is". If you are setting up Gmaj as an applet, be sure to unzip the archive in a directory/folder that will be accessible to your web server, e.g., a new gmaj directory somewhere in the server's document space.

If you are running Gmaj in stand-alone mode, you will also need to have Java installed on your computer. For applets, the server does not need Java but the end user does; you may want to mention this on your Gmaj web page. In both cases Java 1.3 or higher is required, and for best compatibility Sun's JRE (or JDK) is recommended.

For stand-alone mode, that's all there is to the installation; you will specify different start-up parameters for Gmaj each time you run it (see Starting and Running Gmaj). The remaining sections on this page apply only to applet setup.

Data Files

In addition to the alignment data, Gmaj can display several kinds of annotations, including genes/exons, repeats, linkbars, color underlays, text highlights, and reconstruction scores for ancestral sequences, with a meta-data parameters file to tie them all together. For detailed descriptions of these files and their format requirements, please see Input Files for Gmaj.

When setting up Gmaj as an applet, the data files must be accessible to your web server. Also, due to Java security restrictions, they must all be located on the same server as the gmaj.jar file, because an applet is normally only allowed to contact the same server it was loaded from. We find it convenient to group the files for each invocation (e.g., each genomic region) in a separate subdirectory of the gmaj directory. It is also possible to bundle them into a single zipped data file for each invocation, which eases both storage requirements and download time (discussed further in Input Files for Gmaj).

Web Page

The last step in setting up the applet is to create a web page on your server that invokes it with the appropriate parameters for loading your data files. The applet normally appears as a labeled button that opens a Gmaj window when the user clicks on it; thus you can have several buttons on the same page, each set up to display a different set of data. The basic format of the HTML code looks like this:

<applet code="edu.psu.bx.gmaj.MajApplet.class"
        width="200" height="30">
<param name=paramfile   value="/java/gmaj/alpha/demo.gmaj">
<param name=bundle      value="/java/gmaj/alpha/">
<param name=buttonlabel value="Alpha-globin">
<param name=nobutton    value="false">
<param name=initzoom    value="mouse 110000 147000">
<param name=posturl     value="/cgi-bin/">
<param name=urlpause    value="100">
<param name=debug       value="false">
<i>Your browser is not responding to the &lt;applet&gt; tag.</i>
This particular fragment is based on the alpha-globin example from our server; naturally you need to replace the values with your own file URLs, button label, etc. A few things to note:

Cathy Riemer, June 2008