KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > xml > dtm > DTMManager


1 /*
2  * Copyright 1999-2004 The Apache Software Foundation.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */

16 /*
17  * $Id: DTMManager.java,v 1.18 2004/02/23 10:29:36 aruny Exp $
18  */

19 package org.apache.xml.dtm;
20
21 import org.apache.xml.res.XMLErrorResources;
22 import org.apache.xml.res.XMLMessages;
23 import org.apache.xml.utils.PrefixResolver;
24 import org.apache.xml.utils.XMLStringFactory;
25
26 /**
27  * A DTMManager instance can be used to create DTM and
28  * DTMIterator objects, and manage the DTM objects in the system.
29  *
30  * <p>The system property that determines which Factory implementation
31  * to create is named "org.apache.xml.utils.DTMFactory". This
32  * property names a concrete subclass of the DTMFactory abstract
33  * class. If the property is not defined, a platform default is be used.</p>
34  *
35  * <p>An instance of this class <emph>must</emph> be safe to use across
36  * thread instances. It is expected that a client will create a single instance
37  * of a DTMManager to use across multiple threads. This will allow sharing
38  * of DTMs across multiple processes.</p>
39  *
40  * <p>Note: this class is incomplete right now. It will be pretty much
41  * modeled after javax.xml.transform.TransformerFactory in terms of its
42  * factory support.</p>
43  *
44  * <p>State: In progress!!</p>
45  */

46 public abstract class DTMManager
47 {
48
49   /** The default property name to load the manager. */
50   private static final String JavaDoc defaultPropName =
51     "org.apache.xml.dtm.DTMManager";
52   
53   /** The default class name to use as the manager. */
54   private static String JavaDoc defaultClassName =
55     "org.apache.xml.dtm.ref.DTMManagerDefault";
56
57   /**
58    * Factory for creating XMLString objects.
59    * %TBD% Make this set by the caller.
60    */

61   protected XMLStringFactory m_xsf = null;
62
63   /**
64    * Default constructor is protected on purpose.
65    */

66   protected DTMManager(){}
67
68   /**
69    * Get the XMLStringFactory used for the DTMs.
70    *
71    *
72    * @return a valid XMLStringFactory object, or null if it hasn't been set yet.
73    */

74   public XMLStringFactory getXMLStringFactory()
75   {
76     return m_xsf;
77   }
78
79   /**
80    * Set the XMLStringFactory used for the DTMs.
81    *
82    *
83    * @param xsf a valid XMLStringFactory object, should not be null.
84    */

85   public void setXMLStringFactory(XMLStringFactory xsf)
86   {
87     m_xsf = xsf;
88   }
89
90   /**
91    * Obtain a new instance of a <code>DTMManager</code>.
92    * This static method creates a new factory instance
93    * This method uses the following ordered lookup procedure to determine
94    * the <code>DTMManager</code> implementation class to
95    * load:
96    * <ul>
97    * <li>
98    * Use the <code>org.apache.xml.dtm.DTMManager</code> system
99    * property.
100    * </li>
101    * <li>
102    * Use the JAVA_HOME(the parent directory where jdk is
103    * installed)/lib/xalan.properties for a property file that contains the
104    * name of the implementation class keyed on the same value as the
105    * system property defined above.
106    * </li>
107    * <li>
108    * Use the Services API (as detailed in the JAR specification), if
109    * available, to determine the classname. The Services API will look
110    * for a classname in the file
111    * <code>META-INF/services/org.apache.xml.dtm.DTMManager</code>
112    * in jars available to the runtime.
113    * </li>
114    * <li>
115    * Use the default <code>DTMManager</code> classname, which is
116    * <code>org.apache.xml.dtm.ref.DTMManagerDefault</code>.
117    * </li>
118    * </ul>
119    *
120    * Once an application has obtained a reference to a <code>
121    * DTMManager</code> it can use the factory to configure
122    * and obtain parser instances.
123    *
124    * @return new DTMManager instance, never null.
125    *
126    * @throws DTMConfigurationException
127    * if the implementation is not available or cannot be instantiated.
128    */

129   public static DTMManager newInstance(XMLStringFactory xsf)
130            throws DTMConfigurationException
131   {
132     DTMManager factoryImpl = null;
133     try
134     {
135       factoryImpl = (DTMManager) ObjectFactory
136         .createObject(defaultPropName, defaultClassName);
137     }
138     catch (ObjectFactory.ConfigurationError e)
139     {
140       throw new DTMConfigurationException(XMLMessages.createXMLMessage(
141         XMLErrorResources.ER_NO_DEFAULT_IMPL, null), e.getException());
142         //"No default implementation found");
143
}
144
145     if (factoryImpl == null)
146     {
147       throw new DTMConfigurationException(XMLMessages.createXMLMessage(
148         XMLErrorResources.ER_NO_DEFAULT_IMPL, null));
149         //"No default implementation found");
150
}
151
152     factoryImpl.setXMLStringFactory(xsf);
153
154     return factoryImpl;
155   }
156
157   /**
158    * Get an instance of a DTM, loaded with the content from the
159    * specified source. If the unique flag is true, a new instance will
160    * always be returned. Otherwise it is up to the DTMManager to return a
161    * new instance or an instance that it already created and may be being used
162    * by someone else.
163    *
164    * (More parameters may eventually need to be added for error handling
165    * and entity resolution, and to better control selection of implementations.)
166    *
167    * @param source the specification of the source object, which may be null,
168    * in which case it is assumed that node construction will take
169    * by some other means.
170    * @param unique true if the returned DTM must be unique, probably because it
171    * is going to be mutated.
172    * @param whiteSpaceFilter Enables filtering of whitespace nodes, and may
173    * be null.
174    * @param incremental true if the DTM should be built incrementally, if
175    * possible.
176    * @param doIndexing true if the caller considers it worth it to use
177    * indexing schemes.
178    *
179    * @return a non-null DTM reference.
180    */

181   public abstract DTM getDTM(javax.xml.transform.Source JavaDoc source,
182                              boolean unique, DTMWSFilter whiteSpaceFilter,
183                              boolean incremental, boolean doIndexing);
184
185   /**
186    * Get the instance of DTM that "owns" a node handle.
187    *
188    * @param nodeHandle the nodeHandle.
189    *
190    * @return a non-null DTM reference.
191    */

192   public abstract DTM getDTM(int nodeHandle);
193
194   /**
195    * Given a W3C DOM node, try and return a DTM handle.
196    * Note: calling this may be non-optimal.
197    *
198    * @param node Non-null reference to a DOM node.
199    *
200    * @return a valid DTM handle.
201    */

202   public abstract int getDTMHandleFromNode(org.w3c.dom.Node JavaDoc node);
203
204   /**
205    * Creates a DTM representing an empty <code>DocumentFragment</code> object.
206    * @return a non-null DTM reference.
207    */

208   public abstract DTM createDocumentFragment();
209
210   /**
211    * Release a DTM either to a lru pool, or completely remove reference.
212    * DTMs without system IDs are always hard deleted.
213    * State: experimental.
214    *
215    * @param dtm The DTM to be released.
216    * @param shouldHardDelete True if the DTM should be removed no matter what.
217    * @return true if the DTM was removed, false if it was put back in a lru pool.
218    */

219   public abstract boolean release(DTM dtm, boolean shouldHardDelete);
220
221   /**
222    * Create a new <code>DTMIterator</code> based on an XPath
223    * <a HREF="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or
224    * a <a HREF="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.
225    *
226    * @param xpathCompiler ??? Somehow we need to pass in a subpart of the
227    * expression. I hate to do this with strings, since the larger expression
228    * has already been parsed.
229    *
230    * @param pos The position in the expression.
231    * @return The newly created <code>DTMIterator</code>.
232    */

233   public abstract DTMIterator createDTMIterator(Object JavaDoc xpathCompiler,
234           int pos);
235
236   /**
237    * Create a new <code>DTMIterator</code> based on an XPath
238    * <a HREF="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or
239    * a <a HREF="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.
240    *
241    * @param xpathString Must be a valid string expressing a
242    * <a HREF="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or
243    * a <a HREF="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.
244    *
245    * @param presolver An object that can resolve prefixes to namespace URLs.
246    *
247    * @return The newly created <code>DTMIterator</code>.
248    */

249   public abstract DTMIterator createDTMIterator(String JavaDoc xpathString,
250           PrefixResolver presolver);
251
252   /**
253    * Create a new <code>DTMIterator</code> based only on a whatToShow
254    * and a DTMFilter. The traversal semantics are defined as the
255    * descendant access.
256    * <p>
257    * Note that DTMIterators may not be an exact match to DOM
258    * NodeIterators. They are initialized and used in much the same way
259    * as a NodeIterator, but their response to document mutation is not
260    * currently defined.
261    *
262    * @param whatToShow This flag specifies which node types may appear in
263    * the logical view of the tree presented by the iterator. See the
264    * description of <code>NodeFilter</code> for the set of possible
265    * <code>SHOW_</code> values.These flags can be combined using
266    * <code>OR</code>.
267    * @param filter The <code>NodeFilter</code> to be used with this
268    * <code>DTMFilter</code>, or <code>null</code> to indicate no filter.
269    * @param entityReferenceExpansion The value of this flag determines
270    * whether entity reference nodes are expanded.
271    *
272    * @return The newly created <code>DTMIterator</code>.
273    */

274   public abstract DTMIterator createDTMIterator(int whatToShow,
275           DTMFilter filter, boolean entityReferenceExpansion);
276
277   /**
278    * Create a new <code>DTMIterator</code> that holds exactly one node.
279    *
280    * @param node The node handle that the DTMIterator will iterate to.
281    *
282    * @return The newly created <code>DTMIterator</code>.
283    */

284   public abstract DTMIterator createDTMIterator(int node);
285   
286   /* Flag indicating whether an incremental transform is desired */
287   public static boolean m_incremental = false;
288   
289   /**
290    * Set a flag indicating whether an incremental transform is desired
291    * @param incremental boolean to use to set m_incremental.
292    *
293    */

294   public synchronized static boolean getIncremental()
295   {
296     return m_incremental;
297   }
298   
299   /**
300    * Set a flag indicating whether an incremental transform is desired
301    * @param incremental boolean to use to set m_incremental.
302    *
303    */

304   public synchronized static void setIncremental(boolean incremental)
305   {
306     m_incremental = incremental;
307   }
308   
309   
310
311   // -------------------- private methods --------------------
312

313    /**
314    * Temp debug code - this will be removed after we test everything
315    */

316   private static boolean debug;
317
318   static
319   {
320     try
321     {
322       debug = System.getProperty("dtm.debug") != null;
323     }
324     catch (SecurityException JavaDoc ex){}
325   }
326
327   /** This value, set at compile time, controls how many bits of the
328    * DTM node identifier numbers are used to identify a node within a
329    * document, and thus sets the maximum number of nodes per
330    * document. The remaining bits are used to identify the DTM
331    * document which contains this node.
332    *
333    * If you change IDENT_DTM_NODE_BITS, be sure to rebuild _ALL_ the
334    * files which use it... including the IDKey testcases.
335    *
336    * (FuncGenerateKey currently uses the node identifier directly and
337    * thus is affected when this changes. The IDKEY results will still be
338    * _correct_ (presuming no other breakage), but simple equality
339    * comparison against the previous "golden" files will probably
340    * complain.)
341    * */

342   public static final int IDENT_DTM_NODE_BITS = 16;
343     
344
345   /** When this bitmask is ANDed with a DTM node handle number, the result
346    * is the low bits of the node's index number within that DTM. To obtain
347    * the high bits, add the DTM ID portion's offset as assigned in the DTM
348    * Manager.
349    */

350   public static final int IDENT_NODE_DEFAULT = (1<<IDENT_DTM_NODE_BITS)-1;
351
352
353   /** When this bitmask is ANDed with a DTM node handle number, the result
354    * is the DTM's document identity number.
355    */

356   public static final int IDENT_DTM_DEFAULT = ~IDENT_NODE_DEFAULT;
357
358   /** This is the maximum number of DTMs available. The highest DTM is
359     * one less than this.
360    */

361   public static final int IDENT_MAX_DTMS = (IDENT_DTM_DEFAULT >>> IDENT_DTM_NODE_BITS) + 1;
362
363
364   /**
365    * %TBD% Doc
366    *
367    * NEEDSDOC @param dtm
368    *
369    * NEEDSDOC ($objectName$) @return
370    */

371   public abstract int getDTMIdentity(DTM dtm);
372
373   /**
374    * %TBD% Doc
375    *
376    * NEEDSDOC ($objectName$) @return
377    */

378   public int getDTMIdentityMask()
379   {
380     return IDENT_DTM_DEFAULT;
381   }
382
383   /**
384    * %TBD% Doc
385    *
386    * NEEDSDOC ($objectName$) @return
387    */

388   public int getNodeIdentityMask()
389   {
390     return IDENT_NODE_DEFAULT;
391   }
392
393 }
394
Popular Tags