141 * Create a new instance of the factory.
142 * If the classLoader argument is null, then the ContextClassLoader is used.
143 * <p>
144 * This method uses the following ordered lookup procedure to determine
145 * the XMLEventFactory implementation class to load:
146 * </p>
147 * <ul>
148 * <li>
149 * Use the value of the system property identified by {@code factoryId}.
150 * </li>
151 * <li>
152 * Use the properties file "lib/stax.properties" in the JRE directory.
153 * This configuration file is in standard java.util.Properties format
154 * and contains the fully qualified name of the implementation class
155 * with the key being the given {@code factoryId}.
156 * </li>
157 * <li>
158 * If {@code factoryId} is "javax.xml.stream.XMLEventFactory",
159 * use the service-provider loading facilities, defined by the
160 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
161 * implementation of the service using the {@linkplain
162 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism}:
163 * the service-provider loading facility will use the {@linkplain
164 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
165 * to attempt to load the service. If the context class
166 * loader is null, the {@linkplain
167 * ClassLoader#getSystemClassLoader() system class loader} will be used.
168 * </li>
169 * <li>
170 * Otherwise, throws a {@link FactoryConfigurationError}.
171 * </li>
172 * </ul>
173 *
174 * <p>
175 * Note that this is a new method that replaces the deprecated
176 * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
177 * newInstance(String factoryId, ClassLoader classLoader)} method.
178 * No changes in behavior are defined by this replacement method relative
179 * to the deprecated method.
180 * </p>
181 *
182 * @param factoryId Name of the factory to find, same as
183 * a property name
184 * @param classLoader classLoader to use
185 * @return the factory implementation
186 * @throws FactoryConfigurationError in case of {@linkplain
187 * java.util.ServiceConfigurationError service configuration error} or if
188 * the implementation is not available or cannot be instantiated.
189 */
190 public static XMLEventFactory newFactory(String factoryId,
191 ClassLoader classLoader)
192 throws FactoryConfigurationError {
193 //do not fallback if given classloader can't find the class, throw exception
194 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
195 }
196
197 /**
198 * This method allows setting of the Location on each event that
199 * is created by this factory. The values are copied by value into
200 * the events created by this factory. To reset the location
201 * information set the location to null.
|
141 * Create a new instance of the factory.
142 * If the classLoader argument is null, then the ContextClassLoader is used.
143 * <p>
144 * This method uses the following ordered lookup procedure to determine
145 * the XMLEventFactory implementation class to load:
146 * </p>
147 * <ul>
148 * <li>
149 * Use the value of the system property identified by {@code factoryId}.
150 * </li>
151 * <li>
152 * Use the properties file "lib/stax.properties" in the JRE directory.
153 * This configuration file is in standard java.util.Properties format
154 * and contains the fully qualified name of the implementation class
155 * with the key being the given {@code factoryId}.
156 * </li>
157 * <li>
158 * If {@code factoryId} is "javax.xml.stream.XMLEventFactory",
159 * use the service-provider loading facilities, defined by the
160 * {@link java.util.ServiceLoader} class, to attempt to locate and load an
161 * implementation of the service using the specified {@code ClassLoader}.
162 * If {@code classLoader} is null, the {@linkplain
163 * java.util.ServiceLoader#load(java.lang.Class) default loading mechanism} will apply:
164 * That is, the service-provider loading facility will use the {@linkplain
165 * java.lang.Thread#getContextClassLoader() current thread's context class loader}
166 * to attempt to load the service. If the context class
167 * loader is null, the {@linkplain
168 * ClassLoader#getSystemClassLoader() system class loader} will be used.
169 * </li>
170 * <li>
171 * Otherwise, throws a {@link FactoryConfigurationError}.
172 * </li>
173 * </ul>
174 *
175 * <p>
176 * Note that this is a new method that replaces the deprecated
177 * {@link #newInstance(java.lang.String, java.lang.ClassLoader)
178 * newInstance(String factoryId, ClassLoader classLoader)} method.
179 * No changes in behavior are defined by this replacement method relative
180 * to the deprecated method.
181 * </p>
182 *
183 * @apiNote The parameter factoryId defined here is inconsistent with that
184 * of other JAXP factories where the first parameter is fully qualified
185 * factory class name that provides implementation of the factory.
186 *
187 * @param factoryId Name of the factory to find, same as
188 * a property name
189 * @param classLoader classLoader to use
190 * @return the factory implementation
191 * @throws FactoryConfigurationError in case of {@linkplain
192 * java.util.ServiceConfigurationError service configuration error} or if
193 * the implementation is not available or cannot be instantiated.
194 */
195 public static XMLEventFactory newFactory(String factoryId,
196 ClassLoader classLoader)
197 throws FactoryConfigurationError {
198 //do not fallback if given classloader can't find the class, throw exception
199 return FactoryFinder.find(XMLEventFactory.class, factoryId, classLoader, null);
200 }
201
202 /**
203 * This method allows setting of the Location on each event that
204 * is created by this factory. The values are copied by value into
205 * the events created by this factory. To reset the location
206 * information set the location to null.
|