1 /* 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 3 * 4 * This code is free software; you can redistribute it and/or modify it 5 * under the terms of the GNU General Public License version 2 only, as 6 * published by the Free Software Foundation. Oracle designates this 7 * particular file as subject to the "Classpath" exception as provided 8 * by Oracle in the LICENSE file that accompanied this code. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /* 26 * Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 27 */ 28 29 package javax.xml.stream; 30 import javax.xml.stream.events.*; 31 import javax.xml.namespace.NamespaceContext; 32 import javax.xml.namespace.QName; 33 import java.util.Iterator; 34 /** 35 * This interface defines a utility class for creating instances of 36 * XMLEvents 37 * @version 1.2 38 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 39 * @see javax.xml.stream.events.StartElement 40 * @see javax.xml.stream.events.EndElement 41 * @see javax.xml.stream.events.ProcessingInstruction 42 * @see javax.xml.stream.events.Comment 43 * @see javax.xml.stream.events.Characters 44 * @see javax.xml.stream.events.StartDocument 45 * @see javax.xml.stream.events.EndDocument 46 * @see javax.xml.stream.events.DTD 47 * @since 1.6 48 */ 49 public abstract class XMLEventFactory { 50 protected XMLEventFactory(){} 51 52 static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory"; 53 static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl"; 54 55 56 /** 57 * Create a new instance of the factory 58 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 59 */ 60 public static XMLEventFactory newInstance() 61 throws FactoryConfigurationError 62 { 63 return (XMLEventFactory) FactoryFinder.find( 64 JAXPFACTORYID, 65 DEFAULIMPL); 66 } 67 68 /** 69 * Create a new instance of the factory. 70 * This static method creates a new factory instance. 71 * This method uses the following ordered lookup procedure to determine 72 * the XMLEventFactory implementation class to load: 73 * Use the javax.xml.stream.XMLEventFactory system property. 74 * Use the properties file "lib/stax.properties" in the JRE directory. 75 * This configuration file is in standard java.util.Properties format 76 * and contains the fully qualified name of the implementation class 77 * with the key being the system property defined above. 78 * Use the Services API (as detailed in the JAR specification), if available, 79 * to determine the classname. The Services API will look for a classname 80 * in the file META-INF/services/javax.xml.stream.XMLEventFactory in jars 81 * available to the runtime. 82 * Platform default XMLEventFactory instance. 83 * 84 * Once an application has obtained a reference to a XMLEventFactory it 85 * can use the factory to configure and obtain stream instances. 86 * 87 * Note that this is a new method that replaces the deprecated newInstance() method. 88 * No changes in behavior are defined by this replacement method relative to 89 * the deprecated method. 90 * 91 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 92 */ 93 public static XMLEventFactory newFactory() 94 throws FactoryConfigurationError 95 { 96 return (XMLEventFactory) FactoryFinder.find( 97 JAXPFACTORYID, 98 DEFAULIMPL); 99 } 100 101 /** 102 * Create a new instance of the factory 103 * 104 * @param factoryId Name of the factory to find, same as 105 * a property name 106 * @param classLoader classLoader to use 107 * @return the factory implementation 108 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 109 * 110 * @deprecated This method has been deprecated to maintain API consistency. 111 * All newInstance methods have been replaced with corresponding 112 * newFactory methods. The replacement {@link 113 * #newFactory(java.lang.String, java.lang.ClassLoader)} 114 * method defines no changes in behavior. 115 */ 116 public static XMLEventFactory newInstance(String factoryId, 117 ClassLoader classLoader) 118 throws FactoryConfigurationError { 119 try { 120 //do not fallback if given classloader can't find the class, throw exception 121 return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null); 122 } catch (FactoryFinder.ConfigurationError e) { 123 throw new FactoryConfigurationError(e.getException(), 124 e.getMessage()); 125 } 126 } 127 128 /** 129 * Create a new instance of the factory. 130 * If the classLoader argument is null, then the ContextClassLoader is used. 131 * 132 * Note that this is a new method that replaces the deprecated 133 * newInstance(String factoryId, ClassLoader classLoader) method. 134 * No changes in behavior are defined by this replacement method relative 135 * to the deprecated method. 136 * 137 * @param factoryId Name of the factory to find, same as 138 * a property name 139 * @param classLoader classLoader to use 140 * @return the factory implementation 141 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 142 */ 143 public static XMLEventFactory newFactory(String factoryId, 144 ClassLoader classLoader) 145 throws FactoryConfigurationError { 146 try { 147 //do not fallback if given classloader can't find the class, throw exception 148 return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null); 149 } catch (FactoryFinder.ConfigurationError e) { 150 throw new FactoryConfigurationError(e.getException(), 151 e.getMessage()); 152 } 153 } 154 155 /** 156 * This method allows setting of the Location on each event that 157 * is created by this factory. The values are copied by value into 158 * the events created by this factory. To reset the location 159 * information set the location to null. 160 * @param location the location to set on each event created 161 */ 162 public abstract void setLocation(Location location); 163 164 /** 165 * Create a new Attribute 166 * @param prefix the prefix of this attribute, may not be null 167 * @param namespaceURI the attribute value is set to this value, may not be null 168 * @param localName the local name of the XML name of the attribute, localName cannot be null 169 * @param value the attribute value to set, may not be null 170 * @return the Attribute with specified values 171 */ 172 public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value); 173 174 /** 175 * Create a new Attribute 176 * @param localName the local name of the XML name of the attribute, localName cannot be null 177 * @param value the attribute value to set, may not be null 178 * @return the Attribute with specified values 179 */ 180 public abstract Attribute createAttribute(String localName, String value); 181 182 /** 183 * Create a new Attribute 184 * @param name the qualified name of the attribute, may not be null 185 * @param value the attribute value to set, may not be null 186 * @return the Attribute with specified values 187 */ 188 public abstract Attribute createAttribute(QName name, String value); 189 190 /** 191 * Create a new default Namespace 192 * @param namespaceURI the default namespace uri 193 * @return the Namespace with the specified value 194 */ 195 public abstract Namespace createNamespace(String namespaceURI); 196 197 /** 198 * Create a new Namespace 199 * @param prefix the prefix of this namespace, may not be null 200 * @param namespaceUri the attribute value is set to this value, may not be null 201 * @return the Namespace with the specified values 202 */ 203 public abstract Namespace createNamespace(String prefix, String namespaceUri); 204 205 /** 206 * Create a new StartElement. Namespaces can be added to this StartElement 207 * by passing in an Iterator that walks over a set of Namespace interfaces. 208 * Attributes can be added to this StartElement by passing an iterator 209 * that walks over a set of Attribute interfaces. 210 * 211 * @param name the qualified name of the attribute, may not be null 212 * @param attributes an optional unordered set of objects that 213 * implement Attribute to add to the new StartElement, may be null 214 * @param namespaces an optional unordered set of objects that 215 * implement Namespace to add to the new StartElement, may be null 216 * @return an instance of the requested StartElement 217 */ 218 public abstract StartElement createStartElement(QName name, 219 Iterator attributes, 220 Iterator namespaces); 221 222 /** 223 * Create a new StartElement. This defaults the NamespaceContext to 224 * an empty NamespaceContext. Querying this event for its namespaces or 225 * attributes will result in an empty iterator being returned. 226 * 227 * @param namespaceUri the uri of the QName of the new StartElement 228 * @param localName the local name of the QName of the new StartElement 229 * @param prefix the prefix of the QName of the new StartElement 230 * @return an instance of the requested StartElement 231 */ 232 public abstract StartElement createStartElement(String prefix, 233 String namespaceUri, 234 String localName); 235 /** 236 * Create a new StartElement. Namespaces can be added to this StartElement 237 * by passing in an Iterator that walks over a set of Namespace interfaces. 238 * Attributes can be added to this StartElement by passing an iterator 239 * that walks over a set of Attribute interfaces. 240 * 241 * @param namespaceUri the uri of the QName of the new StartElement 242 * @param localName the local name of the QName of the new StartElement 243 * @param prefix the prefix of the QName of the new StartElement 244 * @param attributes an unordered set of objects that implement 245 * Attribute to add to the new StartElement 246 * @param namespaces an unordered set of objects that implement 247 * Namespace to add to the new StartElement 248 * @return an instance of the requested StartElement 249 */ 250 public abstract StartElement createStartElement(String prefix, 251 String namespaceUri, 252 String localName, 253 Iterator attributes, 254 Iterator namespaces 255 ); 256 /** 257 * Create a new StartElement. Namespaces can be added to this StartElement 258 * by passing in an Iterator that walks over a set of Namespace interfaces. 259 * Attributes can be added to this StartElement by passing an iterator 260 * that walks over a set of Attribute interfaces. 261 * 262 * @param namespaceUri the uri of the QName of the new StartElement 263 * @param localName the local name of the QName of the new StartElement 264 * @param prefix the prefix of the QName of the new StartElement 265 * @param attributes an unordered set of objects that implement 266 * Attribute to add to the new StartElement, may be null 267 * @param namespaces an unordered set of objects that implement 268 * Namespace to add to the new StartElement, may be null 269 * @param context the namespace context of this element 270 * @return an instance of the requested StartElement 271 */ 272 public abstract StartElement createStartElement(String prefix, 273 String namespaceUri, 274 String localName, 275 Iterator attributes, 276 Iterator namespaces, 277 NamespaceContext context 278 ); 279 280 /** 281 * Create a new EndElement 282 * @param name the qualified name of the EndElement 283 * @param namespaces an optional unordered set of objects that 284 * implement Namespace that have gone out of scope, may be null 285 * @return an instance of the requested EndElement 286 */ 287 public abstract EndElement createEndElement(QName name, 288 Iterator namespaces); 289 290 /** 291 * Create a new EndElement 292 * @param namespaceUri the uri of the QName of the new StartElement 293 * @param localName the local name of the QName of the new StartElement 294 * @param prefix the prefix of the QName of the new StartElement 295 * @return an instance of the requested EndElement 296 */ 297 public abstract EndElement createEndElement(String prefix, 298 String namespaceUri, 299 String localName); 300 /** 301 * Create a new EndElement 302 * @param namespaceUri the uri of the QName of the new StartElement 303 * @param localName the local name of the QName of the new StartElement 304 * @param prefix the prefix of the QName of the new StartElement 305 * @param namespaces an unordered set of objects that implement 306 * Namespace that have gone out of scope, may be null 307 * @return an instance of the requested EndElement 308 */ 309 public abstract EndElement createEndElement(String prefix, 310 String namespaceUri, 311 String localName, 312 Iterator namespaces); 313 314 /** 315 * Create a Characters event, this method does not check if the content 316 * is all whitespace. To create a space event use #createSpace(String) 317 * @param content the string to create 318 * @return a Characters event 319 */ 320 public abstract Characters createCharacters(String content); 321 322 /** 323 * Create a Characters event with the CData flag set to true 324 * @param content the string to create 325 * @return a Characters event 326 */ 327 public abstract Characters createCData(String content); 328 329 /** 330 * Create a Characters event with the isSpace flag set to true 331 * @param content the content of the space to create 332 * @return a Characters event 333 */ 334 public abstract Characters createSpace(String content); 335 /** 336 * Create an ignorable space 337 * @param content the space to create 338 * @return a Characters event 339 */ 340 public abstract Characters createIgnorableSpace(String content); 341 342 /** 343 * Creates a new instance of a StartDocument event 344 * @return a StartDocument event 345 */ 346 public abstract StartDocument createStartDocument(); 347 348 /** 349 * Creates a new instance of a StartDocument event 350 * 351 * @param encoding the encoding style 352 * @param version the XML version 353 * @param standalone the status of standalone may be set to "true" or "false" 354 * @return a StartDocument event 355 */ 356 public abstract StartDocument createStartDocument(String encoding, 357 String version, 358 boolean standalone); 359 360 /** 361 * Creates a new instance of a StartDocument event 362 * 363 * @param encoding the encoding style 364 * @param version the XML version 365 * @return a StartDocument event 366 */ 367 public abstract StartDocument createStartDocument(String encoding, 368 String version); 369 370 /** 371 * Creates a new instance of a StartDocument event 372 * 373 * @param encoding the encoding style 374 * @return a StartDocument event 375 */ 376 public abstract StartDocument createStartDocument(String encoding); 377 378 /** 379 * Creates a new instance of an EndDocument event 380 * @return an EndDocument event 381 */ 382 public abstract EndDocument createEndDocument(); 383 384 /** Creates a new instance of a EntityReference event 385 * 386 * @param name The name of the reference 387 * @param declaration the declaration for the event 388 * @return an EntityReference event 389 */ 390 public abstract EntityReference createEntityReference(String name, 391 EntityDeclaration declaration); 392 /** 393 * Create a comment 394 * @param text The text of the comment 395 * a Comment event 396 */ 397 public abstract Comment createComment(String text); 398 399 /** 400 * Create a processing instruction 401 * @param target The target of the processing instruction 402 * @param data The text of the processing instruction 403 * @return a ProcessingInstruction event 404 */ 405 public abstract ProcessingInstruction createProcessingInstruction(String target, 406 String data); 407 408 /** 409 * Create a document type definition event 410 * This string contains the entire document type declaration that matches 411 * the doctypedecl in the XML 1.0 specification 412 * @param dtd the text of the document type definition 413 * @return a DTD event 414 */ 415 public abstract DTD createDTD(String dtd); 416 }