1 /*
2 * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package jdk.internal.util.xml.impl;
27
28 import java.io.File;
29 import java.io.IOException;
30 import java.io.InputStream;
31 import jdk.internal.org.xml.sax.InputSource;
32 import jdk.internal.org.xml.sax.SAXException;
33 import jdk.internal.org.xml.sax.XMLReader;
34 import jdk.internal.org.xml.sax.helpers.DefaultHandler;
35
36
37 /**
38 * Defines the API that wraps an {@link org.xml.sax.XMLReader}
39 * implementation class. In JAXP 1.0, this class wrapped the
40 * {@link org.xml.sax.Parser} interface, however this interface was
41 * replaced by the {@link org.xml.sax.XMLReader}. For ease
42 * of transition, this class continues to support the same name
43 * and interface as well as supporting new methods.
44 *
45 * An instance of this class can be obtained from the
46 * {@link javax.xml.parsers.SAXParserFactory#newSAXParser()} method.
47 * Once an instance of this class is obtained, XML can be parsed from
48 * a variety of input sources. These input sources are InputStreams,
49 * Files, URLs, and SAX InputSources.<p>
50 *
51 * This static method creates a new factory instance based
52 * on a system property setting or uses the platform default
53 * if no property has been defined.<p>
54 *
55 * The system property that controls which Factory implementation
56 * to create is named <code>"javax.xml.parsers.SAXParserFactory"</code>.
57 * This property names a class that is a concrete subclass of this
58 * abstract class. If no property is defined, a platform default
59 * will be used.</p>
60 *
61 * As the content is parsed by the underlying parser, methods of the
62 * given
63 * {@link org.xml.sax.helpers.DefaultHandler} are called.<p>
64 *
65 * Implementors of this class which wrap an underlaying implementation
66 * can consider using the {@link org.xml.sax.helpers.ParserAdapter}
67 * class to initially adapt their SAX1 implementation to work under
68 * this revised class.
69 *
70 * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
71 * @version $Revision: 1.8 $, $Date: 2010-11-01 04:36:09 $
72 *
73 * @author Joe Wang
74 * This is a subset of that in JAXP, javax.xml.parsers.SAXParser
75 *
76 */
77 public abstract class SAXParser {
78
79 /**
80 * <p>Protected constructor to prevent instantiation.</p>
81 */
82 protected SAXParser () {
83
84 }
85
86 /**
87 * Parse the content of the given {@link java.io.InputStream}
88 * instance as XML using the specified
89 * {@link org.xml.sax.helpers.DefaultHandler}.
90 *
91 * @param is InputStream containing the content to be parsed.
92 * @param dh The SAX DefaultHandler to use.
93 *
94 * @throws IllegalArgumentException If the given InputStream is null.
95 * @throws IOException If any IO errors occur.
96 * @throws SAXException If any SAX errors occur during processing.
97 *
98 * @see org.xml.sax.DocumentHandler
99 */
100 public void parse(InputStream is, DefaultHandler dh)
101 throws SAXException, IOException {
102 if (is == null) {
103 throw new IllegalArgumentException("InputStream cannot be null");
104 }
105
106 InputSource input = new InputSource(is);
107 this.parse(input, dh);
108 }
109
110 /**
111 * Parse the content described by the giving Uniform Resource
112 * Identifier (URI) as XML using the specified
113 * {@link org.xml.sax.helpers.DefaultHandler}.
114 *
115 * @param uri The location of the content to be parsed.
116 * @param dh The SAX DefaultHandler to use.
117 *
118 * @throws IllegalArgumentException If the uri is null.
119 * @throws IOException If any IO errors occur.
120 * @throws SAXException If any SAX errors occur during processing.
121 *
122 * @see org.xml.sax.DocumentHandler
123 */
124 public void parse(String uri, DefaultHandler dh)
125 throws SAXException, IOException {
126 if (uri == null) {
127 throw new IllegalArgumentException("uri cannot be null");
128 }
129
130 InputSource input = new InputSource(uri);
131 this.parse(input, dh);
132 }
133
134 /**
135 * Parse the content of the file specified as XML using the
136 * specified {@link org.xml.sax.helpers.DefaultHandler}.
137 *
138 * @param f The file containing the XML to parse
139 * @param dh The SAX DefaultHandler to use.
140 *
141 * @throws IllegalArgumentException If the File object is null.
142 * @throws IOException If any IO errors occur.
143 * @throws SAXException If any SAX errors occur during processing.
144 *
145 * @see org.xml.sax.DocumentHandler
146 */
147 public void parse(File f, DefaultHandler dh)
148 throws SAXException, IOException {
149 if (f == null) {
150 throw new IllegalArgumentException("File cannot be null");
151 }
152
153 //convert file to appropriate URI, f.toURI().toASCIIString()
154 //converts the URI to string as per rule specified in
155 //RFC 2396,
156 InputSource input = new InputSource(f.toURI().toASCIIString());
157 this.parse(input, dh);
158 }
159
160 /**
161 * Parse the content given {@link org.xml.sax.InputSource}
162 * as XML using the specified
163 * {@link org.xml.sax.helpers.DefaultHandler}.
164 *
165 * @param is The InputSource containing the content to be parsed.
166 * @param dh The SAX DefaultHandler to use.
167 *
168 * @throws IllegalArgumentException If the <code>InputSource</code> object
169 * is <code>null</code>.
170 * @throws IOException If any IO errors occur.
171 * @throws SAXException If any SAX errors occur during processing.
172 *
173 * @see org.xml.sax.DocumentHandler
174 */
175 public void parse(InputSource is, DefaultHandler dh)
176 throws SAXException, IOException {
177 if (is == null) {
178 throw new IllegalArgumentException("InputSource cannot be null");
179 }
180
181 XMLReader reader = this.getXMLReader();
182 if (dh != null) {
183 reader.setContentHandler(dh);
184 reader.setEntityResolver(dh);
185 reader.setErrorHandler(dh);
186 reader.setDTDHandler(dh);
187 }
188 reader.parse(is);
189 }
190
191 /**
192 * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
193 * implementation of this class.
194 *
195 * @return The XMLReader that is encapsulated by the
196 * implementation of this class.
197 *
198 * @throws SAXException If any SAX errors occur during processing.
199 */
200
201 public abstract XMLReader getXMLReader() throws SAXException;
202
203 /**
204 * Indicates whether or not this parser is configured to
205 * understand namespaces.
206 *
207 * @return true if this parser is configured to
208 * understand namespaces; false otherwise.
209 */
210
211 public abstract boolean isNamespaceAware();
212
213 /**
214 * Indicates whether or not this parser is configured to
215 * validate XML documents.
216 *
217 * @return true if this parser is configured to
218 * validate XML documents; false otherwise.
219 */
220
221 public abstract boolean isValidating();
222
223 /**
224 * <p>Get the XInclude processing mode for this parser.</p>
225 *
226 * @return
227 * the return value of
228 * the {@link SAXParserFactory#isXIncludeAware()}
229 * when this parser was created from factory.
230 *
231 * @throws UnsupportedOperationException When implementation does not
232 * override this method
233 *
234 * @since 1.5
235 *
236 * @see SAXParserFactory#setXIncludeAware(boolean)
237 */
238 public boolean isXIncludeAware() {
239 throw new UnsupportedOperationException(
240 "This parser does not support specification \""
241 + this.getClass().getPackage().getSpecificationTitle()
242 + "\" version \""
243 + this.getClass().getPackage().getSpecificationVersion()
244 + "\""
245 );
246 }
247 }