Changeset 3612


Ignore:
Timestamp:
Jul 31, 2007, 12:57:17 PM (15 years ago)
Author:
Nicklas Nordborg
Message:

References #595: Write "Appendix: extended-properties.xml reference"

Ready for reading.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/src/docbook/appendix/extended_properties.xml

    r3334 r3612  
    3030  <title>extended-properties.xml reference</title>
    3131 
    32   <para>
    33     This document is only available in the old format.
    34     See <ulink url="http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html"
    35       >http://base.thep.lu.se/chrome/site/doc/admin/extended-properties.html</ulink>.
    36   </para>
    37 
     32 
     33  <bridgehead>What is extended-properties.xml?</bridgehead>
     34
     35  <para>
     36    The <filename>extended-properties.xml</filename> file is a configuration
     37    file for customizing some of the tables in the BASE database.
     38    It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
     39    directory. Only a limited number of tables support this feature, the most important
     40    one is the table for storing reporter information.
     41  </para>
     42
     43  <para>
     44    The default <filename>extended-properties.xml</filename> that ships
     45    with BASE is biased towards the BASE 1.2 setup for 2-spotted microarray
     46    data. If you want your BASE installation to be configured differently we
     47    recommend that you do it before the first initialisation of the database.
     48    It is possible to change the configuration of an existing BASE installation but it
     49    may require manual updates to the database. Follow this procedure:
     50  </para>
     51
     52  <orderedlist>
     53  <listitem>
     54    <para>
     55    Shut down the BASE web server. If you have installed job agents you should shut
     56    down them as well.
     57    </para>
     58  </listitem>
     59 
     60  <listitem>
     61    <para>
     62    Modify the <filename>extended-properties.xml</filename> file. If you have installed
     63    job agents, make sure they all have the same version as the web server.
     64    </para>
     65  </listitem>
     66 
     67  <listitem>
     68    <para>
     69    Run the <filename>updatedb.sh</filename> script. New
     70    columns will automatically be created, but the script can't delete columns that
     71    have been removed, or modify columns that have changed datatype. You will have to
     72    do these kind of changes by manually executing SQL against your database. Check your
     73    database documentation for information about SQL syntax.
     74    </para>
     75   
     76    <tip>
     77      <title>Create a parallell installation</title>
     78      <para>
     79      You can always create a new temporary parallell installation to check
     80      what the table generated by installation script looks like. Compare the
     81      new table to the existing one and make sure they match.
     82      </para>
     83    </tip>
     84  </listitem>
     85 
     86  <listitem>
     87    <para>
     88    Start up the BASE web server and any job agents, if any, again.
     89    </para>
     90  </listitem>
     91 
     92  </orderedlist>
     93
     94  <tip>
     95    <title>Start with few columns</title>
     96    <para>
     97    It is better to start with too few columns, since it is easier to add
     98    more columns than it is to remove columns that are not needed.
     99    </para>
     100  </tip>
     101 
     102  <bridgehead>Sample extended properties setups</bridgehead>
     103 
     104  <itemizedlist>
     105  <listitem>
     106    <para>
     107    After installing BASE the default <filename>extended-properties.xml</filename>
     108    is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename> directory.
     109    This setup is biased towards the BASE 1.2 setup for 2-spotted cDNA arrays.
     110    If you are migrating from BASE 1.2 you need to use the default setup.
     111    </para>
     112  </listitem>
     113 
     114  <listitem>
     115    <para>
     116    A <filename>minimalistic_extended-properties.xml</filename> setup which doesn't
     117    define any extra columns at all. This file
     118    can be found in the <filename>&lt;basedir&gt;/misc/config</filename> directory,
     119    and should be used if it is not known what reporter data will be stored in the
     120    database. The addition of more columns later is straightforward.
     121    </para>
     122  </listitem>
     123  </itemizedlist>
     124
     125
     126  <bridgehead>Format of the extended-properties.xml file</bridgehead>
     127  <para>
     128    The <filename>extended-properties.xml</filename> is an XML file.
     129    The following example will serve as a description of the format:
     130  </para>
     131 
     132  <programlisting>
     133&lt;?xml version="1.0" ?&gt;
     134&lt;!DOCTYPE extended-properties SYSTEM "extended-properties.dtd"&gt;
     135&lt;extended-properties&gt;
     136   &lt;class name="ReporterData"&gt;
     137      &lt;property
     138         name="extra1"
     139         column="extra1"
     140         title="Extra property"
     141         type="string"
     142         length="255"
     143         null="true"
     144         update="true"
     145         insert="true"
     146         averagemethod="max"
     147         description="An extra property for all reporters"
     148      &gt;
     149      &lt;link
     150         regexp=".*"
     151         url="http://www.myexternaldb.com/find?{value}"
     152      /&gt;
     153      &lt;/property&gt;
     154   &lt;/class&gt;
     155&lt;/extended-properties&gt;
     156</programlisting>
     157 
     158  <para>
     159    Each table that can be customized is represented by a <sgmltag class="starttag">class</sgmltag>
     160    tag. The value of the <sgmltag>name</sgmltag> attribute is the name of the Java class
     161    that handles the information in that table. In the case of reporters
     162    the class name is <constant>ReporterData</constant>.
     163  </para>
     164 
     165  <para>
     166    Each <sgmltag class="starttag">class</sgmltag> tag may contain one or more
     167    <sgmltag class="starttag">property</sgmltag> tags, each one describing a single
     168    column in the table. The possible attributes of the <sgmltag class="starttag">property</sgmltag>
     169    tag are:
     170  </para>
     171 
     172    <informaltable frame="all">
     173    <tgroup cols="3" align="left">
     174      <colspec colname="attribute" align="left" />
     175      <colspec colname="required" />
     176      <colspec colname="comment" />
     177      <thead>
     178        <row>
     179          <entry>Attribute</entry>
     180          <entry>Required</entry>
     181          <entry>Comment</entry>
     182        </row>
     183      </thead>
     184      <tbody>
     185        <row>
     186          <entry>name</entry>
     187          <entry>yes</entry>
     188          <entry>
     189            A unique name (within the class) of the extra property.
     190            The name must only contain letters, numbers and underscores but the first character
     191            can't be a number. The name is used to identify the extra column in the Java code
     192            and in the Query API.
     193          </entry>
     194        </row>
     195        <row>
     196          <entry>column</entry>
     197          <entry>yes</entry>
     198          <entry>
     199            The name of the database column. This value must be unique within the
     200            class. Valid names depends on the database, but it should be safe
     201            to follow the same rules as for the <sgmltag>name</sgmltag> attribute.
     202            In most cases, it makes sense to use the same value for both the
     203            <sgmltag>name</sgmltag> and <sgmltag>column</sgmltag> attributes.
     204          </entry>
     205        </row>
     206        <row>
     207          <entry>title</entry>
     208          <entry>no</entry>
     209          <entry>
     210            The title of the extra property as it is displayed in client applications.
     211            If not specified the value of the <sgmltag>name</sgmltag> attrbiute is used.
     212          </entry>
     213        </row>
     214        <row>
     215          <entry>description</entry>
     216          <entry>no</entry>
     217          <entry>
     218            A longer (but still short!) description of the extra property which can be
     219            used in client applications to provide help.
     220          </entry>
     221        </row>
     222        <row>
     223          <entry>type</entry>
     224          <entry>yes</entry>
     225          <entry>
     226            The data type of the column. Allowed values are:
     227            <itemizedlist>
     228            <listitem>
     229              <simpara>int</simpara>
     230            </listitem>
     231            <listitem>
     232              <simpara>long</simpara>
     233            </listitem>
     234            <listitem>
     235              <simpara>float</simpara>
     236            </listitem>
     237            <listitem>
     238              <simpara>double</simpara>
     239            </listitem>
     240            <listitem>
     241              <simpara>boolean</simpara>
     242            </listitem>
     243            <listitem>
     244              <simpara>string</simpara>
     245            </listitem>
     246            <listitem>
     247              <simpara>date</simpara>
     248            </listitem>
     249            </itemizedlist>
     250           
     251            <para>
     252              Note that the given types are converted into the most appropriate database
     253              column type by Hibernate.
     254            </para>
     255          </entry>
     256        </row>
     257        <row>
     258          <entry>length</entry>
     259          <entry>no</entry>
     260          <entry>
     261            If the column is a string type, this is the maximum length that can
     262            be stored in the database. If no value is given, 255 is assumed.
     263          </entry>
     264        </row>
     265        <row>
     266          <entry>null</entry>
     267          <entry>no</entry>
     268          <entry>
     269            If the column should allow <constant>null</constant> values or not.
     270            Allowed values are <constant>true</constant> (default) and
     271            <constant>false</constant>.
     272          </entry>
     273        </row>
     274        <row>
     275          <entry>insert</entry>
     276          <entry>no</entry>
     277          <entry>
     278            If valus for this property should be inserted into the database or not.
     279            Allowed values are <constant>true</constant> (default) and
     280            <constant>false</constant>.
     281          </entry>
     282        </row>
     283        <row>
     284          <entry>update</entry>
     285          <entry>no</entry>
     286          <entry>
     287            If valus for this property should be updated in the database or not.
     288            Allowed values are <constant>true</constant> (default) and
     289            <constant>false</constant>.
     290          </entry>
     291        </row>
     292        <row>
     293          <entry>averagable</entry>
     294          <entry>no</entry>
     295          <entry>
     296            <emphasis>This attribute has been deprecated and replaced by the
     297            <sgmltag>averagemethod</sgmltag> attribute!</emphasis>
     298           
     299            <para>
     300              If it makes sense to calculate the average of a set of values
     301              for this property or not. By default, all numerical columns are
     302              averagable. For non-numerical columns this attribute is ignored.
     303            </para>
     304          </entry>
     305        </row>
     306        <row>
     307          <entry>averagemethod</entry>
     308          <entry>no</entry>
     309          <entry>
     310            The method to use when calculating the average of a set of values.
     311            This attribute replaces the <sgmltag>averagable</sgmltag> attribute.
     312            The following values can be used:
     313             
     314            <itemizedlist>
     315            <listitem>
     316              <simpara>
     317              <constant>none</constant>: average values are not supported
     318              (default for non-numerical columns)
     319              </simpara>
     320            </listitem>
     321            <listitem>
     322              <simpara>
     323              <constant>arithmetic_mean</constant>: calculate the arithmetic mean
     324              (default for numerical columns; not supported for non-numerical columns)
     325              </simpara>
     326            </listitem>
     327            <listitem>
     328              <simpara>
     329              <constant>geometric_mean</constant>: calculate the geometric mean
     330              (not supported for non-numerical columns)
     331              </simpara>
     332            </listitem>
     333            <listitem>
     334              <simpara>
     335              <constant>min</constant>: use the minimum value of the values in the set
     336              </simpara>
     337            </listitem>
     338            <listitem>
     339              <simpara>
     340              <constant>max</constant>: use the maximum value of the values in the set
     341              </simpara>
     342            </listitem>
     343            </itemizedlist>
     344             
     345          </entry>
     346        </row>
     347      </tbody>
     348    </tgroup>
     349    </informaltable>
     350 
     351  <para>
     352    Each <sgmltag class="starttag">property</sgmltag> tag may contain zero or more
     353    <sgmltag class="starttag">link</sgmltag> tags that can be used by client
     354    application to provide clickable links to other databases. Each
     355    <sgmltag class="starttag">link</sgmltag> has a <sgmltag>regexp</sgmltag>
     356    and an <sgmltag>url</sgmltag> attribute. If the regular expression matches
     357    the value a link will be created, otherwise not. The order of the
     358    <sgmltag class="starttag">link</sgmltag> tags are important, since only
     359    the first one that matches is used. The <sgmltag>url</sgmltag> attribute may
     360    contain the string <constant>{value}</constant> which will be replaced by the
     361    actual value when the link is generated.
     362  </para>
     363 
     364  <note>
     365    <para>
     366    If the link contains the character <constant>&amp;</constant> it must be
     367    escaped as <constant>&amp;amp;</constant>. For example, to link to a Unigene
     368    entry:
     369    </para>
     370    <programlisting>
     371&lt;link
     372   regexp="\w+\.\d+"
     373   url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene&amp;amp;term={value}[ClusterID]"
     374/&gt;
     375</programlisting>
     376  </note>
     377
     378 
    38379</appendix>
    39380
Note: See TracChangeset for help on using the changeset viewer.