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 * Create a new instance of the factory
58 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
59 */
60 public static XMLEventFactory newInstance()
61 throws FactoryConfigurationError
62 {
63 return (XMLEventFactory) FactoryFinder.find(
64 JAXPFACTORYID,
65 DEFAULIMPL);
66 }
67
68 /**
69 * Create a new instance of the factory.
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 * Use the javax.xml.stream.XMLEventFactory system property.
74 * Use the properties file "lib/stax.properties" in the JRE directory.
75 * This configuration file is in standard java.util.Properties format
76 * and contains the fully qualified name of the implementation class
77 * with the key being the system property defined above.
78 * Use the Services API (as detailed in the JAR specification), if available,
79 * to determine the classname. The Services API will look for a classname
80 * in the file META-INF/services/javax.xml.stream.XMLEventFactory in jars
81 * available to the runtime.
82 * Platform default XMLEventFactory instance.
83 *
84 * Once an application has obtained a reference to a XMLEventFactory it
85 * can use the factory to configure and obtain stream instances.
86 *
87 * Note that this is a new method that replaces the deprecated newInstance() method.
88 * No changes in behavior are defined by this replacement method relative to
89 * the deprecated method.
90 *
91 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
92 */
93 public static XMLEventFactory newFactory()
94 throws FactoryConfigurationError
95 {
96 return (XMLEventFactory) FactoryFinder.find(
97 JAXPFACTORYID,
98 DEFAULIMPL);
99 }
100
101 /**
102 * Create a new instance of the factory
103 *
104 * @param factoryId Name of the factory to find, same as
105 * a property name
106 * @param classLoader classLoader to use
107 * @return the factory implementation
108 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
109 *
110 * @deprecated This method has been deprecated to maintain API consistency.
111 * All newInstance methods have been replaced with corresponding
112 * newFactory methods. The replacement {@link
113 * #newFactory(java.lang.String, java.lang.ClassLoader)}
114 * method defines no changes in behavior.
115 */
116 public static XMLEventFactory newInstance(String factoryId,
117 ClassLoader classLoader)
118 throws FactoryConfigurationError {
119 try {
120 //do not fallback if given classloader can't find the class, throw exception
121 return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null);
122 } catch (FactoryFinder.ConfigurationError e) {
123 throw new FactoryConfigurationError(e.getException(),
124 e.getMessage());
125 }
126 }
127
128 /**
129 * Create a new instance of the factory.
130 * If the classLoader argument is null, then the ContextClassLoader is used.
131 *
132 * Note that this is a new method that replaces the deprecated
133 * newInstance(String factoryId, ClassLoader classLoader) method.
134 * No changes in behavior are defined by this replacement method relative
135 * to the deprecated method.
136 *
137 * @param factoryId Name of the factory to find, same as
138 * a property name
139 * @param classLoader classLoader to use
140 * @return the factory implementation
141 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
142 */
143 public static XMLEventFactory newFactory(String factoryId,
144 ClassLoader classLoader)
145 throws FactoryConfigurationError {
146 try {
147 //do not fallback if given classloader can't find the class, throw exception
148 return (XMLEventFactory) FactoryFinder.find(factoryId, classLoader, null);
149 } catch (FactoryFinder.ConfigurationError e) {
150 throw new FactoryConfigurationError(e.getException(),
151 e.getMessage());
152 }
153 }
154
155 /**
156 * This method allows setting of the Location on each event that
157 * is created by this factory. The values are copied by value into
158 * the events created by this factory. To reset the location
159 * information set the location to null.
160 * @param location the location to set on each event created
161 */
162 public abstract void setLocation(Location location);
163
164 /**
165 * Create a new Attribute
166 * @param prefix the prefix of this attribute, may not be null
167 * @param namespaceURI the attribute value is set to this value, may not be null
168 * @param localName the local name of the XML name of the attribute, localName cannot be null
169 * @param value the attribute value to set, may not be null
170 * @return the Attribute with specified values
171 */
172 public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value);
|
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 * Create a new instance of the factory
58 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
59 */
60 public static XMLEventFactory newInstance()
61 throws FactoryConfigurationError
62 {
63 return (XMLEventFactory) FactoryFinder.find(XMLEventFactory.class,
64 JAXPFACTORYID,
65 DEFAULIMPL);
66 }
67
68 /**
69 * <p>Create a new instance of the factory.</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 * <ul>
74 * <li>
75 * Use the javax.xml.stream.XMLEventFactory system property.
76 * </li>
77 * <li>
78 * Use the properties file "lib/stax.properties" in the JRE directory.
79 * This configuration file is in standard java.util.Properties format
80 * and contains the fully qualified name of the implementation class
81 * with the key being the system property defined above.
82 * </li>
83 * <li>
84 * <p>Uses the service-provider loading facilities, defined by the {@link java.util.ServiceLoader} class, to attempt
85 * to locate and load an implementation of the service. In case of multiple providers, the first non-default implementation
86 * shall be instantiated and returned. The default implementation is returned if it is the only one
87 * found by the service loader.</p>
88 * <p>
89 * If a misconfigured provider is encountered and {@link java.util.ServiceConfigurationError} is thrown, the error will be wrapped
90 * in a {@link javax.xml.stream.FactoryConfigurationError}.</p>
91 * </li>
92 * <li>
93 * Platform default XMLEventFactory instance.
94 *</li>
95 * </ul>
96 *
97 * Once an application has obtained a reference to a XMLEventFactory it
98 * can use the factory to configure and obtain stream instances.
99 *
100 * Note that this is a new method that replaces the deprecated newInstance() method.
101 * No changes in behavior are defined by this replacement method relative to
102 * the deprecated method.
103 *
104 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
105 */
106 public static XMLEventFactory newFactory()
107 throws FactoryConfigurationError
108 {
109 return (XMLEventFactory) FactoryFinder.find(XMLEventFactory.class,
110 JAXPFACTORYID,
111 DEFAULIMPL);
112 }
113
114 /**
115 * Create a new instance of the factory
116 *
117 * @param factoryId Name of the factory to find, same as
118 * a property name
119 * @param classLoader classLoader to use
120 * @return the factory implementation
121 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded
122 *
123 * @deprecated This method has been deprecated to maintain API consistency.
124 * All newInstance methods have been replaced with corresponding
125 * newFactory methods. The replacement {@link
126 * #newFactory(java.lang.String, java.lang.ClassLoader)}
127 * method defines no changes in behavior.
128 */
129 public static XMLEventFactory newInstance(String factoryId,
130 ClassLoader classLoader)
131 throws FactoryConfigurationError {
132 //do not fallback if given classloader can't find the class, throw exception
133 return (XMLEventFactory) FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
134
135 }
136
137 /**
138 * Create a new instance of the factory.
139 * If the classLoader argument is null, then the ContextClassLoader is used.
140 *
141 * Note that this is a new method that replaces the deprecated
142 * newInstance(String factoryId, ClassLoader classLoader) method.
143 * No changes in behavior are defined by this replacement method relative
144 * to the deprecated method.
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 public static XMLEventFactory newFactory(String factoryId,
153 ClassLoader classLoader)
154 throws FactoryConfigurationError {
155 //do not fallback if given classloader can't find the class, throw exception
156 return (XMLEventFactory) FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
157
158 }
159
160 /**
161 * This method allows setting of the Location on each event that
162 * is created by this factory. The values are copied by value into
163 * the events created by this factory. To reset the location
164 * information set the location to null.
165 * @param location the location to set on each event created
166 */
167 public abstract void setLocation(Location location);
168
169 /**
170 * Create a new Attribute
171 * @param prefix the prefix of this attribute, may not be null
172 * @param namespaceURI the attribute value is set to this value, may not be null
173 * @param localName the local name of the XML name of the attribute, localName cannot be null
174 * @param value the attribute value to set, may not be null
175 * @return the Attribute with specified values
176 */
177 public abstract Attribute createAttribute(String prefix, String namespaceURI, String localName, String value);
|