<?xml version='1.0' encoding='UTF-8'?>
<?xml-stylesheet type="text/css"
		href="/common/mozilla/layout/xml/tests/docbook.css" ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
								 "../../docbook/docbookx.dtd">
<book>


<title> Java TreeView Programmer&apos;s Guide </title>
<info>
	<author> 
		<personname>
		<firstname> Alok </firstname>
			 <surname> Saldanha </surname>
		</personname>
	</author>
</info>

<preface>
<title> Preface </title>
<para>
This manual is designed to get you started developing Java TreeView derivatives. This consists of two things:
</para>
<orderedlist>
<listitem> <para> Getting the tools necessary to develop Java TreeView </para></listitem>
<listitem> <para> An Overview of the archtecture </para></listitem>
</orderedlist>
<para>
Detailed descriptions of classes and stuff can be found in the Javadoc, and probably change too quickly to be worth documenting in a separate manual. 
</para>
<para>
An outdated description of the architecture can be found in my thesis, which is available online. Until we get real funding, I will focus on putting useful reference material in here. This information will not be useful to you unless you are willing to read a lot of source code.
</para>
</preface>



<chapter id="ch1">

<title> Getting Started </title>
<para>
This chapter will get you started with developing java treeview.
</para>

<itemizedlist>
<title>Tools required for developing Java TreeView</title>
<listitem> <para> Java SDK </para> </listitem>
<listitem> <para> JEdit or other code editor </para> </listitem>
<listitem> <para> ant, a Java-based replacement for make</para> </listitem>
<listitem> <para> DocBook environment,
	<emphasis> 
		only for documentation authoring
	 </emphasis>
</para>
</listitem>
</itemizedlist>
<sect1 id="ch1_requiredTools">
<title> Required Tools </title>
<para>
In this section, I will describe the tools required to build java treeview.
</para>

<sect2>
<title> TreeView Source Code </title>
<para>
You must, of course, download the source distribution of Java Treeview from http://jtreeview.sourceforge.net
</para>
</sect2>


<sect2>
<title> Java SDK </title>
<para>
The java sdk can be downloaded from the sun website at http://java.sun.com/j2se/.
</para>
</sect2>

<sect2>
<title> ant </title>
<para>
Apache Ant, the build tool, is available from 
http://ant.apache.org/bindownload.cgi
</para>
</sect2>


<sect2>
<title> Code Editor </title>
<para>
The crossplatform editor jedit is recommended, available from 
http://www.jedit.org/index.php?page=download
</para>
</sect2>

<sect2>
<title> DocBook </title>
<para>
Docbook is more of a file format (an XML dialect to be precise) than a tool.
</para>
</sect2>
</sect1>
<sect1 id="ch1_buildJTV">
<title> Building Java Treeview </title>
<para>
Once you have the java sdk and apache ant installed, unpack the source distribution of java treeview, open a command line shell, switch to the unpacked source directory, which should contain the build.xml file, and type "ant dist" to build java treeview. You should now have a freshly built TreeView.jar sitting in the "dist" subdirectory.
</para>
</sect1>
<sect1 id="ch1_buildDocs"> 
	<title> Building the documentation</title>
	<para> 
		Download a recent version of docbook-xsl or docbook-xsl-ns from
		<ulink url="http://sourceforge.net/project/showfiles.php?group_id=21935">
			http://sourceforge.net/project/showfiles.php?group_id=21935
		</ulink>
		unpack, and set an environment variable $XSL equal to the path. In mac os x, if docbook-xsl is unpacked in /usr/local/share/xml/xsl/docbook-xsl,
		then you would set the path with <command>export XSL=/usr/local/share/xml/xsl/docbook-xsl</command>.
	</para>
	<para>
		Download the current version of docbook (or docbook-4.5.zip, which is known to work) from 
		<ulink url="http://www.oasis-open.org/docbook/">http://www.oasis-open.org/docbook/</ulink>, unpack
		 and make a link called "docbook" in the LinkedView directory.
		This will enable your xml source files to be checked against the DTD, which
		greatly helps with writing the source when you have a DTD aware editor (such as
		<ulink url="http://xmlbuddy.com/">XML Buddy</ulink> for Eclipse). This is also required to resolve external entities, such as "&eacute;".
		
		</para>
	<para>
	You will probably also need the ISO entity sets from http://www.oasis-open.org/docbook/xmlcharent/0.3/index.shtml. Put them in an "ent" subdirectory of the docbook directory (i.e. the docbook-4.5 directory, not the xsl direcgtory).
	</para>
	<para>
		If you want to make the PDFs, you will need FOP (<ulink url="http://xmlgraphics.apache.org/fop/">http://xmlgraphics.apache.org/fop/</ulink>. 
		After you unpack this file, set an environment variable $FOP to point at the directory containing the fop shell script, for example <command>export FOP=/usr/local/share/xml/fop</command>.
		</para>
	<para>
		Make sure you have xsltproc installed. You should now be able to run the createAllDoc.pl script. 
	</para>
</sect1>
</chapter>
<chapter id="ch2">
<title> Reference Material </title>
<para> This chapter will hold reference material for java treeview development
</para>

<sect1> <title> Structure of XML Configuration Files </title>
<para> There are two types of xml configuration files used by java treeview,
a global xml configuration file and a per-document configuration file or JTV. The location of the global xml configuration file is described in the user manual.
</para>
<sect2> <title> Structure of Global XML Configuration File </title>
<para>
There is a single global XML configuration file in which java treeview stores the following information
</para>
<orderedlist>
<listitem> <para> recently used files list</para></listitem>

<listitem> <para> last style used</para></listitem>

<listitem> <para> whether parse quoted strings was used</para></listitem>

<listitem> <para> defaults settings for views</para></listitem>
</orderedlist>
<sect3 id="ch2_xml_global">
<title> Java Treeview 1.1.1 Global XML config</title>
<itemizedlist>
<listitem> <para> ProgramConfig </para> <para> Root node of XML config</para>
	<itemizedlist>
	<listitem> <para> FileMru arributes (style, quotes)</para> 
	<para> Node holds recent files, style attribute indicates last style used to open file, quotes indicate whether parseQuotedStrings was selected</para>
		<itemizedlist>
		<listitem> <para> File attributes (root, dir, style) optional (cdt) </para>
		<para> Node represents an individual file, with the dir it is found in, the root of the filename, and the style to open with. If cdt is specified, it means to use that extension instead of cdt to find the GCDT file.
		</para> </listitem>
		</itemizedlist>
	</listitem>
	<listitem> <para> GeneUrlPresets attribute (default) </para> 
	<para> Holds default gene url presets, default attribute indicated default preset. -1 means do not link at all by default. </para>
		<itemizedlist>
		<listitem> <para> Preset attributes (name, template, header, enabled) </para>
		<para> Holds info for one url preset. Name is the name of the preset, template is the template to fill in, header is which header to fill it in with (by name, not index) and enabled is whether the preset is enabled. I'm not sure when or why I added an enabled flag to all presets.
		</para>
		</listitem></itemizedlist>
	
	</listitem>
	<listitem> <para> ArrayUrlPresets attribute (default) </para> 
	<para> Holds default array url presets, default attribute indicated default preset. -1 means do not link at all by default. </para>
		<itemizedlist>
		<listitem> <para> Preset attributes (name, template, header, enabled) </para>
		<para> Holds info for one url preset. Name is the name of the preset, template is the template to fill in, header is which header to fill it in with (by name, not index) and enabled is whether the preset is enabled. I'm not sure when or why I added an enabled flag to all presets.
		</para>
		</listitem></itemizedlist>
	</listitem>
	<listitem> <para> Plugins</para> 
	<para> Presets and defaults for particular plugins.  </para>
		<itemizedlist>
		<listitem> <para>PluginPresets attrbutes (name)</para>
		<para> presets for plugin identified by name. Nodes will be provided to "presets configuration" dialogs that plugins make available, as well as the plugins themselves. </para>
		</listitem>
		<listitem> <para> PluginDefaults attributes (name) </para> 
		<para> Defaults for particular plugin, identified by name. These defaults shadow the configuration of the plugin in the per-document jtv, and are not directly modified by the plugin.</para>
		</listitem>
		</itemizedlist>
	</listitem>
	<listitem> <para> Registration </para> <para> registration status </para>
		<itemizedlist> <listitem>
		<para> Entry attributes (jtv_version, java_version, java_vendor, os_name, os_arch, os_version, install_ip, install_host, install_date, status, first_name, last_name, email, institution, contactOkay) </para>
		<para> Registration entry, with various info about the installation. status keeps track of the status of that registration, and has values "deferred", "declined", "pending" and "complete". The meaning of these settings, as of all settings, is currently defined only in the source code of java treeview.
		</para>
		</listitem>
		</itemizedlist>
	</listitem>
	</itemizedlist>
	
</listitem>
</itemizedlist>
</sect3>
<sect3 id="ch2_xml_global_1_0">
<title> Java Treeview 1.0.12 Global XML config</title>

<para>
In Java Treeview up until 1.0.12, the global configuration did not make any real distinction between places in which view-specific default values were stored, and places where program-wide defaults were stored. Moving forward, view specific defaults are now placed in a special "Defaults" node, which has subnodes for each type of view, and view-specific presets are put in a special "Presets" node. There are two things that are retained as view-indpendent general presets, the url and gene linking configuration. These pieces are actually provided to the views by the ViewFrame through the getUrlExtractor and getArrayUrlExtractor methods. Moving the per-view presets to their own nodes removes management of the dialogs from the main program, as well as weird calls such as "getKaryoColorPresets" that are clearly used by only one type of view from the LinkedViewFrame interface.
</para>
<para>
The following is the structure of the global configuration as of JTV 1.0.12
</para>
<itemizedlist>
<listitem> <para> ProgramConfig </para> <para> Root node of XML config</para>
	<itemizedlist>
	<listitem> <para> FileMru arributes (style, quotes)</para> 
	<para> Node holds recent files, style attribute indicates last style used to open file, quotes indicate whether parseQuotedStrings was selected</para>
		<itemizedlist>
		<listitem> <para> File attributes (root, dir, style) optional (cdt) </para>
		<para> Node represents an individual file, with the dir it is found in, the root of the filename, and the style to open with. If cdt is specified, it means to use that extension instead of cdt to find the GCDT file.
		</para> </listitem>
		</itemizedlist>
	</listitem>
	<listitem> <para> GeneUrlPresets attribute (default) </para> 
	<para> Holds default gene url presets, default attribute indicated default preset. -1 means do not link at all by default. </para>
		<itemizedlist>
		<listitem> <para> Preset attributes (name, template, header, enabled) </para>
		<para> Holds info for one url preset. Name is the name of the preset, template is the template to fill in, header is which header to fill it in with (by name, not index) and enabled is whether the preset is enabled. I'm not sure when or why I added an enabled flag to all presets.
		</para>
		</listitem></itemizedlist>
	
	</listitem>
	<listitem> <para> ArrayUrlPresetsattribute (default) </para> 
	<para> Holds default array url presets, default attribute indicated default preset. -1 means do not link at all by default. </para>
		<itemizedlist>
		<listitem> <para> Preset attributes (name, template, header, enabled) </para>
		<para> Holds info for one url preset. Name is the name of the preset, template is the template to fill in, header is which header to fill it in with (by name, not index) and enabled is whether the preset is enabled. I'm not sure when or why I added an enabled flag to all presets.
		</para>
		</listitem></itemizedlist>
	</listitem>
	<listitem> <para> ColorPresets</para> 
	<para> color presets for dendrogram</para>
		<itemizedlist>
		<listitem> <para>ColorSet attrbutes (name, up, down)</para>
		<para> Set of colors to use for dendrogram view. name is name, up is up color, down is down color. </para>
		</listitem>
		</itemizedlist>
	</listitem>
	<listitem> <para> KaryoColorPresets</para> <para>color presets forkaryoscope </para>
		<itemizedlist>
		<listitem> <para> KaryoColorSet attribute (name) </para>
		<para> Set of colors for karyoscope view. name is name of set. </para>
		 <itemizedlist><listitem>
		 <para> Color attribute (type, hex) </para>
		 <para> Particular color in set. Type is type of color, hex is hex value for color. </para>
		 </listitem> </itemizedlist>
		 
		 </listitem>
		 </itemizedlist>
	</listitem>
	<listitem> <para> ScatterColorPresets</para><para> sctterview color presets </para>
		<itemizedlist>
		<listitem> <para> ScatterColorSet attribute (name) </para>
		<para> Set of colors for karyoscope view. name is name of set. </para>
		 <itemizedlist>
		 <listitem>
		 <para> Color attribute (type, hex) </para>
		 <para> Particular color in set. Type is type of color, hex is hex value for color. </para>
		 </listitem>
		 </itemizedlist>
		</listitem>
		</itemizedlist>
	</listitem>
	<listitem> <para> CoordsPresets </para> <para> coordinates presets for  karyoscope </para> </listitem>
	<listitem> <para> Registration </para> <para> registration status </para>
		<itemizedlist> <listitem>
		<para> Entry attributes (jtv_version, java_version, java_vendor, os_name, os_arch, os_version, install_ip, install_host, install_date, status, first_name, last_name, email, institution, contactOkay) </para>
		<para> Registration entry, with various info about the installation. status keeps track of the status of that registration, and has values "deferred", "declined", "pending" and "complete". The meaning of these settings, as of all settings, is currently defined only in the source code of java treeview.
		</para>
		</listitem>
		</itemizedlist>
	</listitem>
	</itemizedlist>
	
</listitem>

</itemizedlist>
</sect3>
</sect2>
<sect2> <title> Structure of JTV XML Configuration File </title>
<para>
Each document also has a local JTV file for document-level settings. The nodes i
<itemizedlist>
<listitem>
<para> UrlExtractor attribute (urlTemplate,isEnabled, index)</para>
<para> used for gene url linking </para>
</listitem>
<listitem>
<para> ArrayUrlExtractor attribute (urlTemplate,isEnabled, index)</para>
<para> used for array url linking </para>
</listitem>
</itemizedlist>
</para>
</sect2>
</sect1>
	<sect1 id="ch2_karyoscope">
		<title> Architecture of Karyoscope Plugin </title>
		<para>
			The main class of the Karyoscope Plugin is KaryoPanel.
			It is a container for the KaryoView, KaryoViewParameterPanel and a
			StatusPanel, and coordinates interaction between them.
		</para>
	</sect1>
	<sect1 id="ch2_dendrogram">
		<title> Architecture of Dendrogram Plugin </title>
		<sect2 id="ch2_dendrogram_urlextractor">
		<title> Url Extraction </title>
		<para>
There is a single instance of the UrlExtractor for each document that is loaded 
by java treeview. Each instance contains a reference to the application level 
UrlPresets. Internally, there are two ways that a URL extractor can resolve a
request to make a URL, with the specific URL for a given HEADER (via lookup of the 
column header in the presets) or via the generic URL preset.
		</para>
</sect2>
	</sect1>
	
</chapter>
</book>