A Telemetry Filter Function takes a telemetry streams object as input, and returns another (usually different) telemetry streams object as output. All Telemetry Filter Functions must implement the TelemetryFilter interface. There is only one method in the interface:
public Object compute(Object[] parameters) throws TelemetryFunctionException;
Though the input is any array of objects, the Hackystat telemetry language evaluator makes sure that only objects of the type String, Number, and TelemetryStreamCollection are passed to the telemetry filter function implementation.
All implementations of Telemetry Filter Functions should return TelemetryStreamCollection as the output. The reason why an Object is used as the return type in the method signature is because of the way that the Hackystat telemetry implementation supports arithmetic operations in the telemetry language. Internally, there are four telemetry functions hidden from the end users and even the external developers: AddFunction, SubFunction, MulFunction, and DivFunction. The language interpret translates all arithmetic operators into these telemetry function calls, which might return an instance of Number when interval information cannot be inferred. But that's internal details. All the external developers need to remember is that all custom telemetry function implementation should return TelemetryStreamCollection object as the result.
Defining a new Telemetry Filter Function involves three basic activities: (1) defining a Java class that implements the TelemetryFilter interface, (2) defining a *.telemetry.def.xml file that will be processed by the Hackystat server at run time to dynamically discover this class, and (3) updating your module's local.build.xml file to include an Ant macro that will copy the *.telemetry.def.xml file to the appropriate place during the system build process. Each of these steps will be described in the following sections.
In the following sections, we will use FilterZero telemetry filter function as an example to illustrate how everything is put together. FilterZero related code can be found in hackyCore_Telemetry module.
Example 23.4, “Segment of FilterZero Implementation” shows the main method in FilterZero function implementation. It scans all telemetry streams in a telemetry stream collection, and gets rid of the one with all zero values.
Example 23.4. Segment of FilterZero Implementation
public Object compute(Object[] parameters) throws TelemetryFunctionException {
if (parameters.length != 1 || ! (parameters[0] instanceof TelemetryStreamCollection)) {
throw new TelemetryFunctionException("Telemetry function " + this.getName()
+ " takes 1 TelemetryStreamCollection object.");
}
else {
try {
TelemetryStreamCollection source = (TelemetryStreamCollection) parameters[0];
TelemetryStreamCollection target = new TelemetryStreamCollection(
source.getName(), source.getProject(), source.getInterval());
for (Iterator i = source.getTelemetryStreams().iterator(); i.hasNext(); ) {
TelemetryStream stream = (TelemetryStream) i.next();
if (! this.isAllZero(stream)) {
target.add(stream);
}
}
return target;
}
catch (TelemetryDataModelException ex) {
throw new TelemetryFunctionException(ex);
}
}
}
The Hackystat telemetry implementation instantiates one and only one instance for each declared Telemetry Filter Function. Therefore, you must ensure that your implementation is thread-safe.
After implementing the filter function, the next step is to provide an extension point declaration file so that the Hackystat telemetry infrastructure code knows the existence of the filter function. An example declaration file is provided in Example 23.5, “Segment of local.build.xml file”.
Example 23.5. Segment of local.build.xml file
<function name="FilterZero"
class="org.hackystat.core.telemetry.function.impl.FilterZeroFunction"
description="Filters out telemetry streams with zero values or no value in a
telemetry stream collection."
parameters="(1) The telemetry stream collection to be filtered." />
Table 23.2, “Telemetry Filter Function Declaration” shows the attributes of the extension point XML file.
Table 23.2. Telemetry Filter Function Declaration
| Attribute | Description |
|---|---|
| name | The name of the telemetry filter function. This is the name used in the telemetry language to invoke the function. |
| class | The fully qualified Java class name. This is required by the Hackystat telemetry implementation to instantiate the function through Java reflection mechanism. |
| description | A description of the function. This information is shown to the end users, so that they know what the function does. |
| parameters | A description of the parameters the function takes. This information is shown to the end users, so that they know how to invoke the function using the telemetry language. |
To copy the telemetry function declaration file to its final destination, you make use of a macro called hackyCore_Telemetry.installXmlDefinitions in your local.build.xml file. Example 23.6, “Segment of local.build.xml file” shows the related segment.