1 /*
2 * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
95 * either removed if the correct mapping is inherited from
96 * the parent context of that element, or changed to the
97 * namespace URI of the element or attribute using that prefix.
98 *
99 * @version 1.2
100 * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
101 * @see XMLInputFactory
102 * @see XMLEventWriter
103 * @see XMLStreamWriter
104 * @since 1.6
105 */
106 public abstract class XMLOutputFactory {
107 /**
108 * Property used to set prefix defaulting on the output side
109 */
110 public static final String IS_REPAIRING_NAMESPACES=
111 "javax.xml.stream.isRepairingNamespaces";
112
113 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl";
114
115 protected XMLOutputFactory(){}
116
117 /**
118 * Creates a new instance of the {@code XMLOutputFactory} builtin
119 * system-default implementation.
120 *
121 * @return A new instance of the {@code XMLOutputFactory} builtin
122 * system-default implementation.
123 *
124 * @since 9
125 */
126 public static XMLOutputFactory newDefaultFactory() {
127 return new XMLOutputFactoryImpl();
128 }
129
130 /**
131 * Creates a new instance of the factory in exactly the same manner as the
132 * {@link #newFactory()} method.
133 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
134 */
135 public static XMLOutputFactory newInstance()
136 throws FactoryConfigurationError
137 {
138 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
139 }
140
141 /**
142 * Create a new instance of the factory.
143 * <p>
144 * This static method creates a new factory instance. This method uses the
145 * following ordered lookup procedure to determine the XMLOutputFactory
146 * implementation class to load:
147 * <ul>
148 * <li>
149 * Use the javax.xml.stream.XMLOutputFactory system property.
150 * </li>
151 * <li>
152 * <p>
173 * Use the service-provider loading facility, defined by the
174 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
175 * implementation of the service using the {@linkplain
176 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
177 * the service-provider loading facility will use the {@linkplain
178 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
179 * to attempt to load the service. If the context class
180 * loader is null, the {@linkplain
181 * ClassLoader#getSystemClassLoader() system class loader} will be used.
182 * </li>
183 * <li>
184 * <p>
185 * Otherwise, the {@linkplain #newDefaultFactory() system-default}
186 * implementation is returned.
187 * </li>
188 * </ul>
189 * <p>
190 * Once an application has obtained a reference to a XMLOutputFactory it
191 * can use the factory to configure and obtain stream instances.
192 *
193 * @throws FactoryConfigurationError in case of {@linkplain
194 * java.util.ServiceConfigurationError service configuration error} or if
195 * the implementation is not available or cannot be instantiated.
196 */
197 public static XMLOutputFactory newFactory()
198 throws FactoryConfigurationError
199 {
200 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
201 }
202
203 /**
204 * Create a new instance of the factory.
205 *
206 * @param factoryId Name of the factory to find, same as
207 * a property name
208 * @param classLoader classLoader to use
209 * @return the factory implementation
210 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
211 *
212 * @deprecated This method has been deprecated because it returns an
285 *
286 *
287 * @param factoryId Name of the factory to find, same as
288 * a property name
289 * @param classLoader classLoader to use
290 * @return the factory implementation
291 * @throws FactoryConfigurationError in case of {@linkplain
292 * java.util.ServiceConfigurationError service configuration error} or if
293 * the implementation is not available or cannot be instantiated.
294 */
295 public static XMLOutputFactory newFactory(String factoryId,
296 ClassLoader classLoader)
297 throws FactoryConfigurationError {
298 //do not fallback if given classloader can't find the class, throw exception
299 return FactoryFinder.find(XMLOutputFactory.class, factoryId, classLoader, null);
300 }
301
302 /**
303 * Create a new XMLStreamWriter that writes to a writer
304 * @param stream the writer to write to
305 * @throws XMLStreamException
306 */
307 public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException;
308
309 /**
310 * Create a new XMLStreamWriter that writes to a stream
311 * @param stream the stream to write to
312 * @throws XMLStreamException
313 */
314 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException;
315
316 /**
317 * Create a new XMLStreamWriter that writes to a stream
318 * @param stream the stream to write to
319 * @param encoding the encoding to use
320 * @throws XMLStreamException
321 */
322 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream,
323 String encoding) throws XMLStreamException;
324
325 /**
326 * Create a new XMLStreamWriter that writes to a JAXP result. This method is optional.
327 * @param result the result to write to
328 * @throws UnsupportedOperationException if this method is not
329 * supported by this XMLOutputFactory
330 * @throws XMLStreamException
331 */
332 public abstract XMLStreamWriter createXMLStreamWriter(Result result) throws XMLStreamException;
333
334
335 /**
336 * Create a new XMLEventWriter that writes to a JAXP result. This method is optional.
337 * @param result the result to write to
338 * @throws UnsupportedOperationException if this method is not
339 * supported by this XMLOutputFactory
340 * @throws XMLStreamException
341 */
342 public abstract XMLEventWriter createXMLEventWriter(Result result) throws XMLStreamException;
343
344 /**
345 * Create a new XMLEventWriter that writes to a stream
346 * @param stream the stream to write to
347 * @throws XMLStreamException
348 */
349 public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream) throws XMLStreamException;
350
351
352
353 /**
354 * Create a new XMLEventWriter that writes to a stream
355 * @param stream the stream to write to
356 * @param encoding the encoding to use
357 * @throws XMLStreamException
358 */
359 public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream,
360 String encoding) throws XMLStreamException;
361
362 /**
363 * Create a new XMLEventWriter that writes to a writer
364 * @param stream the stream to write to
365 * @throws XMLStreamException
366 */
367 public abstract XMLEventWriter createXMLEventWriter(java.io.Writer stream) throws XMLStreamException;
368
369 /**
370 * Allows the user to set specific features/properties on the underlying implementation.
371 * @param name The name of the property
372 * @param value The value of the property
373 * @throws java.lang.IllegalArgumentException if the property is not supported
374 */
375 public abstract void setProperty(java.lang.String name,
376 Object value)
377 throws IllegalArgumentException;
378
379 /**
380 * Get a feature/property on the underlying implementation
381 * @param name The name of the property
382 * @return The value of the property
383 * @throws java.lang.IllegalArgumentException if the property is not supported
384 */
385 public abstract Object getProperty(java.lang.String name)
|
1 /*
2 * Copyright (c) 2009, 2020, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
95 * either removed if the correct mapping is inherited from
96 * the parent context of that element, or changed to the
97 * namespace URI of the element or attribute using that prefix.
98 *
99 * @version 1.2
100 * @author Copyright (c) 2009, 2015 by Oracle Corporation. All Rights Reserved.
101 * @see XMLInputFactory
102 * @see XMLEventWriter
103 * @see XMLStreamWriter
104 * @since 1.6
105 */
106 public abstract class XMLOutputFactory {
107 /**
108 * Property used to set prefix defaulting on the output side
109 */
110 public static final String IS_REPAIRING_NAMESPACES=
111 "javax.xml.stream.isRepairingNamespaces";
112
113 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl";
114
115 /**
116 * Protected constructor to prevent instantiation.
117 * Use {@link #newFactory()} instead.
118 */
119 protected XMLOutputFactory(){}
120
121 /**
122 * Creates a new instance of the {@code XMLOutputFactory} builtin
123 * system-default implementation.
124 *
125 * @return A new instance of the {@code XMLOutputFactory} builtin
126 * system-default implementation.
127 *
128 * @since 9
129 */
130 public static XMLOutputFactory newDefaultFactory() {
131 return new XMLOutputFactoryImpl();
132 }
133
134 /**
135 * Creates a new instance of the factory in exactly the same manner as the
136 * {@link #newFactory()} method.
137 * @return an instance of the {@code XMLOutputFactory}
138 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
139 */
140 public static XMLOutputFactory newInstance()
141 throws FactoryConfigurationError
142 {
143 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
144 }
145
146 /**
147 * Create a new instance of the factory.
148 * <p>
149 * This static method creates a new factory instance. This method uses the
150 * following ordered lookup procedure to determine the XMLOutputFactory
151 * implementation class to load:
152 * <ul>
153 * <li>
154 * Use the javax.xml.stream.XMLOutputFactory system property.
155 * </li>
156 * <li>
157 * <p>
178 * Use the service-provider loading facility, defined by the
179 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
180 * implementation of the service using the {@linkplain
181 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
182 * the service-provider loading facility will use the {@linkplain
183 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
184 * to attempt to load the service. If the context class
185 * loader is null, the {@linkplain
186 * ClassLoader#getSystemClassLoader() system class loader} will be used.
187 * </li>
188 * <li>
189 * <p>
190 * Otherwise, the {@linkplain #newDefaultFactory() system-default}
191 * implementation is returned.
192 * </li>
193 * </ul>
194 * <p>
195 * Once an application has obtained a reference to a XMLOutputFactory it
196 * can use the factory to configure and obtain stream instances.
197 *
198 * @return an instance of the {@code XMLOutputFactory}
199 * @throws FactoryConfigurationError in case of {@linkplain
200 * java.util.ServiceConfigurationError service configuration error} or if
201 * the implementation is not available or cannot be instantiated.
202 */
203 public static XMLOutputFactory newFactory()
204 throws FactoryConfigurationError
205 {
206 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL);
207 }
208
209 /**
210 * Create a new instance of the factory.
211 *
212 * @param factoryId Name of the factory to find, same as
213 * a property name
214 * @param classLoader classLoader to use
215 * @return the factory implementation
216 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
217 *
218 * @deprecated This method has been deprecated because it returns an
291 *
292 *
293 * @param factoryId Name of the factory to find, same as
294 * a property name
295 * @param classLoader classLoader to use
296 * @return the factory implementation
297 * @throws FactoryConfigurationError in case of {@linkplain
298 * java.util.ServiceConfigurationError service configuration error} or if
299 * the implementation is not available or cannot be instantiated.
300 */
301 public static XMLOutputFactory newFactory(String factoryId,
302 ClassLoader classLoader)
303 throws FactoryConfigurationError {
304 //do not fallback if given classloader can't find the class, throw exception
305 return FactoryFinder.find(XMLOutputFactory.class, factoryId, classLoader, null);
306 }
307
308 /**
309 * Create a new XMLStreamWriter that writes to a writer
310 * @param stream the writer to write to
311 * @return instance of the {@code XMLStreamWriter}
312 * @throws XMLStreamException if an error occurs
313 */
314 public abstract XMLStreamWriter createXMLStreamWriter(java.io.Writer stream) throws XMLStreamException;
315
316 /**
317 * Create a new XMLStreamWriter that writes to a stream
318 * @param stream the stream to write to
319 * @return instance of the {@code XMLStreamWriter}
320 * @throws XMLStreamException if an error occurs
321 */
322 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream) throws XMLStreamException;
323
324 /**
325 * Create a new XMLStreamWriter that writes to a stream
326 * @param stream the stream to write to
327 * @param encoding the encoding to use
328 * @return instance of the {@code XMLStreamWriter}
329 * @throws XMLStreamException if an error occurs
330 */
331 public abstract XMLStreamWriter createXMLStreamWriter(java.io.OutputStream stream,
332 String encoding) throws XMLStreamException;
333
334 /**
335 * Create a new XMLStreamWriter that writes to a JAXP result. This method is optional.
336 * @param result the result to write to
337 * @return instance of the {@code XMLStreamWriter}
338 * @throws UnsupportedOperationException if this method is not
339 * supported by this XMLOutputFactory
340 * @throws XMLStreamException if an error occurs
341 */
342 public abstract XMLStreamWriter createXMLStreamWriter(Result result) throws XMLStreamException;
343
344
345 /**
346 * Create a new XMLEventWriter that writes to a JAXP result. This method is optional.
347 * @param result the result to write to
348 * @return instance of the {@code XMLEventWriter}
349 * @throws UnsupportedOperationException if this method is not
350 * supported by this XMLOutputFactory
351 * @throws XMLStreamException if an error occurs
352 */
353 public abstract XMLEventWriter createXMLEventWriter(Result result) throws XMLStreamException;
354
355 /**
356 * Create a new XMLEventWriter that writes to a stream
357 * @param stream the stream to write to
358 * @return instance of the {@code XMLEventWriter}
359 * @throws XMLStreamException if an error occurs
360 */
361 public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream) throws XMLStreamException;
362
363
364
365 /**
366 * Create a new XMLEventWriter that writes to a stream
367 * @param stream the stream to write to
368 * @param encoding the encoding to use
369 * @return instance of the {@code XMLEventWriter}
370 * @throws XMLStreamException if an error occurs
371 */
372 public abstract XMLEventWriter createXMLEventWriter(java.io.OutputStream stream,
373 String encoding) throws XMLStreamException;
374
375 /**
376 * Create a new XMLEventWriter that writes to a writer
377 * @param stream the stream to write to
378 * @return instance of the {@code XMLEventWriter}
379 * @throws XMLStreamException if an error occurs
380 */
381 public abstract XMLEventWriter createXMLEventWriter(java.io.Writer stream) throws XMLStreamException;
382
383 /**
384 * Allows the user to set specific features/properties on the underlying implementation.
385 * @param name The name of the property
386 * @param value The value of the property
387 * @throws java.lang.IllegalArgumentException if the property is not supported
388 */
389 public abstract void setProperty(java.lang.String name,
390 Object value)
391 throws IllegalArgumentException;
392
393 /**
394 * Get a feature/property on the underlying implementation
395 * @param name The name of the property
396 * @return The value of the property
397 * @throws java.lang.IllegalArgumentException if the property is not supported
398 */
399 public abstract Object getProperty(java.lang.String name)
|