Model-file

Basics

The model-file controls the creation of a topic map. The model-file is a xml-file and must follow the tmharvest.dtd.

You may reference the dtd with the following doctype-declaration:

  <!DOCTYPE harvest 
    SYSTEM "http://tm4j.org/tmharvest/tmharvest-0.1.dtd">

The principle structure of a model goes like this:

<harvest>

  <context>
    common settings
  </context>

  divers <...Action> and <mergeMap>-elements

  optional <save>-command

</harvest>

<harvest>

The root element

The <harvest>-element is the root-element of the model-file.

The attributes of the <harvest>-element enables an author to identify a topic map which should be filled by this harvesting process.

How the attributes are precisely processed depends on the application that controls the harvesting process.

In the current release only the baselocator-attribute is taken into account. Each time the harvester is started a new topic map will be created in the in-memory-provider with the given baselocator.

<context>

The enviroment of the harvesting process

The <context>-element allows you to setup properties, that are relevant for different actions.

Currently there are two children of the <context>-element defined:

<datasource>

This element enables you to describe a jdbc-datasource as it is required by the SQLProvider. See the dtd for the supported attributes.

<constant>

Serves to define constants. While the modelfile is parsed and new patterns are created, constants are used to replace placeholders. See the definition of the pattern resolving mechanics. See the dtd for the supported attributes.

<...Action>-elements

The action-elements form the backbone of the harvesting process. They allow you to define the structure of the map and how it is populated.

Currently three different actions are defined:

<mergeAction>

loads an external topic map and merges it with the harvested one. The <mergeAction>-element is rather simple. In order to get a formal description, see the dtd. The filename-Attribute of the <mergeAction> is resolved relative to the location of the modelfile.

<saveAction>

saves the harvested topic map in xtm-format. The <saveAction>-element is rather simple. Please see the dtd

<templateAction>

creates, with the help of a template and an external datasource, elements in the topic map. The <templateAction> will be described in greater detail in the following section.

The templateAction

TMharvest uses templates to create and populate topic map objects. The templates contain elements that describe topic map structures. Attributes and bodytext of the elements may contain placeholders. The placeholders are replaced during the harvest process with concrete values from the datasources.

A <templateAction> combines a datasource (defined by a <...Provider>-element) and a <template>.

The template is processed once for each interation of the datasource. On each turn, the placeholders are substituted with concrete values. Afterwards the structures defined by the template are either created or fetched from the topic map and modified.

One harvest model may contain multiple <templateAction>, which are processed sequentially.