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, 2013, by Oracle Corporation. All Rights Reserved.

    27  */

    28 

    29 package javax.xml.stream;

    30 import java.util.Iterator;

    31 import javax.xml.namespace.NamespaceContext;

    32 import javax.xml.namespace.QName;

    33 import javax.xml.stream.events.*;

    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    * Creates a new instance of the factory in exactly the same manner as the

    58    * {@link #newFactory()} method.

    59    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded

    60    */

    61   public static XMLEventFactory newInstance()

    62     throws FactoryConfigurationError

    63   {

    64     return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);

    65   }

    66 

    67   /**

    68    * Create a new instance of the factory.

    69    * <p>

    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    * </p>

    74    * <ul>

    75    * <li>

    76    *   Use the javax.xml.stream.XMLEventFactory system property.

    77    * </li>

    78    * <li>

    79    *   Use the properties file "lib/stax.properties" in the JRE directory.

    80    *     This configuration file is in standard java.util.Properties format

    81    *     and contains the fully qualified name of the implementation class

    82    *     with the key being the system property defined above.

    83    * </li>

    84    * <li>

    85    *   Use the service-provider loading facilities, defined by the

    86    *   {@link java.util.ServiceLoader} class, to attempt to locate and load an

    87    *   implementation of the service using the {@linkplain

    88    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:

    89    *   the service-provider loading facility will use the {@linkplain

    90    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}

    91    *   to attempt to load the service. If the context class

    92    *   loader is null, the {@linkplain

    93    *   ClassLoader#getSystemClassLoader() system class loader} will be used.

    94    * </li>

    95    * <li>

    96    *   Otherwise, the system-default implementation is returned.

    97    * </li>

    98    * </ul>

    99    * <p>

   100    *   Once an application has obtained a reference to a XMLEventFactory it

   101    *   can use the factory to configure and obtain stream instances.

   102    * </p>

   103    * <p>

   104    *   Note that this is a new method that replaces the deprecated newInstance() method.

   105    *     No changes in behavior are defined by this replacement method relative to

   106    *     the deprecated method.

   107    * </p>

   108    * @throws FactoryConfigurationError in case of {@linkplain

   109    *   java.util.ServiceConfigurationError service configuration error} or if

   110    *   the implementation is not available or cannot be instantiated.

   111    */

   112   public static XMLEventFactory newFactory()

   113     throws FactoryConfigurationError

   114   {

   115     return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);

   116   }

   117 

   118   /**

   119    * Create a new instance of the factory

   120    *

   121    * @param factoryId             Name of the factory to find, same as

   122    *                              a property name

   123    * @param classLoader           classLoader to use

   124    * @return the factory implementation

   125    * @throws FactoryConfigurationError if an instance of this factory cannot be loaded

   126    *

   127    * @deprecated  This method has been deprecated to maintain API consistency.

   128    *              All newInstance methods have been replaced with corresponding

   129    *              newFactory methods. The replacement {@link

   130    *              #newFactory(java.lang.String, java.lang.ClassLoader)}

   131    *              method defines no changes in behavior.

   132    */

   133   public static XMLEventFactory newInstance(String factoryId,

   134           ClassLoader classLoader)

   135           throws FactoryConfigurationError {

   136       //do not fallback if given classloader can't find the class, throw exception

   137       return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);

   138   }

   139 

   140   /**

   141    * Create a new instance of the factory.

   142    * If the classLoader argument is null, then the ContextClassLoader is used.

   143    * <p>

   144    * This method uses the following ordered lookup procedure to determine

   145    * the XMLEventFactory implementation class to load:

   146    * </p>

   147    * <ul>

   148    * <li>

   149    *   Use the value of the system property identified by {@code factoryId}.

   150    * </li>

   151    * <li>

   152    *   Use the properties file "lib/stax.properties" in the JRE directory.

   153    *     This configuration file is in standard java.util.Properties format

   154    *     and contains the fully qualified name of the implementation class

   155    *     with the key being the given {@code factoryId}.

   156    * </li>

   157    * <li>

   158    *   If {@code factoryId} is "javax.xml.stream.XMLEventFactory",

   159    *   use the service-provider loading facilities, defined by the

   160    *   {@link java.util.ServiceLoader} class, to attempt to {@linkplain

   161    *   java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}

   162    *   an implementation of the service using the specified {@code ClassLoader}.

   163    *   If {@code classLoader} is null, the {@linkplain

   164    *   java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:

   165    *   That is, the service-provider loading facility will use the {@linkplain

   166    *   java.lang.Thread#getContextClassLoader() current thread's context class loader}

   167    *   to attempt to load the service. If the context class

   168    *   loader is null, the {@linkplain

   169    *   ClassLoader#getSystemClassLoader() system class loader} will be used.

   170    * </li>

   171    * <li>

   172    *   Otherwise, throws a {@link FactoryConfigurationError}.

   173    * </li>

   174    * </ul>

   175    *

   176    * <p>

   177    * Note that this is a new method that replaces the deprecated

   178    *   {@link #newInstance(java.lang.String, java.lang.ClassLoader)

   179    *   newInstance(String factoryId, ClassLoader classLoader)} method.

   180    * No changes in behavior are defined by this replacement method relative

   181    * to the deprecated method.

   182    * </p>

   183    *

   184    * @apiNote The parameter factoryId defined here is inconsistent with that

   185    * of other JAXP factories where the first parameter is fully qualified

   186    * factory class name that provides implementation of the factory.

   187    *

   188    * @param factoryId             Name of the factory to find, same as

   189    *                              a property name

   190    * @param classLoader           classLoader to use

   191    * @return the factory implementation

   192    * @throws FactoryConfigurationError in case of {@linkplain

   193    *   java.util.ServiceConfigurationError service configuration error} or if

   194    *   the implementation is not available or cannot be instantiated.

   195    */

   196   public static XMLEventFactory newFactory(String factoryId,

   197                                            ClassLoader classLoader)

   198           throws FactoryConfigurationError {

   199       //do not fallback if given classloader can't find the class, throw exception

   200       return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);

   201   }

   202 

   203  /**

   204    * This method allows setting of the Location on each event that

   205    * is created by this factory.  The values are copied by value into

   206    * the events created by this factory.  To reset the location

   207    * information set the location to null.

   208    * @param location the location to set on each event created

   209    */

   210   public abstract void setLocation(Location location);

   211 

   212   /**

   213    * Create a new Attribute

   214    * @param prefix the prefix of this attribute, may not be null

   215    * @param namespaceURI the attribute value is set to this value, may not be null

   216    * @param localName the local name of the XML name of the attribute, localName cannot be null

   217    * @param value the attribute value to set, may not be null

   218    * @return the Attribute with specified values

   219    */

   220   public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value);

   221 

   222   /**

   223    * Create a new Attribute

   224    * @param localName the local name of the XML name of the attribute, localName cannot be null

   225    * @param value the attribute value to set, may not be null

   226    * @return the Attribute with specified values

   227    */

   228   public abstract Attribute createAttribute(String localName, String value);

   229 

   230   /**

   231    * Create a new Attribute

   232    * @param name the qualified name of the attribute, may not be null

   233    * @param value the attribute value to set, may not be null

   234    * @return the Attribute with specified values

   235    */

   236   public abstract Attribute createAttribute(QName name, String value);

   237 

   238   /**

   239    * Create a new default Namespace

   240    * @param namespaceURI the default namespace uri

   241    * @return the Namespace with the specified value

   242    */

   243   public abstract Namespace createNamespace(String namespaceURI);

   244 

   245   /**

   246    * Create a new Namespace

   247    * @param prefix the prefix of this namespace, may not be null

   248    * @param namespaceUri the attribute value is set to this value, may not be null

   249    * @return the Namespace with the specified values

   250    */

   251   public abstract Namespace createNamespace(String prefix, String namespaceUri);

   252 

   253   /**

   254    * Create a new StartElement.  Namespaces can be added to this StartElement

   255    * by passing in an Iterator that walks over a set of Namespace interfaces.

   256    * Attributes can be added to this StartElement by passing an iterator

   257    * that walks over a set of Attribute interfaces.

   258    *

   259    * @param name the qualified name of the attribute, may not be null

   260    * @param attributes an optional unordered set of objects that

   261    * implement Attribute to add to the new StartElement, may be null

   262    * @param namespaces an optional unordered set of objects that

   263    * implement Namespace to add to the new StartElement, may be null

   264    * @return an instance of the requested StartElement

   265    */

   266   public abstract StartElement createStartElement(QName name,

   267                                                   Iterator attributes,

   268                                                   Iterator namespaces);

   269 

   270   /**

   271    * Create a new StartElement.  This defaults the NamespaceContext to

   272    * an empty NamespaceContext.  Querying this event for its namespaces or

   273    * attributes will result in an empty iterator being returned.

   274    *

   275    * @param namespaceUri the uri of the QName of the new StartElement

   276    * @param localName the local name of the QName of the new StartElement

   277    * @param prefix the prefix of the QName of the new StartElement

   278    * @return an instance of the requested StartElement

   279    */

   280   public abstract StartElement createStartElement(String prefix,

   281                                                   String namespaceUri,

   282                                                   String localName);

   283   /**

   284    * Create a new StartElement.  Namespaces can be added to this StartElement

   285    * by passing in an Iterator that walks over a set of Namespace interfaces.

   286    * Attributes can be added to this StartElement by passing an iterator

   287    * that walks over a set of Attribute interfaces.

   288    *

   289    * @param namespaceUri the uri of the QName of the new StartElement

   290    * @param localName the local name of the QName of the new StartElement

   291    * @param prefix the prefix of the QName of the new StartElement

   292    * @param attributes an unordered set of objects that implement

   293    * Attribute to add to the new StartElement

   294    * @param namespaces an unordered set of objects that implement

   295    * Namespace to add to the new StartElement

   296    * @return an instance of the requested StartElement

   297    */

   298   public abstract StartElement createStartElement(String prefix,

   299                                                   String namespaceUri,

   300                                                   String localName,

   301                                                   Iterator attributes,

   302                                                   Iterator namespaces

   303                                                   );

   304   /**

   305    * Create a new StartElement.  Namespaces can be added to this StartElement

   306    * by passing in an Iterator that walks over a set of Namespace interfaces.

   307    * Attributes can be added to this StartElement by passing an iterator

   308    * that walks over a set of Attribute interfaces.

   309    *

   310    * @param namespaceUri the uri of the QName of the new StartElement

   311    * @param localName the local name of the QName of the new StartElement

   312    * @param prefix the prefix of the QName of the new StartElement

   313    * @param attributes an unordered set of objects that implement

   314    * Attribute to add to the new StartElement, may be null

   315    * @param namespaces an unordered set of objects that implement

   316    * Namespace to add to the new StartElement, may be null

   317    * @param context the namespace context of this element

   318    * @return an instance of the requested StartElement

   319    */

   320   public abstract StartElement createStartElement(String prefix,

   321                                                   String namespaceUri,

   322                                                   String localName,

   323                                                   Iterator attributes,

   324                                                   Iterator namespaces,

   325                                                   NamespaceContext context

   326                                                   );

   327 

   328   /**

   329    * Create a new EndElement

   330    * @param name the qualified name of the EndElement

   331    * @param namespaces an optional unordered set of objects that

   332    * implement Namespace that have gone out of scope, may be null

   333    * @return an instance of the requested EndElement

   334    */

   335   public abstract EndElement createEndElement(QName name,

   336                                               Iterator namespaces);

   337 

   338   /**

   339    * Create a new EndElement

   340    * @param namespaceUri the uri of the QName of the new StartElement

   341    * @param localName the local name of the QName of the new StartElement

   342    * @param prefix the prefix of the QName of the new StartElement

   343    * @return an instance of the requested EndElement

   344    */

   345   public abstract EndElement createEndElement(String prefix,

   346                                               String namespaceUri,

   347                                               String localName);

   348   /**

   349    * Create a new EndElement

   350    * @param namespaceUri the uri of the QName of the new StartElement

   351    * @param localName the local name of the QName of the new StartElement

   352    * @param prefix the prefix of the QName of the new StartElement

   353    * @param namespaces an unordered set of objects that implement

   354    * Namespace that have gone out of scope, may be null

   355    * @return an instance of the requested EndElement

   356    */

   357   public abstract EndElement createEndElement(String prefix,

   358                                               String namespaceUri,

   359                                               String localName,

   360                                               Iterator namespaces);

   361 

   362   /**

   363    * Create a Characters event, this method does not check if the content

   364    * is all whitespace.  To create a space event use #createSpace(String)

   365    * @param content the string to create

   366    * @return a Characters event

   367    */

   368   public abstract Characters createCharacters(String content);

   369 

   370   /**

   371    * Create a Characters event with the CData flag set to true

   372    * @param content the string to create

   373    * @return a Characters event

   374    */

   375   public abstract Characters createCData(String content);

   376 

   377   /**

   378    * Create a Characters event with the isSpace flag set to true

   379    * @param content the content of the space to create

   380    * @return a Characters event

   381    */

   382   public abstract Characters createSpace(String content);

   383   /**

   384    * Create an ignorable space

   385    * @param content the space to create

   386    * @return a Characters event

   387    */

   388   public abstract Characters createIgnorableSpace(String content);

   389 

   390   /**

   391    * Creates a new instance of a StartDocument event

   392    * @return a StartDocument event

   393    */

   394   public abstract StartDocument createStartDocument();

   395 

   396   /**

   397    * Creates a new instance of a StartDocument event

   398    *

   399    * @param encoding the encoding style

   400    * @param version the XML version

   401    * @param standalone the status of standalone may be set to "true" or "false"

   402    * @return a StartDocument event

   403    */

   404   public abstract StartDocument createStartDocument(String encoding,

   405                                                   String version,

   406                                                   boolean standalone);

   407 

   408   /**

   409    * Creates a new instance of a StartDocument event

   410    *

   411    * @param encoding the encoding style

   412    * @param version the XML version

   413    * @return a StartDocument event

   414    */

   415   public abstract StartDocument createStartDocument(String encoding,

   416                                                   String version);

   417 

   418   /**

   419    * Creates a new instance of a StartDocument event

   420    *

   421    * @param encoding the encoding style

   422    * @return a StartDocument event

   423    */

   424   public abstract StartDocument createStartDocument(String encoding);

   425 

   426   /**

   427    * Creates a new instance of an EndDocument event

   428    * @return an EndDocument event

   429    */

   430   public abstract EndDocument createEndDocument();

   431 

   432   /** Creates a new instance of a EntityReference event

   433    *

   434    * @param name The name of the reference

   435    * @param declaration the declaration for the event

   436    * @return an EntityReference event

   437    */

   438   public abstract EntityReference createEntityReference(String name,

   439                                                         EntityDeclaration declaration);

   440   /**

   441    * Create a comment

   442    * @param text The text of the comment

   443    * a Comment event

   444    */

   445   public abstract Comment createComment(String text);

   446 

   447   /**

   448    * Create a processing instruction

   449    * @param target The target of the processing instruction

   450    * @param data The text of the processing instruction

   451    * @return a ProcessingInstruction event

   452    */

   453   public abstract ProcessingInstruction createProcessingInstruction(String target,

   454                                                                    String data);

   455 

   456   /**

   457    * Create a document type definition event

   458    * This string contains the entire document type declaration that matches

   459    * the doctypedecl in the XML 1.0 specification

   460    * @param dtd the text of the document type definition

   461    * @return a DTD event

   462    */

   463   public abstract DTD createDTD(String dtd);

   464 }