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 }