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