A simple module

How to Create Tag Modules With Java

In this first example we create and install a very simple module. The module gives us an RXML tag that just converts its contents to upper case.

Creating the module

First we create the source file ReverseTag.java

• It imports com.roxen.roxen.* and java.util.Map

• It extends Module - so it must implement the methods info() and queryName()

• It implements ParserModule - so it must implement the method querySimpleTagCallers()

• It implements SimpleTagCaller - so it must implement the methods queryTagName(), queryTagFlags() and tagCalled()

Then we compile the source file to get the file ReverseTag.class

Source code for UppercaseTag.java

import com.roxen.roxen.*;
import java.util.Map;

public class UppercaseTag extends Module
    implements ParserModule, SimpleTagCaller {

    public String info() {
        return "This tag converts its contents to upper case.";
    }

    public String queryName() {
        return "Uppercase Tag";    //The name of the module
    }

    public SimpleTagCaller[] querySimpleTagCallers() {
        return new SimpleTagCaller[] { this };
    }

    public String queryTagName() {
        return "uppercase";        //The name of the tag
    }

    public int queryTagFlags() {
        return FLAG_NONE;
    }

    public String tagCalled(String tag,
                            Map args,
                            String contents,
                            RoxenRequest id,
                            Frame frame) {

        return contents.toUpperCase();	//The actual action
    }
}

Installing the new module

The following steps will add the module to a certain site:

• Copy the class file to somewhere in the module search path, preferably the folder [RoxenHome]/local/modules. Note: Do not use the server folder, since it is overwritten at site upgrades.

• In the admin interface, go to the proper site and select 'Add Module'

• Select 'Reload module list'

• Select 'Local Modules' to expand and show all modules in this group

• At the newly added module (Uppercase Tag) select 'Add module'

• The module now appears in the module list for that site. If changes are made to the module, replace the old class file with the new and select 'Reload'.

A Closer Look At the Methods

public String queryName()

Returns the module name. This is shown both in the list of available modules when adding a module and in the module list for the site after adding the module.

public String info()

Returns a description of the module, shown in the list of available modules.

public SimpleTagCaller[] querySimpleTagCallers()

Returns an array of objects that implement one RXML-tag each. In our simple example, the array consists of only one object, which happens to be the class itself since it also implements the interface SimpleTagCaller. If one module would contain more RXML tag implementations, they would have to be divided into several classes that are packed into a jar-file (more about how to install such a module later).

public String queryTagName()

Returns the name of the actual tag. For example, 'uppercase' means that the tag will be written as <uppercase>content</uppercase>. Tag names are case sensitive.

public int queryTagFlags()

The interface SimpleTagCaller contains a number of flags in the form of int constants. At least one of these shall be returned. Several might be added, and the sum, which represents a bit pattern showing which flags have been set, is returned. There is, for example, one flag showing that the element has no contents, and another showing that the element is a processing instruction. If no other flag is set, then FLAG_NONE shall be returned.

public String tagCalled(String tag, Map args, String contents, RoxenRequest id, Frame frame)

This method evaluates the element (the tag with its parameters and contents) and returns the result. The first parameter is the tag name, for example "uppercase". The second parameter is a map with all pairs of attributes/values from the tag. The third parameter is the content of the element. The last two parameters are Roxen specific environment objects that may provide, for example, the IP number of the client.