There will be times where a Web Determinations interview will have an attribute that requires custom input data, or custom output format of the value of the attribute.
For example, say we have two variable 'number' attributes called 'longitude' and 'latitude'. While it is stored in Web Determinations as a double, during the Web Determinations interview it should allow the user to enter proper longitude and latitude formats; that is, angular measurements that consist of degrees/minutes/seconds and direction (for example, 66 33' 39" N).
Formatter plugins are Platform Session plugins that allow Web Determinations to correctly parse custom input data formats, and correctly 'format' custom output data formats.
With the above example:
See the topic, Formatter - sample code.
Web Determinations ships with a default Formatter. There are no special steps involved in using the default Formatter as it is automatically used to process input and output formats based on the attribute type. The default Formatter does have some very basic configuration to modify formats for Date, DateTime, Currency. More information about configuring these formats can be found in Input and output formats.
Like many other plugins, only one Formatter plugin can be registered per Web Determinations interview. The default Formatter provides important core functionality that needs to be extended (rather than overridden) - therefore custom Formatter plugins in almost all cases, delegate the core functionality to the default Formatter plugin except for functionality that needs to be customized/overridden. For more information about this, refer to the topic below, Developing a Formatter for a specific project/implementation.
A Web Determinations interview has a 'Number' variable attribute (or several attributes) that requires a standardized input format, for example angular measurements such as Latitude and Longitude(degrees/minutes/seconds and direction). The user needs to be able to enter standard angular measurement format(s) for fields that gather input data for those attributes in the Web Determinations interview, and those input values need to be translated to the number value (the format in which Web Determinations stores it).
Following custom input format above, a Web Determinations interview has a 'Number' variable attribute (or several attributes) it needs to display in the aforementioned Latitude/Longitude format. When the value of the attribute(s) needs to be displayed to the user, it needs to be converted from a number value (the format in which Web Determinations stores it) into the standardized angular measurement with direction .
This section details how the Formatter fits into the Web Determinations architecture, and how to use it in the Web Determinations environment.
The default Formatter (DefaultFormatter) plugin is used automatically as it provides core functionality to Web Determinations in terms of parsing all input data and formatting all output data. All input data for attributes provided during the Web Determinations interview; for example, in interview question screen is processed by the registered Formatter plugin. All output data displayed from attribute values; for example, Decision Report for an attribute also uses the registered Formatter plugin.
While other plugins are optional (for example, a Web Determinations interview does not need to have a Data Adaptor), or a List Provider plugin registered to the current interview session, a Formatter must always be registered to a Web Determinations interview. Furthermore, if the registered Formatter is a custom Formatter, it should also provide all the functionality the default Formatter provides together with custom formatting.
Most Web Determinations extensions are provided with input data that has already passed through the registered Formatter plugin, and thus has no need to directly access and use the Formatter. Also, output data returned by Web Determinations extensions to Web Determinations for display, usually passes through the registered Formatter for formatting before being displayed, and thus has no need to directly access and use the Formatter.
Formatter plugins are useful only to Web Determinations extensions that have to handle raw input and output data. These extensions are the Custom Screen and Custom Control plugins. Custom formatting of input and/or output data that is used by multiple Custom Screens/Controls should be contained in a Formatter.
A Formatter plugin implements the interface WebDeterminationsFormatterPlugin. The WebDeterminationsFormatterPlugin interface in turn extends the PlatformSessionPlugin and Formatter interface.
Below are important methods the WebDeterminationsFormatterPlugin interface requires when implemented. For details on other methods required, see the API documentation for the WebDeterminationsFormatterPlugin.
| Method signature |
Description |
|---|---|
| Object parse( byte type, String value, Attribute attr) |
Parses an input data value (String value) and returns its object representation using the input format(s) for the specified attribute value. Used by the Web Determinations to parse input data into a Ruleengine datatype (byte type).
|
| Object parse( byte type, String value) |
Parses an input data value (String value) and returns its object representation using the input format(s) for the specified attribute value. Used by the Web Determinations to parse input data into a Ruleengine datatype (byte type).
|
| String getFormattedValue( byte type, Object value, Attribute attribute) |
Formats a Ruleengine data value into output data (its formatted display representation) according to the specified Ruleengine datatype (byte type).
|
| String getFormattedValue( byte type, Object value) |
Formats a Ruleengine data value into output data (its formatted display representation) according to the specified Ruleengine datatype (byte type).
|
Below is a table listing the various Ruleengine datatypes (which correspond to the various attribute datatypes that exist when authoring rules in Oracle Policy Modeling) and the Java/.NET Object that corresponds to the datatype.
Note that the Ruleengine datatype column is derived from HaleyType values (see API documentation for com.oracle.determinations.engine.HaleyType).
| Ruleengine datatype |
Java/.NET object |
|---|---|
| Boolean | Boolean |
| Statement | Boolean |
| Text | String |
| Number | Double |
| Currency | Double |
| Date | Date |
| DateTime | Date |
| TimeOfDay | com.oracle.determinations.engine.DeterminationsEngineTimeOfDay |
This section explains the various approaches on designing and developing a Formatter plugin for a specific project/implementation.
A custom Formatter is usually required when specific and custom input and/or output format of a particular attribute's data (or attributes') need to be supported.
As was previously mentioned, because Formatters perform core functionality for Web Determinations (that is, parsing/formatting most or all input and output data), custom Formatters usually only need to extend the default Formatter (or override formatting of an existing Ruleengine datatype).
Therefore a custom Formatter should delegate function calls to the DefaultFormatter for normal (core) processing of input/output data, except in cases where the input/output data requires custom formatting (by inspecting the attribute members).
A common way to determine if the input/output data needs custom formatting is by accessing members of the attribute object.
As an example, where Web Determinations needs to be able to process standardized angular movement formats (latitude and longitude), attributes can have a custom property with the key 'latlongformat' and value of 'longitude' or 'latitude'. Attribute custom properties are usually added by the rulebase author in Oracle Policy Modeling.
Note: Longitude can only be East(E) or West(W) directions while Latitude can only be North(N) or South(S) - hence the need for different values in the 'latlongformat' property
In the custom Formatter plugin, the existence of the key in the attribute's properties can trigger the custom formatting, and the key's value determines whether the attribute should be parsed/formatted as a Longitude (which is degrees/minutes/seconds EorW) or Latitude (same as longitude but expects NorS). See the sample code below for code implementation of this design.
Below are descriptions of the input data for the main methods.
The sample code below demonstrate the following
The needsCustomFormat() method encapsulates logic that checks whether a parse/formatting request needs custom formatting, or simply needs the default core formatting. The sample below checks the properties of the Attribute object, by taking in the Attribute object, and the HaleyType byte data. It checks whether the attribute has a property with a certain key value to determine if the input/output data needs custom formatting.
public class CustomFormatter implements WebDeterminationsFormatterPlugin {
private DefaultFormatter defaultFormatter;
//REQUIRED - for Plugin architecture
public CustomFormatter ()
{
}
public CustomFormatter (DefaultFormatter defaultFormatter)
{
this.defaultFormatter = defaultFormatter;
}
public PlatformSessionPlugin getInstance(PlatformSessionRegisterArgs args) {
//Demonstration of a Plugin only registering if the current rulebase is 'CustomFormatter'
if (args.getContext().getInteractiveSession().getRulebase().getIdentifier().equals("CustomFormatter")){
DefaultFormatter defaultFormatter = new DefaultFormatter(args.getContext());
return new CustomFormatter (defaultFormatter);
} else {
return null;
}
}
public String getFormattedValue(byte type, Object value, Attribute attr) {
if(!needsCustomFormat(type, attr).equals(""))
{
//Perform custom formatting
return customFormatting(type, value, attr);
}
else
{
//Perform normal (core) formatting - delegate to DefaultFormatter
return defaultFormatter.getFormattedValue(type, value, attr);
}
}
public Object parse(byte type, String value, Attribute attr) {
if(!needsCustomFormat(type, attr).equals(""))
{
//Perform custom parsing
return customParsing(type, value, attr);
}
else
{
//Perform normal (core) parsing - delegate to DefaultFormatter
return defaultFormatter.parse(type, value, attr);
}
}
/**
* Checks if the Attribute needs the custom formatting that this class provides, using the (custom) Properties of the Attribute
*
* @param type the HaleyType
* @param attr
* @return
*/
private String needsCustomFormat(byte type, Attribute attr)
{
//Perform logic that checks if the Attribute meets the requirements for a custom parse/formatting
Map<String, String> attributeProperties = attr.getProperties();
Set attributePropKeys = attributeProperties.keySet();
Iterator keyIterator = attributePropKeys.iterator();
while(keyIterator.hasNext())
{
String propertyKey = (String)keyIterator.next();
String propertyValue = (String)attributeProperties.get(propertyKey);
if( propertyKey.equals("<expected key value>"))
{
return propertyValue;
}
}
return "";
}
/**
*
* @param type
* @param value
* @param attr
* @return
*/
private Object customParsing(byte type, Object value, Attribute attr)
{
//Perform custom parsing
return null;
}
private String customFormatting(byte type, Object value, Attribute attr)
{
//Perform custom formatting
return "";
}