1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3 *
4 * This code is free software; you can redistribute it and/or modify it
5 * under the terms of the GNU General Public License version 2 only, as
6 * published by the Free Software Foundation. Oracle designates this
7 * particular file as subject to the "Classpath" exception as provided
8 * by Oracle in the LICENSE file that accompanied this code.
9 *
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, 2015, by Oracle Corporation. All Rights Reserved.
27 */
28
29 package javax.xml.stream;
30 import com.sun.xml.internal.stream.events.XMLEventFactoryImpl;
31 import java.util.Iterator;
32 import javax.xml.namespace.NamespaceContext;
33 import javax.xml.namespace.QName;
34 import javax.xml.stream.events.*;
35 /**
36 * This interface defines a utility class for creating instances of
37 * XMLEvents
38 * @version 1.2
39 * @author Copyright (c) 2009 by Oracle Corporation. All Rights Reserved.
40 * @see javax.xml.stream.events.StartElement
41 * @see javax.xml.stream.events.EndElement
42 * @see javax.xml.stream.events.ProcessingInstruction
43 * @see javax.xml.stream.events.Comment
44 * @see javax.xml.stream.events.Characters
45 * @see javax.xml.stream.events.StartDocument
46 * @see javax.xml.stream.events.EndDocument
47 * @see javax.xml.stream.events.DTD
48 * @since 1.6
49 */
50 public abstract class XMLEventFactory {
51 protected XMLEventFactory(){}
52
53 static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
54 static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
55
56
57 /**
58 * Creates a new instance of the {@code XMLEventFactory} builtin
59 * system-default implementation.
60 *
61 * @return A new instance of the {@code XMLEventFactory} builtin
62 * system-default implementation.
63 *
64 * @since 9
65 */
66 public static XMLEventFactory newDefaultFactory() {
67 return new XMLEventFactoryImpl();
68 }
69
70 /**
71 * Creates a new instance of the factory in exactly the same manner as the
72 * {@link #newFactory()} method.
73 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
74 */
75 public static XMLEventFactory newInstance()
76 throws FactoryConfigurationError
77 {
78 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
79 }
80
81 /**
82 * Create a new instance of the factory.
83 * <p>
84 * This static method creates a new factory instance.
85 * This method uses the following ordered lookup procedure to determine
86 * the XMLEventFactory implementation class to load:
87 * <ul>
88 * <li>
89 * Use the javax.xml.stream.XMLEventFactory system property.
90 * </li>
91 * <li>
92 * <p>
93 * Use the configuration file "stax.properties". The file is in standard
94 * {@link java.util.Properties} format and typically located in the
95 * {@code conf} directory of the Java installation. It contains the fully qualified
96 * name of the implementation class with the key being the system property
97 * defined above.
98 *
99 * <p>
100 * The stax.properties file is read only once by the implementation
101 * and its values are then cached for future use. If the file does not exist
102 * when the first attempt is made to read from it, no further attempts are
103 * made to check for its existence. It is not possible to change the value
104 * of any property in stax.properties after it has been read for the first time.
105 *
106 * <p>
107 * Use the jaxp configuration file "jaxp.properties". The file is in the same
108 * format as stax.properties and will only be read if stax.properties does
109 * not exist.
110 * </li>
111 * <li>
112 * <p>
113 * Use the service-provider loading facility, defined by the
114 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
115 * implementation of the service using the {@linkplain
116 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
117 * the service-provider loading facility will use the {@linkplain
118 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
119 * to attempt to load the service. If the context class
120 * loader is null, the {@linkplain
121 * ClassLoader#getSystemClassLoader() system class loader} will be used.
122 * </li>
123 * <li>
124 * <p>
125 * Otherwise, the {@linkplain #newDefaultFactory() system-default}
126 * implementation is returned.
127 * </li>
128 * </ul>
129 * <p>
130 * Once an application has obtained a reference to a XMLEventFactory it
131 * can use the factory to configure and obtain stream instances.
132 * <p>
133 * Note that this is a new method that replaces the deprecated newInstance() method.
134 * No changes in behavior are defined by this replacement method relative to
135 * the deprecated method.
136 *
137 * @throws FactoryConfigurationError in case of {@linkplain
138 * java.util.ServiceConfigurationError service configuration error} or if
139 * the implementation is not available or cannot be instantiated.
140 */
141 public static XMLEventFactory newFactory()
142 throws FactoryConfigurationError
143 {
144 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
145 }
146
147 /**
148 * Create a new instance of the factory
149 *
150 * @param factoryId Name of the factory to find, same as
151 * a property name
152 * @param classLoader classLoader to use
153 * @return the factory implementation
154 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
155 *
156 * @deprecated This method has been deprecated to maintain API consistency.
157 * All newInstance methods have been replaced with corresponding
158 * newFactory methods. The replacement {@link
159 * #newFactory(java.lang.String, java.lang.ClassLoader)}
160 * method defines no changes in behavior.
161 */
162 public static XMLEventFactory newInstance(String factoryId,
163 ClassLoader classLoader)
164 throws FactoryConfigurationError {
165 //do not fallback if given classloader can't find the class, throw exception
166 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
167 }
168
169 /**
170 * Create a new instance of the factory.
171 * If the classLoader argument is null, then the ContextClassLoader is used.
172 * <p>
173 * This method uses the following ordered lookup procedure to determine
174 * the XMLEventFactory implementation class to load:
175 * <ul>
176 * <li>
177 * Use the value of the system property identified by {@code factoryId}.
178 * </li>
179 * <li>
180 * <p>
181 * Use the configuration file "stax.properties". The file is in standard
182 * {@link java.util.Properties} format and typically located in the
183 * conf directory of the Java installation. It contains the fully qualified
184 * name of the implementation class with the key being the system property
185 * defined above.
186 *
187 * <p>
188 * The stax.properties file is read only once by the implementation
189 * and its values are then cached for future use. If the file does not exist
190 * when the first attempt is made to read from it, no further attempts are
191 * made to check for its existence. It is not possible to change the value
192 * of any property in stax.properties after it has been read for the first time.
193 *
194 * <p>
195 * Use the jaxp configuration file "jaxp.properties". The file is in the same
196 * format as stax.properties and will only be read if stax.properties does
197 * not exist.
198 * </li>
199 * <li>
200 * <p>
201 * If {@code factoryId} is "javax.xml.stream.XMLEventFactory",
202 * use the service-provider loading facility, defined by the
203 * {@link java.util.ServiceLoader} class, to attempt to {@linkplain
204 * java.util.ServiceLoader#load(java.lang.Class, java.lang.ClassLoader) locate and load}
205 * an implementation of the service using the specified {@code ClassLoader}.
206 * If {@code classLoader} is null, the {@linkplain
207 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
208 * That is, the service-provider loading facility will use the {@linkplain
209 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
210 * to attempt to load the service. If the context class
211 * loader is null, the {@linkplain
212 * ClassLoader#getSystemClassLoader() system class loader} will be used.
213 * </li>
214 * <li>
215 * <p>
216 * Otherwise, throws a {@link FactoryConfigurationError}.
217 * </li>
218 * </ul>
219 *
220 * <p>
221 * Note that this is a new method that replaces the deprecated
222 * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
223 * newInstance(String factoryId, ClassLoader classLoader)} method.
224 * No changes in behavior are defined by this replacement method relative
225 * to the deprecated method.
226 *
227 * @apiNote The parameter factoryId defined here is inconsistent with that
228 * of other JAXP factories where the first parameter is fully qualified
229 * factory class name that provides implementation of the factory.
230 *
231 * @param factoryId Name of the factory to find, same as
232 * a property name
233 * @param classLoader classLoader to use
234 * @return the factory implementation
235 * @throws FactoryConfigurationError in case of {@linkplain
236 * java.util.ServiceConfigurationError service configuration error} or if
237 * the implementation is not available or cannot be instantiated.
238 */
239 public static XMLEventFactory newFactory(String factoryId,
240 ClassLoader classLoader)
241 throws FactoryConfigurationError {
242 //do not fallback if given classloader can't find the class, throw exception
243 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
244 }
245
246 /**
247 * This method allows setting of the Location on each event that
248 * is created by this factory. The values are copied by value into
249 * the events created by this factory. To reset the location
250 * information set the location to null.
251 * @param location the location to set on each event created
252 */
253 public abstract void setLocation(Location location);
254
255 /**
256 * Create a new Attribute
257 * @param prefix the prefix of this attribute, may not be null
258 * @param namespaceURI the attribute value is set to this value, may not be null
259 * @param localName the local name of the XML name of the attribute, localName cannot be null
260 * @param value the attribute value to set, may not be null
261 * @return the Attribute with specified values
262 */
263 public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value);
264
265 /**
266 * Create a new Attribute
267 * @param localName the local name of the XML name of the attribute, localName cannot be null
268 * @param value the attribute value to set, may not be null
269 * @return the Attribute with specified values
270 */
271 public abstract Attribute createAttribute(String localName, String value);
272
273 /**
274 * Create a new Attribute
275 * @param name the qualified name of the attribute, may not be null
276 * @param value the attribute value to set, may not be null
277 * @return the Attribute with specified values
278 */
279 public abstract Attribute createAttribute(QName name, String value);
280
281 /**
282 * Create a new default Namespace
283 * @param namespaceURI the default namespace uri
284 * @return the Namespace with the specified value
285 */
286 public abstract Namespace createNamespace(String namespaceURI);
287
288 /**
289 * Create a new Namespace
290 * @param prefix the prefix of this namespace, may not be null
291 * @param namespaceUri the attribute value is set to this value, may not be null
292 * @return the Namespace with the specified values
293 */
294 public abstract Namespace createNamespace(String prefix, String namespaceUri);
295
296 /**
297 * Create a new StartElement. Namespaces can be added to this StartElement
298 * by passing in an Iterator that walks over a set of Namespace interfaces.
299 * Attributes can be added to this StartElement by passing an iterator
300 * that walks over a set of Attribute interfaces.
301 *
302 * @param name the qualified name of the attribute, may not be null
303 * @param attributes an optional unordered set of objects that
304 * implement Attribute to add to the new StartElement, may be null
305 * @param namespaces an optional unordered set of objects that
306 * implement Namespace to add to the new StartElement, may be null
307 * @return an instance of the requested StartElement
308 */
309 public abstract StartElement createStartElement(QName name,
310 Iterator attributes,
311 Iterator namespaces);
312
313 /**
314 * Create a new StartElement. This defaults the NamespaceContext to
315 * an empty NamespaceContext. Querying this event for its namespaces or
316 * attributes will result in an empty iterator being returned.
317 *
318 * @param namespaceUri the uri of the QName of the new StartElement
319 * @param localName the local name of the QName of the new StartElement
320 * @param prefix the prefix of the QName of the new StartElement
321 * @return an instance of the requested StartElement
322 */
323 public abstract StartElement createStartElement(String prefix,
324 String namespaceUri,
325 String localName);
326 /**
327 * Create a new StartElement. Namespaces can be added to this StartElement
328 * by passing in an Iterator that walks over a set of Namespace interfaces.
329 * Attributes can be added to this StartElement by passing an iterator
330 * that walks over a set of Attribute interfaces.
331 *
332 * @param namespaceUri the uri of the QName of the new StartElement
333 * @param localName the local name of the QName of the new StartElement
334 * @param prefix the prefix of the QName of the new StartElement
335 * @param attributes an unordered set of objects that implement
336 * Attribute to add to the new StartElement
337 * @param namespaces an unordered set of objects that implement
338 * Namespace to add to the new StartElement
339 * @return an instance of the requested StartElement
340 */
341 public abstract StartElement createStartElement(String prefix,
342 String namespaceUri,
343 String localName,
344 Iterator attributes,
345 Iterator namespaces
346 );
347 /**
348 * Create a new StartElement. Namespaces can be added to this StartElement
349 * by passing in an Iterator that walks over a set of Namespace interfaces.
350 * Attributes can be added to this StartElement by passing an iterator
351 * that walks over a set of Attribute interfaces.
352 *
353 * @param namespaceUri the uri of the QName of the new StartElement
354 * @param localName the local name of the QName of the new StartElement
355 * @param prefix the prefix of the QName of the new StartElement
356 * @param attributes an unordered set of objects that implement
357 * Attribute to add to the new StartElement, may be null
358 * @param namespaces an unordered set of objects that implement
359 * Namespace to add to the new StartElement, may be null
360 * @param context the namespace context of this element
361 * @return an instance of the requested StartElement
362 */
363 public abstract StartElement createStartElement(String prefix,
364 String namespaceUri,
365 String localName,
366 Iterator attributes,
367 Iterator namespaces,
368 NamespaceContext context
369 );
370
371 /**
372 * Create a new EndElement
373 * @param name the qualified name of the EndElement
374 * @param namespaces an optional unordered set of objects that
375 * implement Namespace that have gone out of scope, may be null
376 * @return an instance of the requested EndElement
377 */
378 public abstract EndElement createEndElement(QName name,
379 Iterator namespaces);
380
381 /**
382 * Create a new EndElement
383 * @param namespaceUri the uri of the QName of the new StartElement
384 * @param localName the local name of the QName of the new StartElement
385 * @param prefix the prefix of the QName of the new StartElement
386 * @return an instance of the requested EndElement
387 */
388 public abstract EndElement createEndElement(String prefix,
389 String namespaceUri,
390 String localName);
391 /**
392 * Create a new EndElement
393 * @param namespaceUri the uri of the QName of the new StartElement
394 * @param localName the local name of the QName of the new StartElement
395 * @param prefix the prefix of the QName of the new StartElement
396 * @param namespaces an unordered set of objects that implement
397 * Namespace that have gone out of scope, may be null
398 * @return an instance of the requested EndElement
399 */
400 public abstract EndElement createEndElement(String prefix,
401 String namespaceUri,
402 String localName,
403 Iterator namespaces);
404
405 /**
406 * Create a Characters event, this method does not check if the content
407 * is all whitespace. To create a space event use #createSpace(String)
408 * @param content the string to create
409 * @return a Characters event
410 */
411 public abstract Characters createCharacters(String content);
412
413 /**
414 * Create a Characters event with the CData flag set to true
415 * @param content the string to create
416 * @return a Characters event
417 */
418 public abstract Characters createCData(String content);
419
420 /**
421 * Create a Characters event with the isSpace flag set to true
422 * @param content the content of the space to create
423 * @return a Characters event
424 */
425 public abstract Characters createSpace(String content);
426 /**
427 * Create an ignorable space
428 * @param content the space to create
429 * @return a Characters event
430 */
431 public abstract Characters createIgnorableSpace(String content);
432
433 /**
434 * Creates a new instance of a StartDocument event
435 * @return a StartDocument event
436 */
437 public abstract StartDocument createStartDocument();
438
439 /**
440 * Creates a new instance of a StartDocument event
441 *
442 * @param encoding the encoding style
443 * @param version the XML version
444 * @param standalone the status of standalone may be set to "true" or "false"
445 * @return a StartDocument event
446 */
447 public abstract StartDocument createStartDocument(String encoding,
448 String version,
449 boolean standalone);
450
451 /**
452 * Creates a new instance of a StartDocument event
453 *
454 * @param encoding the encoding style
455 * @param version the XML version
456 * @return a StartDocument event
457 */
458 public abstract StartDocument createStartDocument(String encoding,
459 String version);
460
461 /**
462 * Creates a new instance of a StartDocument event
463 *
464 * @param encoding the encoding style
465 * @return a StartDocument event
466 */
467 public abstract StartDocument createStartDocument(String encoding);
468
469 /**
470 * Creates a new instance of an EndDocument event
471 * @return an EndDocument event
472 */
473 public abstract EndDocument createEndDocument();
474
475 /** Creates a new instance of a EntityReference event
476 *
477 * @param name The name of the reference
478 * @param declaration the declaration for the event
479 * @return an EntityReference event
480 */
481 public abstract EntityReference createEntityReference(String name,
482 EntityDeclaration declaration);
483 /**
484 * Create a comment
485 * @param text The text of the comment
486 * a Comment event
487 */
488 public abstract Comment createComment(String text);
489
490 /**
491 * Create a processing instruction
492 * @param target The target of the processing instruction
493 * @param data The text of the processing instruction
494 * @return a ProcessingInstruction event
495 */
496 public abstract ProcessingInstruction createProcessingInstruction(String target,
497 String data);
498
499 /**
500 * Create a document type definition event
501 * This string contains the entire document type declaration that matches
502 * the doctypedecl in the XML 1.0 specification
503 * @param dtd the text of the document type definition
504 * @return a DTD event
505 */
506 public abstract DTD createDTD(String dtd);
507 }