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 }