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
26package jdk.internal.util.xml;
27
28import java.io.File;
29import java.io.IOException;
30import java.io.InputStream;
31import jdk.internal.org.xml.sax.InputSource;
32import jdk.internal.org.xml.sax.SAXException;
33import jdk.internal.org.xml.sax.XMLReader;
34import 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>&quot;javax.xml.parsers.SAXParserFactory&quot;</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 */
77public abstract class SAXParser {
78
79    /**
80     * <p>Protected constructor to prevent instantiation.</p>
81     */
82    protected SAXParser() {
83    }
84
85    /**
86     * Parse the content of the given {@link java.io.InputStream}
87     * instance as XML using the specified
88     * {@link org.xml.sax.helpers.DefaultHandler}.
89     *
90     * @param is InputStream containing the content to be parsed.
91     * @param dh The SAX DefaultHandler to use.
92     *
93     * @throws IllegalArgumentException If the given InputStream is null.
94     * @throws IOException If any IO errors occur.
95     * @throws SAXException If any SAX errors occur during processing.
96     *
97     * @see org.xml.sax.DocumentHandler
98     */
99    public void parse(InputStream is, DefaultHandler dh)
100        throws SAXException, IOException
101    {
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    {
127        if (uri == null) {
128            throw new IllegalArgumentException("uri cannot be null");
129        }
130
131        InputSource input = new InputSource(uri);
132        this.parse(input, dh);
133    }
134
135    /**
136     * Parse the content of the file specified as XML using the
137     * specified {@link org.xml.sax.helpers.DefaultHandler}.
138     *
139     * @param f The file containing the XML to parse
140     * @param dh The SAX DefaultHandler to use.
141     *
142     * @throws IllegalArgumentException If the File object is null.
143     * @throws IOException If any IO errors occur.
144     * @throws SAXException If any SAX errors occur during processing.
145     *
146     * @see org.xml.sax.DocumentHandler
147     */
148    public void parse(File f, DefaultHandler dh)
149        throws SAXException, IOException
150    {
151        if (f == null) {
152            throw new IllegalArgumentException("File cannot be null");
153        }
154
155        //convert file to appropriate URI, f.toURI().toASCIIString()
156        //converts the URI to string as per rule specified in
157        //RFC 2396,
158        InputSource input = new InputSource(f.toURI().toASCIIString());
159        this.parse(input, dh);
160    }
161
162    /**
163     * Parse the content given {@link org.xml.sax.InputSource}
164     * as XML using the specified
165     * {@link org.xml.sax.helpers.DefaultHandler}.
166     *
167     * @param is The InputSource containing the content to be parsed.
168     * @param dh The SAX DefaultHandler to use.
169     *
170     * @throws IllegalArgumentException If the <code>InputSource</code> object
171     *   is <code>null</code>.
172     * @throws IOException If any IO errors occur.
173     * @throws SAXException If any SAX errors occur during processing.
174     *
175     * @see org.xml.sax.DocumentHandler
176     */
177    public void parse(InputSource is, DefaultHandler dh)
178        throws SAXException, IOException
179    {
180        if (is == null) {
181            throw new IllegalArgumentException("InputSource cannot be null");
182        }
183
184        XMLReader reader = this.getXMLReader();
185        if (dh != null) {
186            reader.setContentHandler(dh);
187            reader.setEntityResolver(dh);
188            reader.setErrorHandler(dh);
189            reader.setDTDHandler(dh);
190        }
191        reader.parse(is);
192    }
193
194    /**
195     * Returns the {@link org.xml.sax.XMLReader} that is encapsulated by the
196     * implementation of this class.
197     *
198     * @return The XMLReader that is encapsulated by the
199     *         implementation of this class.
200     *
201     * @throws SAXException If any SAX errors occur during processing.
202     */
203    public abstract XMLReader getXMLReader() throws SAXException;
204
205    /**
206     * Indicates whether or not this parser is configured to
207     * understand namespaces.
208     *
209     * @return true if this parser is configured to
210     *         understand namespaces; false otherwise.
211     */
212    public abstract boolean isNamespaceAware();
213
214    /**
215     * Indicates whether or not this parser is configured to
216     * validate XML documents.
217     *
218     * @return true if this parser is configured to
219     *         validate XML documents; false otherwise.
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