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