Package com.onwbp.adaptation

# Class XPathExpressionHelper

java.lang.Object
com.onwbp.adaptation.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 Summary

  Constructors
  Constructor
  Description
  `XPathExpressionHelper()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static String`
  `buildXPath(Path aTablePath, XPathFilter anXPathFilter)`
  Builds an XPath expression given a table path and an optional XPath filter.
  `static String`
  `buildXPath(Path aTablePath, String aPredicate)`
  Builds an XPath expression given a table path and an optional predicate expression.
  `static AdaptationFilter`
  `createAdaptationFilterForXPath(String anXPath, SchemaNode aTable, Locale aLocale)`
  Creates a new filter, given a table and an XPath expression.
  `static Request`
  `createRequestForXPath(Adaptation aDataSet, String anXPath)`
  Creates a new request given a dataset and an XPath expression.
  `static String`
  `encodeLiteralStringWithDelimiters(String aLiteralExpression)`
  Encodes a valid string literal with its delimiters to be used in an XPath predicate.
  `static String`
  `getPredicateForXPath(String anXPath)`
  Returns the predicate expression from an XPath expression, `null` if the expression does not specify a predicate.
  `static Path`
  `getTablePathForXPath(String anXPath)`
  Returns the table path expression based on the specified XPath expression.
  `static XPathFilter`
  `getXPathFilterForXPath(boolean isCached, String anXPath)`
  Returns an XPath filter from an XPath expression, `null` if the expression does not specify a predicate.
  `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.
  `static Adaptation`
  `lookupFirstRecordMatchingXPath(boolean checkActualPrimaryKey, Adaptation aDataSet, String anXPath, boolean includeOcculting)`
  Returns a record based on the specified dataset and XPath expression, `null` if no such record exists.
  `static Adaptation`
  `lookupFirstRecordMatchingXPath(Adaptation aDataSet, String anXPath)`
  Returns the first record that matches the specified XPath predicate, `null` if no such record exists.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### XPathExpressionHelper

    public XPathExpressionHelper()

- ## Method Details

  - ### 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

  - ### getPredicateForXPath

    public static String getPredicateForXPath(String anXPath) throws MalformedXPathExpressionException
    Returns the predicate expression 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 `./field='a'`.

    Throws:
      `IllegalArgumentException` - if the specified path is not defined.
      `MalformedXPathExpressionException` - if the specified path is not syntactically correct.
    See Also:
      - 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

  - ### getTablePathForXPath

    public static Path getTablePathForXPath(String anXPath) throws MalformedXPathExpressionException
    Returns the table path expression based on the specified XPath expression.

    For example, for the XPath expression `/root/table[./field='a']`, this method returns `/root/table`.

    Throws:
      `IllegalArgumentException` - if the specified path is not defined.
      `MalformedXPathExpressionException` - if the specified XPath expression is not syntactically correct.
    See Also:
      - Supported XPath syntax

  - ### createRequestForXPath

    public static Request createRequestForXPath(Adaptation aDataSet, String anXPath) throws MalformedXPathExpressionException, PathAccessException
    Creates a new request given a dataset and an XPath expression.
    Throws:
      `IllegalArgumentException` - if one of the specified arguments is not defined.
      `IllegalArgumentException` - if the specified `Adaptation` is not a dataset.
      `MalformedXPathExpressionException` - if the specified XPath expression is not syntactically correct.
      `PathAccessException` - if the extracted table path expression does not refer to an existing table node in the underlying structure.
    See Also:
      - Supported XPath syntax

  - ### createAdaptationFilterForXPath

    public static AdaptationFilter createAdaptationFilterForXPath(String anXPath, SchemaNode aTable, Locale aLocale)
    Creates a new filter, given a table and an XPath expression.
    Throws:
      `IllegalArgumentException` - if one of the specified arguments is not defined.
      `IllegalArgumentException` - if the specified `SchemaNode` is not a table.
      `MalformedXPathExpressionException` - if the specified XPath expression is not syntactically correct.
      `PathAccessException` - if the extracted table path expression does not refer to an existing table node in the underlying structure.
    Since:
      6.0.0

  - ### lookupFirstRecordMatchingXPath

    public static Adaptation lookupFirstRecordMatchingXPath(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(
    >             false,
    >             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)
    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