Java > Open Source Codes > com > sun > org > apache > xpath > internal > objects > XObject


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: XObject.java,v 1.25 2004/02/17 04:34:38 minchau Exp $
18  */
19 package com.sun.org.apache.xpath.internal.objects;
20
21 import java.io.Serializable ;
22
23 import com.sun.org.apache.xalan.internal.res.XSLMessages;
24 import com.sun.org.apache.xml.internal.dtm.DTM;
25 import com.sun.org.apache.xml.internal.dtm.DTMIterator;
26 import com.sun.org.apache.xml.internal.utils.XMLString;
27 import com.sun.org.apache.xpath.internal.Expression;
28 import com.sun.org.apache.xpath.internal.ExpressionOwner;
29 import com.sun.org.apache.xpath.internal.NodeSetDTM;
30 import com.sun.org.apache.xpath.internal.XPathContext;
31 import com.sun.org.apache.xpath.internal.XPathException;
32 import com.sun.org.apache.xpath.internal.XPathVisitor;
33 import com.sun.org.apache.xpath.internal.res.XPATHErrorResources;
34
35 import org.w3c.dom.DocumentFragment ;
36 import org.w3c.dom.NodeList ;
37 import org.w3c.dom.traversal.NodeIterator;
38
39 /**
40  * This class represents an XPath object, and is capable of
41  * converting the object to various types, such as a string.
42  * This class acts as the base class to other XPath type objects,
43  * such as XString, and provides polymorphic casting capabilities.
44  * @xsl.usage general
45  */
46 public class XObject extends Expression implements Serializable , Cloneable
47 {
48
49   /**
50    * The java object which this object wraps.
51    * @serial
52    */
53   protected Object m_obj; // This may be NULL!!!
54
55   /**
56    * Create an XObject.
57    */
58   public XObject(){}
59
60   /**
61    * Create an XObject.
62    *
63    * @param obj Can be any object, should be a specific type
64    * for derived classes, or null.
65    */
66   public XObject(Object obj)
67   {
68     m_obj = obj;
69   }
70
71   /**
72    * For support of literal objects in xpaths.
73    *
74    * @param xctxt The XPath execution context.
75    *
76    * @return This object.
77    *
78    * @throws javax.xml.transform.TransformerException
79    */
80   public XObject execute(XPathContext xctxt)
81           throws javax.xml.transform.TransformerException
82   {
83     return this;
84   }
85
86   /**
87    * Specify if it's OK for detach to release the iterator for reuse.
88    * This function should be called with a value of false for objects that are
89    * stored in variables.
90    * Calling this with a value of false on a XNodeSet will cause the nodeset
91    * to be cached.
92    *
93    * @param allowRelease true if it is OK for detach to release this iterator
94    * for pooling.
95    */
96   public void allowDetachToRelease(boolean allowRelease){}
97
98   /**
99    * Detaches the <code>DTMIterator</code> from the set which it iterated
100    * over, releasing any computational resources and placing the iterator
101    * in the INVALID state. After <code>detach</code> has been invoked,
102    * calls to <code>nextNode</code> or <code>previousNode</code> will
103    * raise a runtime exception.
104    */
105   public void detach(){}
106
107   /**
108    * Forces the object to release it's resources. This is more harsh than
109    * detach().
110    */
111   public void destruct()
112   {
113
114     if (null != m_obj)
115     {
116       allowDetachToRelease(true);
117       detach();
118
119       m_obj = null;
120     }
121   }
122   
123   /**
124    * Reset for fresh reuse.
125    */
126   public void reset()
127   {
128   }
129
130   /**
131    * Directly call the
132    * characters method on the passed ContentHandler for the
133    * string-value. Multiple calls to the
134    * ContentHandler's characters methods may well occur for a single call to
135    * this method.
136    *
137    * @param ch A non-null reference to a ContentHandler.
138    *
139    * @throws org.xml.sax.SAXException
140    */
141   public void dispatchCharactersEvents(org.xml.sax.ContentHandler ch)
142           throws org.xml.sax.SAXException
143   {
144     xstr().dispatchCharactersEvents(ch);
145   }
146
147   /**
148    * Create the right XObject based on the type of the object passed. This
149    * function can not make an XObject that exposes DOM Nodes, NodeLists, and
150    * NodeIterators to the XSLT stylesheet as node-sets.
151    *
152    * @param val The java object which this object will wrap.
153    *
154    * @return the right XObject based on the type of the object passed.
155    */
156   static public XObject create(Object val)
157   {
158     return XObjectFactory.create(val);
159   }
160   
161   /**
162    * Create the right XObject based on the type of the object passed.
163    * This function <emph>can</emph> make an XObject that exposes DOM Nodes, NodeLists, and
164    * NodeIterators to the XSLT stylesheet as node-sets.
165    *
166    * @param val The java object which this object will wrap.
167    * @param xctxt The XPath context.
168    *
169    * @return the right XObject based on the type of the object passed.
170    */
171   static public XObject create(Object val, XPathContext xctxt)
172   {
173     return XObjectFactory.create(val, xctxt);
174   }
175
176   /** Constant for NULL object type */
177   public static final int CLASS_NULL = -1;
178
179   /** Constant for UNKNOWN object type */
180   public static final int CLASS_UNKNOWN = 0;
181
182   /** Constant for BOOLEAN object type */
183   public static final int CLASS_BOOLEAN = 1;
184
185   /** Constant for NUMBER object type */
186   public static final int CLASS_NUMBER = 2;
187
188   /** Constant for STRING object type */
189   public static final int CLASS_STRING = 3;
190
191   /** Constant for NODESET object type */
192   public static final int CLASS_NODESET = 4;
193
194   /** Constant for RESULT TREE FRAGMENT object type */
195   public static final int CLASS_RTREEFRAG = 5;
196
197   /** Represents an unresolved variable type as an integer. */
198   public static final int CLASS_UNRESOLVEDVARIABLE = 600;
199
200   /**
201    * Tell what kind of class this is.
202    *
203    * @return CLASS_UNKNOWN
204    */
205   public int getType()
206   {
207     return CLASS_UNKNOWN;
208   }
209
210   /**
211    * Given a request type, return the equivalent string.
212    * For diagnostic purposes.
213    *
214    * @return type string "#UNKNOWN" + object class name
215    */
216   public String getTypeString()
217   {
218     return "#UNKNOWN (" + object().getClass().getName() + ")";
219   }
220
221   /**
222    * Cast result object to a number. Always issues an error.
223    *
224    * @return 0.0
225    *
226    * @throws javax.xml.transform.TransformerException
227    */
228   public double num() throws javax.xml.transform.TransformerException
229   {
230
231     error(XPATHErrorResources.ER_CANT_CONVERT_TO_NUMBER,
232           new Object []{ getTypeString() }); //"Can not convert "+getTypeString()+" to a number");
233
234     return 0.0;
235   }
236   
237   /**
238    * Cast result object to a number, but allow side effects, such as the
239    * incrementing of an iterator.
240    *
241    * @return numeric value of the string conversion from the
242    * next node in the NodeSetDTM, or NAN if no node was found
243    */
244   public double numWithSideEffects() throws javax.xml.transform.TransformerException
245   {
246     return num();
247   }
248
249   /**
250    * Cast result object to a boolean. Always issues an error.
251    *
252    * @return false
253    *
254    * @throws javax.xml.transform.TransformerException
255    */
256   public boolean bool() throws javax.xml.transform.TransformerException
257   {
258
259     error(XPATHErrorResources.ER_CANT_CONVERT_TO_NUMBER,
260           new Object []{ getTypeString() }); //"Can not convert "+getTypeString()+" to a number");
261
262     return false;
263   }
264   
265   /**
266    * Cast result object to a boolean, but allow side effects, such as the
267    * incrementing of an iterator.
268    *
269    * @return True if there is a next node in the nodeset
270    */
271   public boolean boolWithSideEffects() throws javax.xml.transform.TransformerException
272   {
273     return bool();
274   }
275
276
277   /**
278    * Cast result object to a string.
279    *
280    * @return The string this wraps or the empty string if null
281    */
282   public XMLString xstr()
283   {
284     return XMLStringFactoryImpl.getFactory().newstr(str());
285   }
286
287   /**
288    * Cast result object to a string.
289    *
290    * @return The object as a string
291    */
292   public String str()
293   {
294     return (m_obj != null) ? m_obj.toString() : "";
295   }
296
297   /**
298    * Return the string representation of the object
299    *
300    *
301    * @return the string representation of the object
302    */
303   public String toString()
304   {
305     return str();
306   }
307
308   /**
309    * Cast result object to a result tree fragment.
310    *
311    * @param support XPath context to use for the conversion
312    *
313    * @return the objec as a result tree fragment.
314    */
315   public int rtf(XPathContext support)
316   {
317
318     int result = rtf();
319
320     if (DTM.NULL == result)
321     {
322       DTM frag = support.createDocumentFragment();
323
324       // %OPT%
325 frag.appendTextChild(str());
326
327       result = frag.getDocument();
328     }
329
330     return result;
331   }
332   
333   /**
334    * Cast result object to a result tree fragment.
335    *
336    * @param support XPath context to use for the conversion
337    *
338    * @return the objec as a result tree fragment.
339    */
340   public DocumentFragment rtree(XPathContext support)
341   {
342     DocumentFragment docFrag = null;
343     int result = rtf();
344
345     if (DTM.NULL == result)
346     {
347       DTM frag = support.createDocumentFragment();
348
349       // %OPT%
350 frag.appendTextChild(str());
351
352       docFrag = (DocumentFragment )frag.getNode(frag.getDocument());
353     }
354     else
355     {
356       DTM frag = support.getDTM(result);
357       docFrag = (DocumentFragment )frag.getNode(frag.getDocument());
358     }
359
360     return docFrag;
361   }
362   
363   
364   /**
365    * For functions to override.
366    *
367    * @return null
368    */
369   public DocumentFragment rtree()
370   {
371     return null;
372   }
373
374   /**
375    * For functions to override.
376    *
377    * @return null
378    */
379   public int rtf()
380   {
381     return DTM.NULL;
382   }
383
384   /**
385    * Return a java object that's closest to the representation
386    * that should be handed to an extension.
387    *
388    * @return The object that this class wraps
389    */
390   public Object object()
391   {
392     return m_obj;
393   }
394
395   /**
396    * Cast result object to a nodelist. Always issues an error.
397    *
398    * @return null
399    *
400    * @throws javax.xml.transform.TransformerException
401    */
402   public DTMIterator iter() throws javax.xml.transform.TransformerException
403   {
404
405     error(XPATHErrorResources.ER_CANT_CONVERT_TO_NODELIST,
406           new Object []{ getTypeString() }); //"Can not convert "+getTypeString()+" to a NodeList!");
407
408     return null;
409   }
410   
411   /**
412    * Get a fresh copy of the object. For use with variables.
413    *
414    * @return This object, unless overridden by subclass.
415    */
416   public XObject getFresh()
417   {
418     return this;
419   }
420
421   
422   /**
423    * Cast result object to a nodelist. Always issues an error.
424    *
425    * @return null
426    *
427    * @throws javax.xml.transform.TransformerException
428    */
429   public NodeIterator nodeset() throws javax.xml.transform.TransformerException
430   {
431
432     error(XPATHErrorResources.ER_CANT_CONVERT_TO_NODELIST,
433           new Object []{ getTypeString() }); //"Can not convert "+getTypeString()+" to a NodeList!");
434
435     return null;
436   }
437   
438   /**
439    * Cast result object to a nodelist. Always issues an error.
440    *
441    * @return null
442    *
443    * @throws javax.xml.transform.TransformerException
444    */
445   public NodeList nodelist() throws javax.xml.transform.TransformerException
446   {
447
448     error(XPATHErrorResources.ER_CANT_CONVERT_TO_NODELIST,
449           new Object []{ getTypeString() }); //"Can not convert "+getTypeString()+" to a NodeList!");
450
451     return null;
452   }
453
454
455   /**
456    * Cast result object to a nodelist. Always issues an error.
457    *
458    * @return The object as a NodeSetDTM.
459    *
460    * @throws javax.xml.transform.TransformerException
461    */
462   public NodeSetDTM mutableNodeset()
463           throws javax.xml.transform.TransformerException
464   {
465
466     error(XPATHErrorResources.ER_CANT_CONVERT_TO_MUTABLENODELIST,
467           new Object []{ getTypeString() }); //"Can not convert "+getTypeString()+" to a NodeSetDTM!");
468
469     return (NodeSetDTM) m_obj;
470   }
471
472   /**
473    * Cast object to type t.
474    *
475    * @param t Type of object to cast this to
476    * @param support XPath context to use for the conversion
477    *
478    * @return This object as the given type t
479    *
480    * @throws javax.xml.transform.TransformerException
481    */
482   public Object castToType(int t, XPathContext support)
483           throws javax.xml.transform.TransformerException
484   {
485
486     Object result;
487
488     switch (t)
489     {
490     case CLASS_STRING :
491       result = str();
492       break;
493     case CLASS_NUMBER :
494       result = new Double (num());
495       break;
496     case CLASS_NODESET :
497       result = iter();
498       break;
499     case CLASS_BOOLEAN :
500       result = new Boolean (bool());
501       break;
502     case CLASS_UNKNOWN :
503       result = m_obj;
504       break;
505
506     // %TBD% What to do here?
507 // case CLASS_RTREEFRAG :
508 // result = rtree(support);
509 // break;
510 default :
511       error(XPATHErrorResources.ER_CANT_CONVERT_TO_TYPE,
512             new Object []{ getTypeString(),
513                           Integer.toString(t) }); //"Can not convert "+getTypeString()+" to a type#"+t);
514
515       result = null;
516     }
517
518     return result;
519   }
520
521   /**
522    * Tell if one object is less than the other.
523    *
524    * @param obj2 Object to compare this to
525    *
526    * @return True if this object is less than the given object
527    *
528    * @throws javax.xml.transform.TransformerException
529    */
530   public boolean lessThan(XObject obj2)
531           throws javax.xml.transform.TransformerException
532   {
533
534     // In order to handle the 'all' semantics of
535 // nodeset comparisons, we always call the
536 // nodeset function. Because the arguments
537 // are backwards, we call the opposite comparison
538 // function.
539 if (obj2.getType() == XObject.CLASS_NODESET)
540       return obj2.greaterThan(this);
541
542     return this.num() < obj2.num();
543   }
544
545   /**
546    * Tell if one object is less than or equal to the other.
547    *
548    * @param obj2 Object to compare this to
549    *
550    * @return True if this object is less than or equal to the given object
551    *
552    * @throws javax.xml.transform.TransformerException
553    */
554   public boolean lessThanOrEqual(XObject obj2)
555           throws javax.xml.transform.TransformerException
556   {
557
558     // In order to handle the 'all' semantics of
559 // nodeset comparisons, we always call the
560 // nodeset function. Because the arguments
561 // are backwards, we call the opposite comparison
562 // function.
563 if (obj2.getType() == XObject.CLASS_NODESET)
564       return obj2.greaterThanOrEqual(this);
565
566     return this.num() <= obj2.num();
567   }
568
569   /**
570    * Tell if one object is greater than the other.
571    *
572    * @param obj2 Object to compare this to
573    *
574    * @return True if this object is greater than the given object
575    *
576    * @throws javax.xml.transform.TransformerException
577    */
578   public boolean greaterThan(XObject obj2)
579           throws javax.xml.transform.TransformerException
580   {
581
582     // In order to handle the 'all' semantics of
583 // nodeset comparisons, we always call the
584 // nodeset function. Because the arguments
585 // are backwards, we call the opposite comparison
586 // function.
587 if (obj2.getType() == XObject.CLASS_NODESET)
588       return obj2.lessThan(this);
589
590     return this.num() > obj2.num();
591   }
592
593   /**
594    * Tell if one object is greater than or equal to the other.
595    *
596    * @param obj2 Object to compare this to
597    *
598    * @return True if this object is greater than or equal to the given object
599    *
600    * @throws javax.xml.transform.TransformerException
601    */
602   public boolean greaterThanOrEqual(XObject obj2)
603           throws javax.xml.transform.TransformerException
604   {
605
606     // In order to handle the 'all' semantics of
607 // nodeset comparisons, we always call the
608 // nodeset function. Because the arguments
609 // are backwards, we call the opposite comparison
610 // function.
611 if (obj2.getType() == XObject.CLASS_NODESET)
612       return obj2.lessThanOrEqual(this);
613
614     return this.num() >= obj2.num();
615   }
616
617   /**
618    * Tell if two objects are functionally equal.
619    *
620    * @param obj2 Object to compare this to
621    *
622    * @return True if this object is equal to the given object
623    *
624    * @throws javax.xml.transform.TransformerException
625    */
626   public boolean equals(XObject obj2)
627   {
628
629     // In order to handle the 'all' semantics of
630 // nodeset comparisons, we always call the
631 // nodeset function.
632 if (obj2.getType() == XObject.CLASS_NODESET)
633       return obj2.equals(this);
634
635     if (null != m_obj)
636     {
637       return m_obj.equals(obj2.m_obj);
638     }
639     else
640     {
641       return obj2.m_obj == null;
642     }
643   }
644
645   /**
646    * Tell if two objects are functionally not equal.
647    *
648    * @param obj2 Object to compare this to
649    *
650    * @return True if this object is not equal to the given object
651    *
652    * @throws javax.xml.transform.TransformerException
653    */
654   public boolean notEquals(XObject obj2)
655           throws javax.xml.transform.TransformerException
656   {
657
658     // In order to handle the 'all' semantics of
659 // nodeset comparisons, we always call the
660 // nodeset function.
661 if (obj2.getType() == XObject.CLASS_NODESET)
662       return obj2.notEquals(this);
663
664     return !equals(obj2);
665   }
666
667   /**
668    * Tell the user of an error, and probably throw an
669    * exception.
670    *
671    * @param msg Error message to issue
672    *
673    * @throws javax.xml.transform.TransformerException
674    */
675   protected void error(String msg)
676           throws javax.xml.transform.TransformerException
677   {
678     error(msg, null);
679   }
680
681   /**
682    * Tell the user of an error, and probably throw an
683    * exception.
684    *
685    * @param msg Error message to issue
686    * @param args Arguments to use in the message
687    *
688    * @throws javax.xml.transform.TransformerException
689    */
690   protected void error(String msg, Object [] args)
691           throws javax.xml.transform.TransformerException
692   {
693
694     String fmsg = XSLMessages.createXPATHMessage(msg, args);
695
696     // boolean shouldThrow = support.problem(m_support.XPATHPROCESSOR,
697 // m_support.ERROR,
698 // null,
699 // null, fmsg, 0, 0);
700 // if(shouldThrow)
701 {
702       throw new XPathException(fmsg, this);
703     }
704   }
705   
706   
707   /**
708    * XObjects should not normally need to fix up variables.
709    */
710   public void fixupVariables(java.util.Vector vars, int globalsSize)
711   {
712     // no-op
713 }
714
715
716   /**
717    * Cast result object to a string.
718    *
719    *
720    * NEEDSDOC @param fsb
721    * @return The string this wraps or the empty string if null
722    */
723   public void appendToFsb(com.sun.org.apache.xml.internal.utils.FastStringBuffer fsb)
724   {
725     fsb.append(str());
726   }
727   
728   /**
729    * @see XPathVisitable#callVisitors(ExpressionOwner, XPathVisitor)
730    */
731   public void callVisitors(ExpressionOwner owner, XPathVisitor visitor)
732   {
733     assertion(false, "callVisitors should not be called for this object!!!");
734   }
735   /**
736    * @see Expression#deepEquals(Expression)
737    */
738   public boolean deepEquals(Expression expr)
739   {
740     if(!isSameClass(expr))
741         return false;
742         
743     // If equals at the expression level calls deepEquals, I think we're
744 // still safe from infinite recursion since this object overrides
745 // equals. I hope.
746 if(!this.equals((XObject)expr))
747         return false;
748         
749     return true;
750   }
751
752 }
753

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags