Templates

A template contains elements that describe topicmap objects that you want to create or modify. For example, you can define that an occurrence is added to a certain topic, or you describe an association which shall be created.

A template is processed once for each datarecord that the provider returns.

In each iteration, the placeholders in the template are substituted with concrete value from the current record. Afterwards theese completed elements serve to identify or create topic map objects.

The following strategies are used throughout the template-based harvesting:

Identification of topics

Whenever an element stands for a topic or a reference to a topic (this is true for: <topic>, <instanceOf>, <roleSpec> and <player>) you may use one of the identification attributes to lookup an existing topic.

If no topic that matches the given criteria can be found, a new one is created. In this case, the new topic will automatically be populated with a set of characteristics which depend on the match criteria used.

The names of the identification attributes start with the prefix by. The values of the identification attributes may contain placeholders.

The following identification attributes are currently supported:

byID

Identifies a topic by its internal tm4j-id.

If the topic is created by parsing a xtm-source, the tm4j-id equals the id-attribute from the xml-serialisation. If no id-attribute was defined for the topic, tm4j assigns the topic object a new generic id.

Note

Unfortunately, the current implementation of the ltm-parser (in tm4j-0.8.3 and prior versions) does not preserve the assigned ids. For a deeper discussion see working with ltm-files in TMHarvest in the tips section.

If no topic with the given id exists, a new topic is created and the given id is assigned to it. The resourceLocator of the topic is assembled from the baseLocator of the topicmap and the given id, which is used as the fragment-Identifier.

byResourceLocator

Identifies a topic by the given resourceLocator.

The resourceLocator of a topic is composed of the baseLocator of its parent topicmap and a fragment identifier. The fragment identifier is defined by the id-attribute of the XTM-File (respectively the ID from LTM-File), or maybe by a byID-attribute, if the topic was created by TMHarvest. If no id was around when the topic was created, tm4j did assign a generic id to the topic.

If no topic with the given resourceLocator could be found, a new one is created. The given resourceLocator is assigned to the new topic and the fragment identifier of the locator is used as id.

bySubjectIndicator

Identifies a topic by the given subjectIndicator.

If no topic with the given subjectIndicator could be found, TMHarvest creates a new topic. A new id is generated for the topic and the given subjectIndidcator is assigned to the new topic.

byTolog

Identifies a topic by the given tolog query.

The first column of the query's resultset should refer to a topic. If the query returns more than one row, only the first row is taken into account.

Note

Unlike the other forms of topic idenfication, if the query does not return a topic, TMHarvest does not create a new one.

Patternresolving

You may use placeholders in the attributes and in the bodytexts of the template elements. TMHarvest substitutes the placeholders with concrete values in two stages of the harvesting process:

While the harvest model is parsed, the <constant>-elements from the <context>-element are used to substitute placeholders.
The remaining placeholders, that did not match to a constant, are left untouched until their template is processed. While TMHarvest iterates over the datasources the placeholders are substituted for each record with the actual data.

The syntax of the placeholders follow the well-known format "${REF}". "REF" is the name, under which a provider exports a value. The dollar-sign and the braces serves as placeholder identification.

If a placeholders name is not bound to a value in a record, the placeholder remains in the resulting string as a literal, all inclusive the dollar-sign and the braces.

The patterns may contain mixed static and dynamic parts as in the following example "id=${REF}".

Supposed a provider returns as a record two name-value-pairs:

  price=23
  currency=euro

The pattern:

"Price: ${price} ${currency}"

will be substituted to the following string:

"Price: 23 euro"

Error handling

Each template element may contain an onError-attribute. With this attribute you define, how TMHarvest reacts if an exception is thrown during the processing of the element's body.

The dtd defines three values, that can be assigned to the onError-attribute.

pass: The Exception is passed through to the parent element. This is the default for all template-elements. If an exception is passed through by the two top-level elements <topic> and <association> than the harvesting process is canceled.
ignore: The exception is ignored. If the exception occurs before or while some element is created, the element does not exist and can not be used by its parent. This may lead to subsequent exceptions.
remove: The element, which was actually processed, while the exception was thrown, will be removed..
Note
Currently (in TMHarvest 0.1), when an error occurs it is not possible to distinguish between elements that were just created and and elements that were fetched from a merged topic map. This means, that using onError="remove" may lead to the removal of elements, that existed innocently in the topicmap, before the template that caused the error was processed.

Template elements

TMHarvest currently defines the following elements to create or modify topic map objects. The name of the elements follow the XTM-Sytax.

template

Root element of the template. Contains <topic>- and <association>-elements.

topic

Creates a new topic or modifies an existing one. An existing one ist specified by one of the identification-attributes. If no such topic can be found, a new one is created.

association

Creates a new association of the (optional) given type and with the specified members. Members and types are specified within child elements.

subjectIndicator

Creates a subject indicator and adds it to the enclosing topic.

The enclosed text may contain placeholders which are resolved against the current record.

instanceOf

Creates a typing association for the enclosing element.

The topic, which plays the role of class in this association is fetched by using the identifying attributes. If no topic could be found, a new one is created.

basename

Creates a basename and adds it to the enclosing topic.

The enclosed text may contain placeholders which are resolved against the current record.

occurrence

Creates an occurrence and adds it to the enclosing topic.

data

Creates an inline-resource and adds it to the enclosing occurrence.

The enclosed text may contain placeholders which are resolved against the current record

resource

Creates a link to an in- or external resource and adds it to the enclosing occurrence.

The enclosed text may contain placeholders which are resolved against the current record

member

Creates a member elements and adds it ot the enclosig association.

roleSpec

Creates a roleSpec for the enclosing member.

Identifies the role defining topic by the usual attributes.

player

Creates a player for the enclosing member.

Identifies the role playing topic by the usual attributes.