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
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>
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 *
129 * @throws FactoryConfigurationError in case of {@linkplain
130 * java.util.ServiceConfigurationError service configuration error} or if
131 * the implementation is not available or cannot be instantiated.
132 */
133 public static XMLEventFactory newFactory()
134 throws FactoryConfigurationError
135 {
136 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
137 }
138
139 /**
140 * Create a new instance of the factory
141 *
142 * @param factoryId Name of the factory to find, same as
143 * a property name
144 * @param classLoader classLoader to use
145 * @return the factory implementation
146 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
147 *
148 * @deprecated This method has been deprecated to maintain API consistency.
457 * @param encoding the encoding style
458 * @return a StartDocument event
459 */
460 public abstract StartDocument createStartDocument(String encoding);
461
462 /**
463 * Creates a new instance of an EndDocument event
464 * @return an EndDocument event
465 */
466 public abstract EndDocument createEndDocument();
467
468 /** Creates a new instance of a EntityReference event
469 *
470 * @param name The name of the reference
471 * @param declaration the declaration for the event
472 * @return an EntityReference event
473 */
474 public abstract EntityReference createEntityReference(String name,
475 EntityDeclaration declaration);
476 /**
477 * Create a comment
478 * @param text The text of the comment
479 * a Comment event
480 */
481 public abstract Comment createComment(String text);
482
483 /**
484 * Create a processing instruction
485 * @param target The target of the processing instruction
486 * @param data The text of the processing instruction
487 * @return a ProcessingInstruction event
488 */
489 public abstract ProcessingInstruction createProcessingInstruction(String target,
490 String data);
491
492 /**
493 * Create a document type definition event
494 * This string contains the entire document type declaration that matches
495 * the doctypedecl in the XML 1.0 specification
496 * @param dtd the text of the document type definition
497 * @return a DTD event
498 */
499 public abstract DTD createDTD(String dtd);
|
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
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 static final String JAXPFACTORYID = "javax.xml.stream.XMLEventFactory";
49 static final String DEFAULIMPL = "com.sun.xml.internal.stream.events.XMLEventFactoryImpl";
50
51 /**
52 * Protected constructor to prevent instantiation.
53 * Use {@link #newFactory()} instead.
54 */
55 protected XMLEventFactory(){}
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 *
74 * @return an instance of the {@code XMLEventFactory}
75 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
76 */
77 public static XMLEventFactory newInstance()
78 throws FactoryConfigurationError
79 {
80 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
81 }
82
83 /**
84 * Create a new instance of the factory.
85 * <p>
86 * This static method creates a new factory instance.
87 * This method uses the following ordered lookup procedure to determine
88 * the XMLEventFactory implementation class to load:
89 * <ul>
90 * <li>
91 * Use the javax.xml.stream.XMLEventFactory system property.
92 * </li>
93 * <li>
94 * <p>
115 * Use the service-provider loading facility, defined by the
116 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
117 * implementation of the service using the {@linkplain
118 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
119 * the service-provider loading facility will use the {@linkplain
120 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
121 * to attempt to load the service. If the context class
122 * loader is null, the {@linkplain
123 * ClassLoader#getSystemClassLoader() system class loader} will be used.
124 * </li>
125 * <li>
126 * <p>
127 * Otherwise, the {@linkplain #newDefaultFactory() system-default}
128 * implementation is returned.
129 * </li>
130 * </ul>
131 * <p>
132 * Once an application has obtained a reference to a XMLEventFactory it
133 * can use the factory to configure and obtain stream instances.
134 *
135 * @return an instance of the {@code XMLEventFactory}
136 * @throws FactoryConfigurationError in case of {@linkplain
137 * java.util.ServiceConfigurationError service configuration error} or if
138 * the implementation is not available or cannot be instantiated.
139 */
140 public static XMLEventFactory newFactory()
141 throws FactoryConfigurationError
142 {
143 return FactoryFinder.find(XMLEventFactory.class, DEFAULIMPL);
144 }
145
146 /**
147 * Create a new instance of the factory
148 *
149 * @param factoryId Name of the factory to find, same as
150 * a property name
151 * @param classLoader classLoader to use
152 * @return the factory implementation
153 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
154 *
155 * @deprecated This method has been deprecated to maintain API consistency.
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 * @return 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);
|