| /* |
| * 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/>. |
| */ |
| package org.apache.xml.utils; |
| |
| /** |
| * A DTMManager instance can be used to create DTM and |
| * DTMIterator objects, and manage the DTM objects in the system. |
| * |
| * <p>The system property that determines which Factory implementation |
| * to create is named "org.apache.xml.utils.DTMFactory". This |
| * property names a concrete subclass of the DTMFactory abstract |
| * class. If the property is not defined, a platform default is be used.</p> |
| * |
| * <p>An instance of this class <emph>must</emph> be safe to use across |
| * thread instances. It is expected that a client will create a single instance |
| * of a DTMManager to use across multiple threads. This will allow sharing |
| * of DTMs across multiple processes.</p> |
| * |
| * <p>Note: this class is incomplete right now. It will be pretty much |
| * modeled after javax.xml.transform.TransformerFactory in terms of its |
| * factory support.</p> |
| * |
| * <p>State: In progress!!</p> |
| */ |
| public abstract class DTMManager |
| { |
| |
| /** |
| * Default constructor is protected on purpose. |
| */ |
| protected DTMManager(){} |
| |
| /** |
| * Get an instance of a DTM. If the unique flag is true, a new instance will |
| * always be returned. Otherwise it is up to the DTMManager to return a |
| * new instance or an instance that it already created and may be being used |
| * by someone else. |
| * (I think more parameters will need to be added for error handling, and entity |
| * resolution). |
| * |
| * @param source the specification of the source object. |
| * @param unique true if the returned DTM must be unique, probably because it |
| * is going to be mutated. |
| * |
| * @return a non-null DTM reference. |
| */ |
| public abstract DTM getDTM(javax.xml.transform.Source source, |
| boolean unique); |
| |
| /** |
| * Get an instance of a DTM that "owns" a node handle. |
| * |
| * @param nodeHandle the nodeHandle. |
| * |
| * @return a non-null DTM reference. |
| */ |
| public abstract DTM getDTM(int nodeHandle); |
| |
| |
| /** |
| * Create a new <code>DTMIterator</code> based on an XPath |
| * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or |
| * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>. |
| * |
| * @param xpathCompiler ??? Somehow we need to pass in a subpart of the |
| * expression. I hate to do this with strings, since the larger expression |
| * has already been parsed. |
| * |
| * @param pos The position in the expression. |
| * @return The newly created <code>DTMIterator</code>. |
| */ |
| public abstract DTMIterator createDTMIterator(Object xpathCompiler, |
| int pos); |
| |
| /** |
| * Create a new <code>DTMIterator</code> based on an XPath |
| * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or |
| * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>. |
| * |
| * @param xpathString Must be a valid string expressing a |
| * <a href="http://www.w3.org/TR/xpath#NT-LocationPath>LocationPath</a> or |
| * a <a href="http://www.w3.org/TR/xpath#NT-UnionExpr">UnionExpr</a>. |
| * |
| * @param presolver An object that can resolve prefixes to namespace URLs. |
| * |
| * @return The newly created <code>DTMIterator</code>. |
| */ |
| public abstract DTMIterator createDTMIterator(String xpathString, |
| PrefixResolver presolver); |
| |
| /** |
| * Create a new <code>DTMIterator</code> based only on a whatToShow and |
| * a DTMFilter. The traversal semantics are defined as the descendant |
| * access. |
| * |
| * @param whatToShow This flag specifies which node types may appear in |
| * the logical view of the tree presented by the iterator. See the |
| * description of <code>NodeFilter</code> for the set of possible |
| * <code>SHOW_</code> values.These flags can be combined using |
| * <code>OR</code>. |
| * @param filter The <code>NodeFilter</code> to be used with this |
| * <code>TreeWalker</code>, or <code>null</code> to indicate no filter. |
| * @param entityReferenceExpansion The value of this flag determines |
| * whether entity reference nodes are expanded. |
| * |
| * @return The newly created <code>NodeIterator</code>. |
| */ |
| public abstract DTMIterator createDTMIterator(int whatToShow, |
| DTMFilter filter, boolean entityReferenceExpansion); |
| } |