xpath.java

The JDOM build system is based on Jakarta Ant, which is a Java building tool originally developed fo

    * @param  context   the element to use as context for evaluating
    *                   the XPath expression.
    *
    * @return the string value of the first node selected by applying
    *         the wrapped XPath expression to the given context.
    *
    * @throws JDOMException   if the XPath expression is invalid or
    *                         its evaluation on the specified context
    *                         failed.
    */
   abstract public String valueOf(Object context) throws JDOMException;

   /**
    * Returns the number value of the first node selected by applying
    * the wrapped XPath expression to the given context.
    *
    * @param  context   the element to use as context for evaluating
    *                   the XPath expression.
    *
    * @return the number value of the first node selected by applying
    *         the wrapped XPath expression to the given context,
    *         <code>null</code> if no node was selected or the
    *         special value {@link java.lang.Double#NaN}
    *         (Not-a-Number) if the selected value can not be
    *         converted into a number value.
    *
    * @throws JDOMException   if the XPath expression is invalid or
    *                         its evaluation on the specified context
    *                         failed.
    */
   abstract public Number numberValueOf(Object context) throws JDOMException;

   /**
    * Defines an XPath variable and sets its value.
    *
    * @param  name    the variable name.
    * @param  value   the variable value.
    *
    * @throws IllegalArgumentException   if <code>name</code> is not
    *                                    a valid XPath variable name
    *                                    or if the value type is not
    *                                    supported by the underlying
    *                                    implementation
    */
   abstract public void setVariable(String name, Object value);

   /**
    * Adds a namespace definition to the list of namespaces known of
    * this XPath expression.
    * <p>
    * <strong>Note</strong>: In XPath, there is no such thing as a
    * 'default namespace'.  The empty prefix <b>always</b> resolves
    * to the empty namespace URI.</p>
    *
    * @param  namespace   the namespace.
    */
   abstract public void addNamespace(Namespace namespace);

   /**
    * Adds a namespace definition (prefix and URI) to the list of
    * namespaces known of this XPath expression.
    * <p>
    * <strong>Note</strong>: In XPath, there is no such thing as a
    * 'default namespace'.  The empty prefix <b>always</b> resolves
    * to the empty namespace URI.</p>
    *
    * @param  prefix   the namespace prefix.
    * @param  uri      the namespace URI.
    *
    * @throws IllegalNameException   if the prefix or uri are null or
    *                                empty strings or if they contain
    *                                illegal characters.
    */
   public void addNamespace(String prefix, String uri) {
      addNamespace(Namespace.getNamespace(prefix, uri));
   }

   /**
    * Returns the wrapped XPath expression as a string.
    *
    * @return the wrapped XPath expression as a string.
    */
   abstract public String getXPath();


   /**
    * Evaluates an XPath expression and returns the list of selected
    * items.
    * <p>
    * <strong>Note</strong>: This method should not be used when the
    * same XPath expression needs to be applied several times (on the
    * same or different contexts) as it requires the expression to be
    * compiled before being evaluated.  In such cases,
    * {@link #newInstance allocating} an XPath wrapper instance and
    * {@link #selectNodes(java.lang.Object) evaluating} it several
    * times is way more efficient.
    * </p>
    *
    * @param  context   the node to use as context for evaluating
    *                   the XPath expression.
    * @param  path      the XPath expression to evaluate.
    *
    * @return the list of selected items, which may be of types: {@link Element},
    *         {@link Attribute}, {@link Text}, {@link CDATA},
    *         {@link Comment}, {@link ProcessingInstruction}, Boolean,
    *         Double, or String.
    *
    * @throws JDOMException   if the XPath expression is invalid or
    *                         its evaluation on the specified context
    *                         failed.
    */
   public static List selectNodes(Object context, String path)
                                                        throws JDOMException {
      return newInstance(path).selectNodes(context);
   }

   /**
    * Evaluates the wrapped XPath expression and returns the first
    * entry in the list of selected nodes (or atomics).
    * <p>
    * <strong>Note</strong>: This method should not be used when the
    * same XPath expression needs to be applied several times (on the
    * same or different contexts) as it requires the expression to be
    * compiled before being evaluated.  In such cases,
    * {@link #newInstance allocating} an XPath wrapper instance and
    * {@link #selectSingleNode(java.lang.Object) evaluating} it
    * several times is way more efficient.
    * </p>
    *
    * @param  context   the element to use as context for evaluating
    *                   the XPath expression.
    * @param  path      the XPath expression to evaluate.
    *
    * @return the first selected item, which may be of types: {@link Element},
    *         {@link Attribute}, {@link Text}, {@link CDATA},
    *         {@link Comment}, {@link ProcessingInstruction}, Boolean,
    *         Double, String, or <code>null</code> if no item was selected.
    *
    * @throws JDOMException   if the XPath expression is invalid or
    *                         its evaluation on the specified context
    *                         failed.
    */
   public static Object selectSingleNode(Object context, String path)
                                                        throws JDOMException {
      return newInstance(path).selectSingleNode(context);
   }


   //-------------------------------------------------------------------------
   // Serialization support
   //-------------------------------------------------------------------------

   /**
    * <i>[Serialization support]</i> Returns the alternative object
    * to write to the stream when serializing this object.  This
    * method returns an instance of a dedicated nested class to
    * serialize XPath expressions independently of the concrete
    * implementation being used.
    * <p>
    * <strong>Note</strong>: Subclasses are not allowed to override
    * this method to ensure valid serialization of all
    * implementations.</p>
    *
    * @return an XPathString instance configured with the wrapped
    *         XPath expression.
    *
    * @throws ObjectStreamException   never.
    */
   protected final Object writeReplace() throws ObjectStreamException {
      return new XPathString(this.getXPath());
   }

   /**
    * The XPathString is dedicated to serialize instances of
    * XPath subclasses in a implementation-independent manner.
    * <p>
    * XPathString ensures that only string data are serialized.  Upon
    * deserialization, XPathString relies on XPath factory method to
    * to create instances of the concrete XPath wrapper currently
    * configured.</p>
    */
   private final static class XPathString implements Serializable {
      /**
       * The XPath expression as a string.
       */
      private String xPath = null;

      /**
       * Creates a new XPathString instance from the specified
       * XPath expression.
       *
       * @param  xpath   the XPath expression.
       */
      public XPathString(String xpath) {
         super();

         this.xPath = xpath;
      }

      /**
       * <i>[Serialization support]</i> Resolves the read XPathString
       * objects into XPath implementations.
       *
       * @return an instance of a concrete implementation of
       *         XPath.
       *
       * @throws ObjectStreamException   if no XPath could be built
       *                                 from the read object.
       */
      private Object readResolve() throws ObjectStreamException {
         try {
            return XPath.newInstance(this.xPath);
         }
         catch (JDOMException ex1) {
            throw new InvalidObjectException(
                        "Can't create XPath object for expression \"" +
                        this.xPath + "\": " + ex1.toString());
         }
      }
   }
}