103 * 104 * @version 1.2 105 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 106 * @see XMLInputFactory 107 * @see XMLEventWriter 108 * @see XMLStreamWriter 109 * @since 1.6 110 */ 111 public abstract class XMLOutputFactory { 112 /** 113 * Property used to set prefix defaulting on the output side 114 */ 115 public static final String IS_REPAIRING_NAMESPACES= 116 "javax.xml.stream.isRepairingNamespaces"; 117 118 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl"; 119 120 protected XMLOutputFactory(){} 121 122 /** 123 * Create a new instance of the factory. 124 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 125 */ 126 public static XMLOutputFactory newInstance() 127 throws FactoryConfigurationError 128 { 129 return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory", 130 DEFAULIMPL); 131 } 132 133 /** 134 * Create a new instance of the factory. 135 * This static method creates a new factory instance. This method uses the 136 * following ordered lookup procedure to determine the XMLOutputFactory 137 * implementation class to load: 138 * Use the javax.xml.stream.XMLOutputFactory system property. 139 * Use the properties file "lib/stax.properties" in the JRE directory. 140 * This configuration file is in standard java.util.Properties format 141 * and contains the fully qualified name of the implementation class 142 * with the key being the system property defined above. 143 * Use the Services API (as detailed in the JAR specification), if available, 144 * to determine the classname. The Services API will look for a classname 145 * in the file META-INF/services/javax.xml.stream.XMLOutputFactory in jars 146 * available to the runtime. 147 * Platform default XMLOutputFactory instance. 148 * 149 * Once an application has obtained a reference to a XMLOutputFactory it 150 * can use the factory to configure and obtain stream instances. 151 * 152 * Note that this is a new method that replaces the deprecated newInstance() method. 153 * No changes in behavior are defined by this replacement method relative to the 154 * deprecated method. 155 * 156 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 157 */ 158 public static XMLOutputFactory newFactory() 159 throws FactoryConfigurationError 160 { 161 return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory", 162 DEFAULIMPL); 163 } 164 165 /** 166 * Create a new instance of the factory. 167 * 168 * @param factoryId Name of the factory to find, same as 169 * a property name 170 * @param classLoader classLoader to use 171 * @return the factory implementation 172 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 173 * 174 * @deprecated This method has been deprecated because it returns an 175 * instance of XMLInputFactory, which is of the wrong class. 176 * Use the new method {@link #newFactory(java.lang.String, 177 * java.lang.ClassLoader)} instead. 178 */ 179 public static XMLInputFactory newInstance(String factoryId, 180 ClassLoader classLoader) 181 throws FactoryConfigurationError { 182 try { 183 //do not fallback if given classloader can't find the class, throw exception 184 return (XMLInputFactory) FactoryFinder.find(factoryId, classLoader, null); 185 } catch (FactoryFinder.ConfigurationError e) { 186 throw new FactoryConfigurationError(e.getException(), 187 e.getMessage()); 188 } 189 } 190 191 /** 192 * Create a new instance of the factory. 193 * If the classLoader argument is null, then the ContextClassLoader is used. 194 * 195 * Note that this is a new method that replaces the deprecated 196 * newInstance(String factoryId, ClassLoader classLoader) method. 197 * 198 * No changes in behavior are defined by this replacement method relative 199 * to the deprecated method. 200 * 201 * 202 * @param factoryId Name of the factory to find, same as 203 * a property name 204 * @param classLoader classLoader to use 205 * @return the factory implementation 206 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 207 */ 208 public static XMLOutputFactory newFactory(String factoryId, 209 ClassLoader classLoader) 210 throws FactoryConfigurationError { 211 try { 212 //do not fallback if given classloader can't find the class, throw exception 213 return (XMLOutputFactory) FactoryFinder.find(factoryId, classLoader, null); 214 } catch (FactoryFinder.ConfigurationError e) { 215 throw new FactoryConfigurationError(e.getException(), 216 e.getMessage()); 217 } 218 } 219 220 /** 221 * Create a new XMLStreamWriter that writes to a writer 222 * @param stream the writer to write to 223 * @throws XMLStreamException 224 */ 225 public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException; 226 227 /** 228 * Create a new XMLStreamWriter that writes to a stream 229 * @param stream the stream to write to 230 * @throws XMLStreamException 231 */ 232 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException; 233 234 /** 235 * Create a new XMLStreamWriter that writes to a stream 236 * @param stream the stream to write to 237 * @param encoding the encoding to use | 103 * 104 * @version 1.2 105 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved. 106 * @see XMLInputFactory 107 * @see XMLEventWriter 108 * @see XMLStreamWriter 109 * @since 1.6 110 */ 111 public abstract class XMLOutputFactory { 112 /** 113 * Property used to set prefix defaulting on the output side 114 */ 115 public static final String IS_REPAIRING_NAMESPACES= 116 "javax.xml.stream.isRepairingNamespaces"; 117 118 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl"; 119 120 protected XMLOutputFactory(){} 121 122 /** 123 * Creates a new instance of the factory in exactly the same manner as the 124 * {@link #newFactory()} method. 125 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 126 */ 127 public static XMLOutputFactory newInstance() 128 throws FactoryConfigurationError 129 { 130 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL); 131 } 132 133 /** 134 * Create a new instance of the factory. 135 * <p> 136 * This static method creates a new factory instance. This method uses the 137 * following ordered lookup procedure to determine the XMLOutputFactory 138 * implementation class to load: 139 * </p> 140 * <ul> 141 * <li> 142 * Use the javax.xml.stream.XMLOutputFactory system property. 143 * </li> 144 * <li> 145 * Use the properties file "lib/stax.properties" in the JRE directory. 146 * This configuration file is in standard java.util.Properties format 147 * and contains the fully qualified name of the implementation class 148 * with the key being the system property defined above. 149 * </li> 150 * <li> 151 * Use the service-provider loading facilities, defined by the 152 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 153 * implementation of the service. 154 * </li> 155 * <li> 156 * Otherwise, the system-default implementation is returned. 157 * </li> 158 * <p> 159 * Once an application has obtained a reference to a XMLOutputFactory it 160 * can use the factory to configure and obtain stream instances. 161 * </p> 162 * <p> 163 * Note that this is a new method that replaces the deprecated newInstance() method. 164 * No changes in behavior are defined by this replacement method relative to the 165 * deprecated method. 166 * </p> 167 * @throws FactoryConfigurationError in case of {@linkplain 168 * java.util.ServiceConfigurationError service configuration error} or if 169 * the implementation is not available or cannot be instantiated. 170 */ 171 public static XMLOutputFactory newFactory() 172 throws FactoryConfigurationError 173 { 174 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL); 175 } 176 177 /** 178 * Create a new instance of the factory. 179 * 180 * @param factoryId Name of the factory to find, same as 181 * a property name 182 * @param classLoader classLoader to use 183 * @return the factory implementation 184 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 185 * 186 * @deprecated This method has been deprecated because it returns an 187 * instance of XMLInputFactory, which is of the wrong class. 188 * Use the new method {@link #newFactory(java.lang.String, 189 * java.lang.ClassLoader)} instead. 190 */ 191 public static XMLInputFactory newInstance(String factoryId, 192 ClassLoader classLoader) 193 throws FactoryConfigurationError { 194 //do not fallback if given classloader can't find the class, throw exception 195 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null); 196 } 197 198 /** 199 * Create a new instance of the factory. 200 * If the classLoader argument is null, then the ContextClassLoader is used. 201 * <p> 202 * This method uses the following ordered lookup procedure to determine 203 * the XMLOutputFactory implementation class to load: 204 * </p> 205 * <ul> 206 * <li> 207 * Use the value of the system property identified by {@code factoryId}. 208 * </li> 209 * <li> 210 * Use the properties file "lib/stax.properties" in the JRE directory. 211 * This configuration file is in standard java.util.Properties format 212 * and contains the fully qualified name of the implementation class 213 * with the key being the given {@code factoryId}. 214 * </li> 215 * <li> 216 * If {@code factoryId} is the base service class name, 217 * use the service-provider loading facilities, defined by the 218 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 219 * implementation of the service. 220 * </li> 221 * <li> 222 * Otherwise, throws a {@link FactoryConfigurationError}. 223 * </li> 224 * </ul> 225 * 226 * <p> 227 * Note that this is a new method that replaces the deprecated 228 * {@link #newInstance(java.lang.String, java.lang.ClassLoader) 229 * newInstance(String factoryId, ClassLoader classLoader)} method. 230 * No changes in behavior are defined by this replacement method relative 231 * to the deprecated method. 232 * </p> 233 * 234 * @param factoryId Name of the factory to find, same as 235 * a property name 236 * @param classLoader classLoader to use 237 * @return the factory implementation 238 * @throws FactoryConfigurationError in case of {@linkplain 239 * java.util.ServiceConfigurationError service configuration error} or if 240 * the implementation is not available or cannot be instantiated. 241 */ 242 public static XMLOutputFactory newFactory(String factoryId, 243 ClassLoader classLoader) 244 throws FactoryConfigurationError { 245 //do not fallback if given classloader can't find the class, throw exception 246 return FactoryFinder.find(XMLOutputFactory.class, factoryId, classLoader, null); 247 } 248 249 /** 250 * Create a new XMLStreamWriter that writes to a writer 251 * @param stream the writer to write to 252 * @throws XMLStreamException 253 */ 254 public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException; 255 256 /** 257 * Create a new XMLStreamWriter that writes to a stream 258 * @param stream the stream to write to 259 * @throws XMLStreamException 260 */ 261 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException; 262 263 /** 264 * Create a new XMLStreamWriter that writes to a stream 265 * @param stream the stream to write to 266 * @param encoding the encoding to use |