com.netrics.likeit

Class NetricsPredicateMapper

java.lang.Object

com.netrics.likeit.NetricsPredicateMapper

public class NetricsPredicateMapper
extends java.lang.Object

Remap field names and data values in a predicate string. This class is used to map values that appear in a predicate string expression. It allows field names and data values to be changed in the string. This class is intended to be used in association with the ANetricsQueryBuilder class. To support predicate queries the class must have a means of updating the field names used, and substituting data values into the query at run time.

The ANetricsQueryBuilder class tracks two sets of names:

1. Output Field Names. These are the names sent to the Patterns server to reference a record field value. Within a Predicate String Expression it takes the form: $"field-name". Field name expressions cannot appear in string constants or other field name expressions. They appear only at the top level of the Predicate String Expression.
2. Input Data Names. These are the names of the input data items used to generate the query text. A standard Predicate String Expression has no representation for intput data items. This class extends the standard expression to add a means of specifying an input data item. It takes the form: ${data-item-name}. All text between the curly braces is the name of the input data field. Input data items can appear both at the top level and within string constants.

To allow the character sequence ${ to be expressed in a string constant (or elsewhere) the sequence $\ can be used to represent a single dollar sign that has no special meaning. This sequence is translated to a single dollar sign character by this class.

The ANetricsQueryBuilder class allows both the input and output field names to be updated at run time. This class must support these operations. It does so through the setFieldNames and setDataNames methods.

The class must also allow the data values to be inserted into the expression. The getMappedExpr method is used to retrieve the fully mapped Predicate String Expression.

When a data value is inserted into a predicate expression string constant the mapper will encode the value before inserting it. The value should not be encoded before passing it to the predicate expression mapper.

Some Things To Note:

This class does not validate the predicate expression syntax. If given an invalid predicate expression, it will quietly generate an invalid predicate expression.

A data item name may contain any character except a closing curly brace. This includes double quotes. So expressions of the form $"first" = "${"data-item-1"}" are valid. Beware of: $"first" = "${data-item-1"} : this is an unterminated string constant.

Unterminated field names expressions or data item expressions are treated as fixed values. For example: "George" = $"first and "George" = "${first" are both output exactly as is, as neither has a substitution section. The unterminated Field Name and Data sections are treated as if they were fixed text.

Constructor Summary

Constructors

Constructor and Description
NetricsPredicateMapper(java.lang.String pred_str) Create a predicate expression string mapper.

Method Summary

Modifier and Type	Method and Description
java.util.Set<java.lang.String>	getCurrentDataNames() Get the set of the current data item names.
java.util.Set<java.lang.String>	getCurrentFieldNames() Get the set of the current field names.
java.lang.String	getMappedExpr(java.util.List<java.lang.String> data_names, java.util.List<java.lang.String> data_values) Get the fully mapped predicate expression.
java.lang.String	getMappedExpr(java.util.Map<java.lang.String,java.lang.String> data_values) Get the fully mapped predicate expression.
java.util.Set<java.lang.String>	getOriginalDataNames() Get the set of the original data item names.
java.util.Set<java.lang.String>	getOriginalFieldNames() Get the set of the original field names.
NetricsPredicateMapper	setDataNames(java.util.List<java.lang.String> original_names, java.util.List<java.lang.String> new_names) Update the data item name mappings.
NetricsPredicateMapper	setDataNames(java.util.Map<java.lang.String,java.lang.String> data_names) Update the data item name mappings.
NetricsPredicateMapper	setDefaultValue(java.lang.String default_value) Set the default value for unspecified data items.
NetricsPredicateMapper	setFieldNames(java.util.List<java.lang.String> original_names, java.util.List<java.lang.String> new_names) Update the field name mappings.
NetricsPredicateMapper	setFieldNames(java.util.Map<java.lang.String,java.lang.String> field_map) Update the field name mappings.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

NetricsPredicateMapper

public NetricsPredicateMapper(java.lang.String pred_str)

Create a predicate expression string mapper. Create a mapper for an extended predicate expression string. This is a string that may include the special ${data-item-name} expressions.

Parameters:

pred_str - the predicate expression string to be mapped.

Method Detail

setDefaultValue

public NetricsPredicateMapper setDefaultValue(java.lang.String default_value)

Set the default value for unspecified data items. If no value for a data item is given this value is inserted into the expression. If not specified with a call to this method an zero length string is inserted.

Parameters:

default_value - the default value for unspecified strings. If null a zero length string is used (the default).

Returns:

this object for chaining.

getOriginalFieldNames

public java.util.Set<java.lang.String> getOriginalFieldNames()

Get the set of the original field names. This retrieves the set of field names referenced in the unmapped version of the predicate expression.

Returns:

an unmodifiable set containing all of the field names referenced.

getCurrentFieldNames

public java.util.Set<java.lang.String> getCurrentFieldNames()

Get the set of the current field names. This retrieves the set of field names referenced in the mapped version of the predicate expression.

Returns:

an unmodifiable set containing all of the field names referenced.

getOriginalDataNames

public java.util.Set<java.lang.String> getOriginalDataNames()

Get the set of the original data item names. This retrieves the set of data item names referenced in the unmapped version of the predicate expression.

Returns:

an unmodifiable set containing all of the data item names referenced.

getCurrentDataNames

public java.util.Set<java.lang.String> getCurrentDataNames()

Get the set of the current data item names. This retrieves the set of data item names referenced in the mapped version of the predicate expression.

Returns:

an unmodifiable set containing all of the data item names referenced.

setFieldNames

public NetricsPredicateMapper setFieldNames(java.util.Map<java.lang.String,java.lang.String> field_map)

Update the field name mappings. This remaps the field names in the predicate expression. This entirely replaces any previous field mappings applied.

Parameters:

field_map - a mapping where the key is the original field name and the value is the new name to use. If this is null it reverts to using the original field names. Any field name not included in the map is left as the original name.

Returns:

this object for method chaining.

setFieldNames

public NetricsPredicateMapper setFieldNames(java.util.List<java.lang.String> original_names,
                                            java.util.List<java.lang.String> new_names)
                                     throws java.lang.IllegalArgumentException

Update the field name mappings. This remaps the field names in the predicate expression. This entirely replaces any previous field mappings applied. This method takes in the mappings as a list of the original names, and a corresponding list of the new names.

Parameters:

original_names - a list of the original field names.

new_names - a list of the new names. The names must be in the same position in the list as the associated original name in the original_names list.

Returns:

this object for method chaining.

Throws:

java.lang.IllegalArgumentException - if either argument is null, or the two lists are different lengths.

setDataNames

public NetricsPredicateMapper setDataNames(java.util.Map<java.lang.String,java.lang.String> data_names)

Update the data item name mappings. This remaps the data item names in the predicate expression. This entirely replaces any previous data item name mappings applied.

Parameters:

data_names - a mapping where the key is the original data item name, and the value is the new data item name to use. If this is null it reverts to using the original data item names. Any data item not included in the map is left as the original name.

Returns:

this object for method chaining.

setDataNames

public NetricsPredicateMapper setDataNames(java.util.List<java.lang.String> original_names,
                                           java.util.List<java.lang.String> new_names)
                                    throws java.lang.IllegalArgumentException

Update the data item name mappings. This remaps the data item names in the predicate expression. This entirely replaces any previous data item mappings applied. This method takes in the mappings as a list of the original names, and a corresponding list of the new names.

Parameters:

original_names - a list of the original data item names.

new_names - a list of the new names. The names must be in the same position in the list as the associated original name in the original_names list.

Returns:

this object for method chaining.

Throws:

java.lang.IllegalArgumentException - if either argument is null, or the two lists have different lengths.

getMappedExpr

public java.lang.String getMappedExpr(java.util.Map<java.lang.String,java.lang.String> data_values)

Get the fully mapped predicate expression. This applies the data value mappings, and the escaping of $\ values. The returned string has all of the currently defined field name mappings applied. Data items that do not appear in the given data_values map are assigned the default value.

Data values inserted into predicate string constants have the special characters: &, ", \n and \0 encoded as &, ", 
 and � respectively.

Parameters:

data_values - a mapping where the key is the mapped data item name, and the value is the value for that data item.

Returns:

the fully mapped predicate expression.

getMappedExpr

public java.lang.String getMappedExpr(java.util.List<java.lang.String> data_names,
                                      java.util.List<java.lang.String> data_values)
                               throws java.lang.IllegalArgumentException

Get the fully mapped predicate expression. This applies the data value mappings, and the escaping of $\ values. The returned string has all of the currently defined field name mappings applied. Data items that do not appear in the given lists are assigned the default value.

Data values inserted into predicate string constants have the special characters: &, ", \n and \0 encoded as &, ", 
 and � respectively.

Parameters:

data_names - a list of the current data item names.

data_values - a list of the data item values. The values must be in the same position in the list as the associated name in the data_names list.

Returns:

the fully mapped predicate expression.

Throws:

java.lang.IllegalArgumentException - if either argument is null, or the two lists have different lengths.