2 Copyright (C) 2004, 2005 Free Software Foundation, Inc.
4 This file is part of GNU Classpath.
6 GNU Classpath is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 2, or (at your option)
11 GNU Classpath is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Classpath; see the file COPYING. If not, write to the
18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
21 Linking this library statically or dynamically with other modules is
22 making a combined work based on this library. Thus, the terms and
23 conditions of the GNU General Public License cover the whole
26 As a special exception, the copyright holders of this library give you
27 permission to link this library with independent modules to produce an
28 executable, regardless of the license terms of these independent
29 modules, and to copy and distribute the resulting executable under
30 terms of your choice, provided that you also meet, for each linked
31 independent module, the terms and conditions of the license of that
32 module. An independent module is a module which is not derived from
33 or based on this library. If you modify this library, you may extend
34 this exception to your version of the library, but you are not
35 obligated to do so. If you do not wish to do so, delete this
36 exception statement from your version. */
38 package javax
.xml
.parsers
;
41 import java
.io
.FileInputStream
;
42 import java
.io
.InputStream
;
43 import java
.io
.IOException
;
44 import javax
.xml
.validation
.Schema
;
45 import org
.xml
.sax
.HandlerBase
;
46 import org
.xml
.sax
.InputSource
;
47 import org
.xml
.sax
.Parser
;
48 import org
.xml
.sax
.SAXException
;
49 import org
.xml
.sax
.SAXNotRecognizedException
;
50 import org
.xml
.sax
.SAXNotSupportedException
;
51 import org
.xml
.sax
.XMLReader
;
52 import org
.xml
.sax
.helpers
.DefaultHandler
;
55 * Convenience class for using or accessing a SAX version 1 or 2 parser.
56 * Instances of this class are <em>not</em> guaranteed to be thread safe.
58 * @author (a href='mailto:dog@gnu.org'>Chris Burdess</a)
60 public abstract class SAXParser
68 * Parse the specifed input stream, reporting SAX1 events to the given
70 * Prefer the SAX2 version of this method, since the HandlerBase class is
72 * Also prefer the version of this method that specifies a system ID, in
73 * order to resolve external references correctly.
74 * @param is an XML input stream
75 * @param hb the SAX1 handler
76 * @exception IllegalArgumentException if the input stream is null
77 * @see #parse(java.io.InputStream,org.xml.sax.helpers.DefaultHandler)
79 public void parse(InputStream is
, HandlerBase hb
)
80 throws SAXException
, IOException
84 throw new IllegalArgumentException("input stream is null");
86 parse(new InputSource(is
), hb
);
90 * Parse the specified input stream, reporting SAX1 events to the given
92 * Prefer the SAX2 version of this method, since the HandlerBase class is
94 * @param is an XML input stream
95 * @param hb the SAX1 handler
96 * @param systemId the system ID of the XML document
97 * @exception IllegalArgumentException if the input stream is null
98 * @see #parse(java.io.InputStream,org.xml.sax.helpers.DefaultHandler,java.lang.String)
100 public void parse(InputStream is
, HandlerBase hb
, String systemId
)
101 throws SAXException
, IOException
105 throw new IllegalArgumentException("input stream is null");
107 InputSource source
= new InputSource(is
);
108 source
.setSystemId(systemId
);
113 * Parse the specified input stream, reporting SAX2 events to the given
115 * Prefer the version of this method that specifies a system ID, in
116 * order to resolve external references correctly.
117 * @param is an XML input stream
118 * @param dh the SAX2 handler
119 * @exception IllegalArgumentException if the input stream is null
121 public void parse(InputStream is
, DefaultHandler dh
)
122 throws SAXException
, IOException
126 throw new IllegalArgumentException("input stream is null");
128 parse(new InputSource(is
), dh
);
132 * Parse the specified input stream, reporting SAX2 events to the given
134 * @param is an XML input stream
135 * @param dh the SAX2 handler
136 * @param systemId the system ID of the XML document
137 * @exception IllegalArgumentException if the input stream is null
139 public void parse (InputStream is
, DefaultHandler dh
, String systemId
)
140 throws SAXException
, IOException
144 throw new IllegalArgumentException("input stream is null");
146 InputSource source
= new InputSource(is
);
147 source
.setSystemId(systemId
);
152 * Parse the content of the specified URI, reporting SAX1 events to the
154 * Prefer the SAX2 version of this method, since the HandlerBase class is
156 * @param uri an XML system ID
157 * @param hb the SAX1 handler
158 * @exception IllegalArgumentException if the URI is null
159 * @see #parse(java.lang.String,org.xml.sax.helpers.DefaultHandler)
161 public void parse(String uri
, HandlerBase hb
)
162 throws SAXException
, IOException
166 throw new IllegalArgumentException("URI is null");
168 parse(new InputSource(uri
), hb
);
172 * Parse the content of the specified URI, reporting SAX2 events to the
174 * @param uri an XML system ID
175 * @param dh the SAX2 handler
176 * @exception IllegalArgumentException if the URI is null
178 public void parse(String uri
, DefaultHandler dh
)
179 throws SAXException
, IOException
183 throw new IllegalArgumentException("URI is null");
185 parse(new InputSource(uri
), dh
);
189 * Parse the content of the specified file, reporting SAX1 events to the
191 * Prefer the SAX2 version of this method, since the HandlerBase class is
193 * @param f an XML file
194 * @param hb the SAX1 handler
195 * @exception IllegalArgumentException if the file is null
196 * @see #parse(java.io.File,org.xml.sax.helpers.DefaultHandler)
198 public void parse(File f
, HandlerBase hb
)
199 throws SAXException
, IOException
203 throw new IllegalArgumentException("file is null");
205 InputSource source
= new InputSource(new FileInputStream(f
));
206 source
.setSystemId(f
.toURL().toString());
211 * Parse the content of the specified file, reporting SAX2 events to the
213 * @param f an XML file
214 * @param dh the SAX2 handler
215 * @exception IllegalArgumentException if the file is null
217 public void parse(File f
, DefaultHandler dh
)
218 throws SAXException
, IOException
222 throw new IllegalArgumentException("file is null");
224 InputSource source
= new InputSource(new FileInputStream(f
));
225 source
.setSystemId(f
.toURL().toString());
230 * Parse the specified input source, reporting SAX1 events to the
232 * Prefer the SAX2 version of this method, since the HandlerBase class is
234 * @param is the SAX input source
235 * @param hb the SAX1 handler
236 * @exception IllegalArgumentException if the input source is null
237 * @see #parse(org.xml.sax.InputSource,org.xml.sax.helpers.DefaultHandler)
239 public void parse(InputSource is
, HandlerBase hb
)
240 throws SAXException
, IOException
244 throw new IllegalArgumentException("input source is null");
246 Parser parser
= getParser();
247 parser
.setDocumentHandler(hb
);
248 parser
.setDTDHandler(hb
);
249 parser
.setEntityResolver(hb
);
250 parser
.setErrorHandler(hb
);
255 * Parse the specified input source, reporting SAX2 events to the
257 * @param is an XML file
258 * @param dh the SAX2 handler
259 * @exception IllegalArgumentException if the input source is null
261 public void parse(InputSource is
, DefaultHandler dh
)
262 throws SAXException
, IOException
266 throw new IllegalArgumentException("input source is null");
268 XMLReader reader
= getXMLReader();
269 reader
.setContentHandler(dh
);
270 reader
.setDTDHandler(dh
);
271 reader
.setEntityResolver(dh
);
272 reader
.setErrorHandler(dh
);
277 * Returns the underlying SAX1 parser.
279 public abstract Parser
getParser() throws SAXException
;
282 * Returns the underlying SAX2 parser.
285 public abstract XMLReader
getXMLReader() throws SAXException
;
288 * Indicates whether this parser is XML Namespace aware.
290 public abstract boolean isNamespaceAware();
293 * Indicates whether this parser will validate its input.
295 public abstract boolean isValidating();
298 * Sets the specified SAX2 parser property.
299 * @param name the name of the property
300 * @param value the value of the property
302 public abstract void setProperty(String name
, Object value
)
303 throws SAXNotRecognizedException
, SAXNotSupportedException
;
306 * Returns the value of the specified SAX2 parser property.
307 * @param name the name of the property
309 public abstract Object
getProperty(String name
)
310 throws SAXNotRecognizedException
, SAXNotSupportedException
;
312 // -- JAXP 1.3 methods --
315 * Resets this parser to its original configuration.
323 * Returns the schema in use by this parser.
326 public Schema
getSchema()
332 * Indicates whether this parser is XInclude-aware.
335 public boolean isXIncludeAware()