Tailoring CData Arc with Custom Formatters

The Formatters within CData Arc (Arc) can be extended, through the use of a pre-existing interface, to make use of pre-written code, specialized use cases, and familiar development environments. Arc supports the development of custom Formatters in both C# and Java languages through a straightforward process of wrapping the desired functionality in a simple interface.

This article is designed to walk through the process of developing and calling a custom Formatter within Arc.

Formatters within Arc

Arc comes with a variety of pre-built Formatters that are responsible for modifying or formatting values within a section of ArcScript. These Formatters are commonly used to make sure that data is formatted correctly in order to conform to the requirements of a particular flow or use case.

Some common Formatters within Arc include the equals() formatter which acts as a simple condition checker, which will return true if the input attribute matches the configured value, and will otherwise return false. The todate() formatter is used often to transform an input date format to a different output date format. This is useful when a database requires a specific format for a date column when inserting data. The add() formatter is commonly used to add values together, such as multiple item prices in a single order.

However, sometimes a use case arises where the creation of a custom formatter might serve better than using one or a combination of the pre-built formatters that come with Arc. For example, it might be necessary to remove any occurrences of double-spaces in a string in order to pass a requirement set by a trading partner. Instead of using a combination of pre-build formatters to solve this, you could easily create your own custom formatter that is built to remove any instances of double-spaces. This is the example that will be fleshed out in more detail as this article progresses.

All formatters within Arc, both pre-built and custom, are unique in their functionality however they do share a commonality when it comes to how they are executed and how they are called within Arc.

Attributes, Pipes and Parameters

Calling a formatter within Arc will require the understanding and use of three different concepts; Attributes, Pipes and Parameters.

Attributes, which can be thought of as the input to the formatter, are passed into formatters using vertical pipe characters ( | ) where the left side of the pipe is the attribute. An abstract representation of calling a formatter looks like this:

[item.attribute | formatter(parameters)]

Where item.attribute is the input attribute, formatter is the name of the formatter that will act on the attribute and parameters is an optional set of parameters that can control the output for the formatter. Some formatters do not require an input attribute or parameters, while for other formatters, these can be optional or even required. Take for example the replace formatter:

[input.string | replace(oldvalue, newvalue[, ishex])]

In the above replace formatter, input.string is the input attribute, oldvalue and newvalue are both required parameters, while ishex is an optional parameter. When the replace formatter executes it searches the input attribute for the value set as oldvalue, removes it, and replaces it with newvalue. The optional ishex parameter indicates if the oldvalue parameter is a hex representation of a character to replace.

For formatters that do not require input, such as the now() date formatter, an underscore must be provided before the pipe in order to signal that no input is being passed:

<arc:set attr="timestamp" value="[_ | now()]" />

You can also chain together multiple formatters in a single expression by simply separating them with a pipe character.

Creating Custom Formatters for use in Arc

The core principle of developing a custom formatter is simple and involves implementing a two-method interface called RSBFormatter. This interface can be manipulated using either Java or C#, but for the example presented within this article, C# will be used.

Referencing the RSBFormatter interface

In order to implement the RSBFormatter interface in code, the project must reference RSSBus.dll (Windows) or rssbus.jar (Java). For Windows, the .dll to include is located here:

C:\Program Files\CData\CData Arc\www\bin\RSSBus.dll

In Java, the .jar file to include is located in the WEB-INF/lib folder for the server hosting the application; for example when using the embedded Jetty server the file is located here:

/opt/arc/webapp/WEB-INF/lib/rssbus.jar

Please keep in mind that this path to the WEB-INF/lib folder may differ when hosting Arc on an external servlet like Tomcat.

This interface is the backbone to all formatters within Arc, and must be referenced when writing code to create your own custom formatter. To reference this interface, start by creating your own class that implements the RSBFormatter.

Going back to the example use case of removing all double-spaces, a custom formatter called "noDoubleSpace" will be created to replace those double-spaces with a single space. Using C#, start off by defining a class (noDoubleSpace) and an optional namespace (custom):

namespace custom
{
    public class noDoubleSpace : RSBFormatter
    { }
}

Keep in mind that namespaces are completely optional but can be a good way of grouping classes together for organization and distinguishability, especially if creating multiple formatters at once.

Once the class has been created, the RSBFormatter must define two methods:

• Info()
• Format()

The Info() method

The Info() method returns a simple string that describes the Formatter as well as the expected input parameters and output parameters. The format of this String is the following XML structure:

<arc:info desc="A description of the formatter">
    <input name="InputAttrOne" desc="A description of this input attribute" />
    <input name="InputAttrTwo" desc="A description of this input attribute" />
    <output name="OutputAttrOnee" desc="A description of this output attribute" />
    <output name="OutputAttrTwo" desc="A description of this output attribute" />
</arc:info>

For example, here is the full Info() method for the noDoubleSpace formatter that is being created within this article:

public string Info() {
    return "<rsb:info title='noDoubleSpace' desc='Returns the input string with all double-spaces replaced with single-spaces.'>"+ 
        "<output desc='Result of replacing all double-spaces with a single-space'/>"+
        "</rsb:info>";
}

Since the noDoubleSpace formatter does not require any input, such as a number, there is no input element defined within the Info() method. However, when looking at a formatter that does have the option to specify an input parameter, such as the add() formatter, this line would be present:

<input name='value' desc='The optional numeric value to add to the specified attribute value. Default is 1.' default='1'/>

The Format() method

The Format() method performs the actual logic behind the formatter. The arguments passed to this method define the input attribute and any associated parameters to be used within the Formatter. The Format() method should be used to wrap the intended functionality of the custom formatter and to include code for reading input and writing output.

To help demonstrate the Format() method, recall the noDoubleSpace custom class that was created earlier and simply create a Format() method within that class and add the logic behind the formatter. In this case, regex is used to replace all instances of double-spaces with a single space.

public string Format(string[] value)
{
    RegexOptions options = RegexOptions.None;
    Regex regex = new Regex("[ ]{2,}", options);
    string retValue = (regex.Replace(value[0], " "));
    
    return Convert.ToString(retValue);
}

In this example formatter, the Format() method only takes in one argument, being the input string (value). A regex expression is then applied to the string to replace all double-spaces with single spaces. Finally, the modified string (retValue) is returned.

Compiling and exporting your formatter

Once the logic behind your formatter is complete and it is ready to be implemented in Arc, compile the formatter into a .dll or .jar depending on your environment and place it in the same location where the RSSBus .dll or .jar file was located.

If the compiled .dll or .jar file is placed into the directory while the server is running, the server will need to be restarted in order for Arc to recognize the new formatter file.

Using your formatter within Arc

Once the formatter has been compiled into a .dll or .jar file and placed it in the appropriate location, it is ready to be used within Arc. Since custom formatters implement the same RSBFormatter interface as the built-in operations, the method for calling your custom formatter will be very similar to the way to currently call formatters, with the addition of one extra piece of syntax.

If a namespace was created for the custom formatter, it will need to be utilized in order to call your formatter using ArcScript. In the example presented in this article, the formatter was assigned a namespace of "custom." To call the noDoubleSpace formatter, include the namespace before it:

<arc:set attr="some.attr" value="This is a test.  Remove the double spaces." />

    <arc:set attr="nospace.attr" value="[some.attr | custom.noDoubleSpace()]" />

Once the formatter has been applied to the string, the nospace.attr, if evaluated, would read: "This is a test. Remove the double spaces."

If you did not create a namespace, then you would simply call your formatter by its class name without a namespace prefix.