Custom Template Handlers

1. What are Template Handlers?
2. Handler usage format
3. Handler definition
4. Write your own handler

1. What are Template Handlers
Template Handlers are used for generating meaningful strings for dumped output files. They are mainly used for creation the output build.xml file of ANT.
The template handlers are part of a general extendable mechanism for generating ANT code according to information gathered from project definition files.

The handlers use Invicta API for accessing the project's definition information.

The actual usage of the handlers is in target templates of Type Definition Files (e.g. JAR.xml) for automatically generating code.

A template handler is a simple Java class that extends net.sf.invicta.handler.InvictaBasicHandler

Return to top

2. Handler usage format

Target templates should use handlers by containing one of the following:

%{token}

Replaced by a special string that matches the given token.

For example:

%{componentName}

Replaced by the name of the component that has this type definition (e.g. sample.utils).

Current available tokens:

componentName

componentDir

projectName

%{handler_name;parameter1;parameter2;parameter}

Replaced by the result of the handler specified by handler_name running on the given list of parameters.

For example:

%{property;build.lib.dir}

Replaced by the result of the property handler running on the parameter build.lib.dir in the context of the component that has this type definition. In this case, the property handler will check if build.lib.dir property is defined for this component type and return its reference value.

%{handler_name;key1=value1;key2=value2;key3=value3}

Replaced by the result of the handler specified by handler_name running on the given map of parameters. Each key is a parameter name followed by its value.

For example:

%{property;name=build.lib.dir;component=sample.utils}

Replaced by the result of the property handler running on the parameter name with the value build.lib.dir and the parameter component with the value sample.utils. In this case, the property handler will check if build.lib.dir property is defined for a component named sample.utils and and return its reference value.

Return to top

3. Handler Definition
Each handler defines its name to be used when called from ANT templates.
Handlers are classes that must be located in the CLASSPATH of the JVM that executes Invicta.

Handlers are defined in multiple services files that must be located in the CLASSPATH. The services file name is:

META-INF/services/net.sf.invicta.handler.InvictaHandler

Handlers classes and 'services' definition file can be stored in multiple JAR files. The built-in handlers are defined and stored in invicta.jar.

Return to top

4. Write your own Handler

Step by step instructions for writing your own handler:

Create a handler class

Create a new Java class that extends net.sf.invicta.handler.InvictaBasicHandler, for example:

net.sf.myproj.handlers.MyPropertyHandler

Implement abstract methods

Implement the following methods of InvictaBasicHandler:

- String getName() - Returns the name of this handler.

For example:

public String getName() {
    return "myProperty";
}

- String handle(List params) throws InvictaException - Returns the output string of a handler execution according to a given list of parameters.

For example:

public String handle(List params) throws InvictaException {
    String propertyName = getParameter(0);
    String result = getComponent().getPropertyValue(propertyName);

    return "my" + result;
}

- String handle(Map paramsMap) throws InvictaException - Returns the output string of a handler execution according to a given map of parameters.

For example:

public String handle(Map paramsMap) throws InvictaException {
    String propertyName = getParameter("name");
    String result = getComponent().getPropertyValue(propertyName);

    return "my" + result;
}

Add your handler's logic by doing the following:

- Process the given parameters using various utility methods. There are many useful methods, refer to Invicta API documentation for a complete list. A few examples:

int getParametersNumber();

String getParameter(int index);

String getParameter(Object key);

boolean getBooleanParameter(int index, boolean defaultValue);

boolean getBooleanParameter(Object key, boolean defaultValue);

- Use getComponent() for getting an InvictaComponent object of the current processed component.

- Use getProject() for getting an InvictaProject object of the current processed project.

- See Invicta API documentation for more details.

- Throw InvictaException on critical errors.

- Use log(String message) for displaying messages to the user.

Define your handler by adding the following line to a file named:

    META-INF/services/net.sf.invicta.handler.InvictaHandler

For example:

net.sf.myproj.handlers.MyPropertyHandler

This file has to be located in the JVM CLASSPATH (the META-INF directory is at the root of a classpath location).

Compile your handler class, pack it together with the "services" file in a JAR file and make sure that this JAR file is located in the CLASSPATH of the JVM that runs the Invicta (you may need to edit Invicta's startup scripts, such as invicta.build.xml).

Test your handler by using it in a target template of a type definition file . For example, add the following line:

<echo message="%{myProperty;build.dir}"/>

Document your handler !

Return to top