Contents > 9 Extending the Metrics and Rule Engine > 9.7 Metrics Engine Extension Guidelines
9.7 Metrics Engine Extension Guidelines
Before you embark on creating new custom procedures and functions,
consider the following guidelines.
General guidelines
- The procedure and function classes must have public visibility, and
they must have a public constructor without arguments
(usually the default constructor).
- The classes must be stateless. Do not define or use instance fields
in these classes. The method implementations must be reentrant.
- Avoid side effects in the method implementations. For instance, do not
modify the intermediate sets obtained from calls to method
evalSetExpression, as these sets may be cached by the metrics
engine and used elsewhere.
Guidelines for metric, set, and rule procedures
- Defining new procedures should rarely be necessary. The primary means of
defining new metrics and rules is the SDMetricsML, which is faster to do and
only requires a text editor for tool support. Only when the capabilities
of the SDMetricsML are absolutely insufficient should you consider defining
new procedures.
- A metric, set, or rule procedure does not define a concrete metric, set,
or rule. It rather provides a template and algorithm for the definition of
a whole family of different metrics/sets/rules. Think of the many different
metrics you can define with just the "projection" procedure. Therefore, aim
to define the attributes of your procedures to provide as much flexibility as
possible. Make sure that all inputs to the procedure can be specified as
procedure attributes, and only hardcode default values for optional attributes
in the implementation of the procedure.
- When you define the attributes for your new procedure, use established
groups of attributes such as the standard filter attributes
supported by class FilterAttributeProcessor,
or the "sum/stat" attributes of class SummationHelper. Your new
procedures will better blend in and form a cohesive whole with the standard
procedures, and the implementation of your procedure will be easier.
Guidelines for boolean, scalar, and set functions
- As with procedures, defining new functions should rarely be necessary.
- The return type of the function determines where the function can be used:
- Boolean functions return Booleans and are used in condition expressions.
- Scalar functions return numbers, strings, or a model elements and are
used in metric expressions.
- Set functions return sets (regular or multisets, element or value sets)
and are used in set expressions.
- The types of the arguments to the function are independent from the return type of the function.
Each function type can have condition expressions, metric expressions, and/or set expressions as
arguments. You can mix and match the argument types as needed.
The methods evalExpression, evalBooleanExpression, and
evalSetExpression are equally provided by all of the function base classes.
Where to go from here
The above examples of custom procedures and functions did not cover
the entire metrics and rule engine API. On the SDMetrics web site,
you can