org.javarosa.xpath.expr

Class XPathFuncExpr

java.lang.Object

org.javarosa.xpath.expr.XPathExpression

org.javarosa.xpath.expr.XPathFuncExpr

All Implemented Interfaces:

Serializable, Externalizable

public class XPathFuncExpr
extends XPathExpression

Representation of an xpath function expression.

All of the built-in xpath functions are included here, as well as the xpath type conversion logic

Evaluation of functions can delegate out to custom function handlers that must be registered at runtime.

Author:

Drew Roos

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
XPathExpression[]	args
XPathQName	id

Constructor Summary

Constructors

Constructor and Description
XPathFuncExpr()
XPathFuncExpr(XPathQName id, XPathExpression[] args)

Method Summary

Modifier and Type	Method and Description
static Boolean	boolNot(Object o)
static Boolean	boolStr(Object o)
static Boolean	checklist(Object oMin, Object oMax, Object[] factors) perform a 'checklist' computation, enabling expressions like 'if there are at least 3 risk factors active'
static Boolean	checklistWeighted(Object oMin, Object oMax, Object[] flags, Object[] weights) very similar to checklist, only each factor is assigned a real-number 'weight'.
static Double	count(Object o) count the number of nodes in a nodeset
static Double	countSelected(Object o) return the number of choices in a multi-select answer
boolean	equals(Object o)
Object	eval(DataInstance model, EvaluationContext evalContext) Evaluate the function call.
static String	formatDateTime(Object inputValue, Object format)
static Object	ifThenElse(DataInstance model, EvaluationContext ec, XPathExpression[] args, Object[] argVals)
static Object	indexedRepeat(DataInstance model, EvaluationContext ec, XPathExpression[] args, Object[] argVals) This provides a method of indexing fields stored in prior repeat groups.
static boolean	isNull(Object o) HANDLERS FOR BUILT-IN FUNCTIONS ******** the functions below are the handlers for the built-in xpath function suite if you add a function to the suite, it should adhere to the following pattern: * the function takes in its arguments as objects (DO NOT cast the arguments when calling the handler up in eval() (i.e., return stringLength((String)argVals[0]) <--- NO!) * the function converts the generic argument(s) to the desired type using the built-in xpath type conversion functions (toBoolean(), toNumeric(), toString(), toDate()) * the function MUST return an object of type Boolean, Double, String, or Date; it may never return null (instead return the empty string or NaN) * the function may throw exceptions, but should try as hard as possible not to, and if it must, strive to make it an XPathException
static String	join(Object oSep, Object[] argVals) concatenate an arbitrary-length argument list of string values together
static Boolean	multiSelected(Object o1, Object o2, String functionName) return whether a particular choice of a multi-select is selected
static String	normalizeSpace(Object o)
Object	pivot(DataInstance model, EvaluationContext evalContext, List<Object> pivots, Object sentinal) Pivot this expression, returning values if appropriate, and adding any pivots to the list.
void	readExternal(DataInputStream in, PrototypeFactory pf)
static Boolean	regex(Object o1, Object o2) determine if a string matches a regular expression.
static String	selectedAt(Object o1, Object o2) Get the Nth item in a selected list
static Double	stringLength(Object o)
static String	substring(Object o1, Object o2, Object o3)
static Double	sum(Object[] argVals) sum the values in a nodeset; each element is coerced to a numeric value
static Boolean	toBoolean(Object o) convert a value to a boolean using xpath's type conversion rules
static Object	toDate(Object input, boolean preserveTime) Convert a value to a Date.
static Object	toDecimalDateTime(Object o, boolean keepDate)
static Double	toDouble(Object o)
static Double	toInt(Object o) convert a number to an integer by truncating the fractional part.
static Double	toNumeric(Object o) convert a value to a number using xpath's type conversion rules (note that xpath itself makes no distinction between integer and floating point numbers)
String	toString()
static String	toString(Object o) convert a value to a string using xpath's type conversion rules
static Object	unpack(Object o)
void	writeExternal(DataOutputStream out)

Methods inherited from class org.javarosa.xpath.expr.XPathExpression

eval, hashCode, pivot, print, printParseTree

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

id

public XPathQName id

args

public XPathExpression[] args

Constructor Detail

XPathFuncExpr

public XPathFuncExpr()

XPathFuncExpr

public XPathFuncExpr(XPathQName id,
                     XPathExpression[] args)

Method Detail

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

Overrides:

equals in class Object

readExternal

public void readExternal(DataInputStream in,
                         PrototypeFactory pf)
                  throws IOException,
                         DeserializationException

Throws:

IOException

DeserializationException

writeExternal

public void writeExternal(DataOutputStream out)
                   throws IOException

Throws:

IOException

eval

public Object eval(DataInstance model,
                   EvaluationContext evalContext)

Evaluate the function call.

First check if the function is a member of the built-in function suite. If not, then check for any custom handlers registered to handler the function. If not, throw and exception.

Both function name and appropriate arguments are taken into account when finding a suitable handler. For built-in functions, the number of arguments must match; for custom functions, the supplied arguments must match one of the function prototypes defined by the handler.

Specified by:

eval in class XPathExpression

isNull

public static boolean isNull(Object o)

HANDLERS FOR BUILT-IN FUNCTIONS ******** the functions below are the handlers for the built-in xpath function suite if you add a function to the suite, it should adhere to the following pattern: * the function takes in its arguments as objects (DO NOT cast the arguments when calling the handler up in eval() (i.e., return stringLength((String)argVals[0]) <--- NO!) * the function converts the generic argument(s) to the desired type using the built-in xpath type conversion functions (toBoolean(), toNumeric(), toString(), toDate()) * the function MUST return an object of type Boolean, Double, String, or Date; it may never return null (instead return the empty string or NaN) * the function may throw exceptions, but should try as hard as possible not to, and if it must, strive to make it an XPathException

stringLength

public static Double stringLength(Object o)

normalizeSpace

public static String normalizeSpace(Object o)

toBoolean

public static Boolean toBoolean(Object o)

convert a value to a boolean using xpath's type conversion rules

toDouble

public static Double toDouble(Object o)

toNumeric

public static Double toNumeric(Object o)

convert a value to a number using xpath's type conversion rules (note that xpath itself makes no distinction between integer and floating point numbers)

toInt

public static Double toInt(Object o)

convert a number to an integer by truncating the fractional part. if non-numeric, coerce the value to a number first. note that the resulting return value is still a Double, as required by the xpath engine

toString

public static String toString(Object o)

convert a value to a string using xpath's type conversion rules

toDate

public static Object toDate(Object input,
                            boolean preserveTime)

Convert a value to a Date. note that xpath has no intrinsic representation of dates, so this is off-spec.

Dates convert to strings as 'yyyy-mm-dd', convert to numbers as # of days since the unix epoch, and convert to booleans always as 'true'.

This function parses input values to dates. Input values can be: * A well formatted ISO8601 string representation of a date, with or without time. Examples: '2018-01-01', '2018-01-01T10:20:30.400', '2018-01-01T10:20:30.400+02' * An epoch integer measured in days (Days since 1970-01-01, negative values are allowed)

Some values won't get parsed and will be returned as is without throwing an exception: * Empty string * Double.NaN (used by xpath as 'null value') * A value that is already a Date

Any other value will throw an exception. Specifically: * Double.POSITIVE_INFINITY and Double.NEGATIVE_INFINITY * A double value less than Integer.MIN_VALUE or greater than Integer.MAX_VALUE * A non parseable string

Parameters:

input - an Object containing a well formatted Date string, an epoch integer (in days) or a Date instance

Returns:

a Date instance

toDecimalDateTime

public static Object toDecimalDateTime(Object o,
                                       boolean keepDate)

boolNot

public static Boolean boolNot(Object o)

boolStr

public static Boolean boolStr(Object o)

formatDateTime

public static String formatDateTime(Object inputValue,
                                    Object format)

ifThenElse

public static Object ifThenElse(DataInstance model,
                                EvaluationContext ec,
                                XPathExpression[] args,
                                Object[] argVals)

indexedRepeat

public static Object indexedRepeat(DataInstance model,
                                   EvaluationContext ec,
                                   XPathExpression[] args,
                                   Object[] argVals)
                            throws XPathTypeMismatchException

This provides a method of indexing fields stored in prior repeat groups.

args[0] = generic XPath expression to index args[1] = generic XPath expression for group to index args[2] = index number for group args[3] = generic XPath expression for add'l group to index (if 5 or 7 parameters passed) args[4] = index number for group (if 5 or 7 parameters passed) args[5] = generic XPath expression for add'l group to index (if 7 parameters passed) args[6] = index number for group (if 7 parameters passed)

Throws:

XPathTypeMismatchException

multiSelected

public static Boolean multiSelected(Object o1,
                                    Object o2,
                                    String functionName)

return whether a particular choice of a multi-select is selected

Parameters:

o1 - XML-serialized answer to multi-select question (i.e, space-delimited choice values)

o2 - choice to look for

countSelected

public static Double countSelected(Object o)

return the number of choices in a multi-select answer

Parameters:

o - XML-serialized answer to multi-select question (i.e, space-delimited choice values)

selectedAt

public static String selectedAt(Object o1,
                                Object o2)

Get the Nth item in a selected list

Parameters:

o1 - XML-serialized answer to multi-select question (i.e, space-delimited choice values)

o2 - the integer index into the list to return

count

public static Double count(Object o)

count the number of nodes in a nodeset

sum

public static Double sum(Object[] argVals)

sum the values in a nodeset; each element is coerced to a numeric value

join

public static String join(Object oSep,
                          Object[] argVals)

concatenate an arbitrary-length argument list of string values together

substring

public static String substring(Object o1,
                               Object o2,
                               Object o3)

checklist

public static Boolean checklist(Object oMin,
                                Object oMax,
                                Object[] factors)

perform a 'checklist' computation, enabling expressions like 'if there are at least 3 risk factors active'

the first argument is a numeric value expressing the minimum number of factors required. if -1, no minimum is applicable the second argument is a numeric value expressing the maximum number of allowed factors. if -1, no maximum is applicalbe arguments 3 through the end are the individual factors, each coerced to a boolean value

Returns:

true if the count of 'true' factors is between the applicable minimum and maximum, inclusive

checklistWeighted

public static Boolean checklistWeighted(Object oMin,
                                        Object oMax,
                                        Object[] flags,
                                        Object[] weights)

very similar to checklist, only each factor is assigned a real-number 'weight'.

the first and second args are again the minimum and maximum, but -1 no longer means 'not applicable'.

subsequent arguments come in pairs: first the boolean value, then the floating-point weight for that value

the weights of all the 'true' factors are summed, and the function returns whether this sum is between the min and max

regex

public static Boolean regex(Object o1,
                            Object o2)

determine if a string matches a regular expression.

Parameters:

o1 - string being matched

o2 - regular expression

unpack

public static Object unpack(Object o)

pivot

public Object pivot(DataInstance model,
                    EvaluationContext evalContext,
                    List<Object> pivots,
                    Object sentinal)
             throws UnpivotableExpressionException

Description copied from class: XPathExpression

Pivot this expression, returning values if appropriate, and adding any pivots to the list.

Overrides:

pivot in class XPathExpression

Parameters:

model - The model to evaluate the current expression against

evalContext - The evaluation context to evaluate against

pivots - The list of pivot points in the xpath being evaluated. Pivots should be added to this list.

sentinal - The value which is being pivoted around.

Returns:

null - If a pivot was identified in this expression sentinal - If the current expression represents the sentinal being pivoted any other value - The result of the expression if no pivots are detected

Throws:

UnpivotableExpressionException - If the expression is too complex to pivot