118 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl"; |
118 static final String DEFAULIMPL = "com.sun.xml.internal.stream.XMLOutputFactoryImpl"; |
119 |
119 |
120 protected XMLOutputFactory(){} |
120 protected XMLOutputFactory(){} |
121 |
121 |
122 /** |
122 /** |
123 * Create a new instance of the factory. |
123 * Creates a new instance of the factory in exactly the same manner as the |
|
124 * {@link #newFactory()} method. |
124 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded |
125 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded |
125 */ |
126 */ |
126 public static XMLOutputFactory newInstance() |
127 public static XMLOutputFactory newInstance() |
127 throws FactoryConfigurationError |
128 throws FactoryConfigurationError |
128 { |
129 { |
129 return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory", |
130 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL); |
130 DEFAULIMPL); |
|
131 } |
131 } |
132 |
132 |
133 /** |
133 /** |
134 * Create a new instance of the factory. |
134 * Create a new instance of the factory. |
|
135 * <p> |
135 * This static method creates a new factory instance. This method uses the |
136 * This static method creates a new factory instance. This method uses the |
136 * following ordered lookup procedure to determine the XMLOutputFactory |
137 * following ordered lookup procedure to determine the XMLOutputFactory |
137 * implementation class to load: |
138 * implementation class to load: |
|
139 * </p> |
|
140 * <ul> |
|
141 * <li> |
138 * Use the javax.xml.stream.XMLOutputFactory system property. |
142 * Use the javax.xml.stream.XMLOutputFactory system property. |
|
143 * </li> |
|
144 * <li> |
139 * Use the properties file "lib/stax.properties" in the JRE directory. |
145 * Use the properties file "lib/stax.properties" in the JRE directory. |
140 * This configuration file is in standard java.util.Properties format |
146 * This configuration file is in standard java.util.Properties format |
141 * and contains the fully qualified name of the implementation class |
147 * and contains the fully qualified name of the implementation class |
142 * with the key being the system property defined above. |
148 * with the key being the system property defined above. |
143 * Use the Services API (as detailed in the JAR specification), if available, |
149 * </li> |
144 * to determine the classname. The Services API will look for a classname |
150 * <li> |
145 * in the file META-INF/services/javax.xml.stream.XMLOutputFactory in jars |
151 * Use the service-provider loading facilities, defined by the |
146 * available to the runtime. |
152 * {@link java.util.ServiceLoader} class, to attempt to locate and load an |
147 * Platform default XMLOutputFactory instance. |
153 * implementation of the service. |
148 * |
154 * </li> |
|
155 * <li> |
|
156 * Otherwise, the system-default implementation is returned. |
|
157 * </li> |
|
158 * <p> |
149 * Once an application has obtained a reference to a XMLOutputFactory it |
159 * Once an application has obtained a reference to a XMLOutputFactory it |
150 * can use the factory to configure and obtain stream instances. |
160 * can use the factory to configure and obtain stream instances. |
151 * |
161 * </p> |
|
162 * <p> |
152 * Note that this is a new method that replaces the deprecated newInstance() method. |
163 * Note that this is a new method that replaces the deprecated newInstance() method. |
153 * No changes in behavior are defined by this replacement method relative to the |
164 * No changes in behavior are defined by this replacement method relative to the |
154 * deprecated method. |
165 * deprecated method. |
155 * |
166 * </p> |
156 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded |
167 * @throws FactoryConfigurationError in case of {@linkplain |
|
168 * java.util.ServiceConfigurationError service configuration error} or if |
|
169 * the implementation is not available or cannot be instantiated. |
157 */ |
170 */ |
158 public static XMLOutputFactory newFactory() |
171 public static XMLOutputFactory newFactory() |
159 throws FactoryConfigurationError |
172 throws FactoryConfigurationError |
160 { |
173 { |
161 return (XMLOutputFactory) FactoryFinder.find("javax.xml.stream.XMLOutputFactory", |
174 return FactoryFinder.find(XMLOutputFactory.class, DEFAULIMPL); |
162 DEFAULIMPL); |
|
163 } |
175 } |
164 |
176 |
165 /** |
177 /** |
166 * Create a new instance of the factory. |
178 * Create a new instance of the factory. |
167 * |
179 * |
177 * java.lang.ClassLoader)} instead. |
189 * java.lang.ClassLoader)} instead. |
178 */ |
190 */ |
179 public static XMLInputFactory newInstance(String factoryId, |
191 public static XMLInputFactory newInstance(String factoryId, |
180 ClassLoader classLoader) |
192 ClassLoader classLoader) |
181 throws FactoryConfigurationError { |
193 throws FactoryConfigurationError { |
182 try { |
194 //do not fallback if given classloader can't find the class, throw exception |
183 //do not fallback if given classloader can't find the class, throw exception |
195 return FactoryFinder.find(XMLInputFactory.class, factoryId, classLoader, null); |
184 return (XMLInputFactory) FactoryFinder.find(factoryId, classLoader, null); |
|
185 } catch (FactoryFinder.ConfigurationError e) { |
|
186 throw new FactoryConfigurationError(e.getException(), |
|
187 e.getMessage()); |
|
188 } |
|
189 } |
196 } |
190 |
197 |
191 /** |
198 /** |
192 * Create a new instance of the factory. |
199 * Create a new instance of the factory. |
193 * If the classLoader argument is null, then the ContextClassLoader is used. |
200 * If the classLoader argument is null, then the ContextClassLoader is used. |
194 * |
201 * <p> |
|
202 * This method uses the following ordered lookup procedure to determine |
|
203 * the XMLOutputFactory implementation class to load: |
|
204 * </p> |
|
205 * <ul> |
|
206 * <li> |
|
207 * Use the value of the system property identified by {@code factoryId}. |
|
208 * </li> |
|
209 * <li> |
|
210 * Use the properties file "lib/stax.properties" in the JRE directory. |
|
211 * This configuration file is in standard java.util.Properties format |
|
212 * and contains the fully qualified name of the implementation class |
|
213 * with the key being the given {@code factoryId}. |
|
214 * </li> |
|
215 * <li> |
|
216 * If {@code factoryId} is "javax.xml.stream.XMLOutputFactory", |
|
217 * use the service-provider loading facilities, defined by the |
|
218 * {@link java.util.ServiceLoader} class, to attempt to locate and load an |
|
219 * implementation of the service. |
|
220 * </li> |
|
221 * <li> |
|
222 * Otherwise, throws a {@link FactoryConfigurationError}. |
|
223 * </li> |
|
224 * </ul> |
|
225 * |
|
226 * <p> |
195 * Note that this is a new method that replaces the deprecated |
227 * Note that this is a new method that replaces the deprecated |
196 * newInstance(String factoryId, ClassLoader classLoader) method. |
228 * {@link #newInstance(java.lang.String, java.lang.ClassLoader) |
197 * |
229 * newInstance(String factoryId, ClassLoader classLoader)} method. |
198 * No changes in behavior are defined by this replacement method relative |
230 * No changes in behavior are defined by this replacement method relative |
199 * to the deprecated method. |
231 * to the deprecated method. |
200 * |
232 * </p> |
201 * |
233 * |
202 * @param factoryId Name of the factory to find, same as |
234 * @param factoryId Name of the factory to find, same as |
203 * a property name |
235 * a property name |
204 * @param classLoader classLoader to use |
236 * @param classLoader classLoader to use |
205 * @return the factory implementation |
237 * @return the factory implementation |
206 * @throws FactoryConfigurationError if an instance of this factory cannot be loaded |
238 * @throws FactoryConfigurationError in case of {@linkplain |
|
239 * java.util.ServiceConfigurationError service configuration error} or if |
|
240 * the implementation is not available or cannot be instantiated. |
207 */ |
241 */ |
208 public static XMLOutputFactory newFactory(String factoryId, |
242 public static XMLOutputFactory newFactory(String factoryId, |
209 ClassLoader classLoader) |
243 ClassLoader classLoader) |
210 throws FactoryConfigurationError { |
244 throws FactoryConfigurationError { |
211 try { |
245 //do not fallback if given classloader can't find the class, throw exception |
212 //do not fallback if given classloader can't find the class, throw exception |
246 return FactoryFinder.find(XMLOutputFactory.class, factoryId, classLoader, null); |
213 return (XMLOutputFactory) FactoryFinder.find(factoryId, classLoader, null); |
|
214 } catch (FactoryFinder.ConfigurationError e) { |
|
215 throw new FactoryConfigurationError(e.getException(), |
|
216 e.getMessage()); |
|
217 } |
|
218 } |
247 } |
219 |
248 |
220 /** |
249 /** |
221 * Create a new XMLStreamWriter that writes to a writer |
250 * Create a new XMLStreamWriter that writes to a writer |
222 * @param stream the writer to write to |
251 * @param stream the writer to write to |