KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > sun > org > apache > xerces > internal > parsers > AbstractDOMParser


1 /*
2  * The Apache Software License, Version 1.1
3  *
4  *
5  * Copyright (c) 2001-2004 The Apache Software Foundation.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * 1. Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  *
15  * 2. Redistributions in binary form must reproduce the above copyright
16  * notice, this list of conditions and the following disclaimer in
17  * the documentation and/or other materials provided with the
18  * distribution.
19  *
20  * 3. The end-user documentation included with the redistribution,
21  * if any, must include the following acknowledgment:
22  * "This product includes software developed by the
23  * Apache Software Foundation (http://www.apache.org/)."
24  * Alternately, this acknowledgment may appear in the software itself,
25  * if and wherever such third-party acknowledgments normally appear.
26  *
27  * 4. The names "Xerces" and "Apache Software Foundation" must
28  * not be used to endorse or promote products derived from this
29  * software without prior written permission. For written
30  * permission, please contact apache@apache.org.
31  *
32  * 5. Products derived from this software may not be called "Apache",
33  * nor may "Apache" appear in their name, without prior written
34  * permission of the Apache Software Foundation.
35  *
36  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
37  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
38  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
39  * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
40  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
41  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
42  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
43  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
44  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
45  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
46  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47  * SUCH DAMAGE.
48  * ====================================================================
49  *
50  * This software consists of voluntary contributions made by many
51  * individuals on behalf of the Apache Software Foundation and was
52  * originally based on software copyright (c) 1999, International
53  * Business Machines, Inc., http://www.apache.org. For more
54  * information on the Apache Software Foundation, please see
55  * <http://www.apache.org/>.
56  */
57
58 package com.sun.org.apache.xerces.internal.parsers;
59
60 import java.util.Locale JavaDoc;
61 import java.util.Stack JavaDoc;
62
63 import com.sun.org.apache.xerces.internal.dom.AttrImpl;
64 import com.sun.org.apache.xerces.internal.dom.CoreDocumentImpl;
65 import com.sun.org.apache.xerces.internal.dom.DOMErrorImpl;
66 import com.sun.org.apache.xerces.internal.dom.DeferredDocumentImpl;
67 import com.sun.org.apache.xerces.internal.dom.DocumentImpl;
68 import com.sun.org.apache.xerces.internal.dom.DocumentTypeImpl;
69 import com.sun.org.apache.xerces.internal.dom.DOMMessageFormatter;
70 import com.sun.org.apache.xerces.internal.dom.ElementDefinitionImpl;
71 import com.sun.org.apache.xerces.internal.dom.ElementImpl;
72 import com.sun.org.apache.xerces.internal.dom.EntityImpl;
73 import com.sun.org.apache.xerces.internal.dom.EntityReferenceImpl;
74 import com.sun.org.apache.xerces.internal.dom.NodeImpl;
75 import com.sun.org.apache.xerces.internal.dom.NotationImpl;
76 import com.sun.org.apache.xerces.internal.dom.PSVIAttrNSImpl;
77 import com.sun.org.apache.xerces.internal.dom.PSVIDocumentImpl;
78 import com.sun.org.apache.xerces.internal.dom.PSVIElementNSImpl;
79 import com.sun.org.apache.xerces.internal.dom.TextImpl;
80 import com.sun.org.apache.xerces.internal.impl.Constants;
81 import com.sun.org.apache.xerces.internal.xs.XSTypeDefinition;
82 import com.sun.org.apache.xerces.internal.util.DOMErrorHandlerWrapper;
83 import com.sun.org.apache.xerces.internal.util.TypeInfoImpl;
84 import com.sun.org.apache.xerces.internal.xni.Augmentations;
85 import com.sun.org.apache.xerces.internal.xni.NamespaceContext;
86 import com.sun.org.apache.xerces.internal.xni.QName;
87 import com.sun.org.apache.xerces.internal.xni.XMLAttributes;
88 import com.sun.org.apache.xerces.internal.xni.XMLLocator;
89 import com.sun.org.apache.xerces.internal.xni.XMLResourceIdentifier;
90 import com.sun.org.apache.xerces.internal.xni.XMLString;
91 import com.sun.org.apache.xerces.internal.xni.XNIException;
92 import com.sun.org.apache.xerces.internal.xni.parser.XMLParserConfiguration;
93 import com.sun.org.apache.xerces.internal.xs.AttributePSVI;
94 import com.sun.org.apache.xerces.internal.xs.ElementPSVI;
95 import org.w3c.dom.Attr JavaDoc;
96 import org.w3c.dom.CDATASection JavaDoc;
97 import org.w3c.dom.Comment JavaDoc;
98 import org.w3c.dom.DOMError JavaDoc;
99 import org.w3c.dom.Document JavaDoc;
100 import org.w3c.dom.DocumentType JavaDoc;
101 import org.w3c.dom.Element JavaDoc;
102 import org.w3c.dom.EntityReference JavaDoc;
103 import org.w3c.dom.NamedNodeMap JavaDoc;
104 import org.w3c.dom.Node JavaDoc;
105 import org.w3c.dom.NodeList JavaDoc;
106 import org.w3c.dom.ProcessingInstruction JavaDoc;
107 import org.w3c.dom.Text JavaDoc;
108 import org.w3c.dom.TypeInfo JavaDoc;
109 import org.w3c.dom.ls.LSParserFilter JavaDoc;
110 import org.w3c.dom.traversal.NodeFilter;
111
112 /**
113  * This is the base class of all DOM parsers. It implements the XNI
114  * callback methods to create the DOM tree. After a successful parse of
115  * an XML document, the DOM Document object can be queried using the
116  * <code>getDocument</code> method. The actual pipeline is defined in
117  * parser configuration.
118  *
119  * @author Arnaud Le Hors, IBM
120  * @author Andy Clark, IBM
121  * @author Elena Litani, IBM
122  *
123  * @version $Id: AbstractDOMParser.java,v 1.108 2004/02/17 07:14:48 neeraj Exp $
124  */
125 public class AbstractDOMParser extends AbstractXMLDocumentParser {
126
127     //
128 // Constants
129 //
130 // feature ids
131
132     /** Feature id: namespace. */
133     protected static final String JavaDoc NAMESPACES =
134     Constants.SAX_FEATURE_PREFIX+Constants.NAMESPACES_FEATURE;
135
136     /** Feature id: create entity ref nodes. */
137     protected static final String JavaDoc CREATE_ENTITY_REF_NODES =
138     Constants.XERCES_FEATURE_PREFIX + Constants.CREATE_ENTITY_REF_NODES_FEATURE;
139
140     /** Feature id: include comments. */
141     protected static final String JavaDoc INCLUDE_COMMENTS_FEATURE =
142     Constants.XERCES_FEATURE_PREFIX + Constants.INCLUDE_COMMENTS_FEATURE;
143
144     /** Feature id: create cdata nodes. */
145     protected static final String JavaDoc CREATE_CDATA_NODES_FEATURE =
146     Constants.XERCES_FEATURE_PREFIX + Constants.CREATE_CDATA_NODES_FEATURE;
147
148     /** Feature id: include ignorable whitespace. */
149     protected static final String JavaDoc INCLUDE_IGNORABLE_WHITESPACE =
150     Constants.XERCES_FEATURE_PREFIX + Constants.INCLUDE_IGNORABLE_WHITESPACE;
151
152     /** Feature id: defer node expansion. */
153     protected static final String JavaDoc DEFER_NODE_EXPANSION =
154     Constants.XERCES_FEATURE_PREFIX + Constants.DEFER_NODE_EXPANSION_FEATURE;
155
156
157     /** Recognized features. */
158     private static final String JavaDoc[] RECOGNIZED_FEATURES = {
159         NAMESPACES,
160         CREATE_ENTITY_REF_NODES,
161         INCLUDE_COMMENTS_FEATURE,
162         CREATE_CDATA_NODES_FEATURE,
163         INCLUDE_IGNORABLE_WHITESPACE,
164         DEFER_NODE_EXPANSION
165     };
166
167     // property ids
168
169     /** Property id: document class name. */
170     protected static final String JavaDoc DOCUMENT_CLASS_NAME =
171     Constants.XERCES_PROPERTY_PREFIX + Constants.DOCUMENT_CLASS_NAME_PROPERTY;
172
173     protected static final String JavaDoc CURRENT_ELEMENT_NODE=
174     Constants.XERCES_PROPERTY_PREFIX + Constants.CURRENT_ELEMENT_NODE_PROPERTY;
175
176     // protected static final String GRAMMAR_POOL =
177 // Constants.XERCES_PROPERTY_PREFIX + Constants.XMLGRAMMAR_POOL_PROPERTY;
178
179     /** Recognized properties. */
180     private static final String JavaDoc[] RECOGNIZED_PROPERTIES = {
181         DOCUMENT_CLASS_NAME,
182         CURRENT_ELEMENT_NODE,
183     };
184
185     // other
186
187     /** Default document class name. */
188     protected static final String JavaDoc DEFAULT_DOCUMENT_CLASS_NAME =
189     "com.sun.org.apache.xerces.internal.dom.DocumentImpl";
190
191     protected static final String JavaDoc CORE_DOCUMENT_CLASS_NAME =
192     "com.sun.org.apache.xerces.internal.dom.CoreDocumentImpl";
193
194     protected static final String JavaDoc PSVI_DOCUMENT_CLASS_NAME =
195     "com.sun.org.apache.xerces.internal.dom.PSVIDocumentImpl";
196
197     /**
198      * If the user stops the process, this exception will be thrown.
199      */
200     public static final RuntimeException JavaDoc abort = new RuntimeException JavaDoc();
201
202     // debugging
203
204     private static final boolean DEBUG_EVENTS = false;
205     private static final boolean DEBUG_BASEURI = false;
206
207     //
208 // Data
209 //
210
211     /** DOM L3 error handler */
212     protected DOMErrorHandlerWrapper fErrorHandler = null;
213
214     /** True if inside DTD. */
215     protected boolean fInDTD;
216
217     // features
218
219     /** Create entity reference nodes. */
220     protected boolean fCreateEntityRefNodes;
221
222     /** Include ignorable whitespace. */
223     protected boolean fIncludeIgnorableWhitespace;
224
225     /** Include Comments. */
226     protected boolean fIncludeComments;
227
228     /** Create cdata nodes. */
229     protected boolean fCreateCDATANodes;
230
231     // dom information
232
233     /** The document. */
234     protected Document JavaDoc fDocument;
235
236     /** The default Xerces document implementation, if used. */
237     protected CoreDocumentImpl fDocumentImpl;
238
239     /** Whether to store PSVI information in DOM tree. */
240     protected boolean fStorePSVI;
241
242     /** The document class name to use. */
243     protected String JavaDoc fDocumentClassName;
244
245     /** The document type node. */
246     protected DocumentType JavaDoc fDocumentType;
247
248     /** Current node. */
249     protected Node JavaDoc fCurrentNode;
250     protected CDATASection JavaDoc fCurrentCDATASection;
251     protected EntityImpl fCurrentEntityDecl;
252     protected int fDeferredEntityDecl;
253
254     /** Character buffer */
255     protected final StringBuffer JavaDoc fStringBuffer = new StringBuffer JavaDoc (50);
256
257     // internal subset
258
259     /** Internal subset buffer. */
260     protected StringBuffer JavaDoc fInternalSubset;
261
262     // deferred expansion data
263
264     protected boolean fDeferNodeExpansion;
265     protected boolean fNamespaceAware;
266     protected DeferredDocumentImpl fDeferredDocumentImpl;
267     protected int fDocumentIndex;
268     protected int fDocumentTypeIndex;
269     protected int fCurrentNodeIndex;
270     protected int fCurrentCDATASectionIndex;
271
272     // state
273
274     /** True if inside DTD external subset. */
275     protected boolean fInDTDExternalSubset;
276
277     /** Root element name */
278     protected QName fRoot = new QName();
279
280     /** True if inside CDATA section. */
281     protected boolean fInCDATASection;
282
283     /** True if saw the first chunk of characters*/
284     protected boolean fFirstChunk = false;
285
286
287     /** LSParserFilter: specifies that element with given QNAME and all its children
288         must be rejected */
289     protected boolean fFilterReject = false;
290
291     // data
292
293     /** Base uri stack*/
294     protected Stack JavaDoc fBaseURIStack = new Stack JavaDoc ();
295
296
297     /** LSParserFilter: the QNAME of rejected element*/
298     protected final QName fRejectedElement = new QName ();
299
300     /** LSParserFilter: store qnames of skipped elements*/
301     protected Stack JavaDoc fSkippedElemStack = null;
302
303     /** LSParserFilter: true if inside entity reference */
304     protected boolean fInEntityRef = false;
305
306     /** Attribute QName. */
307     private QName fAttrQName = new QName ();
308
309     // handlers
310
311     protected LSParserFilter JavaDoc fDOMFilter = null;
312
313     //
314 // Constructors
315 //
316
317     /** Default constructor. */
318     protected AbstractDOMParser (XMLParserConfiguration config) {
319
320         super (config);
321
322
323         // add recognized features
324 fConfiguration.addRecognizedFeatures (RECOGNIZED_FEATURES);
325
326         // set default values
327 fConfiguration.setFeature (CREATE_ENTITY_REF_NODES, true);
328         fConfiguration.setFeature (INCLUDE_IGNORABLE_WHITESPACE, true);
329         fConfiguration.setFeature (DEFER_NODE_EXPANSION, true);
330         fConfiguration.setFeature (INCLUDE_COMMENTS_FEATURE, true);
331         fConfiguration.setFeature (CREATE_CDATA_NODES_FEATURE, true);
332
333         // add recognized properties
334 fConfiguration.addRecognizedProperties (RECOGNIZED_PROPERTIES);
335
336         // set default values
337 fConfiguration.setProperty (DOCUMENT_CLASS_NAME,
338         DEFAULT_DOCUMENT_CLASS_NAME);
339
340     } // <init>(XMLParserConfiguration)
341
342     /**
343      * This method retreives the name of current document class.
344      */
345     protected String JavaDoc getDocumentClassName() {
346         return fDocumentClassName;
347     }
348
349     /**
350      * This method allows the programmer to decide which document
351      * factory to use when constructing the DOM tree. However, doing
352      * so will lose the functionality of the default factory. Also,
353      * a document class other than the default will lose the ability
354      * to defer node expansion on the DOM tree produced.
355      *
356      * @param documentClassName The fully qualified class name of the
357      * document factory to use when constructing
358      * the DOM tree.
359      *
360      * @see #getDocumentClassName
361      * @see #DEFAULT_DOCUMENT_CLASS_NAME
362      */
363     protected void setDocumentClassName (String JavaDoc documentClassName) {
364
365         // normalize class name
366 if (documentClassName == null) {
367             documentClassName = DEFAULT_DOCUMENT_CLASS_NAME;
368         }
369
370         if (!documentClassName.equals(DEFAULT_DOCUMENT_CLASS_NAME) &&
371             !documentClassName.equals(PSVI_DOCUMENT_CLASS_NAME)) {
372             // verify that this class exists and is of the right type
373 try {
374                 Class JavaDoc _class = ObjectFactory.findProviderClass (documentClassName,
375                 ObjectFactory.findClassLoader (), true);
376                 //if (!_class.isAssignableFrom(Document.class)) {
377 if (!Document JavaDoc.class.isAssignableFrom (_class)) {
378                     throw new IllegalArgumentException JavaDoc (
379                         DOMMessageFormatter.formatMessage(
380                         DOMMessageFormatter.DOM_DOMAIN,
381                         "InvalidDocumentClassName", new Object JavaDoc [] {documentClassName}));
382                 }
383             }
384             catch (ClassNotFoundException JavaDoc e) {
385                 throw new IllegalArgumentException JavaDoc (
386                     DOMMessageFormatter.formatMessage(
387                     DOMMessageFormatter.DOM_DOMAIN,
388                     "MissingDocumentClassName", new Object JavaDoc [] {documentClassName}));
389             }
390         }
391
392         // set document class name
393 fDocumentClassName = documentClassName;
394         if (!documentClassName.equals(DEFAULT_DOCUMENT_CLASS_NAME)) {
395             fDeferNodeExpansion = false;
396         }
397
398     } // setDocumentClassName(String)
399
400     //
401 // Public methods
402 //
403
404     /** Returns the DOM document object. */
405     public Document JavaDoc getDocument() {
406         return fDocument;
407     } // getDocument():Document
408
409     //
410 // XMLDocumentParser methods
411 //
412
413     /**
414      * Resets the parser state.
415      *
416      * @throws SAXException Thrown on initialization error.
417      */
418     public void reset () throws XNIException {
419         super.reset ();
420
421
422         // get feature state
423 fCreateEntityRefNodes =
424         fConfiguration.getFeature (CREATE_ENTITY_REF_NODES);
425
426         fIncludeIgnorableWhitespace =
427         fConfiguration.getFeature (INCLUDE_IGNORABLE_WHITESPACE);
428
429         fDeferNodeExpansion =
430         fConfiguration.getFeature (DEFER_NODE_EXPANSION);
431
432         fNamespaceAware = fConfiguration.getFeature (NAMESPACES);
433
434         fIncludeComments = fConfiguration.getFeature (INCLUDE_COMMENTS_FEATURE);
435
436         fCreateCDATANodes = fConfiguration.getFeature (CREATE_CDATA_NODES_FEATURE);
437
438         // get property
439 setDocumentClassName ((String JavaDoc)
440         fConfiguration.getProperty (DOCUMENT_CLASS_NAME));
441
442         // reset dom information
443 fDocument = null;
444         fDocumentImpl = null;
445         fStorePSVI = false;
446         fDocumentType = null;
447         fDocumentTypeIndex = -1;
448         fDeferredDocumentImpl = null;
449         fCurrentNode = null;
450
451         // reset string buffer
452 fStringBuffer.setLength (0);
453
454         // reset state information
455 fRoot.clear();
456         fInDTD = false;
457         fInDTDExternalSubset = false;
458         fInCDATASection = false;
459         fFirstChunk = false;
460         fCurrentCDATASection = null;
461         fCurrentCDATASectionIndex = -1;
462         fBaseURIStack.removeAllElements ();
463
464
465     } // reset()
466
467     /**
468      * Set the locale to use for messages.
469      *
470      * @param locale The locale object to use for localization of messages.
471      *
472      */
473     public void setLocale (Locale JavaDoc locale) {
474         fConfiguration.setLocale (locale);
475
476     } // setLocale(Locale)
477
478     //
479 // XMLDocumentHandler methods
480 //
481
482     /**
483      * This method notifies the start of a general entity.
484      * <p>
485      * <strong>Note:</strong> This method is not called for entity references
486      * appearing as part of attribute values.
487      *
488      * @param name The name of the general entity.
489      * @param identifier The resource identifier.
490      * @param encoding The auto-detected IANA encoding name of the entity
491      * stream. This value will be null in those situations
492      * where the entity encoding is not auto-detected (e.g.
493      * internal entities or a document entity that is
494      * parsed from a java.io.Reader).
495      * @param augs Additional information that may include infoset augmentations
496      *
497      * @exception XNIException Thrown by handler to signal an error.
498      */
499     public void startGeneralEntity(String JavaDoc name,
500                                    XMLResourceIdentifier identifier,
501                                    String JavaDoc encoding, Augmentations augs)
502         throws XNIException {
503         if (DEBUG_EVENTS) {
504             System.out.println("==>startGeneralEntity ("+name+")");
505             if (DEBUG_BASEURI) {
506                 System.out.println(" expandedSystemId( **baseURI): "+identifier.getExpandedSystemId());
507                 System.out.println(" baseURI:"+ identifier.getBaseSystemId());
508             }
509         }
510
511         // Always create entity reference nodes to be able to recreate
512 // entity as a part of doctype
513 if (!fDeferNodeExpansion) {
514              if (fFilterReject) {
515                  return;
516              }
517             setCharacterData(true);
518             EntityReference JavaDoc er = fDocument.createEntityReference(name);
519             if (fDocumentImpl != null) {
520                 // REVISIT: baseURI/actualEncoding
521 // remove dependency on our implementation when DOM L3 is REC
522 //
523 EntityReferenceImpl erImpl =(EntityReferenceImpl)er;
524
525                 // set base uri
526 erImpl.setBaseURI(identifier.getExpandedSystemId());
527                 if (fDocumentType != null) {
528                     // set actual encoding
529 NamedNodeMap JavaDoc entities = fDocumentType.getEntities();
530                     fCurrentEntityDecl = (EntityImpl) entities.getNamedItem(name);
531                     if (fCurrentEntityDecl != null) {
532                         fCurrentEntityDecl.setInputEncoding(encoding);
533                     }
534
535                 }
536                 // we don't need synchronization now, because entity ref will be
537 // expanded anyway. Synch only needed when user creates entityRef node
538 erImpl.needsSyncChildren(false);
539             }
540             fInEntityRef = true;
541             fCurrentNode.appendChild (er);
542             fCurrentNode = er;
543         }
544         else {
545
546             int er =
547                fDeferredDocumentImpl.createDeferredEntityReference(name, identifier.getExpandedSystemId());
548             if (fDocumentTypeIndex != -1) {
549                 // find corresponding Entity decl
550 int node = fDeferredDocumentImpl.getLastChild(fDocumentTypeIndex, false);
551                 while (node != -1) {
552                     short nodeType = fDeferredDocumentImpl.getNodeType(node, false);
553                     if (nodeType == Node.ENTITY_NODE) {
554                         String JavaDoc nodeName =
555                             fDeferredDocumentImpl.getNodeName(node, false);
556                         if (nodeName.equals(name)) {
557                             fDeferredEntityDecl = node;
558                             fDeferredDocumentImpl.setInputEncoding(node, encoding);
559                             break;
560                         }
561                     }
562                     node = fDeferredDocumentImpl.getRealPrevSibling(node, false);
563                 }
564             }
565             fDeferredDocumentImpl.appendChild(fCurrentNodeIndex, er);
566             fCurrentNodeIndex = er;
567         }
568
569     } // startGeneralEntity(String,XMLResourceIdentifier, Augmentations)
570
571     /**
572      * Notifies of the presence of a TextDecl line in an entity. If present,
573      * this method will be called immediately following the startEntity call.
574      * <p>
575      * <strong>Note:</strong> This method will never be called for the
576      * document entity; it is only called for external general entities
577      * referenced in document content.
578      * <p>
579      * <strong>Note:</strong> This method is not called for entity references
580      * appearing as part of attribute values.
581      *
582      * @param version The XML version, or null if not specified.
583      * @param encoding The IANA encoding name of the entity.
584      * @param augs Additional information that may include infoset augmentations
585      *
586      * @throws XNIException Thrown by handler to signal an error.
587      */
588     public void textDecl(String JavaDoc version, String JavaDoc encoding, Augmentations augs) throws XNIException {
589         if (fInDTD){
590             return;
591         }
592         if (!fDeferNodeExpansion) {
593             if (fCurrentEntityDecl != null && !fFilterReject) {
594                 fCurrentEntityDecl.setXmlEncoding(encoding);
595                 if(version != null)
596                     fCurrentEntityDecl.setXmlVersion(version);
597             }
598         }
599         else {
600             if (fDeferredEntityDecl !=-1) {
601                fDeferredDocumentImpl.setEntityInfo(fDeferredEntityDecl, version, encoding);
602             }
603         }
604     } // textDecl(String,String)
605
606     /**
607      * A comment.
608      *
609      * @param text The text in the comment.
610      * @param augs Additional information that may include infoset augmentations
611      *
612      * @throws XNIException Thrown by application to signal an error.
613      */
614     public void comment(XMLString text, Augmentations augs) throws XNIException {
615         if (fInDTD) {
616             if (fInternalSubset != null && !fInDTDExternalSubset) {
617                 fInternalSubset.append("<!-- ");
618                 fInternalSubset.append(text.toString());
619                 fInternalSubset.append(" -->");
620             }
621             return;
622         }
623         if (!fIncludeComments || fFilterReject) {
624               return;
625         }
626         if (!fDeferNodeExpansion) {
627             Comment JavaDoc comment = fDocument.createComment (text.toString ());
628
629             setCharacterData (false);
630             fCurrentNode.appendChild (comment);
631             if (fDOMFilter !=null && !fInEntityRef &&
632             (fDOMFilter.getWhatToShow () & NodeFilter.SHOW_COMMENT)!= 0) {
633                 short code = fDOMFilter.acceptNode (comment);
634                 switch (code) {
635                     case LSParserFilter.FILTER_INTERRUPT:{
636                         throw abort;
637                     }
638                     case LSParserFilter.FILTER_REJECT:{
639                         // REVISIT: the constant FILTER_REJECT should be changed when new
640 // DOM LS specs gets published
641
642                         // fall through to SKIP since comment has no children.
643 }
644                     case LSParserFilter.FILTER_SKIP: {
645                         // REVISIT: the constant FILTER_SKIP should be changed when new
646 // DOM LS specs gets published
647 fCurrentNode.removeChild(comment);
648                         // make sure we don't loose chars if next event is characters()
649 fFirstChunk = true;
650                         return;
651                     }
652
653                     default: {
654                         // accept node
655 }
656                 }
657             }
658
659         }
660         else {
661             int comment =
662                 fDeferredDocumentImpl.createDeferredComment(text.toString());
663             fDeferredDocumentImpl.appendChild(fCurrentNodeIndex, comment);
664         }
665
666     } // comment(XMLString)
667
668     /**
669      * A processing instruction. Processing instructions consist of a
670      * target name and, optionally, text data. The data is only meaningful
671      * to the application.
672      * <p>
673      * Typically, a processing instruction's data will contain a series
674      * of pseudo-attributes. These pseudo-attributes follow the form of
675      * element attributes but are <strong>not</strong> parsed or presented
676      * to the application as anything other than text. The application is
677      * responsible for parsing the data.
678      *
679      * @param target The target.
680      * @param data The data or null if none specified.
681      * @param augs Additional information that may include infoset augmentations
682      *
683      * @throws XNIException Thrown by handler to signal an error.
684      */
685     public void processingInstruction (String JavaDoc target, XMLString data, Augmentations augs)
686     throws XNIException {
687
688         if (fInDTD) {
689             if (fInternalSubset != null && !fInDTDExternalSubset) {
690                 fInternalSubset.append ("<?");
691                 fInternalSubset.append (target.toString ());
692                 fInternalSubset.append (' ');
693                 fInternalSubset.append (data.toString ());
694                 fInternalSubset.append ("?>");
695
696             }
697             return;
698         }
699
700         if (DEBUG_EVENTS) {
701             System.out.println ("==>processingInstruction ("+target+")");
702         }
703         if (!fDeferNodeExpansion) {
704             if (fFilterReject) {
705                 return;
706             }
707             ProcessingInstruction JavaDoc pi =
708             fDocument.createProcessingInstruction (target, data.toString ());
709
710
711             setCharacterData (false);
712             fCurrentNode.appendChild (pi);
713             if (fDOMFilter !=null && !fInEntityRef &&
714             (fDOMFilter.getWhatToShow () & NodeFilter.SHOW_PROCESSING_INSTRUCTION)!= 0) {
715                 short code = fDOMFilter.acceptNode (pi);
716                 switch (code) {
717                     case LSParserFilter.FILTER_INTERRUPT:{
718                         throw abort;
719                     }
720                     case LSParserFilter.FILTER_REJECT:{
721                         // fall through to SKIP since PI has no children.
722 }
723                     case LSParserFilter.FILTER_SKIP: {
724                         fCurrentNode.removeChild(pi);
725                         // fFirstChunk must be set to true so that data
726 // won't be lost in the case where the child before PI is
727 // a text node and the next event is characters.
728 fFirstChunk = true;
729                         return;
730                     }
731                     default: {
732                     }
733                 }
734             }
735         }
736         else {
737             int pi = fDeferredDocumentImpl.
738                 createDeferredProcessingInstruction(target, data.toString());
739             fDeferredDocumentImpl.appendChild(fCurrentNodeIndex, pi);
740         }
741
742     } // processingInstruction(String,XMLString)
743
744     /**
745      * The start of the document.
746      *
747      * @param locator The system identifier of the entity if the entity
748      * is external, null otherwise.
749      * @param encoding The auto-detected IANA encoding name of the entity
750      * stream. This value will be null in those situations
751      * where the entity encoding is not auto-detected (e.g.
752      * internal entities or a document entity that is
753      * parsed from a java.io.Reader).
754      * @param namespaceContext
755      * The namespace context in effect at the
756      * start of this document.
757      * This object represents the current context.
758      * Implementors of this class are responsible
759      * for copying the namespace bindings from the
760      * the current context (and its parent contexts)
761      * if that information is important.
762      * @param augs Additional information that may include infoset augmentations
763      *
764      * @throws XNIException Thrown by handler to signal an error.
765      */
766     public void startDocument (XMLLocator locator, String JavaDoc encoding,
767     NamespaceContext namespaceContext, Augmentations augs)
768     throws XNIException {
769
770         if (!fDeferNodeExpansion) {
771             if (fDocumentClassName.equals (DEFAULT_DOCUMENT_CLASS_NAME)) {
772                 fDocument = new DocumentImpl ();
773                 fDocumentImpl = (CoreDocumentImpl)fDocument;
774                 // REVISIT: when DOM Level 3 is REC rely on Document.support
775 // instead of specific class
776 // set DOM error checking off
777 fDocumentImpl.setStrictErrorChecking (false);
778                 // set actual encoding
779 fDocumentImpl.setInputEncoding (encoding);
780                 // set documentURI
781 fDocumentImpl.setDocumentURI (locator.getExpandedSystemId ());
782             }
783             else if (fDocumentClassName.equals (PSVI_DOCUMENT_CLASS_NAME)) {
784                 fDocument = new PSVIDocumentImpl();
785                 fDocumentImpl = (CoreDocumentImpl)fDocument;
786                 fStorePSVI = true;
787                 // REVISIT: when DOM Level 3 is REC rely on Document.support
788 // instead of specific class
789 // set DOM error checking off
790 fDocumentImpl.setStrictErrorChecking (false);
791                 // set actual encoding
792 fDocumentImpl.setInputEncoding (encoding);
793                 // set documentURI
794 fDocumentImpl.setDocumentURI (locator.getExpandedSystemId ());
795             }
796             else {
797                 // use specified document class
798 try {
799                     ClassLoader JavaDoc cl = ObjectFactory.findClassLoader();
800                     Class JavaDoc documentClass = ObjectFactory.findProviderClass (fDocumentClassName,
801                         cl, true);
802                     fDocument = (Document JavaDoc)documentClass.newInstance ();
803
804                     // if subclass of our own class that's cool too
805 Class JavaDoc defaultDocClass =
806                     ObjectFactory.findProviderClass (CORE_DOCUMENT_CLASS_NAME,
807                         cl, true);
808                     if (defaultDocClass.isAssignableFrom (documentClass)) {
809                         fDocumentImpl = (CoreDocumentImpl)fDocument;
810
811                         Class JavaDoc psviDocClass = ObjectFactory.findProviderClass (PSVI_DOCUMENT_CLASS_NAME,
812                             cl, true);
813                         if (psviDocClass.isAssignableFrom (documentClass)) {
814                             fStorePSVI = true;
815                         }
816
817                         // REVISIT: when DOM Level 3 is REC rely on
818 // Document.support instead