3. Implementation classes

XML Calabash Reference (Version 0.28)

3. Implementation classes

In order to run an atomic step (implemented in the JVM), the processor must know what class provides its implementation. Prior to XML Calabash 1.2.0, the preferred mechanism was to use annotations.

However, it turns out in practice that access to annotations can be challenging. They depend (I infer) on the security settings of the class loader in effect and are sometimes unavailable. The preferred mechanism is now a properties file.

3.1. Implementation class property file

Add a Java property file named “com.xmlcalabash.properties” to the jar file that includes the class which implements the step. The property file can declare namespaces and step implementations. For example:

cx = namespace http://xmlcalabash.com/ns/extensions
px = namespace http://example.com/ns/xproc

com.xmlcalabash.extensions.StepA = step cx:step-a
com.xmlcalabash.extensions.StepB = step cx:step-c
com.xmlcalabash.extensions.StepC = step cx:step-c,px:step-c-legacy

Namespaces prefixes are declared by using the prefix as the key in the property file with the value “namespace URI”.

Steps are declared by using the implementation class name as the key with the value “step QName” where QName is the step type. If the class implements multiple step types, use a comma separated list of step QNames.

For backwards compatibility, annotations take preference over property values. Also, any parsing errors in the property file(s) are reported as log messages at the DEBUG level.

3.2. Implementation class annotations

The preferred way to identify implementation classes is with the XMLCalabash annotation:

package com.example.package;

import com.xmlcalabash.core.XMLCalabash;
import com.xmlcalabash.library.DefaultStep;

@XMLCalabash(
        name = "ex:step-name",
        type = "{http://example.com/ns/extensions}step-name")

public class StepName extends DefaultStep {
   …
}

The name annotation might be used in messages, but it's the type annotation that's important. It must be the namespace URI and local name of the step type in “Clark notation.” If there are multiple steps that share an implementation the type annotation may be a space-separated list of tokens.

3.3. Implementation classes in the configuration file

If for some reason it isn't possible to use a property file or an annotation, the cc:implementation element in the XML Configuration file can be used instead:

XML configuration: <cc:implementation type="QName" class-name="class-name"/>

The type attribute may be a space-separated list of QNames. The class-name must be a fully qualified class name, such as com.xmlcalabash.library.Identity.


2 . Saxon configuration		4 . Schema aware processing