| <?xml version="1.0" standalone="no"?> |
| <!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd"> |
| <!-- |
| * The Apache Software License, Version 1.1 |
| * |
| * |
| * Copyright (c) 1999 The Apache Software Foundation. All rights |
| * reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions |
| * are met: |
| * |
| * 1. Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * |
| * 2. Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in |
| * the documentation and/or other materials provided with the |
| * distribution. |
| * |
| * 3. The end-user documentation included with the redistribution, |
| * if any, must include the following acknowledgment: |
| * "This product includes software developed by the |
| * Apache Software Foundation (http://www.apache.org/)." |
| * Alternately, this acknowledgment may appear in the software itself, |
| * if and wherever such third-party acknowledgments normally appear. |
| * |
| * 4. The names "Xalan" and "Apache Software Foundation" must |
| * not be used to endorse or promote products derived from this |
| * software without prior written permission. For written |
| * permission, please contact apache@apache.org. |
| * |
| * 5. Products derived from this software may not be called "Apache", |
| * nor may "Apache" appear in their name, without prior written |
| * permission of the Apache Software Foundation. |
| * |
| * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED |
| * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR |
| * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF |
| * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
| * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, |
| * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT |
| * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| * SUCH DAMAGE. |
| * ==================================================================== |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals on behalf of the Apache Software Foundation and was |
| * originally based on software copyright (c) 1999, Lotus |
| * Development Corporation., http://www.lotus.com. For more |
| * information on the Apache Software Foundation, please see |
| * <http://www.apache.org/>. |
| --> |
| <s1 title="&xslt4j; DTM"> |
| <ul> |
| <li><link anchor="intro">Introduction</link></li> |
| <li><link anchor="settings">Performance settings</link></li> |
| </ul><anchor name="intro"/> |
| <s2 title="Introduction"> |
| <p>The Document Table Model (DTM) is an interface to a Document Model designed specifically for the needs of our XPath and XSLT |
| implementations. The motivation behind this model is to optimize performance and minimize storage.</p> |
| <p>Specifically, DTM avoids the overhead of instantiating the objects the standard DOM requires to represent a tree of nodes. |
| DTM uses unique integer "handles" to identify nodes, integer ID values to represent URLs, local names, and expanded names, and |
| integer index and length references to a string buffer to represent the text value of each node.</p> |
| <p>In general, the "read" APIs to DTM resemble those of the W3C Document Object Model (<resource-ref idref="dom"/>) interface. |
| However, in place of the DOM object tree of nodes, DTM uses integer arrays and string pools to represent the structure and content |
| of the XML document to be transformed. DTM also structures the document's contents slightly differently, to better match the XPath |
| data model; some details and constraints present in a standard DOM are suppressed, and a few XPath-specific features are added.</p> |
| <p>DTM is intended to be a read-only model, and so does not attempt to replicate the DOM's write or create-node operations.</p> |
| <p>The details of constructing a DTM vary depending on which implementation of this API you are using. Two reference implementations are |
| currently available:</p> |
| <ul> |
| <li>SAX2DTM (built via a SAX stream)</li> |
| <li>DOM2DTM (which provides DTM access to an existing DOM)</li> |
| </ul> |
| <p>Both DTMs can be built incrementally (see <link anchor="incremental">incremental transforms</link>). When operating incrementally, the |
| DTM allows the Xalan processor to begin reading the DTM and performing the transformation while the DTM is still being assembled |
| (for example, while the parser is still parsing the XML source), and attempts to do only as much work as is needed to support the |
| read requests actually made by the XPath or XSLT processor.</p> |
| <p>For the convenience of user-written extensions, a proxy mechanism presents the contents of the DTM as a read-only subset of the DOM.</p> |
| </s2><anchor name="settings"/> |
| <s2 title="DTM performance settings"> |
| <p>&xslt4j; implements two DTM performance features that you can control with the TransformerFactory |
| <jump href="apidocs/javax/xml/transform/TransformerFactory.html#setAttribute(java.lang.String, java.lang.Object)">setAttribute(String name, Object value)</jump> |
| method.</p> |
| <table> |
| <tr> |
| <th>Attribute name (URL)</th> |
| <th>Default setting</th> |
| <th>Description</th> |
| </tr> |
| <tr> |
| <td>"http://xml.apache.org/xalan/features/incremental"</td> |
| <td>false</td> |
| <td><link anchor="incremental">incremental transforms</link></td> |
| </tr> |
| <tr> |
| <td>"http://xml.apache.org/xalan/features/optimize"</td> |
| <td>true</td> |
| <td><link anchor="optimized">optimized transforms</link></td> |
| </tr> |
| </table> |
| <p>Both of these DTM settings are described below.</p> |
| <note>The DTM also provides a setting that you can use to track location information for each node in the source document. See |
| <link idref="features" anchor="source_location">"http://apache.org/xalan/features/source_location"</link></note> |
| <anchor name="incremental"/> |
| <s3 title="'http://xml.apache.org/xalan/features/incremental'"> |
| <p>Set this feature to true to enable incremental transformations. If set to false (the default), the transform and the parse |
| are performed on the same thread.</p> |
| <note> When set to true: If the parser is Xerces, we perform an |
| incremental transform on a single thread using the Xerces |
| "parse on demand" feature. If the parser is not Xerces, we run the |
| transform in one thread and the parse in another. Exception: if the |
| parser is not Xerces and the XML source is a DOMSource, setting this |
| feature to true has no effect.</note> |
| <p>Example: setting incremental transforms to true:</p> |
| <source>javax.xml.transform.TransformerFactory tFactory = |
| javax.xml.transform.TransformerFactory.newInstance(); |
| // setAttribute() takes a String and an Object. |
| tFactory.setAttribute |
| ("http://xml.apache.org/xalan/features/incremental", |
| java.lang.Boolean.TRUE); |
| ...</source> |
| </s3><anchor name="optimized"/> |
| <s3 title="'http://xml.apache.org/xalan/features/optimize'"> |
| <p>When set to true (the default), this feature enables optimizations that may involve structural rewrites of the stylesheet. |
| Any tool that requires direct access to the stylesheet structure should set this feature to false.</p> |
| </s3> |
| </s2> |
| </s1> |