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   defaultPropName =
51      "org.apache.xml.dtm.DTMManager";
52    
53    /** The default class name to use as the manager. */
54    private static String   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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags