org.apache.camel.language.xpath

Class XPathBuilder

java.lang.Object

org.apache.camel.support.service.BaseService

org.apache.camel.support.service.ServiceSupport

org.apache.camel.language.xpath.XPathBuilder

All Implemented Interfaces:

AutoCloseable, org.apache.camel.CamelContextAware, org.apache.camel.Expression, org.apache.camel.Predicate, org.apache.camel.Service, org.apache.camel.ShutdownableService, org.apache.camel.spi.ExpressionResultTypeAware, org.apache.camel.spi.NamespaceAware, org.apache.camel.StatefulService, org.apache.camel.SuspendableService

public class XPathBuilder
extends org.apache.camel.support.service.ServiceSupport
implements org.apache.camel.CamelContextAware, org.apache.camel.Expression, org.apache.camel.Predicate, org.apache.camel.spi.NamespaceAware, org.apache.camel.spi.ExpressionResultTypeAware

Creates an XPath expression builder which creates a nodeset result by default. If you want to evaluate a String expression then call stringResult()

An XPath object is not thread-safe and not reentrant. In other words, it is the application's responsibility to make sure that one XPath object is not used from more than one thread at any given time, and while the evaluate method is invoked, applications may not recursively call the evaluate method.

This implementation is thread safe by using thread locals and pooling to allow concurrency.

Important: After configuring the XPathBuilder its advised to invoke BaseService.start() to prepare the builder before using; though the builder will auto-start on first use.

See Also:

XPathConstants.NODESET

Field Summary

Fields inherited from class org.apache.camel.support.service.BaseService

BUILDED, FAILED, INITIALIZED, INITIALIZING, lock, NEW, SHUTDOWN, SHUTTINGDOWN, STARTED, STARTING, status, STOPPED, STOPPING, SUSPENDED, SUSPENDING

Constructor Summary

Constructors

Constructor and Description
XPathBuilder(String text)

Method Summary

Modifier and Type	Method and Description
XPathBuilder	booleanResult() Sets the expression result type to XPathConstants.BOOLEAN
protected XPathFunctionResolver	createDefaultFunctionResolver(XPathFunctionResolver parent)
protected static XPathFactory	createDefaultXPathFactory()
protected DefaultNamespaceContext	createNamespaceContext(XPathFactory factory)
protected XPathExpression	createTraceNamespaceExpression()
protected XPathExpression	createXPathExpression() Creates a new xpath expression as there we no available in the pool.
protected XPathFactory	createXPathFactory()
XPathBuilder	documentType(Class<?> documentType) Configures the document type to use.
protected Object	doGetDocument(org.apache.camel.Exchange exchange, Object body)
protected Object	doInEvaluateAs(XPathExpression xpathExpression, org.apache.camel.Exchange exchange, QName resultQName)
void	doStart()
void	doStop()
void	enableSaxon() Enables Saxon on this particular XPath expression, as saxon() sets the default static XPathFactory which may have already been initialised by previous XPath expressions
String	evaluate(org.apache.camel.CamelContext context, Object body) Evaluates the given xpath using the provided body as a String return type.
<T> T	evaluate(org.apache.camel.CamelContext context, Object body, Class<T> type) Evaluates the given xpath using the provided body.
Object	evaluate(org.apache.camel.Exchange exchange)
<T> T	evaluate(org.apache.camel.Exchange exchange, Class<T> type)
protected Object	evaluateAs(org.apache.camel.Exchange exchange, QName resultQName) Evaluates the expression as the given result type
XPathBuilder	factory(XPathFactory xpathFactory) Configures to use the provided XPath factory.
XPathBuilder	factoryClassName(String factoryClassName) Sets the factory class name to use
XPathBuilder	functionResolver(XPathFunctionResolver functionResolver) Sets the XPathFunctionResolver instance to use on these XPath expressions
XPathFunction	getBodyFunction() Gets the XPathFunction for getting the input message body.
org.apache.camel.CamelContext	getCamelContext()
protected Object	getDocument(org.apache.camel.Exchange exchange, Object body) Strategy method to extract the document from the exchange.
Class<?>	getDocumentType()
String	getExpressionText()
String	getFactoryClassName()
XPathFunctionResolver	getFunctionResolver()
XPathFunction	getHeaderFunction() Gets the XPathFunction for getting the input message header.
String	getHeaderName()
DefaultNamespaceContext	getNamespaceContext() Gets the namespace context, can be null if no custom context has been assigned.
Map<String,String>	getNamespaces()
String	getObjectModelUri()
XPathFunction	getOutBodyFunction() Gets the XPathFunction for getting the output message body.
XPathFunction	getOutHeaderFunction() Gets the XPathFunction for getting the output message header.
XPathFunction	getPropertiesFunction() Gets the XPathFunction for getting the exchange properties.
QName	getResultQName()
Class<?>	getResultType()
XPathFunction	getSimpleFunction() Gets the XPathFunction for executing simple language as xpath function.
String	getText()
XPathFactory	getXPathFactory() Gets the xpath factory, can be null if no custom factory has been assigned.
void	init(org.apache.camel.CamelContext context)
protected boolean	isInputStreamNeeded(org.apache.camel.Exchange exchange) Checks whether we need an InputStream to access the message body.
protected boolean	isInputStreamNeeded(org.apache.camel.Exchange exchange, String headerName) Checks whether we need an InputStream to access the message header.
protected boolean	isInputStreamNeededForObject(org.apache.camel.Exchange exchange, Object obj) Checks whether we need an InputStream to access this object Depending on the content in the object, we may not need to convert to InputStream.
boolean	isLogNamespaces()
boolean	isPreCompile()
boolean	isThreadSafety()
boolean	isUseSaxon()
XPathBuilder	logNamespaces() Activates trace logging of all discovered namespaces in the message - to simplify debugging namespace-related issues Namespaces are printed in Hashmap style {xmlns:prefix=[namespaceURI], xmlns:prefix=[namespaceURI]}.
boolean	matches(org.apache.camel.CamelContext context, Object body) Matches the given xpath using the provided body.
boolean	matches(org.apache.camel.Exchange exchange)
XPathBuilder	namespace(String prefix, String uri) Registers the namespace prefix and URI with the builder so that the prefix can be used in XPath expressions
XPathBuilder	namespaces(org.apache.camel.support.builder.Namespaces namespaces) Registers namespaces with the builder so that the registered prefixes can be used in XPath expressions
XPathBuilder	nodeResult() Sets the expression result type to XPathConstants.NODE
XPathBuilder	nodeSetResult() Sets the expression result type to XPathConstants.NODESET
XPathBuilder	numberResult() Sets the expression result type to XPathConstants.NUMBER
XPathBuilder	objectModel(String uri) Sets the object model URI to use
protected void	populateDefaultNamespaces(DefaultNamespaceContext context) Populate a number of standard prefixes if they are not already there
XPathBuilder	preCompile(boolean preCompile) Whether to enable pre-compiling the xpath expression during initialization phase.
XPathBuilder	resultType(Class<?> resultType) Sets the expression result type to the given resultType
XPathBuilder	saxon() Configures to use Saxon as the XPathFactory which allows you to use XPath 2.0 functions which may not be part of the build in JDK XPath parser.
void	setBodyFunction(XPathFunction bodyFunction)
void	setCamelContext(org.apache.camel.CamelContext camelContext)
void	setDocumentType(Class<?> documentType)
void	setFactoryClassName(String factoryClassName)
void	setFunctionResolver(XPathFunctionResolver functionResolver)
void	setHeaderFunction(XPathFunction headerFunction)
void	setHeaderName(String headerName)
void	setLogNamespaces(boolean logNamespaces)
void	setNamespaceContext(DefaultNamespaceContext namespaceContext)
protected void	setNamespaceIfNotPresent(DefaultNamespaceContext context, String prefix, String uri)
void	setNamespaces(Map<String,String> namespaces)
void	setObjectModelUri(String objectModelUri)
void	setOutBodyFunction(XPathFunction outBodyFunction)
void	setOutHeaderFunction(XPathFunction outHeaderFunction)
void	setPreCompile(boolean preCompile)
void	setPropertiesFunction(XPathFunction propertiesFunction)
void	setResultQName(QName resultQName)
void	setResultType(Class<?> resultType)
void	setSimpleFunction(XPathFunction simpleFunction)
void	setThreadSafety(boolean threadSafety)
void	setUseSaxon(boolean useSaxon) Whether to enable Saxon on this particular XPath expression.
void	setXPathFactory(XPathFactory xpathFactory)
XPathBuilder	stringResult() Sets the expression result type to XPathConstants.STRING
XPathBuilder	threadSafety(boolean threadSafety) Whether to enable thread-safety for the returned result of the xpath expression.
String	toString()
XPathBuilder	variable(String name, Object value) Registers a variable (in the global namespace) which can be referred to from XPath expressions
static XPathBuilder	xpath(String text)
static XPathBuilder	xpath(String text, Class<?> resultType)

Methods inherited from class org.apache.camel.support.service.BaseService

build, doBuild, doFail, doInit, doLifecycleChange, doResume, doShutdown, doSuspend, fail, getStatus, init, isBuild, isInit, isNew, isRunAllowed, isShutdown, isStarted, isStarting, isStartingOrStarted, isStopped, isStopping, isStoppingOrStopped, isSuspended, isSuspending, isSuspendingOrSuspended, resume, shutdown, start, stop, suspend

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.apache.camel.CamelContextAware

trySetCamelContext

Methods inherited from interface org.apache.camel.StatefulService

getStatus, isRunAllowed, isStarted, isStarting, isStopped, isStopping, isSuspending

Methods inherited from interface org.apache.camel.SuspendableService

isSuspended, resume, suspend

Methods inherited from interface org.apache.camel.ShutdownableService

shutdown

Methods inherited from interface org.apache.camel.Service

build, close, init, start, stop

Constructor Detail

XPathBuilder

public XPathBuilder(String text)

Parameters:

text - The XPath expression

Method Detail

xpath

public static XPathBuilder xpath(String text)

Parameters:

text - The XPath expression

Returns:

A new XPathBuilder object

xpath

public static XPathBuilder xpath(String text,
                                 Class<?> resultType)

Parameters:

text - The XPath expression

resultType - The result type that the XPath expression will return.

Returns:

A new XPathBuilder object

init

public void init(org.apache.camel.CamelContext context)

Specified by:

init in interface org.apache.camel.Expression

Specified by:

init in interface org.apache.camel.Predicate

toString

public String toString()

Overrides:

toString in class Object

getCamelContext

public org.apache.camel.CamelContext getCamelContext()

Specified by:

getCamelContext in interface org.apache.camel.CamelContextAware

setCamelContext

public void setCamelContext(org.apache.camel.CamelContext camelContext)

Specified by:

setCamelContext in interface org.apache.camel.CamelContextAware

matches

public boolean matches(org.apache.camel.Exchange exchange)

Specified by:

matches in interface org.apache.camel.Predicate

evaluate

public <T> T evaluate(org.apache.camel.Exchange exchange,
                      Class<T> type)

Specified by:

evaluate in interface org.apache.camel.Expression

matches

public boolean matches(org.apache.camel.CamelContext context,
                       Object body)

Matches the given xpath using the provided body.

Parameters:

context - the camel context

body - the body

Returns:

true if matches, false otherwise

evaluate

public <T> T evaluate(org.apache.camel.CamelContext context,
                      Object body,
                      Class<T> type)

Evaluates the given xpath using the provided body.

The evaluation uses by default XPathConstants.NODESET as the type used during xpath evaluation. The output from xpath is then afterwards type converted using Camel's type converter to the given type.

If you want to evaluate xpath using a different type, then call setResultType(Class) prior to calling this evaluate method.

Parameters:

context - the camel context

body - the body

type - the type to return

Returns:

result of the evaluation

evaluate

public String evaluate(org.apache.camel.CamelContext context,
                       Object body)

Evaluates the given xpath using the provided body as a String return type.

Parameters:

context - the camel context

body - the body

Returns:

result of the evaluation

booleanResult

public XPathBuilder booleanResult()

Sets the expression result type to XPathConstants.BOOLEAN

Returns:

the current builder

nodeResult

public XPathBuilder nodeResult()

Sets the expression result type to XPathConstants.NODE

Returns:

the current builder

nodeSetResult

public XPathBuilder nodeSetResult()

Sets the expression result type to XPathConstants.NODESET

Returns:

the current builder

numberResult

public XPathBuilder numberResult()

Sets the expression result type to XPathConstants.NUMBER

Returns:

the current builder

stringResult

public XPathBuilder stringResult()

Sets the expression result type to XPathConstants.STRING

Returns:

the current builder

resultType

public XPathBuilder resultType(Class<?> resultType)

Sets the expression result type to the given resultType

Returns:

the current builder

objectModel

public XPathBuilder objectModel(String uri)

Sets the object model URI to use

Returns:

the current builder

factoryClassName

public XPathBuilder factoryClassName(String factoryClassName)

Sets the factory class name to use

Returns:

the current builder

saxon

public XPathBuilder saxon()

Configures to use Saxon as the XPathFactory which allows you to use XPath 2.0 functions which may not be part of the build in JDK XPath parser.

Returns:

the current builder

functionResolver

public XPathBuilder functionResolver(XPathFunctionResolver functionResolver)

Sets the XPathFunctionResolver instance to use on these XPath expressions

Returns:

the current builder

namespace

public XPathBuilder namespace(String prefix,
                              String uri)

Registers the namespace prefix and URI with the builder so that the prefix can be used in XPath expressions

Parameters:

prefix - is the namespace prefix that can be used in the XPath expressions

uri - is the namespace URI to which the prefix refers

Returns:

the current builder

namespaces

public XPathBuilder namespaces(org.apache.camel.support.builder.Namespaces namespaces)

Registers namespaces with the builder so that the registered prefixes can be used in XPath expressions

Parameters:

namespaces - is namespaces object that should be used in the XPath expression

Returns:

the current builder

variable

public XPathBuilder variable(String name,
                             Object value)

Registers a variable (in the global namespace) which can be referred to from XPath expressions

Parameters:

name - name of variable

value - value of variable

Returns:

the current builder

documentType

public XPathBuilder documentType(Class<?> documentType)

Configures the document type to use.

The document type controls which kind of Class Camel should convert the payload to before doing the xpath evaluation.

For example you can set it to InputSource to use SAX streams. By default Camel uses Document as the type.

Parameters:

documentType - the document type

Returns:

the current builder

factory

public XPathBuilder factory(XPathFactory xpathFactory)

Configures to use the provided XPath factory.

Can be used to use Saxon instead of the build in factory from the JDK.

Parameters:

xpathFactory - the xpath factory to use

Returns:

the current builder.

logNamespaces

public XPathBuilder logNamespaces()

Activates trace logging of all discovered namespaces in the message - to simplify debugging namespace-related issues

Namespaces are printed in Hashmap style {xmlns:prefix=[namespaceURI], xmlns:prefix=[namespaceURI]}.

The implicit XML namespace is omitted (http://www.w3.org/XML/1998/namespace). XML allows for namespace prefixes to be redefined/overridden due to hierarchical scoping, i.e. prefix abc can be mapped to http://abc.com, and deeper in the document it can be mapped to http://def.com. When two prefixes are detected which are equal but are mapped to different namespace URIs, Camel will show all namespaces URIs it is mapped to in an array-style.

This feature is disabled by default.

Returns:

the current builder.

threadSafety

public XPathBuilder threadSafety(boolean threadSafety)

Whether to enable thread-safety for the returned result of the xpath expression. This applies to when using NODESET as the result type, and the returned set has multiple elements. In this situation there can be thread-safety issues if you process the NODESET concurrently such as from a Camel Splitter EIP in parallel processing mode. This option prevents concurrency issues by doing defensive copies of the nodes.

It is recommended to turn this option on if you are using camel-saxon or Saxon in your application. Saxon has thread-safety issues which can be prevented by turning this option on.

Thread-safety is disabled by default

Returns:

the current builder.

preCompile

public XPathBuilder preCompile(boolean preCompile)

Whether to enable pre-compiling the xpath expression during initialization phase. pre-compile is enabled by default. This can be used to turn off, for example in cases the compilation phase is desired at the starting phase, such as if the application is pre-built with graalvm which would then load the xpath factory of the built operating system, and not a JVM runtime.

Returns:

the current builder.

getXPathFactory

public XPathFactory getXPathFactory()

Gets the xpath factory, can be null if no custom factory has been assigned.

A default factory will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the factory, or null if this builder has not been started/used before.

setXPathFactory

public void setXPathFactory(XPathFactory xpathFactory)

getDocumentType

public Class<?> getDocumentType()

setDocumentType

public void setDocumentType(Class<?> documentType)

getText

public String getText()

getResultQName

public QName getResultQName()

setResultQName

public void setResultQName(QName resultQName)

getHeaderName

public String getHeaderName()

setHeaderName

public void setHeaderName(String headerName)

isThreadSafety

public boolean isThreadSafety()

setThreadSafety

public void setThreadSafety(boolean threadSafety)

isPreCompile

public boolean isPreCompile()

setPreCompile

public void setPreCompile(boolean preCompile)

getNamespaceContext

public DefaultNamespaceContext getNamespaceContext()

Gets the namespace context, can be null if no custom context has been assigned.

A default context will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the context, or null if this builder has not been started/used before.

setNamespaceContext

public void setNamespaceContext(DefaultNamespaceContext namespaceContext)

getFunctionResolver

public XPathFunctionResolver getFunctionResolver()

setFunctionResolver

public void setFunctionResolver(XPathFunctionResolver functionResolver)

setNamespaces

public void setNamespaces(Map<String,String> namespaces)

Specified by:

setNamespaces in interface org.apache.camel.spi.NamespaceAware

getNamespaces

public Map<String,String> getNamespaces()

Specified by:

getNamespaces in interface org.apache.camel.spi.NamespaceAware

getBodyFunction

public XPathFunction getBodyFunction()

Gets the XPathFunction for getting the input message body.

A default function will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the function, or null if this builder has not been started/used before.

setBodyFunction

public void setBodyFunction(XPathFunction bodyFunction)

getHeaderFunction

public XPathFunction getHeaderFunction()

Gets the XPathFunction for getting the input message header.

A default function will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the function, or null if this builder has not been started/used before.

setHeaderFunction

public void setHeaderFunction(XPathFunction headerFunction)

getOutBodyFunction

public XPathFunction getOutBodyFunction()

Gets the XPathFunction for getting the output message body.

A default function will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the function, or null if this builder has not been started/used before.

setOutBodyFunction

public void setOutBodyFunction(XPathFunction outBodyFunction)

getOutHeaderFunction

public XPathFunction getOutHeaderFunction()

Gets the XPathFunction for getting the output message header.

A default function will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the function, or null if this builder has not been started/used before.

setOutHeaderFunction

public void setOutHeaderFunction(XPathFunction outHeaderFunction)

getPropertiesFunction

public XPathFunction getPropertiesFunction()

Gets the XPathFunction for getting the exchange properties.

A default function will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the function, or null if this builder has not been started/used before.

setPropertiesFunction

public void setPropertiesFunction(XPathFunction propertiesFunction)

getSimpleFunction

public XPathFunction getSimpleFunction()

Gets the XPathFunction for executing simple language as xpath function.

A default function will be assigned (if no custom assigned) when either starting this builder or on first evaluation.

Returns:

the function, or null if this builder has not been started/used before.

setSimpleFunction

public void setSimpleFunction(XPathFunction simpleFunction)

getExpressionText

public String getExpressionText()

Specified by:

getExpressionText in interface org.apache.camel.spi.ExpressionResultTypeAware

getResultType

public Class<?> getResultType()

Specified by:

getResultType in interface org.apache.camel.spi.ExpressionResultTypeAware

setResultType

public void setResultType(Class<?> resultType)

setLogNamespaces

public void setLogNamespaces(boolean logNamespaces)

isLogNamespaces

public boolean isLogNamespaces()

enableSaxon

public void enableSaxon()

Enables Saxon on this particular XPath expression, as saxon() sets the default static XPathFactory which may have already been initialised by previous XPath expressions

setUseSaxon

public void setUseSaxon(boolean useSaxon)

Whether to enable Saxon on this particular XPath expression.

isUseSaxon

public boolean isUseSaxon()

getObjectModelUri

public String getObjectModelUri()

setObjectModelUri

public void setObjectModelUri(String objectModelUri)

getFactoryClassName

public String getFactoryClassName()

setFactoryClassName

public void setFactoryClassName(String factoryClassName)

evaluate

public Object evaluate(org.apache.camel.Exchange exchange)

evaluateAs

protected Object evaluateAs(org.apache.camel.Exchange exchange,
                            QName resultQName)

Evaluates the expression as the given result type

doInEvaluateAs

protected Object doInEvaluateAs(XPathExpression xpathExpression,
                                org.apache.camel.Exchange exchange,
                                QName resultQName)

createXPathExpression

protected XPathExpression createXPathExpression()
                                         throws XPathExpressionException

Creates a new xpath expression as there we no available in the pool.

This implementation must be synchronized to ensure thread safety, as this XPathBuilder instance may not have been started prior to being used.

Throws:

XPathExpressionException

createTraceNamespaceExpression

protected XPathExpression createTraceNamespaceExpression()
                                                  throws XPathExpressionException

Throws:

XPathExpressionException

createNamespaceContext

protected DefaultNamespaceContext createNamespaceContext(XPathFactory factory)

populateDefaultNamespaces

protected void populateDefaultNamespaces(DefaultNamespaceContext context)

Populate a number of standard prefixes if they are not already there

setNamespaceIfNotPresent

protected void setNamespaceIfNotPresent(DefaultNamespaceContext context,
                                        String prefix,
                                        String uri)

createDefaultFunctionResolver

protected XPathFunctionResolver createDefaultFunctionResolver(XPathFunctionResolver parent)

isInputStreamNeeded

protected boolean isInputStreamNeeded(org.apache.camel.Exchange exchange)

Checks whether we need an InputStream to access the message body.

Depending on the content in the message body, we may not need to convert to InputStream.

Parameters:

exchange - the current exchange

Returns:

true to convert to InputStream beforehand converting afterwards.

isInputStreamNeeded

protected boolean isInputStreamNeeded(org.apache.camel.Exchange exchange,
                                      String headerName)

Checks whether we need an InputStream to access the message header.

Depending on the content in the message header, we may not need to convert to InputStream.

Parameters:

exchange - the current exchange

Returns:

true to convert to InputStream beforehand converting afterwards.

isInputStreamNeededForObject

protected boolean isInputStreamNeededForObject(org.apache.camel.Exchange exchange,
                                               Object obj)

Checks whether we need an InputStream to access this object

Depending on the content in the object, we may not need to convert to InputStream.

Parameters:

exchange - the current exchange

Returns:

true to convert to InputStream beforehand converting afterwards.

getDocument

protected Object getDocument(org.apache.camel.Exchange exchange,
                             Object body)

Strategy method to extract the document from the exchange.

doGetDocument

protected Object doGetDocument(org.apache.camel.Exchange exchange,
                               Object body)
                        throws Exception

Throws:

Exception

doStart

public void doStart()
             throws Exception

Overrides:

doStart in class org.apache.camel.support.service.BaseService

Throws:

Exception

doStop

public void doStop()
            throws Exception

Overrides:

doStop in class org.apache.camel.support.service.BaseService

Throws:

Exception

createXPathFactory

protected XPathFactory createXPathFactory()
                                   throws XPathFactoryConfigurationException

Throws:

XPathFactoryConfigurationException

createDefaultXPathFactory

protected static XPathFactory createDefaultXPathFactory()
                                                 throws XPathFactoryConfigurationException

Throws:

XPathFactoryConfigurationException