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>"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 */ 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