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); | 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 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 * 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 FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL); 64 } 65 66 /** 67 * Create a new instance of the factory. 68 * <p> 69 * This static method creates a new factory instance. 70 * This method uses the following ordered lookup procedure to determine 71 * the XMLEventFactory implementation class to load: 72 * </p> 73 * <ul> 74 * <li> 75 * Use the javax.xml.stream.XMLEventFactory system property. 76 * </li> 77 * <li> 78 * Use the properties file "lib/stax.properties" in the JRE directory. 79 * This configuration file is in standard java.util.Properties format 80 * and contains the fully qualified name of the implementation class 81 * with the key being the system property defined above. 82 * </li> 83 * <li> 84 * Use the service-provider loading facilities, defined by the 85 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 86 * implementation of the service. 87 * </li> 88 * <li> 89 * Otherwise, the system-default implementation is returned. 90 * </li> 91 * </ul> 92 * <p> 93 * Once an application has obtained a reference to a XMLEventFactory it 94 * can use the factory to configure and obtain stream instances. 95 * </p> 96 * <p> 97 * Note that this is a new method that replaces the deprecated newInstance() method. 98 * No changes in behavior are defined by this replacement method relative to 99 * the deprecated method. 100 * </p> 101 * @throws FactoryConfigurationError in case of {@linkplain 102 * java.util.ServiceConfigurationError service configuration error} or if 103 * the implementation is not available or cannot be instantiated. 104 */ 105 public static XMLEventFactory newFactory() 106 throws FactoryConfigurationError 107 { 108 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL); 109 } 110 111 /** 112 * Create a new instance of the factory 113 * 114 * @param factoryId Name of the factory to find, same as 115 * a property name 116 * @param classLoader classLoader to use 117 * @return the factory implementation 118 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 119 * 120 * @deprecated This method has been deprecated to maintain API consistency. 121 * All newInstance methods have been replaced with corresponding 122 * newFactory methods. The replacement {@link 123 * #newFactory(java.lang.String, java.lang.ClassLoader)} 124 * method defines no changes in behavior. 125 */ 126 public static XMLEventFactory newInstance(String factoryId, 127 ClassLoader classLoader) 128 throws FactoryConfigurationError { 129 //do not fallback if given classloader can't find the class, throw exception 130 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null); 131 } 132 133 /** 134 * Create a new instance of the factory. 135 * If the classLoader argument is null, then the ContextClassLoader is used. 136 * 137 * Note that this is a new method that replaces the deprecated 138 * newInstance(String factoryId, ClassLoader classLoader) method. 139 * No changes in behavior are defined by this replacement method relative 140 * to the deprecated method. 141 * 142 * @param factoryId Name of the factory to find, same as 143 * a property name 144 * @param classLoader classLoader to use 145 * @return the factory implementation 146 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 147 */ 148 public static XMLEventFactory newFactory(String factoryId, 149 ClassLoader classLoader) 150 throws FactoryConfigurationError { 151 //do not fallback if given classloader can't find the class, throw exception 152 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null); 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); |