src/javax/xml/stream/XMLEventFactory.java
Print this page
*** 25,38 ****
/*
* Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
*/
package javax.xml.stream;
! import javax.xml.stream.events.*;
import javax.xml.namespace.NamespaceContext;
import javax.xml.namespace.QName;
! import java.util.Iterator;
/**
* This interface defines a utility class for creating instances of
* XMLEvents
* @version 1.2
* @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
--- 25,38 ----
/*
* Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
*/
package javax.xml.stream;
! import java.util.Iterator;
import javax.xml.namespace.NamespaceContext;
import javax.xml.namespace.QName;
! import javax.xml.stream.events.*;
/**
* This interface defines a utility class for creating instances of
* XMLEvents
* @version 1.2
* @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
*** 52,103 ****
static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
/**
! * Create a new instance of the factory
* @throws FactoryConfigurationError if an instance of this factory cannot be loaded
*/
public static XMLEventFactory newInstance()
throws FactoryConfigurationError
{
! return (XMLEventFactory) FactoryFinder.find(
! JAXPFACTORYID,
! DEFAULIMPL);
}
/**
* 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.
! *
! * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
*/
public static XMLEventFactory newFactory()
throws FactoryConfigurationError
{
! return (XMLEventFactory) FactoryFinder.find(
! JAXPFACTORYID,
! DEFAULIMPL);
}
/**
* Create a new instance of the factory
*
--- 52,116 ----
static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
/**
! * Create a new instance of the factory.
! * Same as {@link #newFactory()}.
* @throws FactoryConfigurationError if an instance of this factory cannot be loaded
*/
public static XMLEventFactory newInstance()
throws FactoryConfigurationError
{
! return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
}
/**
* Create a new instance of the factory.
+ * <p>
* This static method creates a new factory instance.
* This method uses the following ordered lookup procedure to determine
* the XMLEventFactory implementation class to load:
+ * </p>
+ * <ul>
+ * <li>
* Use the javax.xml.stream.XMLEventFactory system property.
! * </li>
! * <li>
! * Use the properties file "lib/stax.properties" in the JRE directory,
! * if present, otherwise, use the properties file "lib/jaxp.properties"
! * in the JRE directory.
! * These configuration files are in standard java.util.Properties format
! * and contain the fully qualified name of the implementation class
* with the key being the system property defined above.
! * </li>
! * <li>
! * Use the service-provider loading facilities, defined by the
! * {@link java.util.ServiceLoader} class, to attempt to locate and load an
! * implementation of the service.
! * </li>
! * <li>
! * Otherwise, the system-default implementation is returned.
! * </li>
! * </ul>
! * <p>
* Once an application has obtained a reference to a XMLEventFactory it
* can use the factory to configure and obtain stream instances.
! * </p>
! * <p>
* 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.
! * </p>
! * @throws FactoryConfigurationError in case of {@linkplain
! * java.util.ServiceConfigurationError service configuration error} or if
! * the implementation is not available or cannot be instantiated.
*/
public static XMLEventFactory newFactory()
throws FactoryConfigurationError
{
! return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
}
/**
* Create a new instance of the factory
*
*** 114,157 ****
* method defines no changes in behavior.
*/
public static XMLEventFactory newInstance(String factoryId,
ClassLoader classLoader)
throws FactoryConfigurationError {
- try {
//do not fallback if given classloader can't find the class, throw exception
! return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null);
! } catch (FactoryFinder.ConfigurationError e) {
! throw new FactoryConfigurationError(e.getException(),
! e.getMessage());
! }
}
/**
* 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.
*
* @param factoryId Name of the factory to find, same as
* a property name
* @param classLoader classLoader to use
* @return the factory implementation
! * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
*/
public static XMLEventFactory newFactory(String factoryId,
ClassLoader classLoader)
throws FactoryConfigurationError {
- try {
//do not fallback if given classloader can't find the class, throw exception
! return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null);
! } catch (FactoryFinder.ConfigurationError e) {
! throw new FactoryConfigurationError(e.getException(),
! e.getMessage());
! }
}
/**
* This method allows setting of the Location on each event that
* is created by this factory. The values are copied by value into
--- 127,191 ----
* method defines no changes in behavior.
*/
public static XMLEventFactory newInstance(String factoryId,
ClassLoader classLoader)
throws FactoryConfigurationError {
//do not fallback if given classloader can't find the class, throw exception
! return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
}
/**
* Create a new instance of the factory.
* If the classLoader argument is null, then the ContextClassLoader is used.
+ * <p>
+ * This method uses the following ordered lookup procedure to determine
+ * the XMLEventFactory implementation class to load:
+ * </p>
+ * <ul>
+ * <li>
+ * Use the value of the system property identified by {@code factoryId}.
+ * </li>
+ * <li>
+ * Use the properties file "lib/stax.properties" in the JRE directory,
+ * if present, otherwise, use the properties file "lib/jaxp.properties"
+ * in the JRE directory.
+ * These configuration files are in standard java.util.Properties format
+ * and contain the fully qualified name of the implementation class
+ * with the key being the given {@code factoryId}.
+ * </li>
+ * <li>
+ * If {@code factoryId} is the base service class name,
+ * use the service-provider loading facilities, defined by the
+ * {@link java.util.ServiceLoader} class, to attempt to locate and load an
+ * implementation of the service.
+ * </li>
+ * <li>
+ * Otherwise, throws a {@link FactoryConfigurationError}.
+ * </li>
+ * </ul>
*
+ * <p>
* Note that this is a new method that replaces the deprecated
! * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
! * newInstance(String factoryId, ClassLoader classLoader)} method.
* No changes in behavior are defined by this replacement method relative
* to the deprecated method.
+ * </p>
*
* @param factoryId Name of the factory to find, same as
* a property name
* @param classLoader classLoader to use
* @return the factory implementation
! * @throws FactoryConfigurationError in case of {@linkplain
! * java.util.ServiceConfigurationError service configuration error} or if
! * the implementation is not available or cannot be instantiated.
*/
public static XMLEventFactory newFactory(String factoryId,
ClassLoader classLoader)
throws FactoryConfigurationError {
//do not fallback if given classloader can't find the class, throw exception
! return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
}
/**
* This method allows setting of the Location on each event that
* is created by this factory. The values are copied by value into