Package 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 Details

  • Constructor Details

  • Method Details

    • 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