XPathFactory.java revision 86acc043d3334651ee26c65467d78d6cefedd397
1320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/* 2320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Licensed to the Apache Software Foundation (ASF) under one or more 3320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * contributor license agreements. See the NOTICE file distributed with 4320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this work for additional information regarding copyright ownership. 5320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The ASF licenses this file to You under the Apache License, Version 2.0 6320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * (the "License"); you may not use this file except in compliance with 7320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the License. You may obtain a copy of the License at 8320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 9320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * http://www.apache.org/licenses/LICENSE-2.0 10320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 11320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Unless required by applicable law or agreed to in writing, software 12320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * distributed under the License is distributed on an "AS IS" BASIS, 13320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * See the License for the specific language governing permissions and 15320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * limitations under the License. 16320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 17320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson// $Id: XPathFactory.java 888889 2009-12-09 17:43:18Z mrglavas $ 18320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 19320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpackage javax.xml.xpath; 20320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 21320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson/** 22320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>An <code>XPathFactory</code> instance can be used to create 23320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link javax.xml.xpath.XPath} objects.</p> 24320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 25320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson *<p>See {@link #newInstance(String uri)} for lookup mechanism.</p> 26320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 27320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="mailto:Norman.Walsh@Sun.com">Norman Walsh</a> 28320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @author <a href="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a> 29320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @version $Revision: 888889 $, $Date: 2009-12-09 09:43:18 -0800 (Wed, 09 Dec 2009) $ 30320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @since 1.5 31320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 32320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilsonpublic abstract class XPathFactory { 33320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 34f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 35320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 36320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>The default property name according to the JAXP spec.</p> 37320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 38320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final String DEFAULT_PROPERTY_NAME = "javax.xml.xpath.XPathFactory"; 39320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 40320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 41320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Default Object Model URI.</p> 42320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 43320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final String DEFAULT_OBJECT_MODEL_URI = "http://java.sun.com/jaxp/xpath/dom"; 44f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 45320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 46320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Protected constructor as {@link #newInstance()}, {@link #newInstance(String uri)} 47f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * or {@link #newInstance(String uri, String factoryClassName, ClassLoader classLoader)} 48320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * should be used to create a new instance of an <code>XPathFactory</code>.</p> 49320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 50320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson protected XPathFactory() { 51320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 52320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 53320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 54320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Get a new <code>XPathFactory</code> instance using the default object model, 55320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link #DEFAULT_OBJECT_MODEL_URI}, 56320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the W3C DOM.</p> 57f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 58320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>This method is functionally equivalent to:</p> 59320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 60320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * newInstance(DEFAULT_OBJECT_MODEL_URI) 61320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </pre> 62f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 63f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p> 64f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 65320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Instance of an <code>XPathFactory</code>. 66320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 67320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final XPathFactory newInstance() { 68d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes try { 69d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes return newInstance(DEFAULT_OBJECT_MODEL_URI); 70f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 71d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes catch (XPathFactoryConfigurationException xpathFactoryConfigurationException) { 72d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes throw new RuntimeException( 73d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes "XPathFactory#newInstance() failed to create an XPathFactory for the default object model: " 74d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes + DEFAULT_OBJECT_MODEL_URI 75d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes + " with the XPathFactoryConfigurationException: " 76d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes + xpathFactoryConfigurationException.toString() 77d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes ); 78d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes } 79320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 80320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 81320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 82320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Get a new <code>XPathFactory</code> instance using the specified object model.</p> 83f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 84320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>To find a <code>XPathFactory</code> object, 85320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * this method looks the following places in the following order where "the class loader" refers to the context class loader:</p> 86320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <ol> 87320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 88320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If the system property {@link #DEFAULT_PROPERTY_NAME} + ":uri" is present, 89320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * where uri is the parameter to this method, then its value is read as a class name. 90320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The method will try to create a new instance of this class by using the class loader, 91320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and returns it if it is successfully created. 92320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 93320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 94320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * ${java.home}/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for. 95320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * If present, the value is processed just like above. 96320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 97320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 98320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The class loader is asked for service provider provider-configuration files matching <code>javax.xml.xpath.XPathFactory</code> 99320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * in the resource directory META-INF/services. 100320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * See the JAR File Specification for file format and parsing rules. 101320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Each potential service provider is required to implement the method: 102320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 103320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * {@link #isObjectModelSupported(String objectModel)} 104320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </pre> 105320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The first service provider found in class loader order that supports the specified object model is returned. 106320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 107320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <li> 108320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Platform default <code>XPathFactory</code> is located in a platform specific way. 109320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * There must be a platform default XPathFactory for the W3C DOM, i.e. {@link #DEFAULT_OBJECT_MODEL_URI}. 110320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </li> 111320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </ol> 112320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>If everything fails, an <code>XPathFactoryConfigurationException</code> will be thrown.</p> 113f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 114320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Tip for Trouble-shooting:</p> 115320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed. 116320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it. 117320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * For example:</p> 118320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <pre> 119320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory 120320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </pre> 121f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 122320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param uri Identifies the underlying object model. 123320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * The specification only defines the URI {@link #DEFAULT_OBJECT_MODEL_URI}, 124320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <code>http://java.sun.com/jaxp/xpath/dom</code> for the W3C DOM, 125320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the org.w3c.dom package, and implementations are free to introduce other URIs for other object models. 126f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 127320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Instance of an <code>XPathFactory</code>. 128f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 129320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathFactoryConfigurationException If the specified object model is unavailable. 130f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @throws NullPointerException If <code>uri</code> is <code>null</code>. 131320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException If <code>uri.length() == 0</code>. 132320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 133320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static final XPathFactory newInstance(final String uri) 134320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throws XPathFactoryConfigurationException { 135320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (uri == null) { 13686acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("uri == null"); 137320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 138320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (uri.length() == 0) { 139320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new IllegalArgumentException( 140320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson "XPathFactory#newInstance(String uri) cannot be called with uri == \"\"" 141320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson ); 142320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 143670c354edf01dcda0d9c4363a0996923bb30169bJesse Wilson ClassLoader classLoader = Thread.currentThread().getContextClassLoader(); 144f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes if (classLoader == null) { 145320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson //use the current class loader 146320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson classLoader = XPathFactory.class.getClassLoader(); 147f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes } 148320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson XPathFactory xpathFactory = new XPathFactoryFinder(classLoader).newFactory(uri); 149320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (xpathFactory == null) { 150320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new XPathFactoryConfigurationException( 151670c354edf01dcda0d9c4363a0996923bb30169bJesse Wilson "No XPathFactory implementation found for the object model: " 152320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson + uri 153320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson ); 154320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 155320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson return xpathFactory; 156320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 157f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes 158320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 159320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return Instance of an <code>XPathFactory</code>. 160f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 161320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathFactoryConfigurationException If the specified object model is unavailable. 162f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * @throws NullPointerException If <code>uri</code> is <code>null</code>. 163320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws IllegalArgumentException If <code>uri.length() == 0</code>. 164320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 165320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public static XPathFactory newInstance(String uri, String factoryClassName, 166320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson ClassLoader classLoader) throws XPathFactoryConfigurationException { 167320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (uri == null) { 16886acc043d3334651ee26c65467d78d6cefedd397Kenny Root throw new NullPointerException("uri == null"); 169320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 170320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (uri.length() == 0) { 171320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new IllegalArgumentException( 172320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson "XPathFactory#newInstance(String uri) cannot be called with uri == \"\"" 173320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson ); 174320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 175320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (factoryClassName == null) { 176320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new XPathFactoryConfigurationException("factoryClassName cannot be null."); 177320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 178320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (classLoader == null) { 179670c354edf01dcda0d9c4363a0996923bb30169bJesse Wilson classLoader = Thread.currentThread().getContextClassLoader(); 180320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 181320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson XPathFactory xpathFactory = new XPathFactoryFinder(classLoader).createInstance(factoryClassName); 182320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson if (xpathFactory == null || !xpathFactory.isObjectModelSupported(uri)) { 183320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson throw new XPathFactoryConfigurationException( 184670c354edf01dcda0d9c4363a0996923bb30169bJesse Wilson "No XPathFactory implementation found for the object model: " 185320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson + uri 186320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson ); 187320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 188320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson return xpathFactory; 189320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson } 190320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 191d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes /** 192d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p>Is specified object model supported by this <code>XPathFactory</code>?</p> 193f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 194d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @param objectModel Specifies the object model which the returned <code>XPathFactory</code> will understand. 195f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 196d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @return <code>true</code> if <code>XPathFactory</code> supports <code>objectModel</code>, else <code>false</code>. 197f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 198d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @throws NullPointerException If <code>objectModel</code> is <code>null</code>. 199d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @throws IllegalArgumentException If <code>objectModel.length() == 0</code>. 200d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes */ 201d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes public abstract boolean isObjectModelSupported(String objectModel); 202320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 203320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 204320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Set a feature for this <code>XPathFactory</code> and <code>XPath</code>s created by this factory.</p> 205f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 206320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 207320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Feature names are fully qualified {@link java.net.URI}s. 208320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Implementations may define their own features. 209320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathFactoryConfigurationException} is thrown if this <code>XPathFactory</code> or the <code>XPath</code>s 210320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it creates cannot support the feature. 211320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * It is possible for an <code>XPathFactory</code> to expose a feature value but be unable to change its state. 212320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </p> 213f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 214320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 215320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature. 216320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * When the feature is <code>true</code>, any reference to an external function is an error. 217320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Under these conditions, the implementation must not call the {@link XPathFunctionResolver} 218320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * and must throw an {@link XPathFunctionException}. 219320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </p> 220f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 221320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param name Feature name. 222320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param value Is feature state <code>true</code> or <code>false</code>. 223f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 224320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s 225320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it creates cannot support this feature. 226320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException if <code>name</code> is <code>null</code>. 227320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 228d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes public abstract void setFeature(String name, boolean value) 229d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes throws XPathFactoryConfigurationException; 230320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 231d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes /** 232d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * <p>Get the state of the named feature.</p> 233f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 234320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p> 235320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Feature names are fully qualified {@link java.net.URI}s. 236320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * Implementations may define their own features. 237320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * An {@link XPathFactoryConfigurationException} is thrown if this <code>XPathFactory</code> or the <code>XPath</code>s 238320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it creates cannot support the feature. 239320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * It is possible for an <code>XPathFactory</code> to expose a feature value but be unable to change its state. 240320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * </p> 241f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 242d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @param name Feature name. 243f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 244d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes * @return State of the named feature. 245f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 246320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s 247320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * it creates cannot support this feature. 248320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException if <code>name</code> is <code>null</code>. 249d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes */ 250d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes public abstract boolean getFeature(String name) 251d21d78fd49a2d798218e8c8aefbddb26a0e71bbbElliott Hughes throws XPathFactoryConfigurationException; 252320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 253320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 254320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Establish a default variable resolver.</p> 255320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 256320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Any <code>XPath</code> objects constructed from this factory will use 257320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the specified resolver by default.</p> 258f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 259320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> is <code>null</code>.</p> 260f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 261320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param resolver Variable resolver. 262f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 263320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>resolver</code> is <code>null</code>. 264320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 265320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract void setXPathVariableResolver(XPathVariableResolver resolver); 266320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 267320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 268320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Establish a default function resolver.</p> 269f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 270320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Any <code>XPath</code> objects constructed from this factory will use 271320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * the specified resolver by default.</p> 272320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * 273320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> is <code>null</code>.</p> 274f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 275320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @param resolver XPath function resolver. 276f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 277320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @throws NullPointerException If <code>resolver</code> is <code>null</code>. 278320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 279320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract void setXPathFunctionResolver(XPathFunctionResolver resolver); 280320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson 281320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson /** 282320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * <p>Return a new <code>XPath</code> using the underlying object 283320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * model determined when the <code>XPathFactory</code> was instantiated.</p> 284f33eae7e84eb6d3b0f4e86b59605bb3de73009f3Elliott Hughes * 285320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson * @return New instance of an <code>XPath</code>. 286320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson */ 287320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson public abstract XPath newXPath(); 288320c9890e8241fb0ad05de6fa5e6c3eb3aece159Jesse Wilson} 289