KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > xml > xpath > XPathFactory


1 // $Id: XPathFactory.java,v 1.13.10.1.2.1 2004/09/16 09:25:15 nb131165 Exp $
2
3 /*
4  * @(#)XPathFactory.java 1.10 05/01/04
5  *
6  * Copyright 2005 Sun Microsystems, Inc. All rights reserved.
7  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
8  */
9
10 package javax.xml.xpath;
11
12 /**
13  * <p>An <code>XPathFactory</code> instance can be used to create
14  * {@link javax.xml.xpath.XPath} objects.</p>
15  *
16  *<p>See {@link #newInstance(String uri)} for lookup mechanism.</p>
17  *
18  * @author <a HREF="mailto:Norman.Walsh@Sun.com">Norman Walsh</a>
19  * @author <a HREF="mailto:Jeff.Suttor@Sun.com">Jeff Suttor</a>
20  * @version $Revision: 1.13.10.1.2.1 $, $Date: 2004/09/16 09:25:15 $
21  * @since 1.5
22  */
23 public abstract class XPathFactory {
24
25     
26     /**
27      * <p>The default property name according to the JAXP spec.</p>
28      */
29     public static final String JavaDoc DEFAULT_PROPERTY_NAME = "javax.xml.xpath.XPathFactory";
30
31     /**
32      * <p>Default Object Model URI.</p>
33      */
34     public static final String JavaDoc DEFAULT_OBJECT_MODEL_URI = "http://java.sun.com/jaxp/xpath/dom";
35
36     /**
37      *<p> Take care of restrictions imposed by java security model </p>
38      */
39     private static SecuritySupport JavaDoc ss = new SecuritySupport JavaDoc() ;
40     
41     /**
42      * <p>Protected constructor as {@link #newInstance()} or {@link #newInstance(String uri)}
43      * should be used to create a new instance of an <code>XPathFactory</code>.</p>
44      */
45     protected XPathFactory() {
46     }
47
48     /**
49      * <p>Get a new <code>XPathFactory</code> instance using the default object model,
50      * {@link #DEFAULT_OBJECT_MODEL_URI},
51      * the W3C DOM.</p>
52      *
53      * <p>This method is functionally equivalent to:</p>
54      * <pre>
55      * newInstance(DEFAULT_OBJECT_MODEL_URI)
56      * </pre>
57      *
58      * <p>Since the implementation for the W3C DOM is always available, this method will never fail.</p>
59      *
60      * @return Instance of an <code>XPathFactory</code>.
61      */
62     public static final XPathFactory JavaDoc newInstance() {
63         
64         try {
65             return newInstance(DEFAULT_OBJECT_MODEL_URI);
66         } catch (XPathFactoryConfigurationException JavaDoc xpathFactoryConfigurationException) {
67             throw new RuntimeException JavaDoc(
68                 "XPathFactory#newInstance() failed to create an XPathFactory for the default object model: "
69                 + DEFAULT_OBJECT_MODEL_URI
70                 + " with the XPathFactoryConfigurationException: "
71                 + xpathFactoryConfigurationException.toString()
72             );
73         }
74     }
75
76     /**
77     * <p>Get a new <code>XPathFactory</code> instance using the specified object model.</p>
78     *
79     * <p>To find a <code>XPathFactory</code> object,
80     * this method looks the following places in the following order where "the class loader" refers to the context class loader:</p>
81     * <ol>
82     * <li>
83     * If the system property {@link #DEFAULT_PROPERTY_NAME} + ":uri" is present,
84     * where uri is the parameter to this method, then its value is read as a class name.
85     * The method will try to create a new instance of this class by using the class loader,
86     * and returns it if it is successfully created.
87     * </li>
88     * <li>
89     * ${java.home}/lib/jaxp.properties is read and the value associated with the key being the system property above is looked for.
90     * If present, the value is processed just like above.
91     * </li>
92     * <li>
93     * The class loader is asked for service provider provider-configuration files matching <code>javax.xml.xpath.XPathFactory</code>
94     * in the resource directory META-INF/services.
95     * See the JAR File Specification for file format and parsing rules.
96     * Each potential service provider is required to implement the method:
97     * <pre>
98     * {@link #isObjectModelSupported(String objectModel)}
99     * </pre>
100     * The first service provider found in class loader order that supports the specified object model is returned.
101     * </li>
102     * <li>
103     * Platform default <code>XPathFactory</code> is located in a platform specific way.
104     * There must be a platform default XPathFactory for the W3C DOM, i.e. {@link #DEFAULT_OBJECT_MODEL_URI}.
105     * </li>
106     * </ol>
107     * <p>If everything fails, an <code>XPathFactoryConfigurationException</code> will be thrown.</p>
108     *
109     * <p>Tip for Trouble-shooting:</p>
110     * <p>See {@link java.util.Properties#load(java.io.InputStream)} for exactly how a property file is parsed.
111     * In particular, colons ':' need to be escaped in a property file, so make sure the URIs are properly escaped in it.
112     * For example:</p>
113     * <pre>
114     * http\://java.sun.com/jaxp/xpath/dom=org.acme.DomXPathFactory
115     * </pre>
116     *
117     * @param uri Identifies the underlying object model.
118     * The specification only defines the URI {@link #DEFAULT_OBJECT_MODEL_URI},
119     * <code>http://java.sun.com/jaxp/xpath/dom</code> for the W3C DOM,
120     * the org.w3c.dom package, and implementations are free to introduce other URIs for other object models.
121     *
122     * @return Instance of an <code>XPathFactory</code>.
123     *
124     * @throws XPathFactoryConfigurationException If the specified object model is unavailable.
125     * @throws NullPointerException If <code>uri</code> is <code>null</code>.
126      * @throws IllegalArgumentException If <code>uri.length() == 0</code>.
127     */
128     public static final XPathFactory JavaDoc newInstance(final String JavaDoc uri)
129         throws XPathFactoryConfigurationException JavaDoc {
130             
131         if (uri == null) {
132             throw new NullPointerException JavaDoc(
133                 "XPathFactory#newInstance(String uri) cannot be called with uri == null"
134             );
135         }
136
137         if (uri.length() == 0) {
138             throw new IllegalArgumentException JavaDoc(
139                 "XPathFactory#newInstance(String uri) cannot be called with uri == \"\""
140             );
141         }
142         
143         ClassLoader JavaDoc classLoader = ss.getContextClassLoader();
144         
145         if (classLoader == null) {
146             //use the current class loader
147 classLoader = XPathFactory JavaDoc.class.getClassLoader();
148         }
149         
150         XPathFactory JavaDoc xpathFactory = new XPathFactoryFinder JavaDoc(classLoader).newFactory(uri);
151         
152         if (xpathFactory == null) {
153             throw new XPathFactoryConfigurationException JavaDoc(
154                 "No XPathFctory implementation found for the object model: "
155                 + uri
156             );
157         }
158         
159         return xpathFactory;
160     }
161
162     /**
163      * <p>Is specified object model supported by this <code>XPathFactory</code>?</p>
164      *
165      * @param objectModel Specifies the object model which the returned <code>XPathFactory</code> will understand.
166      *
167      * @return <code>true</code> if <code>XPathFactory</code> supports <code>objectModel</code>, else <code>false</code>.
168      *
169      * @throws NullPointerException If <code>objectModel</code> is <code>null</code>.
170      * @throws IllegalArgumentException If <code>objectModel.length() == 0</code>.
171      */
172     public abstract boolean isObjectModelSupported(String JavaDoc objectModel);
173
174     /**
175      * <p>Set a feature for this <code>XPathFactory</code> and <code>XPath</code>s created by this factory.</p>
176      *
177      * <p>
178      * Feature names are fully qualified {@link java.net.URI}s.
179      * Implementations may define their own features.
180      * An {@link XPathFactoryConfigurationException} is thrown if this <code>XPathFactory</code> or the <code>XPath</code>s
181      * it creates cannot support the feature.
182      * It is possible for an <code>XPathFactory</code> to expose a feature value but be unable to change its state.
183      * </p>
184      *
185      * <p>
186      * All implementations are required to support the {@link javax.xml.XMLConstants#FEATURE_SECURE_PROCESSING} feature.
187      * When the feature is <code>true</code>, any reference to an external function is an error.
188      * Under these conditions, the implementation must not call the {@link XPathFunctionResolver}
189      * and must throw an {@link XPathFunctionException}.
190      * </p>
191      *
192      * @param name Feature name.
193      * @param value Is feature state <code>true</code> or <code>false</code>.
194      *
195      * @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s
196      * it creates cannot support this feature.
197      * @throws NullPointerException if <code>name</code> is <code>null</code>.
198      */
199     public abstract void setFeature(String JavaDoc name, boolean value)
200         throws XPathFactoryConfigurationException JavaDoc;
201
202     /**
203      * <p>Get the state of the named feature.</p>
204      *
205      * <p>
206      * Feature names are fully qualified {@link java.net.URI}s.
207      * Implementations may define their own features.
208      * An {@link XPathFactoryConfigurationException} is thrown if this <code>XPathFactory</code> or the <code>XPath</code>s
209      * it creates cannot support the feature.
210      * It is possible for an <code>XPathFactory</code> to expose a feature value but be unable to change its state.
211      * </p>
212      *
213      * @param name Feature name.
214      *
215      * @return State of the named feature.
216      *
217      * @throws XPathFactoryConfigurationException if this <code>XPathFactory</code> or the <code>XPath</code>s
218      * it creates cannot support this feature.
219      * @throws NullPointerException if <code>name</code> is <code>null</code>.
220      */
221     public abstract boolean getFeature(String JavaDoc name)
222         throws XPathFactoryConfigurationException JavaDoc;
223
224     /**
225      * <p>Establish a default variable resolver.</p>
226      *
227      * <p>Any <code>XPath</code> objects constructed from this factory will use
228      * the specified resolver by default.</p>
229      *
230      * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> is <code>null</code>.</p>
231      *
232      * @param resolver Variable resolver.
233      *
234      * @throws NullPointerException If <code>resolver</code> is <code>null</code>.
235      */
236     public abstract void setXPathVariableResolver(XPathVariableResolver JavaDoc resolver);
237
238     /**
239        * <p>Establish a default function resolver.</p>
240        *
241        * <p>Any <code>XPath</code> objects constructed from this factory will use
242        * the specified resolver by default.</p>
243        *
244        * <p>A <code>NullPointerException</code> is thrown if <code>resolver</code> is <code>null</code>.</p>
245        *
246        * @param resolver XPath function resolver.
247        *
248        * @throws NullPointerException If <code>resolver</code> is <code>null</code>.
249        */
250     public abstract void setXPathFunctionResolver(XPathFunctionResolver JavaDoc resolver);
251
252     /**
253     * <p>Return a new <code>XPath</code> using the underlying object
254     * model determined when the <code>XPathFactory</code> was instantiated.</p>
255     *
256     * @return New instance of an <code>XPath</code>.
257     */
258     public abstract XPath JavaDoc newXPath();
259 }
260
Popular Tags