Find JSRs
Submit this Search


Ad Banner
 
 
 
 

 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