Change Log for JSR-000173 Streaming API for XML

Change Log for JSR-000173 Streaming API for XML

This page details the proposed, accepted and deferred changes to JSR 173 documenting the changes that will go into the next revision, per Spec Lead Guide: Maintenance Review (MR), of the JCP 6.1 document.

Last updated: 24 June 2009

Description

Minor revision 1.2 of Streaming API for XML Processing for the Java Platform

Special notes concerning Proposed Changes 1, 2, 3:
    Since StAX 1.0 standardization, usage, and the problems (proposed resolutions thereof below that constitute this MR) predate
    annotations, and in particular @Depreciated; this MR proposes to depreciate erroneous/superseded APIs using the previous
    JavaDoc @depreciated annotation, thus enabling the use of the new MR release on Java implementations prior to 5.0 (1.5).

    However the JSR MR EG may decide to forgo backwards compatibility prior to Java 5.0 (1.5) and employ the newer annotation based
    depreciation mechanism. This will be resolved prior to the MR being declared final.

   
   Proposed changes  4, 6, 8:  Add new methods
      '[ XMLInput | XMLOutput | XMLEvent ]Factory.newFactory(String factoryId, ClassLoader classloader)'
     for API consistency.   Include JavaDocs to clarify the expected behavior of the
     methods when the ClassLoader argument is null.   The specified behavior is what was implied but not defined
     from the corresponding StAX v1.0  newInstance(String factoryId, ClassLoader classloader)
     methods at the time that the StAX v1.0 specification went final.  
   
   Proposed changes 5, 7, 9:  Add new no-arg methods '[ XMLInput | XMLOutput | XMLEvent ]Factory.newFactory()'
     for API consistency.   Include JavaDocs to all the no-arg methods that clarify the class loading behavior.   This class loading behavior
     description was missing from the corresponding StAX v1.0 no-arg 'newInstance()' methods for  XMLOutputFactory and XMLEventFactory.

Maintenance Lead

Larry Cable, Oracle Corporation
Thorick Chow, Oracle Corporation

Feedback

Comments should be sent to mailto:jsr-173-comments@jcp.org.

PROPOSED CHANGES
Request	Summary	Specification/Interface
1	XMLOutputFactory deprecate via JavaDoc the public static method in:     javax.xml.stream.XMLOutputFactory   public static XMLInputFactory     newInstance(java.lang.String                            factoryId,                         java.lang.ClassLoader                             classLoader)       throws FactoryConfigurationError	XMLOutputFactory class: add deprecated notice to method JavaDoc:   @deprecated This method has been deprecated because it returns an instance of XMLInputFactory, which is of the wrong class.  Use the new method newFactory(java.lang.String factoryId,                    java.lang.ClassLoader classLoader) instead.
2	XMLInputFactory deprecate via JavaDoc the public static method in:     javax.xml.stream.XMLInputFactory   public static XMLInputFactory     newInstance(java.lang.String                           factoryId,                        java.lang.ClassLoader                              classLoader)       throws FactoryConfigurationError	XMLInputFactory class: add deprecation notice to method JavaDoc: @deprecated to maintain API consistency.  All newInstance methods are replaced with corresponding newFactory methods.  The replacement newFactory(String factoryId, ClassLoader classLoader)  method defines no changes in behavior from this method.
3	XMLEventFactory deprecate via JavaDoc the public static method in:     javax.xml.stream.XMLEventFactory   public static XMLEventFactory     newInstance(java.lang.String                           factoryId,                        java.lang.ClassLoader                            classLoader)       throws FactoryConfigurationError	XMLEventFactory class: add deprecation notice to method JavaDoc: @deprecated to maintain API consistency.  All newInstance methods are replaced with corresponding newFactory methods.  The replacement newFactory(String factoryId, ClassLoader classLoader)  method defines no changes in behavior from this method.
4	XMLOutputFactory add public static method to take the place of the method deprecated in proposal request #1:             in class: javax.xml.stream.XMLOutputFactory  public static XMLOutputFactory   newFactory(java.lang.String                        factoryId,                                            java.lang.ClassLoader                        classLoader)  throws FactoryConfigurationError	XMLOutputFactory class:  add new method. JavaDoc to read: Create a new instance of the factory.  If the classLoader argument is null, then the ContextClassLoader is used.   Note that this is a new method that replaces the deprecated newInstance(String factoryId, ClassLoader classLoader) method.  No changes in behavior are defined by this replacement method relative to the deprecated method.
5	XMLOutputFactory add public static method for API consistency:             in class: javax.xml.stream.XMLOutputFactory    public static XMLOutputFactory      newFactory()  throws FactoryConfigurationError	XMLOutputFactory class:  add new method. JavaDoc to read: Create a new instance of the factory. This static method creates a new factory instance. This method uses the following ordered lookup procedure to determine the XMLOutputFactory implementation class to load: Use the javax.xml.stream.XMLOutputFactory system property. Use the properties file "lib/stax.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.stream.XMLOutputFactory in jars available to the runtime. Platform default XMLOutputFactory instance. Once an application has obtained a reference to a XMLOutputFactory it can use the factory to configure and obtain stream instances.  Note that this is a new method that replaces the deprecated newInstance() method.  No changes in behavior are defined by this replacement method relative to the deprecated method.
6	XMLInputFactory add public static method to take the place of the method deprecated in proposal request #2:             in class: javax.xml.stream.XMLInputFactory  public static XMLInputFactory   newFactory(java.lang.String                        factoryId,                                           java.lang.ClassLoader                        classLoader)  throws FactoryConfigurationError	XMLInputFactory class:  add new method. JavaDoc to read: Create a new instance of the factory.  If the classLoader argument is null, then the ContextClassLoader is used.   Note that this is a new method that replaces the deprecated newInstance(String factoryId, ClassLoader classLoader) method.  No changes in behavior are defined by this replacement method relative to the deprecated method.
7	XMLInputFactory add public static method for API consistency:             in class: javax.xml.stream.XMLInputFactory    public static XMLInputFactory      newFactory()  throws FactoryConfigurationError	XMLInputFactory class:  add new method. JavaDoc to read: Create a new instance of the factory. This static method creates a new factory instance. This method uses the following ordered lookup procedure to determine the XMLInputFactory implementation class to load: Use the javax.xml.stream.XMLInputFactory system property. Use the properties file "lib/stax.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.stream.XMLInputFactory in jars available to the runtime. Platform default XMLInputFactory instance. Once an application has obtained a reference to a XMLInputFactory it can use the factory to configure and obtain stream instances.   Note that this is a new method that replaces the deprecated newInstance() method.  No changes in behavior are defined by this replacement method relative to the deprecated method.
8	XMLEventFactory add  public static method to take the place of the method deprecated in proposal request #3:             in class: javax.xml.stream.XMLEventFactory  public static XMLEventFactory   newFactory(java.lang.String                        factoryId,                                           java.lang.ClassLoader                        classLoader)  throws FactoryConfigurationError	XMLEventFactory class:  add new method. JavaDoc to read: Create a new instance of the factory.  If the classLoader argument is null, then the ContextClassLoader is used.   Note that this is a new method that replaces the deprecated newInstance(String factoryId, ClassLoader classLoader) method.  No changes in behavior are defined by this replacement method relative to the deprecated method.
9	XMLEventFactory add  public static method for API consistency            in class: javax.xml.stream.XMLEventFactory    public static XMLEventFactory      newFactory()  throws FactoryConfigurationError	XMLEventFactory class:  add new method. JavaDoc to read: Create a new instance of the factory. This static method creates a new factory instance. This method uses the following ordered lookup procedure to determine the XMLEventFactory implementation class to load: Use the javax.xml.stream.XMLEventFactory system property. Use the properties file "lib/stax.properties" in the JRE directory. This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above. Use the Services API (as detailed in the JAR specification), if available, to determine the classname. The Services API will look for a classname in the file META-INF/services/javax.xml.stream.XMLEventFactory in jars available to the runtime. Platform default XMLEventFactory instance. Once an application has obtained a reference to a XMLEventFactory it can use the factory to configure and obtain stream instances.  Note that this is a new method that replaces the deprecated newInstance() method.  No changes in behavior are defined by this replacement method relative to the deprecated method.

ACCEPTED  CHANGES
Request	Summary	Specification/Interface