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 and Description
XPathExpressionHelper()

Method Summary

Modifier and Type	Method and Description
static String	buildXPath(Path aTablePath, String aPredicate) Builds an XPath expression given a table path and an optional predicate expression.
static String	buildXPath(Path aTablePath, XPathFilter anXPathFilter) Builds an XPath expression given a table path and an optional XPath filter.
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(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) 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.

Methods inherited from class java.lang.Object

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

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

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