com.helger.xml.xpath.XPathHelper Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-xml Show documentation
Java 1.8+ Library with XML handling routines
The newest version!
/*
 * Copyright (C) 2014-2024 Philip Helger (www.helger.com)
 * philip[at]helger[dot]com
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.helger.xml.xpath;

import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.annotation.concurrent.NotThreadSafe;
import javax.xml.namespace.NamespaceContext;
import javax.xml.xpath.XPath;
import javax.xml.xpath.XPathExpression;
import javax.xml.xpath.XPathExpressionException;
import javax.xml.xpath.XPathFactory;
import javax.xml.xpath.XPathFunctionResolver;
import javax.xml.xpath.XPathVariableResolver;

import com.helger.commons.ValueEnforcer;
import com.helger.commons.annotation.Nonempty;
import com.helger.commons.annotation.PresentForCodeCoverage;
import com.helger.commons.lang.ClassLoaderHelper;
import com.helger.xml.EXMLParserFeature;

/**
 * Utility class to create {@link XPath} and {@link XPathExpression} objects
 * more easily.
 *
 * @author Philip Helger
 */
@NotThreadSafe
public final class XPathHelper
{
  private static final XPathFactory XPATH_FACTORY;

  static
  {
    XPATH_FACTORY = XPathFactory.newInstance ();
    EXMLParserFeature.SECURE_PROCESSING.applyTo (XPATH_FACTORY, true);
  }

  @PresentForCodeCoverage
  private static final XPathHelper INSTANCE = new XPathHelper ();

  private XPathHelper ()
  {}

  /**
   * @return The default XPath factory. Be careful when manipulating this
   *         object! Never null.
   */
  @Nonnull
  public static XPathFactory getDefaultXPathFactory ()
  {
    return XPATH_FACTORY;
  }

  /**
   * Create a new {@link XPathFactory} trying to instantiate Saxon class
   * net.sf.saxon.xpath.XPathFactoryImpl first. If that fails, the
   * default XPathFactory is created.
   *
   * @return A new {@link XPathFactory} and never null.
   * @throws IllegalStateException
   *         In case neither Saxon nor default factory could be instantiated!
   */
  @Nonnull
  public static XPathFactory createXPathFactorySaxonFirst ()
  {
    // The XPath object used to compile the expressions
    XPathFactory aXPathFactory;
    try
    {
      // First try to use Saxon, using the context class loader
      aXPathFactory = XPathFactory.newInstance (XPathFactory.DEFAULT_OBJECT_MODEL_URI,
                                                "net.sf.saxon.xpath.XPathFactoryImpl",
                                                ClassLoaderHelper.getContextClassLoader ());
    }
    catch (final Exception ex)
    {
      // Must be Throwable because of e.g. IllegalAccessError (see issue #19)
      // Seems like Saxon is not in the class path - fall back to default JAXP
      try
      {
        aXPathFactory = XPathFactory.newInstance (XPathFactory.DEFAULT_OBJECT_MODEL_URI);
      }
      catch (final Exception ex2)
      {
        throw new IllegalStateException ("Failed to create JAXP XPathFactory", ex2);
      }
    }

    // Secure processing by default
    EXMLParserFeature.SECURE_PROCESSING.applyTo (aXPathFactory, true);
    return aXPathFactory;
  }

  /**
   * Create a new {@link XPath} without any special settings using the default
   * {@link XPathFactory}.
   *
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath ()
  {
    return createNewXPath (XPATH_FACTORY, (XPathVariableResolver) null, (XPathFunctionResolver) null, (NamespaceContext) null);
  }

  /**
   * Create a new {@link XPath} without any special settings.
   *
   * @param aXPathFactory
   *        The XPath factory object to use. May not be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nonnull final XPathFactory aXPathFactory)
  {
    return createNewXPath (aXPathFactory, (XPathVariableResolver) null, (XPathFunctionResolver) null, (NamespaceContext) null);
  }

  /**
   * Create a new {@link XPath} with the passed variable resolver using the
   * default {@link XPathFactory}.
   *
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nullable final XPathVariableResolver aVariableResolver)
  {
    return createNewXPath (XPATH_FACTORY, aVariableResolver, (XPathFunctionResolver) null, (NamespaceContext) null);
  }

  /**
   * Create a new {@link XPath} with the passed variable resolver.
   *
   * @param aXPathFactory
   *        The XPath factory object to use. May not be null.
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nonnull final XPathFactory aXPathFactory, @Nullable final XPathVariableResolver aVariableResolver)
  {
    return createNewXPath (aXPathFactory, aVariableResolver, (XPathFunctionResolver) null, (NamespaceContext) null);
  }

  /**
   * Create a new {@link XPath} with the passed function resolver using the
   * default {@link XPathFactory}.
   *
   * @param aFunctionResolver
   *        Function resolver to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nullable final XPathFunctionResolver aFunctionResolver)
  {
    return createNewXPath (XPATH_FACTORY, (XPathVariableResolver) null, aFunctionResolver, (NamespaceContext) null);
  }

  /**
   * Create a new {@link XPath} with the passed function resolver.
   *
   * @param aXPathFactory
   *        The XPath factory object to use. May not be null.
   * @param aFunctionResolver
   *        Function resolver to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nonnull final XPathFactory aXPathFactory, @Nullable final XPathFunctionResolver aFunctionResolver)
  {
    return createNewXPath (aXPathFactory, (XPathVariableResolver) null, aFunctionResolver, (NamespaceContext) null);
  }

  /**
   * Create a new {@link XPath} with the passed namespace context using the
   * default {@link XPathFactory}.
   *
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nullable final NamespaceContext aNamespaceContext)
  {
    return createNewXPath (XPATH_FACTORY, (XPathVariableResolver) null, (XPathFunctionResolver) null, aNamespaceContext);
  }

  /**
   * Create a new {@link XPath} with the passed namespace context.
   *
   * @param aXPathFactory
   *        The XPath factory object to use. May not be null.
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nonnull final XPathFactory aXPathFactory, @Nullable final NamespaceContext aNamespaceContext)
  {
    return createNewXPath (aXPathFactory, (XPathVariableResolver) null, (XPathFunctionResolver) null, aNamespaceContext);
  }

  /**
   * Create a new {@link XPath} with the passed variable resolver and namespace
   * context using the default {@link XPathFactory}.
   *
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nullable final XPathVariableResolver aVariableResolver,
                                      @Nullable final NamespaceContext aNamespaceContext)
  {
    return createNewXPath (XPATH_FACTORY, aVariableResolver, (XPathFunctionResolver) null, aNamespaceContext);
  }

  /**
   * Create a new {@link XPath} with the passed variable resolver, function
   * resolver and namespace context using the default {@link XPathFactory}.
   *
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @param aFunctionResolver
   *        Function resolver to be used. May be null.
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nullable final XPathVariableResolver aVariableResolver,
                                      @Nullable final XPathFunctionResolver aFunctionResolver,
                                      @Nullable final NamespaceContext aNamespaceContext)
  {
    return createNewXPath (XPATH_FACTORY, aVariableResolver, aFunctionResolver, aNamespaceContext);
  }

  /**
   * Create a new {@link XPath} with the passed variable resolver, function
   * resolver and namespace context.
   *
   * @param aXPathFactory
   *        The XPath factory object to use. May not be null.
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @param aFunctionResolver
   *        Function resolver to be used. May be null.
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @return The created non-null {@link XPath} object
   */
  @Nonnull
  public static XPath createNewXPath (@Nonnull final XPathFactory aXPathFactory,
                                      @Nullable final XPathVariableResolver aVariableResolver,
                                      @Nullable final XPathFunctionResolver aFunctionResolver,
                                      @Nullable final NamespaceContext aNamespaceContext)
  {
    ValueEnforcer.notNull (aXPathFactory, "XPathFactory");

    final XPath aXPath = aXPathFactory.newXPath ();
    if (aVariableResolver != null)
      aXPath.setXPathVariableResolver (aVariableResolver);
    if (aFunctionResolver != null)
      aXPath.setXPathFunctionResolver (aFunctionResolver);
    if (aNamespaceContext != null)
      aXPath.setNamespaceContext (aNamespaceContext);
    return aXPath;
  }

  /**
   * Create a new XPath expression for evaluation using the default
   * {@link XPathFactory}.
   *
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @param aFunctionResolver
   *        Function resolver to be used. May be null.
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @param sXPath
   *        The main XPath string to be evaluated
   * @return The {@link XPathExpression} object to be used.
   * @throws IllegalArgumentException
   *         if the XPath cannot be compiled
   */
  @Nonnull
  public static XPathExpression createNewXPathExpression (@Nullable final XPathVariableResolver aVariableResolver,
                                                          @Nullable final XPathFunctionResolver aFunctionResolver,
                                                          @Nullable final NamespaceContext aNamespaceContext,
                                                          @Nonnull @Nonempty final String sXPath)
  {
    return createNewXPathExpression (createNewXPath (aVariableResolver, aFunctionResolver, aNamespaceContext), sXPath);
  }

  /**
   * Create a new XPath expression for evaluation using the default
   * {@link XPathFactory}.
   *
   * @param aVariableResolver
   *        Variable resolver to be used. May be null.
   * @param sXPath
   *        The main XPath string to be evaluated
   * @return The {@link XPathExpression} object to be used.
   * @throws IllegalArgumentException
   *         if the XPath cannot be compiled
   */
  @Nonnull
  public static XPathExpression createNewXPathExpression (@Nullable final XPathVariableResolver aVariableResolver,
                                                          @Nonnull @Nonempty final String sXPath)
  {
    return createNewXPathExpression (createNewXPath (aVariableResolver), sXPath);
  }

  /**
   * Create a new XPath expression for evaluation using the default
   * {@link XPathFactory}.
   *
   * @param aFunctionResolver
   *        Function resolver to be used. May be null.
   * @param sXPath
   *        The main XPath string to be evaluated
   * @return The {@link XPathExpression} object to be used.
   * @throws IllegalArgumentException
   *         if the XPath cannot be compiled
   */
  @Nonnull
  public static XPathExpression createNewXPathExpression (@Nullable final XPathFunctionResolver aFunctionResolver,
                                                          @Nonnull @Nonempty final String sXPath)
  {
    return createNewXPathExpression (createNewXPath (aFunctionResolver), sXPath);
  }

  /**
   * Create a new XPath expression for evaluation using the default
   * {@link XPathFactory}.
   *
   * @param aNamespaceContext
   *        Namespace context to be used. May be null.
   * @param sXPath
   *        The main XPath string to be evaluated
   * @return The {@link XPathExpression} object to be used.
   * @throws IllegalArgumentException
   *         if the XPath cannot be compiled
   */
  @Nonnull
  public static XPathExpression createNewXPathExpression (@Nullable final NamespaceContext aNamespaceContext,
                                                          @Nonnull @Nonempty final String sXPath)
  {
    return createNewXPathExpression (createNewXPath (aNamespaceContext), sXPath);
  }

  /**
   * Create a new XPath expression for evaluation using the default
   * {@link XPathFactory}.
   *
   * @param sXPath
   *        The main XPath string to be evaluated
   * @return The {@link XPathExpression} object to be used.
   * @throws IllegalArgumentException
   *         if the XPath cannot be compiled
   */
  @Nonnull
  public static XPathExpression createNewXPathExpression (@Nonnull @Nonempty final String sXPath)
  {
    return createNewXPathExpression (createNewXPath (), sXPath);
  }

  /**
   * Create a new XPath expression for evaluation.
   *
   * @param aXPath
   *        The pre-created XPath object. May not be null.
   * @param sXPath
   *        The main XPath string to be evaluated
   * @return The {@link XPathExpression} object to be used.
   * @throws IllegalArgumentException
   *         if the XPath cannot be compiled
   */
  @Nonnull
  public static XPathExpression createNewXPathExpression (@Nonnull final XPath aXPath, @Nonnull @Nonempty final String sXPath)
  {
    ValueEnforcer.notNull (aXPath, "XPath");
    ValueEnforcer.notNull (sXPath, "XPathExpression");

    try
    {
      return aXPath.compile (sXPath);
    }
    catch (final XPathExpressionException ex)
    {
      throw new IllegalArgumentException ("Failed to compile XPath expression '" + sXPath + "'", ex);
    }
  }
}