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.
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.
New! You can install UTGB Shell with Java Web Start-based installer:
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:$PATHIn Mac OS X, JAVA_HOME would be:
export JAVA_HOME=/Library/Java/HomeIn Linux:
export JAVA_HOME=/usr/java/jdk1.6.0_03In 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_03If you have to install utgb-shell using the command-line, follow the steps:
export UTGB_HOME=$HOME/local/utgb-shell-1.2.4
export PATH=$UTGB_HOME/bin:$PATH
export JAVA_HOME=/usr/java/jdk1.6.0_03Type, 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.
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.
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.
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.
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.)
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.
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));
}
}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.
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)
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.
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.
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
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,
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))
This work is licensed under a Creative Commons Attribution-ShareAlike 2.5 License.