Package 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.HasCamelContext, 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:

  • Constructor Details

    • XPathBuilder

      public XPathBuilder(String text)
      Parameters:
      text - The XPath expression

  • Method Details

    • 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.spi.HasCamelContext

    • 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 ahead of time compiled (for example with camel-quarkus) 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)

    • 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)

    • getSource

      public org.apache.camel.Expression getSource()

    • setSource

      public void setSource(org.apache.camel.Expression source)

    • 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.

    • isInputStreamNeededForObject

      protected boolean isInputStreamNeededForObject(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:
      obj - the object
      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