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

Last change on this file was 7497, checked in by Nicklas Nordborg, 3 years ago

References #2125: Add support for hidden extended properties

Updated documentation.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Date Id
File size: 13.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE appendix PUBLIC
3    "-//Dawid Weiss//DTD DocBook V3.1-Based Extension for XML and graphics inclusion//EN"
4    "../../../../lib/docbook/preprocess/dweiss-docbook-extensions.dtd">
5<!--
6  $Id: extended_properties.xml 7497 2018-07-11 13:18:08Z nicklas $
7 
8  Copyright (C) 2007 Nicklas Nordborg, Martin Svensson
9 
10  This file is part of BASE - BioArray Software Environment.
11  Available at http://base.thep.lu.se/
12 
13  BASE is free software; you can redistribute it and/or
14  modify it under the terms of the GNU General Public License
15  as published by the Free Software Foundation; either version 3
16  of the License, or (at your option) any later version.
17 
18  BASE is distributed in the hope that it will be useful,
19  but WITHOUT ANY WARRANTY; without even the implied warranty of
20  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
21  GNU General Public License for more details.
22 
23  You should have received a copy of the GNU General Public License
24  along with BASE. If not, see <http://www.gnu.org/licenses/>.
25-->
26
27<appendix id="appendix.extendedproperties">
28  <?dbhtml filename="extendedproperties.html" ?>
29  <title>extended-properties.xml reference</title>
30 
31 
32  <bridgehead>What is extended-properties.xml?</bridgehead>
33
34  <para>
35    The <filename>extended-properties.xml</filename> file is a configuration
36    file for customizing some of the tables in the BASE database.
37    It is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename>
38    directory. Only a limited number of tables support this feature, the most important
39    one is the table for storing reporter information.
40  </para>
41
42  <tip>
43    <para>
44      It is also possible to put additional extended property definitions in the
45      <filename>&lt;basedir&gt;/www/WEB-INF/classes/extended-properties</filename>
46      subdirectory. BASE will merge all <filename>*.xml</filename> it finds with
47      the main <filename>extended-properties.xml</filename> file. The extra
48      configuration files should have the same format as the main
49      <filename>extended-properties.xml</filename> file. The extra files
50      may contain extra columns for classes that are already
51      defined in the main file, but existing columns can't be removed or
52      re-defined.
53      We recommend that you don't modify the default <filename>extended-properties.xml</filename>
54      file at all (unless you want to remove some of the columns). This will make it
55      easier when upgrading BASE since you don't have to worry about losing
56      your own changes.
57     
58    </para>
59  </tip>
60
61
62  <para>
63    The default <filename>extended-properties.xml</filename> that ships
64    with BASE is biased towards the BASE version 1.2 setup for 2-spotted microarray
65    data. If you want your BASE installation to be configured differently we
66    recommend that you do it before the first initialisation of the database.
67    It is possible to change the configuration of an existing BASE installation but it
68    may require manual updates to the database. Follow this procedure:
69  </para>
70
71  <orderedlist>
72  <listitem>
73    <para>
74    Shut down the BASE web server. If you have installed job agents you should shut
75    down them as well.
76    </para>
77  </listitem>
78 
79  <listitem>
80    <para>
81    Modify the <filename>extended-properties.xml</filename> file or create a new file
82    in the <filename>extended-properties</filename> subdirectory. If you have installed
83    job agents, make sure they all have the same version as the web server.
84    </para>
85  </listitem>
86 
87  <listitem>
88    <para>
89    Run the <filename>updatedb.sh</filename> script. New
90    columns will automatically be created, but the script can't delete columns that
91    have been removed, or modify columns that have changed data type. You will have to
92    do these kind of changes by manually executing SQL against your database. Check your
93    database documentation for information about SQL syntax.
94    </para>
95   
96    <tip>
97      <title>Create a parallel installation</title>
98      <para>
99      You can always create a new temporary parallel installation to check
100      what the table generated by installation script looks like. Compare the
101      new table to the existing one and make sure they match.
102      </para>
103    </tip>
104  </listitem>
105 
106  <listitem>
107    <para>
108    Start up the BASE web server and job agents, if any, again.
109    </para>
110  </listitem>
111 
112  </orderedlist>
113
114  <tip>
115    <title>Start with few columns</title>
116    <para>
117    It is better to start with too few columns, since it is easier to add
118    more columns than it is to remove columns that are not needed.
119    </para>
120  </tip>
121 
122  <bridgehead>Sample extended properties setups</bridgehead>
123 
124  <itemizedlist>
125  <listitem>
126    <para>
127    After installing BASE the default <filename>extended-properties.xml</filename> 
128    is located in the <filename>&lt;basedir&gt;/www/WEB-INF/classes</filename> directory.
129    This setup is biased towards the BASE version 1.2 setup for
130    2-spotted cDNA arrays.  If you are migrating from BASE version 1.2
131    you <emphasis>must</emphasis> to use the default setup.
132    </para>
133  </listitem>
134 
135  <listitem>
136    <para>
137    A <filename>minimalistic_extended-properties.xml</filename> setup which doesn't
138    define any extra columns at all. This file
139    can be found in the <filename>&lt;basedir&gt;/misc/config</filename> directory,
140    and should be used if it is not known what reporter data will be stored in the
141    database. The addition of more columns later is straightforward.
142    </para>
143  </listitem>
144  </itemizedlist>
145
146  <bridgehead>Format of the extended-properties.xml file</bridgehead>
147  <para>
148    The <filename>extended-properties.xml</filename> is an XML file.
149    The following example will serve as a description of the format:
150  </para>
151 
152  <programlisting language="xml">
153&lt;?xml version="1.0" ?&gt;
154&lt;!DOCTYPE extended-properties SYSTEM "extended-properties.dtd"&gt;
155&lt;extended-properties&gt;
156   &lt;class name="ReporterData"&gt;
157      &lt;property
158         name="extra1"
159         column="extra1"
160         title="Extra property"
161         type="string"
162         length="255"
163         null="true"
164         update="true"
165         insert="true"
166         averagemethod="max"
167         restricted-edit="false"
168         hidden="false"
169         description="An extra property for all reporters"
170      &gt;
171      &lt;link
172         regexp=".*"
173         url="http://www.myexternaldb.com/find?{value}"
174      /&gt;
175      &lt;/property&gt;
176   &lt;/class&gt;
177&lt;/extended-properties&gt;
178</programlisting>
179 
180  <para>
181    Each table that can be customized is represented by a <sgmltag class="starttag">class</sgmltag> 
182    tag. The value of the <sgmltag>name</sgmltag> attribute is the name of the Java class
183    that handles the information in that table. In the case of reporters
184    the class name is <constant>ReporterData</constant>.
185  </para>
186 
187  <para>
188    Each <sgmltag class="starttag">class</sgmltag> tag may contain one or more
189    <sgmltag class="starttag">property</sgmltag> tags, each one describing a single
190    column in the table. The possible attributes of the <sgmltag class="starttag">property</sgmltag>
191    tag are:
192  </para>
193 
194    <table frame="all" id="appendix.extendedproperties.property">
195    <title>Attributes for the <sgmltag class="starttag">property</sgmltag> tag</title>
196    <tgroup cols="3" align="left">
197      <colspec colname="attribute" align="left" />
198      <colspec colname="required" />
199      <colspec colname="comment" />
200      <thead>
201        <row>
202          <entry>Attribute</entry>
203          <entry>Required</entry>
204          <entry>Comment</entry>
205        </row>
206      </thead>
207      <tbody>
208        <row>
209          <entry>name</entry>
210          <entry>yes</entry>
211          <entry>
212            A unique name (within the class) of the extra property.
213            The name must only contain letters, numbers and underscores but the first character
214            can't be a number. The name is used to identify the extra column in the Java code
215            and in the Query API.
216          </entry>
217        </row>
218        <row>
219          <entry>column</entry>
220          <entry>yes</entry>
221          <entry>
222            The name of the database column. This value must be unique within the
223            class. Valid names depends on the database, but it should be safe
224            to follow the same rules as for the <sgmltag>name</sgmltag> attribute.
225            In most cases, it makes sense to use the same value for both the
226            <sgmltag>name</sgmltag> and <sgmltag>column</sgmltag> attributes.
227          </entry>
228        </row>
229        <row>
230          <entry>title</entry>
231          <entry>no</entry>
232          <entry>
233            The title of the extra property as it is displayed in client applications.
234            If not specified the value of the <sgmltag>name</sgmltag> attribute is used.
235          </entry>
236        </row>
237        <row>
238          <entry>description</entry>
239          <entry>no</entry>
240          <entry>
241            A longer (but still short!) description of the extra property which can be
242            used in client applications to provide help.
243          </entry>
244        </row>
245        <row>
246          <entry>type</entry>
247          <entry>yes</entry>
248          <entry>
249            The data type of the column. Allowed values are:
250            <itemizedlist>
251            <listitem>
252              <simpara>int</simpara>
253            </listitem>
254            <listitem>
255              <simpara>long</simpara>
256            </listitem>
257            <listitem>
258              <simpara>float</simpara>
259            </listitem>
260            <listitem>
261              <simpara>double</simpara>
262            </listitem>
263            <listitem>
264              <simpara>boolean</simpara>
265            </listitem>
266            <listitem>
267              <simpara>string</simpara>
268            </listitem>
269            <listitem>
270              <simpara>date</simpara>
271            </listitem>
272            <listitem>
273              <simpara>timestamp</simpara>
274            </listitem>
275            </itemizedlist>
276           
277            <para>
278              Note that the given types are converted into the most appropriate database
279              column type by Hibernate.
280            </para>
281          </entry>
282        </row>
283        <row>
284          <entry>length</entry>
285          <entry>no</entry>
286          <entry>
287            If the column is a string type, this is the maximum length that can
288            be stored in the database. If no value is given, 255 is assumed.
289          </entry>
290        </row>
291        <row>
292          <entry>null</entry>
293          <entry>no</entry>
294          <entry>
295            If the column should allow <constant>null</constant> values or not.
296            Allowed values are <constant>true</constant> (default) and
297            <constant>false</constant>.
298          </entry>
299        </row>
300        <row>
301          <entry>insert</entry>
302          <entry>no</entry>
303          <entry>
304            If values for this property should be inserted into the database or not.
305            Allowed values are <constant>true</constant> (default) and
306            <constant>false</constant>.
307          </entry>
308        </row>
309        <row>
310          <entry>update</entry>
311          <entry>no</entry>
312          <entry>
313            If values for this property should be updated in the database or not.
314            Allowed values are <constant>true</constant> (default) and
315            <constant>false</constant>.
316          </entry>
317        </row>
318        <row>
319          <entry>restricted-edit</entry>
320          <entry>no</entry>
321          <entry>
322            Allowed values are <constant>false</constant> (default) and
323            <constant>true</constant>. If set, there is some restriction
324            on who may change the values. This is currently only implemented
325            for users. If the property is restricted only an administrator is allowed
326            to change the value, not the user itself.
327          </entry>
328        </row>
329        <row>
330          <entry>hidden</entry>
331          <entry>no</entry>
332          <entry>
333            Allowed values are <constant>false</constant> (default) and
334            <constant>true</constant>. If set, the property is normally
335            not visible in the user interface. It is still possible for
336            plug-ins and extensions to access and modify the property
337            (using regular access permission rules).
338          </entry>
339        </row>
340        <row>
341          <entry>averagemethod</entry>
342          <entry>no</entry>
343          <entry>
344            The method to use when calculating the average of a set of values.
345            This attribute replaces the <sgmltag>averagable</sgmltag> attribute.
346            The following values can be used:
347             
348            <itemizedlist>
349            <listitem>
350              <simpara>
351              <constant>none</constant>: average values are not supported
352              (default for non-numerical columns)
353              </simpara>
354            </listitem> 
355            <listitem>
356              <simpara>
357              <constant>arithmetic_mean</constant>: calculate the arithmetic mean
358              (default for numerical columns; not supported for non-numerical columns)
359              </simpara>
360            </listitem> 
361            <listitem>
362              <simpara>
363              <constant>geometric_mean</constant>: calculate the geometric mean
364              (not supported for non-numerical columns)
365              </simpara>
366            </listitem> 
367            <listitem>
368              <simpara>
369              <constant>quadratic_mean</constant>: calculate the quadtratic mean
370              (not supported for non-numerical columns)
371              </simpara>
372            </listitem> 
373            <listitem>
374              <simpara>
375              <constant>min</constant>: use the minimum value of the values in the set
376              </simpara>
377            </listitem> 
378            <listitem>
379              <simpara>
380              <constant>max</constant>: use the maximum value of the values in the set
381              </simpara>
382            </listitem> 
383            </itemizedlist>
384             
385          </entry>
386        </row>
387      </tbody>
388    </tgroup>
389    </table>
390 
391  <para>
392    Each <sgmltag class="starttag">property</sgmltag> tag may contain zero or more
393    <sgmltag class="starttag">link</sgmltag> tags that can be used by client
394    application to provide clickable links to other databases. Each
395    <sgmltag class="starttag">link</sgmltag> has a <sgmltag>regexp</sgmltag>
396    and an <sgmltag>url</sgmltag> attribute. If the regular expression matches
397    the value a link will be created, otherwise not. The order of the
398    <sgmltag class="starttag">link</sgmltag> tags are important, since only
399    the first one that matches is used. The <sgmltag>url</sgmltag> attribute may
400    contain the string <constant>{value}</constant> which will be replaced by the
401    actual value when the link is generated.
402  </para>
403 
404  <note>
405    <para>
406    If the link contains the character <constant>&amp;</constant> it must be
407    escaped as <constant>&amp;amp;</constant>. For example, to link to a UniGene
408    entry:
409    </para>
410    <programlisting>
411&lt;link
412   regexp="\w+\.\d+"
413   url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene&amp;amp;term={value}[ClusterID]"
414/&gt;
415</programlisting>
416  </note>
417
418 
419</appendix>
420
Note: See TracBrowser for help on using the repository browser.