1 /* 2 * Copyright (c) 2009, 2020, 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 javax.xml.stream; 27 import com.sun.xml.internal.stream.events.XMLEventFactoryImpl; 28 import java.util.Iterator; 29 import javax.xml.namespace.NamespaceContext; 30 import javax.xml.namespace.QName; 31 import javax.xml.stream.events.*; 32 /** 33 * This interface defines a utility class for creating instances of 34 * XMLEvents 35 * @version 1.2 36 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 37 * @see javax.xml.stream.events.StartElement 38 * @see javax.xml.stream.events.EndElement 39 * @see javax.xml.stream.events.ProcessingInstruction 40 * @see javax.xml.stream.events.Comment 41 * @see javax.xml.stream.events.Characters 42 * @see javax.xml.stream.events.StartDocument 43 * @see javax.xml.stream.events.EndDocument 44 * @see javax.xml.stream.events.DTD 45 * @since 1.6 46 */ 47 public abstract class XMLEventFactory { 48 static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory"; 49 static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl"; 50 51 /** 52 * Protected constructor to prevent instantiation. 53 * Use {@link #newFactory()} instead. 54 */ 55 protected XMLEventFactory(){} 56 57 /** 58 * Creates a new instance of the {@code XMLEventFactory} builtin 59 * system-default implementation. 60 * 61 * @return A new instance of the {@code XMLEventFactory} builtin 62 * system-default implementation. 63 * 64 * @since 9 65 */ 66 public static XMLEventFactory newDefaultFactory() { 67 return new XMLEventFactoryImpl(); 68 } 69 70 /** 71 * Creates a new instance of the factory in exactly the same manner as the 72 * {@link #newFactory()} method. 73 * 74 * @return an instance of the {@code XMLEventFactory} 75 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 76 */ 77 public static XMLEventFactory newInstance() 78 throws FactoryConfigurationError 79 { 80 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL); 81 } 82 83 /** 84 * Create a new instance of the factory. 85 * <p> 86 * This static method creates a new factory instance. 87 * This method uses the following ordered lookup procedure to determine 88 * the XMLEventFactory implementation class to load: 89 * <ul> 90 * <li> 91 * Use the javax.xml.stream.XMLEventFactory system property. 92 * </li> 93 * <li> 94 * <p> 95 * Use the configuration file "stax.properties". The file is in standard 96 * {@link java.util.Properties} format and typically located in the 97 * {@code conf} directory of the Java installation. It contains the fully qualified 98 * name of the implementation class with the key being the system property 99 * defined above. 100 * 101 * <p> 102 * The stax.properties file is read only once by the implementation 103 * and its values are then cached for future use. If the file does not exist 104 * when the first attempt is made to read from it, no further attempts are 105 * made to check for its existence. It is not possible to change the value 106 * of any property in stax.properties after it has been read for the first time. 107 * 108 * <p> 109 * Use the jaxp configuration file "jaxp.properties". The file is in the same 110 * format as stax.properties and will only be read if stax.properties does 111 * not exist. 112 * </li> 113 * <li> 114 * <p> 115 * Use the service-provider loading facility, defined by the 116 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 117 * implementation of the service using the {@linkplain 118 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}: 119 * the service-provider loading facility will use the {@linkplain 120 * java.lang.Thread#getContextClassLoader() current thread's context class loader} 121 * to attempt to load the service. If the context class 122 * loader is null, the {@linkplain 123 * ClassLoader#getSystemClassLoader() system class loader} will be used. 124 * </li> 125 * <li> 126 * <p> 127 * Otherwise, the {@linkplain #newDefaultFactory() system-default} 128 * implementation is returned. 129 * </li> 130 * </ul> 131 * <p> 132 * Once an application has obtained a reference to a XMLEventFactory it 133 * can use the factory to configure and obtain stream instances. 134 * 135 * @return an instance of the {@code XMLEventFactory} 136 * @throws FactoryConfigurationError in case of {@linkplain 137 * java.util.ServiceConfigurationError service configuration error} or if 138 * the implementation is not available or cannot be instantiated. 139 */ 140 public static XMLEventFactory newFactory() 141 throws FactoryConfigurationError 142 { 143 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL); 144 } 145 146 /** 147 * Create a new instance of the factory 148 * 149 * @param factoryId Name of the factory to find, same as 150 * a property name 151 * @param classLoader classLoader to use 152 * @return the factory implementation 153 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 154 * 155 * @deprecated This method has been deprecated to maintain API consistency. 156 * All newInstance methods have been replaced with corresponding 157 * newFactory methods. The replacement {@link 158 * #newFactory(java.lang.String, java.lang.ClassLoader)} 159 * method defines no changes in behavior. 160 */ 161 @Deprecated(since="1.7") 162 public static XMLEventFactory newInstance(String factoryId, 163 ClassLoader classLoader) 164 throws FactoryConfigurationError { 165 //do not fallback if given classloader can't find the class, throw exception 166 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null); 167 } 168 169 /** 170 * Create a new instance of the factory. 171 * If the classLoader argument is null, then the ContextClassLoader is used. 172 * <p> 173 * This method uses the following ordered lookup procedure to determine 174 * the XMLEventFactory implementation class to load: 175 * <ul> 176 * <li> 177 * Use the value of the system property identified by {@code factoryId}. 178 * </li> 179 * <li> 180 * <p> 181 * Use the configuration file "stax.properties". The file is in standard 182 * {@link java.util.Properties} format and typically located in the 183 * conf directory of the Java installation. It contains the fully qualified 184 * name of the implementation class with the key being the system property 185 * defined above. 186 * 187 * <p> 188 * The stax.properties file is read only once by the implementation 189 * and its values are then cached for future use. If the file does not exist 190 * when the first attempt is made to read from it, no further attempts are 191 * made to check for its existence. It is not possible to change the value 192 * of any property in stax.properties after it has been read for the first time. 193 * 194 * <p> 195 * Use the jaxp configuration file "jaxp.properties". The file is in the same 196 * format as stax.properties and will only be read if stax.properties does 197 * not exist. 198 * </li> 199 * <li> 200 * <p> 201 * If {@code factoryId} is "javax.xml.stream.XMLEventFactory", 202 * use the service-provider loading facility, defined by the 203 * {@link java.util.ServiceLoader} class, to attempt to {@linkplain 204 * java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load} 205 * an implementation of the service using the specified {@code ClassLoader}. 206 * If {@code classLoader} is null, the {@linkplain 207 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply: 208 * That is, the service-provider loading facility will use the {@linkplain 209 * java.lang.Thread#getContextClassLoader() current thread's context class loader} 210 * to attempt to load the service. If the context class 211 * loader is null, the {@linkplain 212 * ClassLoader#getSystemClassLoader() system class loader} will be used. 213 * </li> 214 * <li> 215 * <p> 216 * Otherwise, throws a {@link FactoryConfigurationError}. 217 * </li> 218 * </ul> 219 * 220 * <p> 221 * Note that this is a new method that replaces the deprecated 222 * {@link #newInstance(java.lang.String, java.lang.ClassLoader) 223 * newInstance(String factoryId, ClassLoader classLoader)} method. 224 * No changes in behavior are defined by this replacement method relative 225 * to the deprecated method. 226 * 227 * @apiNote The parameter factoryId defined here is inconsistent with that 228 * of other JAXP factories where the first parameter is fully qualified 229 * factory class name that provides implementation of the factory. 230 * 231 * @param factoryId Name of the factory to find, same as 232 * a property name 233 * @param classLoader classLoader to use 234 * @return the factory implementation 235 * @throws FactoryConfigurationError in case of {@linkplain 236 * java.util.ServiceConfigurationError service configuration error} or if 237 * the implementation is not available or cannot be instantiated. 238 */ 239 public static XMLEventFactory newFactory(String factoryId, 240 ClassLoader classLoader) 241 throws FactoryConfigurationError { 242 //do not fallback if given classloader can't find the class, throw exception 243 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null); 244 } 245 246 /** 247 * This method allows setting of the Location on each event that 248 * is created by this factory. The values are copied by value into 249 * the events created by this factory. To reset the location 250 * information set the location to null. 251 * @param location the location to set on each event created 252 */ 253 public abstract void setLocation(Location location); 254 255 /** 256 * Create a new Attribute 257 * @param prefix the prefix of this attribute, may not be null 258 * @param namespaceURI the attribute value is set to this value, may not be null 259 * @param localName the local name of the XML name of the attribute, localName cannot be null 260 * @param value the attribute value to set, may not be null 261 * @return the Attribute with specified values 262 */ 263 public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value); 264 265 /** 266 * Create a new Attribute 267 * @param localName the local name of the XML name of the attribute, localName cannot be null 268 * @param value the attribute value to set, may not be null 269 * @return the Attribute with specified values 270 */ 271 public abstract Attribute createAttribute(String localName, String value); 272 273 /** 274 * Create a new Attribute 275 * @param name the qualified name of the attribute, may not be null 276 * @param value the attribute value to set, may not be null 277 * @return the Attribute with specified values 278 */ 279 public abstract Attribute createAttribute(QName name, String value); 280 281 /** 282 * Create a new default Namespace 283 * @param namespaceURI the default namespace uri 284 * @return the Namespace with the specified value 285 */ 286 public abstract Namespace createNamespace(String namespaceURI); 287 288 /** 289 * Create a new Namespace 290 * @param prefix the prefix of this namespace, may not be null 291 * @param namespaceUri the attribute value is set to this value, may not be null 292 * @return the Namespace with the specified values 293 */ 294 public abstract Namespace createNamespace(String prefix, String namespaceUri); 295 296 /** 297 * Create a new StartElement. Namespaces can be added to this StartElement 298 * by passing in an Iterator that walks over a set of Namespace interfaces. 299 * Attributes can be added to this StartElement by passing an iterator 300 * that walks over a set of Attribute interfaces. 301 * 302 * @param name the qualified name of the attribute, may not be null 303 * @param attributes an optional unordered set of objects that 304 * implement Attribute to add to the new StartElement, may be null 305 * @param namespaces an optional unordered set of objects that 306 * implement Namespace to add to the new StartElement, may be null 307 * @return an instance of the requested StartElement 308 */ 309 public abstract StartElement createStartElement(QName name, 310 Iterator<? extends Attribute> attributes, 311 Iterator<? extends Namespace> namespaces); 312 313 /** 314 * Create a new StartElement. This defaults the NamespaceContext to 315 * an empty NamespaceContext. Querying this event for its namespaces or 316 * attributes will result in an empty iterator being returned. 317 * 318 * @param namespaceUri the uri of the QName of the new StartElement 319 * @param localName the local name of the QName of the new StartElement 320 * @param prefix the prefix of the QName of the new StartElement 321 * @return an instance of the requested StartElement 322 */ 323 public abstract StartElement createStartElement(String prefix, 324 String namespaceUri, 325 String localName); 326 /** 327 * Create a new StartElement. Namespaces can be added to this StartElement 328 * by passing in an Iterator that walks over a set of Namespace interfaces. 329 * Attributes can be added to this StartElement by passing an iterator 330 * that walks over a set of Attribute interfaces. 331 * 332 * @param namespaceUri the uri of the QName of the new StartElement 333 * @param localName the local name of the QName of the new StartElement 334 * @param prefix the prefix of the QName of the new StartElement 335 * @param attributes an unordered set of objects that implement 336 * Attribute to add to the new StartElement 337 * @param namespaces an unordered set of objects that implement 338 * Namespace to add to the new StartElement 339 * @return an instance of the requested StartElement 340 */ 341 public abstract StartElement createStartElement(String prefix, 342 String namespaceUri, 343 String localName, 344 Iterator<? extends Attribute> attributes, 345 Iterator<? extends Namespace> namespaces 346 ); 347 /** 348 * Create a new StartElement. Namespaces can be added to this StartElement 349 * by passing in an Iterator that walks over a set of Namespace interfaces. 350 * Attributes can be added to this StartElement by passing an iterator 351 * that walks over a set of Attribute interfaces. 352 * 353 * @param namespaceUri the uri of the QName of the new StartElement 354 * @param localName the local name of the QName of the new StartElement 355 * @param prefix the prefix of the QName of the new StartElement 356 * @param attributes an unordered set of objects that implement 357 * Attribute to add to the new StartElement, may be null 358 * @param namespaces an unordered set of objects that implement 359 * Namespace to add to the new StartElement, may be null 360 * @param context the namespace context of this element 361 * @return an instance of the requested StartElement 362 */ 363 public abstract StartElement createStartElement(String prefix, 364 String namespaceUri, 365 String localName, 366 Iterator<? extends Attribute> attributes, 367 Iterator<? extends Namespace> namespaces, 368 NamespaceContext context 369 ); 370 371 /** 372 * Create a new EndElement 373 * @param name the qualified name of the EndElement 374 * @param namespaces an optional unordered set of objects that 375 * implement Namespace that have gone out of scope, may be null 376 * @return an instance of the requested EndElement 377 */ 378 public abstract EndElement createEndElement(QName name, 379 Iterator<? extends Namespace> namespaces); 380 381 /** 382 * Create a new EndElement 383 * @param namespaceUri the uri of the QName of the new StartElement 384 * @param localName the local name of the QName of the new StartElement 385 * @param prefix the prefix of the QName of the new StartElement 386 * @return an instance of the requested EndElement 387 */ 388 public abstract EndElement createEndElement(String prefix, 389 String namespaceUri, 390 String localName); 391 /** 392 * Create a new EndElement 393 * @param namespaceUri the uri of the QName of the new StartElement 394 * @param localName the local name of the QName of the new StartElement 395 * @param prefix the prefix of the QName of the new StartElement 396 * @param namespaces an unordered set of objects that implement 397 * Namespace that have gone out of scope, may be null 398 * @return an instance of the requested EndElement 399 */ 400 public abstract EndElement createEndElement(String prefix, 401 String namespaceUri, 402 String localName, 403 Iterator<? extends Namespace> namespaces); 404 405 /** 406 * Create a Characters event, this method does not check if the content 407 * is all whitespace. To create a space event use #createSpace(String) 408 * @param content the string to create 409 * @return a Characters event 410 */ 411 public abstract Characters createCharacters(String content); 412 413 /** 414 * Create a Characters event with the CData flag set to true 415 * @param content the string to create 416 * @return a Characters event 417 */ 418 public abstract Characters createCData(String content); 419 420 /** 421 * Create a Characters event with the isSpace flag set to true 422 * @param content the content of the space to create 423 * @return a Characters event 424 */ 425 public abstract Characters createSpace(String content); 426 /** 427 * Create an ignorable space 428 * @param content the space to create 429 * @return a Characters event 430 */ 431 public abstract Characters createIgnorableSpace(String content); 432 433 /** 434 * Creates a new instance of a StartDocument event 435 * @return a StartDocument event 436 */ 437 public abstract StartDocument createStartDocument(); 438 439 /** 440 * Creates a new instance of a StartDocument event 441 * 442 * @param encoding the encoding style 443 * @param version the XML version 444 * @param standalone the status of standalone may be set to "true" or "false" 445 * @return a StartDocument event 446 */ 447 public abstract StartDocument createStartDocument(String encoding, 448 String version, 449 boolean standalone); 450 451 /** 452 * Creates a new instance of a StartDocument event 453 * 454 * @param encoding the encoding style 455 * @param version the XML version 456 * @return a StartDocument event 457 */ 458 public abstract StartDocument createStartDocument(String encoding, 459 String version); 460 461 /** 462 * Creates a new instance of a StartDocument event 463 * 464 * @param encoding the encoding style 465 * @return a StartDocument event 466 */ 467 public abstract StartDocument createStartDocument(String encoding); 468 469 /** 470 * Creates a new instance of an EndDocument event 471 * @return an EndDocument event 472 */ 473 public abstract EndDocument createEndDocument(); 474 475 /** Creates a new instance of a EntityReference event 476 * 477 * @param name The name of the reference 478 * @param declaration the declaration for the event 479 * @return an EntityReference event 480 */ 481 public abstract EntityReference createEntityReference(String name, 482 EntityDeclaration declaration); 483 /** 484 * Create a comment. 485 * @param text The text of the comment 486 * @return a Comment event 487 */ 488 public abstract Comment createComment(String text); 489 490 /** 491 * Create a processing instruction 492 * @param target The target of the processing instruction 493 * @param data The text of the processing instruction 494 * @return a ProcessingInstruction event 495 */ 496 public abstract ProcessingInstruction createProcessingInstruction(String target, 497 String data); 498 499 /** 500 * Create a document type definition event 501 * This string contains the entire document type declaration that matches 502 * the doctypedecl in the XML 1.0 specification 503 * @param dtd the text of the document type definition 504 * @return a DTD event 505 */ 506 public abstract DTD createDTD(String dtd); 507 }