1 /*
   2  * Copyright (c) 2017, Oracle and/or its affiliates. All rights reserved.
   3  * @LastModified: Oct 2017
   4  */
   5 /*
   6  * Licensed to the Apache Software Foundation (ASF) under one or more
   7  * contributor license agreements.  See the NOTICE file distributed with
   8  * this work for additional information regarding copyright ownership.
   9  * The ASF licenses this file to You under the Apache License, Version 2.0
  10  * (the "License"); you may not use this file except in compliance with
  11  * the License.  You may obtain a copy of the License at
  12  *
  13  *      http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  */
  21 
  22 package com.sun.org.apache.xpath.internal;
  23 
  24 import com.sun.org.apache.xalan.internal.res.XSLMessages;
  25 import com.sun.org.apache.xml.internal.dtm.DTM;
  26 import com.sun.org.apache.xml.internal.dtm.DTMIterator;
  27 import com.sun.org.apache.xml.internal.utils.QName;
  28 import com.sun.org.apache.xml.internal.utils.XMLString;
  29 import com.sun.org.apache.xpath.internal.objects.XNodeSet;
  30 import com.sun.org.apache.xpath.internal.objects.XObject;
  31 import com.sun.org.apache.xpath.internal.res.XPATHErrorResources;
  32 import java.util.List;
  33 import javax.xml.transform.ErrorListener;
  34 import javax.xml.transform.TransformerException;
  35 import org.xml.sax.ContentHandler;
  36 
  37 /**
  38  * This abstract class serves as the base for all expression objects.  An
  39  * Expression can be executed to return a {@link com.sun.org.apache.xpath.internal.objects.XObject},
  40  * normally has a location within a document or DOM, can send error and warning
  41  * events, and normally do not hold state and are meant to be immutable once
  42  * construction has completed.  An exception to the immutibility rule is iterators
  43  * and walkers, which must be cloned in order to be used -- the original must
  44  * still be immutable.


  45  */
  46 public abstract class Expression implements java.io.Serializable, ExpressionNode, XPathVisitable
  47 {
  48     static final long serialVersionUID = 565665869777906902L;
  49   /**
  50    * The location where this expression was built from.  Need for diagnostic
  51    *  messages. May be null.
  52    *  @serial
  53    */
  54   private ExpressionNode m_parent;
  55 
  56   /**
  57    * Tell if this expression or it's subexpressions can traverse outside
  58    * the current subtree.
  59    *
  60    * @return true if traversal outside the context node's subtree can occur.
  61    */
  62   public boolean canTraverseOutsideSubtree()
  63   {
  64     return false;
  65   }
  66 
  67 //  /**
  68 //   * Set the location where this expression was built from.
  69 //   *
  70 //   *
  71 //   * @param locator the location where this expression was built from, may be
  72 //   *                null.
  73 //   */
  74 //  public void setSourceLocator(SourceLocator locator)
  75 //  {
  76 //    m_slocator = locator;
  77 //  }
  78 
  79   /**
  80    * Execute an expression in the XPath runtime context, and return the
  81    * result of the expression.
  82    *
  83    *
  84    * @param xctxt The XPath runtime context.
  85    * @param currentNode The currentNode.
  86    *
  87    * @return The result of the expression in the form of a <code>XObject</code>.
  88    *
  89    * @throws javax.xml.transform.TransformerException if a runtime exception
  90    *         occurs.
  91    */
  92   public XObject execute(XPathContext xctxt, int currentNode)
  93           throws javax.xml.transform.TransformerException
  94   {
  95 
  96     // For now, the current node is already pushed.
  97     return execute(xctxt);
  98   }
  99 
 100   /**
 101    * Execute an expression in the XPath runtime context, and return the
 102    * result of the expression.
 103    *
 104    *
 105    * @param xctxt The XPath runtime context.
 106    * @param currentNode The currentNode.
 107    * @param dtm The DTM of the current node.
 108    * @param expType The expanded type ID of the current node.
 109    *
 110    * @return The result of the expression in the form of a <code>XObject</code>.
 111    *
 112    * @throws javax.xml.transform.TransformerException if a runtime exception
 113    *         occurs.
 114    */
 115   public XObject execute(
 116           XPathContext xctxt, int currentNode, DTM dtm, int expType)
 117             throws javax.xml.transform.TransformerException
 118   {
 119 
 120     // For now, the current node is already pushed.
 121     return execute(xctxt);
 122   }
 123 
 124   /**
 125    * Execute an expression in the XPath runtime context, and return the
 126    * result of the expression.
 127    *
 128    *
 129    * @param xctxt The XPath runtime context.
 130    *
 131    * @return The result of the expression in the form of a <code>XObject</code>.
 132    *
 133    * @throws javax.xml.transform.TransformerException if a runtime exception
 134    *         occurs.
 135    */
 136   public abstract XObject execute(XPathContext xctxt)
 137     throws javax.xml.transform.TransformerException;
 138 
 139   /**
 140    * Execute an expression in the XPath runtime context, and return the
 141    * result of the expression, but tell that a "safe" object doesn't have
 142    * to be returned.  The default implementation just calls execute(xctxt).
 143    *
 144    *
 145    * @param xctxt The XPath runtime context.
 146    * @param destructiveOK true if a "safe" object doesn't need to be returned.
 147    *
 148    * @return The result of the expression in the form of a <code>XObject</code>.
 149    *
 150    * @throws javax.xml.transform.TransformerException if a runtime exception
 151    *         occurs.
 152    */
 153   public XObject execute(XPathContext xctxt, boolean destructiveOK)
 154     throws javax.xml.transform.TransformerException
 155   {
 156         return execute(xctxt);
 157   }
 158 
 159 
 160   /**
 161    * Evaluate expression to a number.
 162    *
 163    *
 164    * @param xctxt The XPath runtime context.
 165    * @return The expression evaluated as a double.
 166    *
 167    * @throws javax.xml.transform.TransformerException
 168    */
 169   public double num(XPathContext xctxt)
 170           throws javax.xml.transform.TransformerException
 171   {
 172     return execute(xctxt).num();
 173   }
 174 
 175   /**
 176    * Evaluate expression to a boolean.
 177    *
 178    *
 179    * @param xctxt The XPath runtime context.
 180    * @return false
 181    *
 182    * @throws javax.xml.transform.TransformerException
 183    */
 184   public boolean bool(XPathContext xctxt)
 185           throws javax.xml.transform.TransformerException
 186   {
 187     return execute(xctxt).bool();
 188   }
 189 
 190   /**
 191    * Cast result object to a string.
 192    *
 193    *
 194    * @param xctxt The XPath runtime context.
 195    * @return The string this wraps or the empty string if null
 196    *
 197    * @throws javax.xml.transform.TransformerException
 198    */
 199   public XMLString xstr(XPathContext xctxt)
 200           throws javax.xml.transform.TransformerException
 201   {
 202     return execute(xctxt).xstr();
 203   }
 204 
 205   /**
 206    * Tell if the expression is a nodeset expression.  In other words, tell
 207    * if you can execute {@link #asNode(XPathContext) asNode} without an exception.
 208    * @return true if the expression can be represented as a nodeset.
 209    */
 210   public boolean isNodesetExpr()
 211   {
 212     return false;
 213   }
 214 
 215   /**
 216    * Return the first node out of the nodeset, if this expression is
 217    * a nodeset expression.
 218    * @param xctxt The XPath runtime context.
 219    * @return the first node out of the nodeset, or DTM.NULL.
 220    *
 221    * @throws javax.xml.transform.TransformerException
 222    */
 223   public int asNode(XPathContext xctxt)
 224           throws javax.xml.transform.TransformerException
 225   {
 226         DTMIterator iter = execute(xctxt).iter();
 227     return iter.nextNode();
 228   }
 229 
 230   /**
 231    * Given an select expression and a context, evaluate the XPath
 232    * and return the resulting iterator.
 233    *
 234    * @param xctxt The execution context.
 235    * @param contextNode The node that "." expresses.
 236    *
 237    *
 238    * @return A valid DTMIterator.
 239    * @throws TransformerException thrown if the active ProblemListener decides
 240    * the error condition is severe enough to halt processing.
 241    *
 242    * @throws javax.xml.transform.TransformerException
 243    * @xsl.usage experimental
 244    */
 245   public DTMIterator asIterator(XPathContext xctxt, int contextNode)
 246           throws javax.xml.transform.TransformerException
 247   {
 248 
 249     try
 250     {
 251       xctxt.pushCurrentNodeAndExpression(contextNode, contextNode);
 252 
 253       return execute(xctxt).iter();
 254     }
 255     finally
 256     {
 257       xctxt.popCurrentNodeAndExpression();
 258     }
 259   }
 260 
 261   /**
 262    * Given an select expression and a context, evaluate the XPath
 263    * and return the resulting iterator, but do not clone.
 264    *
 265    * @param xctxt The execution context.
 266    * @param contextNode The node that "." expresses.
 267    *
 268    *
 269    * @return A valid DTMIterator.
 270    * @throws TransformerException thrown if the active ProblemListener decides
 271    * the error condition is severe enough to halt processing.
 272    *
 273    * @throws javax.xml.transform.TransformerException
 274    * @xsl.usage experimental
 275    */
 276   public DTMIterator asIteratorRaw(XPathContext xctxt, int contextNode)
 277           throws javax.xml.transform.TransformerException
 278   {
 279 
 280     try
 281     {
 282       xctxt.pushCurrentNodeAndExpression(contextNode, contextNode);
 283 
 284       XNodeSet nodeset = (XNodeSet)execute(xctxt);
 285       return nodeset.iterRaw();
 286     }
 287     finally
 288     {
 289       xctxt.popCurrentNodeAndExpression();
 290     }
 291   }
 292 
 293 
 294   /**
 295    * Execute an expression in the XPath runtime context, and return the
 296    * result of the expression.
 297    *
 298    *
 299    * @param xctxt The XPath runtime context.
 300    * NEEDSDOC @param handler
 301    *
 302    * @return The result of the expression in the form of a <code>XObject</code>.
 303    *
 304    * @throws javax.xml.transform.TransformerException if a runtime exception
 305    *         occurs.
 306    * @throws org.xml.sax.SAXException
 307    */
 308   public void executeCharsToContentHandler(
 309           XPathContext xctxt, ContentHandler handler)
 310             throws javax.xml.transform.TransformerException,
 311                    org.xml.sax.SAXException
 312   {
 313 
 314     XObject obj = execute(xctxt);
 315 
 316     obj.dispatchCharactersEvents(handler);
 317     obj.detach();
 318   }
 319 
 320   /**
 321    * Tell if this expression returns a stable number that will not change during
 322    * iterations within the expression.  This is used to determine if a proximity
 323    * position predicate can indicate that no more searching has to occur.
 324    *
 325    *
 326    * @return true if the expression represents a stable number.
 327    */
 328   public boolean isStableNumber()
 329   {
 330     return false;
 331   }
 332 
 333   /**
 334    * This function is used to fixup variables from QNames to stack frame
 335    * indexes at stylesheet build time.
 336    * @param vars List of QNames that correspond to variables.  This list
 337    * should be searched backwards for the first qualified name that
 338    * corresponds to the variable reference qname.  The position of the
 339    * QName in the vector from the start of the vector will be its position
 340    * in the stack frame (but variables above the globalsTop value will need
 341    * to be offset to the current stack frame).
 342    * NEEDSDOC @param globalsSize
 343    */
 344   public abstract void fixupVariables(List<QName> vars, int globalsSize);
 345 
 346   /**
 347    * Compare this object with another object and see
 348    * if they are equal, include the sub heararchy.
 349    *
 350    * @param expr Another expression object.
 351    * @return true if this objects class and the expr
 352    * object's class are the same, and the data contained
 353    * within both objects are considered equal.
 354    */
 355   public abstract boolean deepEquals(Expression expr);
 356 
 357   /**
 358    * This is a utility method to tell if the passed in
 359    * class is the same class as this.  It is to be used by
 360    * the deepEquals method.  I'm bottlenecking it here
 361    * because I'm not totally confident that comparing the
 362    * class objects is the best way to do this.
 363    * @return true of the passed in class is the exact same
 364    * class as this class.
 365    */
 366   protected final boolean isSameClass(Expression expr)
 367   {
 368         if(null == expr)
 369           return false;
 370 
 371         return (getClass() == expr.getClass());
 372   }
 373 
 374   /**
 375    * Warn the user of an problem.
 376    *
 377    * @param xctxt The XPath runtime context.
 378    * @param msg An error msgkey that corresponds to one of the conststants found
 379    *            in {@link com.sun.org.apache.xpath.internal.res.XPATHErrorResources}, which is
 380    *            a key for a format string.
 381    * @param args An array of arguments represented in the format string, which
 382    *             may be null.
 383    *
 384    * @throws TransformerException if the current ErrorListoner determines to
 385    *                              throw an exception.
 386    *
 387    * @throws javax.xml.transform.TransformerException
 388    */
 389   public void warn(XPathContext xctxt, String msg, Object[] args)
 390           throws javax.xml.transform.TransformerException
 391   {
 392 
 393     java.lang.String fmsg = XSLMessages.createXPATHWarning(msg, args);
 394 
 395     if (null != xctxt)
 396     {
 397       ErrorListener eh = xctxt.getErrorListener();
 398 
 399       // TO DO: Need to get stylesheet Locator from here.
 400       eh.warning(new TransformerException(fmsg, xctxt.getSAXLocator()));
 401     }
 402   }
 403 
 404   /**
 405    * Tell the user of an assertion error, and probably throw an
 406    * exception.
 407    *
 408    * @param b  If false, a runtime exception will be thrown.
 409    * @param msg The assertion message, which should be informative.
 410    *
 411    * @throws RuntimeException if the b argument is false.
 412    *
 413    * @throws javax.xml.transform.TransformerException
 414    */
 415   public void assertion(boolean b, java.lang.String msg)
 416   {
 417 
 418     if (!b)
 419     {
 420       java.lang.String fMsg = XSLMessages.createXPATHMessage(
 421         XPATHErrorResources.ER_INCORRECT_PROGRAMMER_ASSERTION,
 422         new Object[]{ msg });
 423 
 424       throw new RuntimeException(fMsg);
 425     }
 426   }
 427 
 428   /**
 429    * Tell the user of an error, and probably throw an
 430    * exception.
 431    *
 432    * @param xctxt The XPath runtime context.
 433    * @param msg An error msgkey that corresponds to one of the constants found
 434    *            in {@link com.sun.org.apache.xpath.internal.res.XPATHErrorResources}, which is
 435    *            a key for a format string.
 436    * @param args An array of arguments represented in the format string, which
 437    *             may be null.
 438    *
 439    * @throws TransformerException if the current ErrorListoner determines to
 440    *                              throw an exception.
 441    *
 442    * @throws javax.xml.transform.TransformerException
 443    */
 444   public void error(XPathContext xctxt, String msg, Object[] args)
 445           throws javax.xml.transform.TransformerException
 446   {
 447 
 448     java.lang.String fmsg = XSLMessages.createXPATHMessage(msg, args);
 449 
 450     if (null != xctxt)
 451     {
 452       ErrorListener eh = xctxt.getErrorListener();
 453       TransformerException te = new TransformerException(fmsg, this);
 454 
 455       eh.fatalError(te);
 456     }
 457   }
 458 
 459   /**
 460    * Get the first non-Expression parent of this node.
 461    * @return null or first ancestor that is not an Expression.
 462    */
 463   public ExpressionNode getExpressionOwner()
 464   {
 465         ExpressionNode parent = exprGetParent();
 466         while((null != parent) && (parent instanceof Expression))
 467                 parent = parent.exprGetParent();
 468         return parent;
 469   }
 470 
 471   //=============== ExpressionNode methods ================
 472 
 473   /** This pair of methods are used to inform the node of its
 474     parent. */
 475   public void exprSetParent(ExpressionNode n)
 476   {
 477         assertion(n != this, "Can not parent an expression to itself!");
 478         m_parent = n;
 479   }
 480 
 481   public ExpressionNode exprGetParent()
 482   {
 483         return m_parent;
 484   }
 485 
 486   /** This method tells the node to add its argument to the node's
 487     list of children.  */
 488   public void exprAddChild(ExpressionNode n, int i)
 489   {
 490         assertion(false, "exprAddChild method not implemented!");
 491   }
 492 
 493   /** This method returns a child node.  The children are numbered
 494      from zero, left to right. */
 495   public ExpressionNode exprGetChild(int i)
 496   {
 497         return null;
 498   }
 499 
 500   /** Return the number of children the node has. */
 501   public int exprGetNumChildren()
 502   {
 503         return 0;
 504   }
 505 
 506   //=============== SourceLocator methods ================
 507 
 508   /**
 509    * Return the public identifier for the current document event.
 510    *
 511    * <p>The return value is the public identifier of the document
 512    * entity or of the external parsed entity in which the markup that
 513    * triggered the event appears.</p>
 514    *
 515    * @return A string containing the public identifier, or
 516    *         null if none is available.
 517    * @see #getSystemId
 518    */
 519   public String getPublicId()
 520   {
 521         if(null == m_parent)
 522           return null;
 523         return m_parent.getPublicId();
 524   }
 525 
 526   /**
 527    * Return the system identifier for the current document event.
 528    *
 529    * <p>The return value is the system identifier of the document
 530    * entity or of the external parsed entity in which the markup that
 531    * triggered the event appears.</p>
 532    *
 533    * <p>If the system identifier is a URL, the parser must resolve it
 534    * fully before passing it to the application.</p>
 535    *
 536    * @return A string containing the system identifier, or null
 537    *         if none is available.
 538    * @see #getPublicId
 539    */
 540   public String getSystemId()
 541   {
 542         if(null == m_parent)
 543           return null;
 544         return m_parent.getSystemId();
 545   }
 546 
 547   /**
 548    * Return the line number where the current document event ends.
 549    *
 550    * <p><strong>Warning:</strong> The return value from the method
 551    * is intended only as an approximation for the sake of error
 552    * reporting; it is not intended to provide sufficient information
 553    * to edit the character content of the original XML document.</p>
 554    *
 555    * <p>The return value is an approximation of the line number
 556    * in the document entity or external parsed entity where the
 557    * markup that triggered the event appears.</p>
 558    *
 559    * @return The line number, or -1 if none is available.
 560    * @see #getColumnNumber
 561    */
 562   public int getLineNumber()
 563   {
 564         if(null == m_parent)
 565           return 0;
 566         return m_parent.getLineNumber();
 567   }
 568 
 569   /**
 570    * Return the character position where the current document event ends.
 571    *
 572    * <p><strong>Warning:</strong> The return value from the method
 573    * is intended only as an approximation for the sake of error
 574    * reporting; it is not intended to provide sufficient information
 575    * to edit the character content of the original XML document.</p>
 576    *
 577    * <p>The return value is an approximation of the column number
 578    * in the document entity or external parsed entity where the
 579    * markup that triggered the event appears.</p>
 580    *
 581    * @return The column number, or -1 if none is available.
 582    * @see #getLineNumber
 583    */
 584   public int getColumnNumber()
 585   {
 586         if(null == m_parent)
 587           return 0;
 588         return m_parent.getColumnNumber();
 589   }
 590 }
--- EOF ---