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