Top Page

UTGB Shell Quick Start

The UTGB Shell is a command-line utility for developing your own genome browser for querying and visualizing biological data. This document is a quick start guide for beginning track development with UTGB in 30 minutes.

Installation of the UTGB

In order to use UTGB, you need a JDK (Java Development Kit) version 1.5 or higher. If you have no JDK in your OS, visit the Sun's Java site (http://java.sun.com), and follow the installation instruction.

Easy Installer

New! You can install UTGB Shell with Java Web Start-based installer:

  • Click http://utgenome.org/toolkit/utgb.jnlp
    • Push the Trust button when certificate confirmation dialog is shown.
    • Push the Install button. The latest version of the utgb-shell will be downloaded from out site, and extracted to the specified installation folder.
  • Default installation path is $HOME/.utgb. We call this folder UTGB_HOME.

Mac OS X and Linux

Set the environment variables UTGB_HOME, PATH and JAVA_HOME in an appropriate file, e.g., .profile, .bash_profile (for Bash), .zprofile (for ZSH), etc.

export UTGB_HOME=$HOME/.utgb
export PATH=$UTGB_HOME/bin:$PATH

In Mac OS X, JAVA_HOME would be:

export JAVA_HOME=/Library/Java/Home

In Linux:

export JAVA_HOME=/usr/java/jdk1.6.0_03

Windows

In Windows, press Win + Pause (or open Control Panel - System - Settings) to open Environment Variable panel for setting the environment variables, PATH, JAVA_HOME.

PATH = (UTGB_HOME)\bin;%PATH%

Replace the above (UTGB_HOME) to your UTGB installation path.

Set the JAVA_HOME variable to your JDK (1.5 or higher) installation. For example,

JAVA_HOME = C:\Program Files\Java\jdk1.6.0_03

Manual Installation

If you have to install utgb-shell using the command-line, follow the steps:

Windows

  • Download the latest version of UTGB shell archive utgb-shell-(version)-package.zip from http://maven.utgenome.org/repository/artifact/org/utgenome/utgb-shell/ (or Download page), unpack it to anywhere you like, e.g., C:\utgb\utgb-shell-1.2.4
  • You need to set two environment variables. Press Win + Pause (or open Control Panel - System - Settings) to open Environment Variable panel.
  • Append C:\utgb\utgb-shell-1.2.4\bin to the PATH variable as follows:
    • PATH = C:\utgb\utgb-shell-1.2.4\bin;%PATH%
  • Set the JAVA_HOME variable to your JDK (1.5 or higher) installation. For example,
    • JAVA_HOME = C:\Program Files\Java\jdk1.6.0_03

Mac OS X & Linux

  • Download the UTGB Shell archive in the same way described in the Windows section. In this example, we use $HOME/local/utgb-shell-1.2.4, where $HOME is your home directory, e.g. /Users/leo (in Mac OS X), /home/leo (in Linux).
  • Install JDK. We assume your JDK is installed in /usr/java/jdk1.6.0_03.
  • Set the following environment variables in one of your .profile, .bash_profile, .zprofile, etc:
  • export UTGB_HOME=$HOME/local/utgb-shell-1.2.4
    export PATH=$UTGB_HOME/bin:$PATH
    export JAVA_HOME=/usr/java/jdk1.6.0_03

Confirm your UTGB Installation

Type, utgb from your Command Prompt or Cygwin (in Windows), terminal shell (in Linux and Mac OS X). If you see the following message, your installation is succeeded.

leo@leopardcat~/../workspace> utgb    
UTGB Shell: version (1.1.0) (Revision: 1755)
type --help for a list of the available sub commands.

Viewing Help Messages

UTGB command has several sub commands. To see a list of all sub commands, type utgb --help.

UTGB Shell: version (1.1.0) (Revision: 1339)
usage: utgb <subcommand> [option] [args]
Type utgb <subcommand> --help for a help on a specific subcommand.

 -h,  --help    display help message
 -v,  --version display version     

[sub commands]
  action        add a new web action handler
  compile       compile java source codes
  create        create a new Maven/Eclipse project for implementing your own track.
  dbinfo        displays database information
  deploy        deploy the war file to the remote tomcat server
  maven         execute maven tasks
  query         performs a query for a database described in the config/track-config.xml file
  server        start up the portable web server

You can see a individual help message for each sub command by typing utgb (sub command) --help.

Create a New Track Project

Type utgb create (your project name):

> utgb create myapp
[Create]        package  = myapp
[Create]        explodedWebappDir        = target/utgb
[Create]        projectName      = myapp
[Create]        group    = org.utgenome.track
[Create]        project folder: myapp
[Create]        create a directory: myapp/src/main/java
[Create]        create a directory: myapp/src/test/java
[Create]        create a directory: myapp/config
[Create]        create a directory: myapp/db
[Create]        create a directory: myapp/lib
[Create]        create a directory: myapp/src/main/webapp
[Create]        create a directory: myapp/src/main/webapp/image
[Create]        create a directory: myapp/src/main/webapp/WEB-INF
[Create]        create a directory: myapp/tomcat
[Create]        create a directory: myapp/tomcat/webapps
[Create]        create a directory: myapp/tomcat/webapps/ROOT
[Create]        create a directory: myapp/tomcat/webapps/ROOT/WEB-INF
[Create]        create a file: myapp/config/track-config.xml
[Create]        create a file: myapp/db/README
[Create]        create a file: myapp/lib/README
[Create]        create a file: myapp/pom.xml
[Create]        create a file: myapp/README
[Create]        create a file: myapp/src/main/webapp/404.jsp
[Create]        create a file: myapp/src/main/webapp/image/utgb.gif
...

For the first time, execution of the create command takes longer time for downloading several JAR files into your local hard disk. Cross your fingers, and wait the completion. The next time, the create command will finish in several seconds.

Compile Your Project

The generated UTGB project consists of several Java files, and you need to compile them before launching the UTGB server. Switch to the newly created project folder (at this time, we call it myapp folder) , then type utgb compile to generate their binary code. If your Java installation is missing or JAVA_HOME environment variable is not properly set, some errors will be prompted. Check your configuration descrived above.

Launch the Portable Web Server

The UTGB shell is bundled with a portable Tomcat server. So, you can start the your web application (track project) immediately on your PC. Type utgb server to launch the web server. If you like to use GUI interface, type utgb server -g; a GUI interface to launch the web server will appear. The UTGB portable server uses a port 8989 in default. You can change the port number using -p option. For details, type utgb server --help. You can stop the server just by pressing Ctrl+C in your shell.

To confirm your web application is working correctly, open http://localhost:8989/myapp in your web browser (IE, Firefox, Opera, etc.)

Create a New Web Action

UTGB track (web application) consists of a set of web actions, accessible from http://localhost:8989/myapp/(action name). To add your own action, type utgb action (action name), which creates a new web action code into you web application source code. To enable the new action in the web browser, you need to recompile the project and then restart the web server.

myapp> utgb action HelloWorld     // HelloWorld.java will be generated

myapp> utgb compile

myapp> utgb server

You may see the new action from http://localhost:8989/myapp/HelloWorld or http://localhost:8989/myapp/helloworld (lower case name). You can write any Java code to generate web contents including plain text, HTML, PNG, JPEG graphics, etc., inside the handle() method in your web actions.

Magic in Web Actions

Web action receives a set of URL query parameters, in the form of String data type. For example, an web request URL http://localhost:8989/myapp/helloworld?name=leo&year=2008 has two parameters, name and year. In the traditional web application development (e.g. CGI), you have to convert the data types of these values; for example, the name value has a String type, so you can use it as is, but the year value must be converted from the String to an Integer type. Programming such data type conversion is bothersome and usually error-prone. In the UTGB, such data type mappings between URL requests and web actions are supported.

All you need is to add public fieds in a web action class for recieving URL request paremeters. The UTGB automatically translates String input values in a URL request by investigating the public field parameter types.

public class HelloWorld extends WebTrackBase
{
    // private fields can be kept secret
    private static final long    serialVersionUID    = 1L;
    private static Logger _logger = Logger.getLogger(HelloWorld.class);
   
    // public fields will be modified according to the web request parameters
    public String name = "Leo";
    public int year = 2007;
    
    public void handle(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException
    {
        // You can use the name and year parameters, recieved from the URL request.
        // The following code displays "Happy New Year! Leo (2007)" if no parameter is set
        response.getWriter().println(String.format("Happy New Year! %s (%d)", name, year));
    }
}

Configuring Databases

UTGB has a built-in support of database access for SQLite, PostgreSQL, MySQL, etc. In order to use such DBMSs, you need to add some configurations in config/common.silk file, written in silk format.

Development with Eclipse

Eclipse is an excellent open-source IDE for developing Java programs. We strongly recommend you to use Eclipse in developing your track programs.

In order to start track development with Eclipse, type utgb eclipse in your project folder. Eclipse project files, .project and .classpath will be created in the folder. Then import your project folder in your Eclipse.

For the first time, you have to set two class path variables in your Eclipse:

M2_REPO = (Your Home Directory)/.m2/repository
UTGB_HOME = (Installation folder of the UTGB)

clip/classpath-variable.gif

These two variables are the same used in the Installation of UTGB.

In the debug dialog of the Eclipse, you will find (your-app-name)-server item in the Java Application, which will start the local web server.

clip/debug-dialog.gif

While you are coding the web application, Eclipse automatically reloads your change to the source codes, so interactive editing of your web application becomes possible with Eclipse.

Generating A GWT-based Genome Browser Interface

Use utgb gwt command:

myapp> utgb gwt
myapp> utgb compile

After the compilation of GWT codes (it usually takes a minute or more), you can see the GWT interface of the genome browser. First, launch the local web server,

myapp> utgb server

then, open the page, http://localhost:8989/myapp/browser.html

clip/utgbentry.gif

You can modify the track contents by editing src/main/webapp/view/default-view.xml file. The format used in this XML file is the same with XML data that can be obtained from the save view button of the UTGB browsers.

To use another type of views, add a view parameter to the above URL, as follows:

http://localhost:8989/myapp/browser.html?view=anotherview.xml

This URL loads src/main/webapp/view/anotherview.xml file, then shows the track contents described in the view XML file.

To change the default parameter values such as species, revision, target etc. you can also use query parameters of the URL:

http://localhost:8989/myapp/browser.html#species=medaka;revision=version1.0;target=scaffold1;start=1;end=1000

This URL shows a browser page of medaka, version1.0, scaffold1, at genome location beginning from 1 to 1000.

Notice Due to the bug contained in the recent update for Safari 4, GWT HostedMode for debugging utgb application using Eclipse crashes in Mac OS X. http://code.google.com/p/utgb/issues/detail?id=79

To resolve this problem,

  • Download the old WebKit, say r51062 from http://nightly.webkit.org/
  • Install it to /Applications folder.
  • Then select Debug -> Debug Configurations ... and select myapp-gwt-mac.
  • Click the Environment tab.
  • Add a variable:
  • DYLD_FRAMEWORK_PATH = /Applications/WebKit.app/Contents/Frameworks/10.5
    (The number 10.5 must be 10.4 (in Tiger) and 10.6 (in Snowleopard))