• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Licensed to the Apache Software Foundation (ASF) under one
3  * or more contributor license agreements. See the NOTICE file
4  * distributed with this work for additional information
5  * regarding copyright ownership. The ASF licenses this file
6  * to you under the Apache License, Version 2.0 (the  "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  *     http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 /*
19  * $Id: DTMManager.java 468653 2006-10-28 07:07:05Z minchau $
20  */
21 package org.apache.xml.dtm;
22 
23 import org.apache.xml.res.XMLErrorResources;
24 import org.apache.xml.res.XMLMessages;
25 import org.apache.xml.utils.PrefixResolver;
26 import org.apache.xml.utils.XMLStringFactory;
27 
28 /**
29  * A DTMManager instance can be used to create DTM and
30  * DTMIterator objects, and manage the DTM objects in the system.
31  *
32  * <p>The system property that determines which Factory implementation
33  * to create is named "org.apache.xml.utils.DTMFactory". This
34  * property names a concrete subclass of the DTMFactory abstract
35  *  class. If the property is not defined, a platform default is be used.</p>
36  *
37  * <p>An instance of this class <emph>must</emph> be safe to use across
38  * thread instances.  It is expected that a client will create a single instance
39  * of a DTMManager to use across multiple threads.  This will allow sharing
40  * of DTMs across multiple processes.</p>
41  *
42  * <p>Note: this class is incomplete right now.  It will be pretty much
43  * modeled after javax.xml.transform.TransformerFactory in terms of its
44  * factory support.</p>
45  *
46  * <p>State: In progress!!</p>
47  */
48 public abstract class DTMManager
49 {
50 
51   /** The default property name to load the manager. */
52   private static final String defaultPropName =
53     "org.apache.xml.dtm.DTMManager";
54 
55   /** The default class name to use as the manager. */
56   private static String defaultClassName =
57     "org.apache.xml.dtm.ref.DTMManagerDefault";
58 
59   /**
60    * Factory for creating XMLString objects.
61    *  %TBD% Make this set by the caller.
62    */
63   protected XMLStringFactory m_xsf = null;
64 
65   /**
66    * Default constructor is protected on purpose.
67    */
DTMManager()68   protected DTMManager(){}
69 
70   /**
71    * Get the XMLStringFactory used for the DTMs.
72    *
73    *
74    * @return a valid XMLStringFactory object, or null if it hasn't been set yet.
75    */
getXMLStringFactory()76   public XMLStringFactory getXMLStringFactory()
77   {
78     return m_xsf;
79   }
80 
81   /**
82    * Set the XMLStringFactory used for the DTMs.
83    *
84    *
85    * @param xsf a valid XMLStringFactory object, should not be null.
86    */
setXMLStringFactory(XMLStringFactory xsf)87   public void setXMLStringFactory(XMLStringFactory xsf)
88   {
89     m_xsf = xsf;
90   }
91 
92   /**
93    * Obtain a new instance of a <code>DTMManager</code>.
94    * This static method creates a new factory instance
95    * This method uses the following ordered lookup procedure to determine
96    * the <code>DTMManager</code> implementation class to
97    * load:
98    * <ul>
99    * <li>
100    * Use the <code>org.apache.xml.dtm.DTMManager</code> system
101    * property.
102    * </li>
103    * <li>
104    * Use the JAVA_HOME(the parent directory where jdk is
105    * installed)/lib/xalan.properties for a property file that contains the
106    * name of the implementation class keyed on the same value as the
107    * system property defined above.
108    * </li>
109    * <li>
110    * Use the Services API (as detailed in the JAR specification), if
111    * available, to determine the classname. The Services API will look
112    * for a classname in the file
113    * <code>META-INF/services/org.apache.xml.dtm.DTMManager</code>
114    * in jars available to the runtime.
115    * </li>
116    * <li>
117    * Use the default <code>DTMManager</code> classname, which is
118    * <code>org.apache.xml.dtm.ref.DTMManagerDefault</code>.
119    * </li>
120    * </ul>
121    *
122    * Once an application has obtained a reference to a <code>
123    * DTMManager</code> it can use the factory to configure
124    * and obtain parser instances.
125    *
126    * @return new DTMManager instance, never null.
127    *
128    * @throws DTMConfigurationException
129    * if the implementation is not available or cannot be instantiated.
130    */
newInstance(XMLStringFactory xsf)131   public static DTMManager newInstance(XMLStringFactory xsf)
132            throws DTMConfigurationException
133   {
134     DTMManager factoryImpl = null;
135     try
136     {
137       factoryImpl = (DTMManager) ObjectFactory
138         .createObject(defaultPropName, defaultClassName);
139     }
140     catch (ObjectFactory.ConfigurationError e)
141     {
142       throw new DTMConfigurationException(XMLMessages.createXMLMessage(
143         XMLErrorResources.ER_NO_DEFAULT_IMPL, null), e.getException());
144         //"No default implementation found");
145     }
146 
147     if (factoryImpl == null)
148     {
149       throw new DTMConfigurationException(XMLMessages.createXMLMessage(
150         XMLErrorResources.ER_NO_DEFAULT_IMPL, null));
151         //"No default implementation found");
152     }
153 
154     factoryImpl.setXMLStringFactory(xsf);
155 
156     return factoryImpl;
157   }
158 
159   /**
160    * Get an instance of a DTM, loaded with the content from the
161    * specified source.  If the unique flag is true, a new instance will
162    * always be returned.  Otherwise it is up to the DTMManager to return a
163    * new instance or an instance that it already created and may be being used
164    * by someone else.
165    *
166    * (More parameters may eventually need to be added for error handling
167    * and entity resolution, and to better control selection of implementations.)
168    *
169    * @param source the specification of the source object, which may be null,
170    *               in which case it is assumed that node construction will take
171    *               by some other means.
172    * @param unique true if the returned DTM must be unique, probably because it
173    * is going to be mutated.
174    * @param whiteSpaceFilter Enables filtering of whitespace nodes, and may
175    *                         be null.
176    * @param incremental true if the DTM should be built incrementally, if
177    *                    possible.
178    * @param doIndexing true if the caller considers it worth it to use
179    *                   indexing schemes.
180    *
181    * @return a non-null DTM reference.
182    */
getDTM(javax.xml.transform.Source source, boolean unique, DTMWSFilter whiteSpaceFilter, boolean incremental, boolean doIndexing)183   public abstract DTM getDTM(javax.xml.transform.Source source,
184                              boolean unique, DTMWSFilter whiteSpaceFilter,
185                              boolean incremental, boolean doIndexing);
186 
187   /**
188    * Get the instance of DTM that "owns" a node handle.
189    *
190    * @param nodeHandle the nodeHandle.
191    *
192    * @return a non-null DTM reference.
193    */
getDTM(int nodeHandle)194   public abstract DTM getDTM(int nodeHandle);
195 
196   /**
197    * Given a W3C DOM node, try and return a DTM handle.
198    * Note: calling this may be non-optimal.
199    *
200    * @param node Non-null reference to a DOM node.
201    *
202    * @return a valid DTM handle.
203    */
getDTMHandleFromNode(org.w3c.dom.Node node)204   public abstract int getDTMHandleFromNode(org.w3c.dom.Node node);
205 
206   /**
207    * Creates a DTM representing an empty <code>DocumentFragment</code> object.
208    * @return a non-null DTM reference.
209    */
createDocumentFragment()210   public abstract DTM createDocumentFragment();
211 
212   /**
213    * Release a DTM either to a lru pool, or completely remove reference.
214    * DTMs without system IDs are always hard deleted.
215    * State: experimental.
216    *
217    * @param dtm The DTM to be released.
218    * @param shouldHardDelete True if the DTM should be removed no matter what.
219    * @return true if the DTM was removed, false if it was put back in a lru pool.
220    */
release(DTM dtm, boolean shouldHardDelete)221   public abstract boolean release(DTM dtm, boolean shouldHardDelete);
222 
223   /**
224    * Create a new <code>DTMIterator</code> based on an XPath
225    * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or
226    * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.
227    *
228    * @param xpathCompiler ??? Somehow we need to pass in a subpart of the
229    * expression.  I hate to do this with strings, since the larger expression
230    * has already been parsed.
231    *
232    * @param pos The position in the expression.
233    * @return The newly created <code>DTMIterator</code>.
234    */
createDTMIterator(Object xpathCompiler, int pos)235   public abstract DTMIterator createDTMIterator(Object xpathCompiler,
236           int pos);
237 
238   /**
239    * Create a new <code>DTMIterator</code> based on an XPath
240    * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or
241    * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.
242    *
243    * @param xpathString Must be a valid string expressing a
244    * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or
245    * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>.
246    *
247    * @param presolver An object that can resolve prefixes to namespace URLs.
248    *
249    * @return The newly created <code>DTMIterator</code>.
250    */
createDTMIterator(String xpathString, PrefixResolver presolver)251   public abstract DTMIterator createDTMIterator(String xpathString,
252           PrefixResolver presolver);
253 
254   /**
255    * Create a new <code>DTMIterator</code> based only on a whatToShow
256    * and a DTMFilter.  The traversal semantics are defined as the
257    * descendant access.
258    * <p>
259    * Note that DTMIterators may not be an exact match to DOM
260    * NodeIterators. They are initialized and used in much the same way
261    * as a NodeIterator, but their response to document mutation is not
262    * currently defined.
263    *
264    * @param whatToShow This flag specifies which node types may appear in
265    *   the logical view of the tree presented by the iterator. See the
266    *   description of <code>NodeFilter</code> for the set of possible
267    *   <code>SHOW_</code> values.These flags can be combined using
268    *   <code>OR</code>.
269    * @param filter The <code>NodeFilter</code> to be used with this
270    *   <code>DTMFilter</code>, or <code>null</code> to indicate no filter.
271    * @param entityReferenceExpansion The value of this flag determines
272    *   whether entity reference nodes are expanded.
273    *
274    * @return The newly created <code>DTMIterator</code>.
275    */
createDTMIterator(int whatToShow, DTMFilter filter, boolean entityReferenceExpansion)276   public abstract DTMIterator createDTMIterator(int whatToShow,
277           DTMFilter filter, boolean entityReferenceExpansion);
278 
279   /**
280    * Create a new <code>DTMIterator</code> that holds exactly one node.
281    *
282    * @param node The node handle that the DTMIterator will iterate to.
283    *
284    * @return The newly created <code>DTMIterator</code>.
285    */
createDTMIterator(int node)286   public abstract DTMIterator createDTMIterator(int node);
287 
288   /* Flag indicating whether an incremental transform is desired */
289   public boolean m_incremental = false;
290 
291   /*
292    * Flag set by FEATURE_SOURCE_LOCATION.
293    * This feature specifies whether the transformation phase should
294    * keep track of line and column numbers for the input source
295    * document.
296    */
297   public boolean m_source_location = false;
298 
299   /**
300    * Get a flag indicating whether an incremental transform is desired
301    * @return incremental boolean.
302    *
303    */
getIncremental()304   public boolean getIncremental()
305   {
306     return m_incremental;
307   }
308 
309   /**
310    * Set a flag indicating whether an incremental transform is desired
311    * This flag should have the same value as the FEATURE_INCREMENTAL feature
312    * which is set by the TransformerFactory.setAttribut() method before a
313    * DTMManager is created
314    * @param incremental boolean to use to set m_incremental.
315    *
316    */
setIncremental(boolean incremental)317   public void setIncremental(boolean incremental)
318   {
319     m_incremental = incremental;
320   }
321 
322   /**
323    * Get a flag indicating whether the transformation phase should
324    * keep track of line and column numbers for the input source
325    * document.
326    * @return source location boolean
327    *
328    */
getSource_location()329   public boolean getSource_location()
330   {
331     return m_source_location;
332   }
333 
334   /**
335    * Set a flag indicating whether the transformation phase should
336    * keep track of line and column numbers for the input source
337    * document.
338    * This flag should have the same value as the FEATURE_SOURCE_LOCATION feature
339    * which is set by the TransformerFactory.setAttribut() method before a
340    * DTMManager is created
341    * @param sourceLocation boolean to use to set m_source_location
342    */
setSource_location(boolean sourceLocation)343   public void setSource_location(boolean sourceLocation){
344     m_source_location = sourceLocation;
345   }
346 
347 
348   // -------------------- private methods --------------------
349 
350    /**
351    * Temp debug code - this will be removed after we test everything
352    */
353   private static boolean debug;
354 
355   static
356   {
357     try
358     {
359       debug = System.getProperty("dtm.debug") != null;
360     }
361     catch (SecurityException ex){}
362   }
363 
364   /** This value, set at compile time, controls how many bits of the
365    * DTM node identifier numbers are used to identify a node within a
366    * document, and thus sets the maximum number of nodes per
367    * document. The remaining bits are used to identify the DTM
368    * document which contains this node.
369    *
370    * If you change IDENT_DTM_NODE_BITS, be sure to rebuild _ALL_ the
371    * files which use it... including the IDKey testcases.
372    *
373    * (FuncGenerateKey currently uses the node identifier directly and
374    * thus is affected when this changes. The IDKEY results will still be
375    * _correct_ (presuming no other breakage), but simple equality
376    * comparison against the previous "golden" files will probably
377    * complain.)
378    * */
379   public static final int IDENT_DTM_NODE_BITS = 16;
380 
381 
382   /** When this bitmask is ANDed with a DTM node handle number, the result
383    * is the low bits of the node's index number within that DTM. To obtain
384    * the high bits, add the DTM ID portion's offset as assigned in the DTM
385    * Manager.
386    */
387   public static final int IDENT_NODE_DEFAULT = (1<<IDENT_DTM_NODE_BITS)-1;
388 
389 
390   /** When this bitmask is ANDed with a DTM node handle number, the result
391    * is the DTM's document identity number.
392    */
393   public static final int IDENT_DTM_DEFAULT = ~IDENT_NODE_DEFAULT;
394 
395   /** This is the maximum number of DTMs available.  The highest DTM is
396     * one less than this.
397    */
398   public static final int IDENT_MAX_DTMS = (IDENT_DTM_DEFAULT >>> IDENT_DTM_NODE_BITS) + 1;
399 
400 
401   /**
402    * %TBD% Doc
403    *
404    * NEEDSDOC @param dtm
405    *
406    * NEEDSDOC ($objectName$) @return
407    */
getDTMIdentity(DTM dtm)408   public abstract int getDTMIdentity(DTM dtm);
409 
410   /**
411    * %TBD% Doc
412    *
413    * NEEDSDOC ($objectName$) @return
414    */
getDTMIdentityMask()415   public int getDTMIdentityMask()
416   {
417     return IDENT_DTM_DEFAULT;
418   }
419 
420   /**
421    * %TBD% Doc
422    *
423    * NEEDSDOC ($objectName$) @return
424    */
getNodeIdentityMask()425   public int getNodeIdentityMask()
426   {
427     return IDENT_NODE_DEFAULT;
428   }
429 
430 }
431