Package com.onwbp.adaptation

Class XPathExpressionHelper

  • public final class XPathExpressionHelper
extends Object
    Builds and manipulates table record XPath expressions.

    A table record XPath expression is of the form: /root/table[./field='a'], where /root/table is the table path and ./field='a' the optional predicate.

    Since:
    5.4.1
    See Also:
    Request.setXPathFilter(String), XPath supported syntax.

    • Constructor Detail

      • XPathExpressionHelper

        public XPathExpressionHelper()

    • Method Detail

      • buildXPath

        public static String buildXPath​(Path aTablePath,
                                String aPredicate)
        Builds an XPath expression given a table path and an optional predicate expression. For example, for a table path such as /root/table and a predicate ./field='a', this method would return /root/table[./field='a'].
        Throws:
        IllegalArgumentException - if one of the specified arguments is not defined.
        See Also:
        Supported XPath syntax

      • buildXPath

        public static String buildXPath​(Path aTablePath,
                                XPathFilter anXPathFilter)
        Builds an XPath expression given a table path and an optional XPath filter. For example, for a table path such as /root/table and an XPath filter having as predicate expression ./field='a', this method would return /root/table[./field='a'].
        Throws:
        IllegalArgumentException - if one of the specified arguments is not defined.
        Since:
        5.7.0
        See Also:
        XPathFilter, Supported XPath syntax

      • getXPathFilterForXPath

        public static XPathFilter getXPathFilterForXPath​(boolean isCached,
                                                 String anXPath)
                                          throws MalformedXPathExpressionException
        Returns an XPath filter from an XPath expression, null if the expression does not specify a predicate.

        For example, for the XPath expression /root/table[./field='a'], this method would return an XPath filter that has as predicate expression ./field='a'.

        Parameters:
        isCached - If true, the filter is cached in order to be reused when the same predicate expression is applied. If false, the filter is not cached and thus it cannot be reused.
        anXPath - the XPath expression.
        Throws:
        IllegalArgumentException - if the specified path is not defined.
        MalformedXPathExpressionException - if the specified path is not syntactically correct.
        Since:
        5.7.0
        See Also:
        XPathFilter, Supported XPath syntax

      • lookupFirstRecordMatchingXPath

        public static Adaptation lookupFirstRecordMatchingXPath​(boolean checkActualPrimaryKey,
                                                        Adaptation aDataSet,
                                                        String anXPath)
        Returns the first record that matches the specified XPath predicate, null if no such record exists.

        This method is equivalent to: 

         AdaptationTable.lookupFirstRecordMatchingXPath(
        checkActualPrimaryKey,
        aDataSet,
        anXPath,
        false);
        Since:
        5.4.3
        See Also:
        lookupFirstRecordMatchingXPath(boolean, Adaptation, String, boolean)

      • lookupFirstRecordMatchingXPath

        public static Adaptation lookupFirstRecordMatchingXPath​(boolean checkActualPrimaryKey,
                                                        Adaptation aDataSet,
                                                        String anXPath,
                                                        boolean includeOcculting)
                                                 throws MalformedXPathExpressionException,
                                                        PathAccessException
        Returns a record based on the specified dataset and XPath expression, null if no such record exists.

        For example, for the XPath expression /root/table[./name='Smith'], this method would return the first record (in primary key order) with its field 'name' equal to "Smith", or null if none exists.

        If the argument checkActualPrimaryKey is true, the predicate must specify the value of each primary key field. Using this type of predicate allows for a much faster resolution.

        Throws:
        IllegalArgumentException - if one of the specified arguments is not defined.
        IllegalArgumentException - if the specified Adaptation is not a dataset.
        IllegalArgumentException - if checkActualPrimaryKey is true and the specified XPath expression argument is not a primary key expression.
        MalformedXPathExpressionException - if the specified XPath expression is not syntactically correct.
        PathAccessException - if the extracted table path expression does not reference an existing table node in the underlying structure.
        Since:
        5.4.3
        See Also:
        Supported XPath syntax, TblTable.lookupFirstRecordMatchingPredicate(boolean, String, boolean)

      • encodeLiteralStringWithDelimiters

        public static String encodeLiteralStringWithDelimiters​(String aLiteralExpression)
        Encodes a valid string literal with its delimiters to be used in an XPath predicate. This method must be used when building an XPath predicate, if there is a chance that a string contains single or double quote characters. For example: 
         ...
 String predicate = "./lastName=" + XPathExpressionHelper.encodeLiteralStringWithDelimiters(aLastName);
 request.setXPathFilter(predicate);
 ...

        By default, the literal expression is delimited by single quotes ('). If the literal expression contains single quotes and no double quotes, it will be delimited by double quotes ("). If the literal expression contains both single and double quotes, any single quotes within will be doubled.

        Examples:

        Value of aLiteralExpression Result of this method
        Coeur 'Coeur'
        Coeur d'Alene "Coeur d'Alene"
        He said: "They live in Coeur d'Alene". 'He said: "They live in Coeur d''Alene".'
        See Also:
        Supported XPath syntax