Appendix C. extended-properties.xml reference

Appendix C. extended-properties.xml reference
Prev	Part VI. Appendix	Next

What is extended-properties.xml?

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

Tip

	Tip
It is also possible to put additional extended property definitions in the `<basedir>/www/WEB-INF/classes/extended-properties` subdirectory. BASE will merge all `*.xml` it finds with the main `extended-properties.xml` file. The extra configuration files should have the same format as the main `extended-properties.xml` 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 `extended-properties.xml` 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.

It is also possible to put additional extended property definitions in the <basedir>/www/WEB-INF/classes/extended-properties subdirectory. BASE will merge all *.xml it finds with the main extended-properties.xml file. The extra configuration files should have the same format as the main extended-properties.xml 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 extended-properties.xml 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.

The default extended-properties.xml 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:

Shut down the BASE web server. If you have installed job agents you should shut down them as well.
Modify the extended-properties.xml file or create a new file in the extended-properties subdirectory. If you have installed job agents, make sure they all have the same version as the web server.

Run the updatedb.sh 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.

	Create a parallel installation
	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.

Start up the BASE web server and job agents, if any, again.

	Start with few columns
	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.

Sample extended properties setups

After installing BASE the default extended-properties.xml is located in the <basedir>/www/WEB-INF/classes 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 must to use the default setup.
A minimalistic_extended-properties.xml setup which doesn't define any extra columns at all. This file can be found in the <basedir>/misc/config 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.

Format of the extended-properties.xml file

The extended-properties.xml is an XML file. The following example will serve as a description of the format:

<?xml version="1.0" ?>
<!DOCTYPE extended-properties SYSTEM "extended-properties.dtd">
<extended-properties>
   <class name="ReporterData">
      <property
         name="extra1"
         column="extra1"
         title="Extra property"
         type="string"
         length="255"
         null="true"
         update="true"
         insert="true"
         averagemethod="max"
         restricted-edit="false"
         hidden="false"
         description="An extra property for all reporters"
      >
      <link
         regexp=".*"
         url="http://www.myexternaldb.com/find?{value}"
      />
      </property>
   </class>
</extended-properties>

Each table that can be customized is represented by a <class> tag. The value of the name attribute is the name of the Java class that handles the information in that table. In the case of reporters the class name is ReporterData.

Each <class> tag may contain one or more <property> tags, each one describing a single column in the table. The possible attributes of the <property> tag are:

Table C.1. Attributes for the <property> tag

Attribute	Required	Comment
name	yes	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.
column	yes	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 `name` attribute. In most cases, it makes sense to use the same value for both the `name` and `column` attributes.
title	no	The title of the extra property as it is displayed in client applications. If not specified the value of the `name` attribute is used.
description	no	A longer (but still short!) description of the extra property which can be used in client applications to provide help.
type	yes	The data type of the column. Allowed values are: int long float double boolean string date timestamp Note that the given types are converted into the most appropriate database column type by Hibernate.
length	no	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.
null	no	If the column should allow `null` values or not. Allowed values are `true` (default) and `false`.
insert	no	If values for this property should be inserted into the database or not. Allowed values are `true` (default) and `false`.
update	no	If values for this property should be updated in the database or not. Allowed values are `true` (default) and `false`.
restricted-edit	no	Allowed values are `false` (default) and `true`. If set, there is some restriction on who may change the values. This is currently only implemented for users. If the property is restricted only an administrator is allowed to change the value, not the user itself.
hidden	no	Allowed values are `false` (default) and `true`. If set, the property is normally not visible in the user interface. It is still possible for plug-ins and extensions to access and modify the property (using regular access permission rules).
averagemethod	no	The method to use when calculating the average of a set of values. This attribute replaces the `averagable` attribute. The following values can be used: `none`: average values are not supported (default for non-numerical columns) `arithmetic_mean`: calculate the arithmetic mean (default for numerical columns; not supported for non-numerical columns) `geometric_mean`: calculate the geometric mean (not supported for non-numerical columns) `quadratic_mean`: calculate the quadtratic mean (not supported for non-numerical columns) `min`: use the minimum value of the values in the set `max`: use the maximum value of the values in the set

Each <property> tag may contain zero or more <link> tags that can be used by client application to provide clickable links to other databases. Each <link> has a regexp and an url attribute. If the regular expression matches the value a link will be created, otherwise not. The order of the <link> tags are important, since only the first one that matches is used. The url attribute may contain the string {value} which will be replaced by the actual value when the link is generated.

Note

	Note
If the link contains the character `&` it must be escaped as `&`. For example, to link to a UniGene entry: <link regexp="\w+\.\d+" url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene&term={value}[ClusterID]" />

If the link contains the character & it must be escaped as &. For example, to link to a UniGene entry:

<link
   regexp="\w+\.\d+"
   url="http://www.ncbi.nlm.nih.gov/entrez/query.fcgi?db=unigene&amp;term={value}[ClusterID]"
/>

Prev	Up	Next
Appendix B. base.config reference	Home	Appendix D. Platforms and raw-data-types.xml reference