source: trunk/doc/src/docbook/appendix/extended_properties.xml @ 5782

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE appendix PUBLIC 
    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN" 
    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
<!--
  $Id: extended_properties.xml 5782 2011-10-04 13:43:16Z nicklas $
  
  Copyright (C) 2007 Nicklas Nordborg, Martin Svensson
  
  This file is part of BASE - BioArray Software Environment.
  Available at http://base.thep.lu.se/
  
  BASE is free software; you can redistribute it and/or
  modify it under the terms of the GNU General Public License
  as published by the Free Software Foundation; either version 3
  of the License, or (at your option) any later version.
  
  BASE is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with BASE. If not, see <http://www.gnu.org/licenses/>.
-->

<appendix id="appendix.extendedproperties">
  <?dbhtml filename="extendedproperties.html" ?>
  <title>extended-properties.xml reference</title>
  
  
  <bridgehead>What is extended-properties.xml?</bridgehead>

  <para>
    The <filename>extended-properties.xml</filename> file is a configuration
    file for customizing some of the tables in the BASE database. 
    It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
    directory. Only a limited number of tables support this feature, the most important
    one is the table for storing reporter information.
  </para>

  <tip>
    <para>
      It is also possible to put additional extended property definitions in the
      <filename>&lt;basedir&gt;/www/WEB-INF/classes/extended-properties</filename>
      subdirectory. BASE will merge all <filename>*.xml</filename> it finds with 
      the main <filename>extended-properties.xml</filename> file. The extra 
      configuration files should have the same format as the main 
      <filename>extended-properties.xml</filename> file. The extra files
      may contain extra columns for classes that are already
      defined in the main file, but existing columns can't be removed or
      re-defined. 
      We recommend that you don't modify the default <filename>extended-properties.xml</filename>
      file at all (unless you want to remove some of the columns). This will make it
      easier when upgrading BASE since you don't have to worry about losing
      your own changes.
      
    </para>
  </tip>


  <para>
    The default <filename>extended-properties.xml</filename> that ships
    with BASE is biased towards the BASE version 1.2 setup for 2-spotted microarray
    data. If you want your BASE installation to be configured differently we
    recommend that you do it before the first initialisation of the database.
    It is possible to change the configuration of an existing BASE installation but it
    may require manual updates to the database. Follow this procedure:
  </para>

  <orderedlist>
  <listitem>
    <para>
    Shut down the BASE web server. If you have installed job agents you should shut
    down them as well.
    </para>
  </listitem>
  
  <listitem>
    <para>
    Modify the <filename>extended-properties.xml</filename> file or create a new file
    in the <filename>extended-properties</filename> subdirectory. If you have installed
    job agents, make sure they all have the same version as the web server.
    </para>
  </listitem>
  
  <listitem>
    <para>
    Run the <filename>updatedb.sh</filename> script. New
    columns will automatically be created, but the script can't delete columns that 
    have been removed, or modify columns that have changed data type. You will have to 
    do these kind of changes by manually executing SQL against your database. Check your 
    database documentation for information about SQL syntax.
    </para>
    
    <tip>
      <title>Create a parallel installation</title>
      <para>
      You can always create a new temporary parallel installation to check 
      what the table generated by installation script looks like. Compare the 
      new table to the existing one and make sure they match.
      </para>
    </tip>
  </listitem>
  
  <listitem>
    <para>
    Start up the BASE web server and job agents, if any, again.
    </para>
  </listitem>
  
  </orderedlist>

  <tip>
    <title>Start with few columns</title>
    <para>
    It is better to start with too few columns, since it is easier to add
    more columns than it is to remove columns that are not needed.
    </para>
  </tip>
  
  <bridgehead>Sample extended properties setups</bridgehead>
  
  <itemizedlist>
  <listitem>
    <para>
    After installing BASE the default <filename>extended-properties.xml</filename> 
    is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename> directory.
    This setup is biased towards the BASE version 1.2 setup for
    2-spotted cDNA arrays.  If you are migrating from BASE version 1.2
    you <emphasis>must</emphasis> to use the default setup.
    </para>
  </listitem>
  
  <listitem>
    <para>
    A <filename>minimalistic_extended-properties.xml</filename> setup which doesn't 
    define any extra columns at all. This file
    can be found in the <filename>&lt;basedir&gt;/misc/config</filename> directory,
    and should be used if it is not known what reporter data will be stored in the 
    database. The addition of more columns later is straightforward.
    </para>
  </listitem>
  </itemizedlist>

  <bridgehead>Format of the extended-properties.xml file</bridgehead>
  <para>
    The <filename>extended-properties.xml</filename> is an XML file.
    The following example will serve as a description of the format:
  </para>
  
  <programlisting language="xml">
&lt;?xml version="1.0" ?&gt;
&lt;!DOCTYPE extended-properties SYSTEM "extended-properties.dtd"&gt;
&lt;extended-properties&gt;
   &lt;class name="ReporterData"&gt;
      &lt;property
         name="extra1"
         column="extra1"
         title="Extra property"
         type="string"
         length="255"
         null="true"
         update="true"
         insert="true"
         averagemethod="max"
         description="An extra property for all reporters"
      &gt;
      &lt;link
         regexp=".*"
         url="http://www.myexternaldb.com/find?{value}"
      /&gt;
      &lt;/property&gt;
   &lt;/class&gt;
&lt;/extended-properties&gt;
</programlisting>
  
  <para>
    Each table that can be customized is represented by a <sgmltag class="starttag">class</sgmltag> 
    tag. The value of the <sgmltag>name</sgmltag> attribute is the name of the Java class
    that handles the information in that table. In the case of reporters
    the class name is <constant>ReporterData</constant>.
  </para>
  
  <para>
    Each <sgmltag class="starttag">class</sgmltag> tag may contain one or more
    <sgmltag class="starttag">property</sgmltag> tags, each one describing a single
    column in the table. The possible attributes of the <sgmltag class="starttag">property</sgmltag>
    tag are:
  </para>
  
    <table frame="all" id="appendix.extendedproperties.property">
    <title>Attributes for the <sgmltag class="starttag">property</sgmltag> tag</title>
    <tgroup cols="3" align="left">
      <colspec colname="attribute" align="left" />
      <colspec colname="required" />
      <colspec colname="comment" />
      <thead>
        <row>
          <entry>Attribute</entry>
          <entry>Required</entry>
          <entry>Comment</entry>
        </row>
      </thead>
      <tbody>
        <row>
          <entry>name</entry>
          <entry>yes</entry>
          <entry>
            A unique name (within the class) of the extra property. 
            The name must only contain letters, numbers and underscores but the first character 
            can't be a number. The name is used to identify the extra column in the Java code
            and in the Query API.
          </entry>
        </row>
        <row>
          <entry>column</entry>
          <entry>yes</entry>
          <entry>
            The name of the database column. This value must be unique within the 
            class. Valid names depends on the database, but it should be safe
            to follow the same rules as for the <sgmltag>name</sgmltag> attribute. 
            In most cases, it makes sense to use the same value for both the 
            <sgmltag>name</sgmltag> and <sgmltag>column</sgmltag> attributes.
          </entry>
        </row>
        <row>
          <entry>title</entry>
          <entry>no</entry>
          <entry>
            The title of the extra property as it is displayed in client applications.
            If not specified the value of the <sgmltag>name</sgmltag> attribute is used.
          </entry>
        </row>
        <row>
          <entry>description</entry>
          <entry>no</entry>
          <entry>
            A longer (but still short!) description of the extra property which can be
            used in client applications to provide help.
          </entry>
        </row>
        <row>
          <entry>type</entry>
          <entry>yes</entry>
          <entry>
            The data type of the column. Allowed values are:
            <itemizedlist>
            <listitem>
              <simpara>int</simpara>
            </listitem>
            <listitem>
              <simpara>long</simpara>
            </listitem>
            <listitem>
              <simpara>float</simpara>
            </listitem>
            <listitem>
              <simpara>double</simpara>
            </listitem>
            <listitem>
              <simpara>boolean</simpara>
            </listitem>
            <listitem>
              <simpara>string</simpara>
            </listitem>
            <listitem>
              <simpara>date</simpara>
            </listitem>
            <listitem>
              <simpara>timestamp</simpara>
            </listitem>
            </itemizedlist>
            
            <para>
              Note that the given types are converted into the most appropriate database 
              column type by Hibernate.
            </para>
          </entry>
        </row>
        <row>
          <entry>length</entry>
          <entry>no</entry>
          <entry>
            If the column is a string type, this is the maximum length that can
            be stored in the database. If no value is given, 255 is assumed.
          </entry>
        </row>
        <row>
          <entry>null</entry>
          <entry>no</entry>
          <entry>
            If the column should allow <constant>null</constant> values or not.
            Allowed values are <constant>true</constant> (default) and 
            <constant>false</constant>.
          </entry>
        </row>
        <row>
          <entry>insert</entry>
          <entry>no</entry>
          <entry>
            If values for this property should be inserted into the database or not.
            Allowed values are <constant>true</constant> (default) and 
            <constant>false</constant>.
          </entry>
        </row>
        <row>
          <entry>update</entry>
          <entry>no</entry>
          <entry>
            If values for this property should be updated in the database or not.
            Allowed values are <constant>true</constant> (default) and 
            <constant>false</constant>.
          </entry>
        </row>
        <row>
          <entry>averagemethod</entry>
          <entry>no</entry>
          <entry>
            The method to use when calculating the average of a set of values. 
            This attribute replaces the <sgmltag>averagable</sgmltag> attribute. 
            The following values can be used:
             
            <itemizedlist>
            <listitem>
              <simpara>
              <constant>none</constant>: average values are not supported 
              (default for non-numerical columns)
              </simpara>
            </listitem> 
            <listitem>
              <simpara>
              <constant>arithmetic_mean</constant>: calculate the arithmetic mean 
              (default for numerical columns; not supported for non-numerical columns)
              </simpara>
            </listitem> 
            <listitem>
              <simpara>
              <constant>geometric_mean</constant>: calculate the geometric mean 
              (not supported for non-numerical columns)
              </simpara>
            </listitem> 
            <listitem>
              <simpara>
              <constant>quadratic_mean</constant>: calculate the quadtratic mean 
              (not supported for non-numerical columns)
              </simpara>
            </listitem> 
            <listitem>
              <simpara>
              <constant>min</constant>: use the minimum value of the values in the set
              </simpara>
            </listitem> 
            <listitem>
              <simpara>
              <constant>max</constant>: use the maximum value of the values in the set
              </simpara>
            </listitem> 
            </itemizedlist>
             
          </entry>
        </row>
      </tbody>
    </tgroup>
    </table>
  
  <para>
    Each <sgmltag class="starttag">property</sgmltag> tag may contain zero or more
    <sgmltag class="starttag">link</sgmltag> tags that can be used by client
    application to provide clickable links to other databases. Each 
    <sgmltag class="starttag">link</sgmltag> has a <sgmltag>regexp</sgmltag>
    and an <sgmltag>url</sgmltag> attribute. If the regular expression matches 
    the value a link will be created, otherwise not. The order of the 
    <sgmltag class="starttag">link</sgmltag> tags are important, since only
    the first one that matches is used. The <sgmltag>url</sgmltag> attribute may
    contain the string <constant>{value}</constant> which will be replaced by the
    actual value when the link is generated.
  </para>
  
  <note>
    <para>
    If the link contains the character <constant>&amp;</constant> it must be
    escaped as <constant>&amp;amp;</constant>. For example, to link to a UniGene 
    entry:
    </para>
    <programlisting>
&lt;link
   regexp="\w+\.\d+"
   url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene&amp;amp;term={value}[ClusterID]"
/&gt;
</programlisting>
  </note>

  
</appendix>