Java > Open Source Codes > com > sun > org > apache > xpath > internal > Expression


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

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags