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 | 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 * Same as {@link #newFactory()}. 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 * if present, otherwise, use the properties file "lib/jaxp.properties" 147 * in the JRE directory. 148 * These configuration files are in standard java.util.Properties format 149 * and contain the fully qualified name of the implementation class 150 * with the key being the system property defined above. 151 * </li> 152 * <li> 153 * Use the service-provider loading facilities, defined by the 154 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 155 * implementation of the service. 156 * </li> 157 * <li> 158 * Otherwise, the system-default implementation is returned. 159 * </li> 160 * <p> 161 * Once an application has obtained a reference to a XMLOutputFactory it 162 * can use the factory to configure and obtain stream instances. 163 * </p> 164 * <p> 165 * Note that this is a new method that replaces the deprecated newInstance() method. 166 * No changes in behavior are defined by this replacement method relative to the 167 * deprecated method. 168 * </p> 169 * @throws FactoryConfigurationError in case of {@linkplain 170 * java.util.ServiceConfigurationError service configuration error} or if 171 * the implementation is not available or cannot be instantiated. 172 */ 173 public static XMLOutputFactory newFactory() 174 throws FactoryConfigurationError 175 { 176 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL); 177 } 178 179 /** 180 * Create a new instance of the factory. 181 * 182 * @param factoryId Name of the factory to find, same as 183 * a property name 184 * @param classLoader classLoader to use 185 * @return the factory implementation 186 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded 187 * 188 * @deprecated This method has been deprecated because it returns an 189 * instance of XMLInputFactory, which is of the wrong class. 190 * Use the new method {@link #newFactory(java.lang.String, 191 * java.lang.ClassLoader)} instead. 192 */ 193 public static XMLInputFactory newInstance(String factoryId, 194 ClassLoader classLoader) 195 throws FactoryConfigurationError { 196 //do not fallback if given classloader can't find the class, throw exception 197 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null); 198 } 199 200 /** 201 * Create a new instance of the factory. 202 * If the classLoader argument is null, then the ContextClassLoader is used. 203 * <p> 204 * This method uses the following ordered lookup procedure to determine 205 * the XMLOutputFactory implementation class to load: 206 * </p> 207 * <ul> 208 * <li> 209 * Use the value of the system property identified by {@code factoryId}. 210 * </li> 211 * <li> 212 * Use the properties file "lib/stax.properties" in the JRE directory, 213 * if present, otherwise, use the properties file "lib/jaxp.properties" 214 * in the JRE directory. 215 * These configuration files are in standard java.util.Properties format 216 * and contain the fully qualified name of the implementation class 217 * with the key being the given {@code factoryId}. 218 * </li> 219 * <li> 220 * If {@code factoryId} is the base service class name, 221 * use the service-provider loading facilities, defined by the 222 * {@link java.util.ServiceLoader} class, to attempt to locate and load an 223 * implementation of the service. 224 * </li> 225 * <li> 226 * Otherwise, throws a {@link FactoryConfigurationError}. 227 * </li> 228 * </ul> 229 * 230 * <p> 231 * Note that this is a new method that replaces the deprecated 232 * {@link #newInstance(java.lang.String, java.lang.ClassLoader) 233 * newInstance(String factoryId, ClassLoader classLoader)} method. 234 * No changes in behavior are defined by this replacement method relative 235 * to the deprecated method. 236 * </p> 237 * 238 * @param factoryId Name of the factory to find, same as 239 * a property name 240 * @param classLoader classLoader to use 241 * @return the factory implementation 242 * @throws FactoryConfigurationError in case of {@linkplain 243 * java.util.ServiceConfigurationError service configuration error} or if 244 * the implementation is not available or cannot be instantiated. 245 */ 246 public static XMLOutputFactory newFactory(String factoryId, 247 ClassLoader classLoader) 248 throws FactoryConfigurationError { 249 //do not fallback if given classloader can't find the class, throw exception 250 return FactoryFinder.find(XMLOutputFactory.class, factoryId, classLoader, null); 251 } 252 253 /** 254 * Create a new XMLStreamWriter that writes to a writer 255 * @param stream the writer to write to 256 * @throws XMLStreamException 257 */ 258 public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException; 259 260 /** 261 * Create a new XMLStreamWriter that writes to a stream 262 * @param stream the stream to write to 263 * @throws XMLStreamException 264 */ 265 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException; 266 267 /** 268 * Create a new XMLStreamWriter that writes to a stream 269 * @param stream the stream to write to 270 * @param encoding the encoding to use |