Package org.apache.camel.language.xpath

Class 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

    • 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

      • 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

      • 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

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

      • getHeaderName

        public String getHeaderName()

      • setHeaderName

        public void setHeaderName​(String headerName)

      • getPropertyName

        public String getPropertyName()

      • setPropertyName

        public void setPropertyName​(String propertyName)

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

      • 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

      • populateDefaultNamespaces

        protected void populateDefaultNamespaces​(DefaultNamespaceContext context)
        Populate a number of standard prefixes if they are not already there

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

      • isInputStreamNeededForProperty

        protected boolean isInputStreamNeededForProperty​(org.apache.camel.Exchange exchange,
                                                 String propertyName)
        Checks whether we need an InputStream to access the exchange property.

        Depending on the content in the exchange property, 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.

      • 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