1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387
/* * The contents of this file are subject to the terms * of the Common Development and Distribution License * (the "License"). You may not use this file except * in compliance with the License. * * You can obtain a copy of the license at * https://jaxp.dev.java.net/CDDLv1.0.html. * See the License for the specific language governing * permissions and limitations under the License. * * When distributing Covered Code, include this CDDL * HEADER in each file and include the License file at * https://jaxp.dev.java.net/CDDLv1.0.html * If applicable add the following below this CDDL HEADER * with the fields enclosed by brackets "[]" replaced with * your own identifying information: Portions Copyright * [year] [name of copyright owner] */ /* * $Id: XPathFactory.java,v 1.4 2005/11/03 19:34:16 jeffsuttor Exp $ * @(#)XPathFactory.java 1.18 06/06/21 * * Copyright 2005 Sun Microsystems, Inc. All Rights Reserved. */ package javax.xml.xpath; /** * <p>An <code>XPathFactory</code> instance can be used to create * {@link javax.xml.xpath.XPath} objects.</p> * *<p>See {@link #newInstance(String uri)} for lookup mechanism.</p> * * <p>The {@link XPathFactory} class is not thread-safe. In other words, * it is the application's responsibility to ensure that at most * one thread is using a {@link XPathFactory} object at any * given moment. Implementations are encouraged to mark methods * as <code>synchronized</code> to protect themselves from broken clients. * * <p>{@link XPathFactory} is not re-entrant. While one of the * <code>newInstance</code> methods is being invoked, applications * may not attempt to recursively invoke a <code>newInstance</code> method, * even from the same thread. * * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> * * @version $Revision: 1.4 $, $Date: 2005/11/03 19:34:16 $ * @since 1.5 */ public abstract class XPathFactory { /** * <p>The default property name according to the JAXP spec.</p> */ public static final String DEFAULT_PROPERTY_NAME = "javax.xml.xpath.XPathFactory"; /** * <p>Default Object Model URI.</p> */ public static final String DEFAULT_OBJECT_MODEL_URI = "http://java.sun.com/jaxp/xpath/dom"; /** *<p> Take care of restrictions imposed by java security model </p> */ private static SecuritySupport ss = new SecuritySupport() ; /** * <p>Protected constructor as {@link #newInstance()} or {@link #newInstance(String uri)} * or {@link #newInstance(String uri, String factoryClassName, ClassLoader classLoader)} * should be used to create a new instance of an <code>XPathFactory</code>.</p> */ protected XPathFactory() { } /** * <p>Get a new <code>XPathFactory</code> instance using the default object model, * {@link #DEFAULT_OBJECT_MODEL_URI}, * the W3C DOM.</p> * * <p>This method is functionally equivalent to:</p> * <pre> * newInstance(DEFAULT_OBJECT_MODEL_URI) * </pre> * * <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p> * * @return Instance of an <code>XPathFactory</code>. * * @throws RuntimeException When there is a failure in creating an * <code>XPathFactory</code> for the default object model. */ public static final XPathFactory newInstance() { try { return newInstance(DEFAULT_OBJECT_MODEL_URI); } catch (XPathFactoryConfigurationException xpathFactoryConfigurationException) { throw new RuntimeException( "XPathFactory#newInstance() failed to create an XPathFactory for the default object model: " + DEFAULT_OBJECT_MODEL_URI + " with the XPathFactoryConfigurationException: " + xpathFactoryConfigurationException.toString() ); } } /** * <p>Get a new <code>XPathFactory</code> instance using the specified object model.</p> * * <p>To find a <code>XPathFactory</code> object, * this method looks the following places in the following order where "the class loader" refers to the context class loader:</p> * <ol> * <li> * If the system property {@link #DEFAULT_PROPERTY_NAME} + ":uri" is present, * where uri is the parameter to this method, then its value is read as a class name. * The method will try to create a new instance of this class by using the class loader, * and returns it if it is successfully created. * </li> * <li> * MISSING_VALUE !/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for. * If present, the value is processed just like above. * </li> * <li> * The class loader is asked for service provider provider-configuration files matching <code>javax.xml.xpath.XPathFactory</code> * in the resource directory META-INF/services. * See the JAR File Specification for file format and parsing rules. * Each potential service provider is required to implement the method: * <pre> * {@link #isObjectModelSupported(String objectModel)} * </pre> * The first service provider found in class loader order that supports the specified object model is returned. * </li> * <li> * Platform default <code>XPathFactory</code> is located in a platform specific way. * There must be a platform default XPathFactory for the W3C DOM, i.e. {@link #DEFAULT_OBJECT_MODEL_URI}. * </li> * </ol> * <p>If everything fails, an <code>XPathFactoryConfigurationException</code> will be thrown.</p> * * <p>Tip for Trouble-shooting:</p> * <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed. * In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it. * For example:</p> * <pre> * http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory * </pre> * * @param uri Identifies the underlying object model. * The specification only defines the URI {@link #DEFAULT_OBJECT_MODEL_URI}, * <code>http://java.sun.com/jaxp/xpath/dom</code> for the W3C DOM, * the org.w3c.dom package, and implementations are free to introduce other URIs for other object models. * * @return Instance of an <code>XPathFactory</code>. * * @throws XPathFactoryConfigurationException If the specified object model is unavailable. * @throws NullPointerException If <code>uri</code> is <code>null</code>. * @throws IllegalArgumentException If <code>uri</code> is <code>null</code> * or <code>uri.length() == 0</code>. */ public static final XPathFactory newInstance(final String uri) throws XPathFactoryConfigurationException { if (uri == null) { throw new NullPointerException( "XPathFactory#newInstance(String uri) cannot be called with uri == null" ); } if (uri.length() == 0) { throw new IllegalArgumentException( "XPathFactory#newInstance(String uri) cannot be called with uri == \"\"" ); } ClassLoader classLoader = ss.getContextClassLoader(); if (classLoader == null) { //use the current class loader classLoader = XPathFactory.class.getClassLoader(); } XPathFactory xpathFactory = new XPathFactoryFinder(classLoader).newFactory(uri); if (xpathFactory == null) { throw new XPathFactoryConfigurationException( "No XPathFactory implementation found for the object model: " + uri ); } return xpathFactory; } /** * <p>Obtain a new instance of a <code>XPathFactory</code> from a factory class name. <code>XPathFactory</code> * is returned if specified factory class supports the specified object model. * This function is useful when there are multiple providers in the classpath. * It gives more control to the application as it can specify which provider * should be loaded.</p> * * * <h2>Tip for Trouble-shooting</h2> * <p>Setting the <code>jaxp.debug</code> system property will cause * this method to print a lot of debug messages * to <code>System.err</code> about what it is doing and where it is looking at.</p> * * <p> If you have problems try:</p> * <pre> * java -Djaxp.debug=1 YourProgram .... * </pre> * * @param uri Identifies the underlying object model. The specification only defines the URI * {@link #DEFAULT_OBJECT_MODEL_URI},<code>http://java.sun.com/jaxp/xpath/dom</code> * for the W3C DOM, the org.w3c.dom package, and implementations are free to introduce * other URIs for other object models. * * @param factoryClassName fully qualified factory class name that provides implementation of <code>javax.xml.xpath.XPathFactory</code>. * * @param classLoader <code>ClassLoader</code> used to load the factory class. If <code>null</code> * current <code>Thread</code>'s context classLoader is used to load the factory class. * * * @return New instance of a <code>XPathFactory</code> * * @throws XPathFactoryConfigurationException * if <code>factoryClassName</code> is <code>null</code>, or * the factory class cannot be loaded, instantiated * or the factory class does not support the object model specified * in the <code>uri</code> parameter. * * @throws NullPointerException If <code>uri</code> is <code>null</code>. * @throws IllegalArgumentException If <code>uri</code> is <code>null</code> * or <code>uri.length() == 0</code>. * * @see #newInstance() * @see #newInstance(String uri) * * @since 1.6 */ public static XPathFactory newInstance(String uri, String factoryClassName, ClassLoader classLoader) throws XPathFactoryConfigurationException{ ClassLoader cl = classLoader; if (uri == null) { throw new NullPointerException( "XPathFactory#newInstance(String uri) cannot be called with uri == null" ); } if (uri.length() == 0) { throw new IllegalArgumentException( "XPathFactory#newInstance(String uri) cannot be called with uri == \"\"" ); } if (cl == null) { cl = ss.getContextClassLoader(); } XPathFactory f = new XPathFactoryFinder(cl).createInstance(factoryClassName); if (f == null) { throw new XPathFactoryConfigurationException( "No XPathFactory implementation found for the object model: " + uri ); } //if this factory supports the given schemalanguage return this factory else thrown exception if(f.isObjectModelSupported(uri)){ return f; }else{ throw new XPathFactoryConfigurationException("Factory " + factoryClassName + " doesn't support given " + uri + " object model"); } } /** * <p>Is specified object model supported by this <code>XPathFactory</code>?</p> * * @param objectModel Specifies the object model which the returned <code>XPathFactory</code> will understand. * * @return <code>true</code> if <code>XPathFactory</code> supports <code>objectModel</code>, else <code>false</code>. * * @throws NullPointerException If <code>objectModel</code> is <code>null</code>. * @throws IllegalArgumentException If <code>objectModel.length() == 0</code>. */ public abstract boolean isObjectModelSupported(String objectModel); /** * <p>Set a feature for this <code>XPathFactory</code> and * <code>XPath</code>s created by this factory.</p> * * <p> * Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * An {@link XPathFactoryConfigurationException} is thrown if this * <code>XPathFactory</code> or the <code>XPath</code>s * it creates cannot support the feature. * It is possible for an <code>XPathFactory</code> to expose a feature value * but be unable to change its state. * </p> * * <p> * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. * When the feature is <code>true</code>, any reference to an external function is an error. * Under these conditions, the implementation must not call the {@link XPathFunctionResolver} * and must throw an {@link XPathFunctionException}. * </p> * * @param name Feature name. * @param value Is feature state <code>true</code> or <code>false</code>. * * @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s * it creates cannot support this feature. * @throws NullPointerException if <code>name</code> is <code>null</code>. */ public abstract void setFeature(String name, boolean value) throws XPathFactoryConfigurationException; /** * <p>Get the state of the named feature.</p> * * <p> * Feature names are fully qualified {@link java.net.URI}s. * Implementations may define their own features. * An {@link XPathFactoryConfigurationException} is thrown if this * <code>XPathFactory</code> or the <code>XPath</code>s * it creates cannot support the feature. * It is possible for an <code>XPathFactory</code> to expose a feature value * but be unable to change its state. * </p> * * @param name Feature name. * * @return State of the named feature. * * @throws XPathFactoryConfigurationException if this * <code>XPathFactory</code> or the <code>XPath</code>s * it creates cannot support this feature. * @throws NullPointerException if <code>name</code> is <code>null</code>. */ public abstract boolean getFeature(String name) throws XPathFactoryConfigurationException; /** * <p>Establish a default variable resolver.</p> * * <p>Any <code>XPath</code> objects constructed from this factory will use * the specified resolver by default.</p> * * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> * is <code>null</code>.</p> * * @param resolver Variable resolver. * * @throws NullPointerException If <code>resolver</code> is * <code>null</code>. */ public abstract void setXPathVariableResolver(XPathVariableResolver resolver); /** * <p>Establish a default function resolver.</p> * * <p>Any <code>XPath</code> objects constructed from this factory will * use the specified resolver by default.</p> * * <p>A <code>NullPointerException</code> is thrown if * <code>resolver</code> is <code>null</code>.</p> * * @param resolver XPath function resolver. * * @throws NullPointerException If <code>resolver</code> is * <code>null</code>. */ public abstract void setXPathFunctionResolver(XPathFunctionResolver resolver); /** * <p>Return a new <code>XPath</code> using the underlying object * model determined when the <code>XPathFactory</code> was instantiated.</p> * * @return New instance of an <code>XPath</code>. */ public abstract XPath newXPath(); }