Page History

The mapping file (ps-example.xml by default) tells XMLPS how to interact with the underlying database.

The tables element tells XMLPS which tables it should care about and how it should join those tables. At the minimum you must specify a default table

<tables default="myDefaultTable">
</tables>

You may also add additional tables to the config as well. All additional tables will be INNER JOINed to the default table before running a query.

<tables default="myDefaultTable">
	<table name="someOtherTable" join="id" tofld="defaultTableId" />
</tables>

A table's join field specifies the field that should be used when joining to the default table. The tofld field specifies which default table field you want to join on. The above configuration will results in the following FROM clause generation:

FROM someOtherTable INNER JOIN myDefaultTable ON someOtherTable.id = myDefaultTable.defaultTableId

You can add as many additional table elements as you need. Just remember that joins are always on the default table and make sure you specify fields that actually exist (for obvious reasons)!

field elements tell XMLPS how is should map query fields to the underlying database. Fields can be either constant or dynamic

Constant fields map a query field to some constant value. As an example, let's say that for some database the STUDY_SITE_ID field is always mapped to 5. Instead of actually querying the database for this value we can just map it:

<field type="constant" name="STUDY_SITE_ID" value="5" />

Note that the field in question doesn't actually need to be stored in the database. You can map fields that don't exist to constant values without having to worrying about sending broken queries to the database. The name field simply specifies the field name IN THE QUERY.

Dynamic fields map a query field to some field in the underlying database.

<field type="dynamic" name="STUDY_PARTICIPANT_ID" dbname="id" />

Whenever a query asks for STUDY_PARTICIPANT_ID the system will run a query for defaultTable.id. If you want to specify which table the value should be pulled from you can:

<field type="dynamic" table="someTableName" name="STUDY_PARTICIPANT_ID" dbname="id" />

Now queries for STUDY_PARTICIPANT_ID will map to someTableName.id instead of using the default table name. You can also specify the default table in the table attribute without worrying that something will break.

Sometimes your dynamic field results might need to be altered post-query. In that case you'll want to use a mapping function. XMLPS comes with ReplaceFunc which simply maps a query result to some other value. Consider the following example which takes numeric results and converts them to a text representation if they are 1, 2, or 3.

<field type="dynamic" table="raceResults" name="RESULTS" dbname="place">
	<translate>
		<func class="org.apache.oodt.xmlps.mapping.funcs.ReplaceFunc" orig="1" with="First!" />
		<func class="org.apache.oodt.xmlps.mapping.funcs.ReplaceFunc" orig="2" with="Second!" />
		<func class="org.apache.oodt.xmlps.mapping.funcs.ReplaceFunc" orig="3" with="Third!" />
	</translate>
</field>

If you would like to make your own custom mapping functions all you need to do is implement the org.apache.xmlps.mapping.funcs.MappingFunc interface.