org.xmlpull.infoset.xpath.jaxen.Navigator Maven / Gradle / Ivy
/*
* $Header: /l/extreme/cvs/codes/xpp5/xis5/infoset_xpath_jaxen/org/xmlpull/infoset/xpath/jaxen/Navigator.java,v 1.1 2005/05/16 23:59:18 aslom Exp $
* $Revision: 1.1 $
* $Date: 2005/05/16 23:59:18 $
*
* ====================================================================
*
* Copyright (C) 2000-2002 bob mcwhirter & James Strachan.
* 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 disclaimer that follows
* these conditions in the documentation and/or other materials
* provided with the distribution.
*
* 3. The name "Jaxen" must not be used to endorse or promote products
* derived from this software without prior written permission. For
* written permission, please contact [email protected].
*
* 4. Products derived from this software may not be called "Jaxen", nor
* may "Jaxen" appear in their name, without prior written permission
* from the Jaxen Project Management ([email protected]).
*
* In addition, we request (but do not require) that you include in the
* end-user documentation provided with the redistribution and/or in the
* software itself an acknowledgement equivalent to the following:
* "This product includes software developed by the
* Jaxen Project (http://www.jaxen.org/)."
* Alternatively, the acknowledgment may be graphical using the logos
* available at http://www.jaxen.org/
*
* 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 Jaxen AUTHORS OR THE PROJECT
* 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 Jaxen Project and was originally
* created by bob mcwhirter and
* James Strachan . For more information on the
* Jaxen Project, please see
* There is a method to obtain a java.util.Iterator,
* for each axis specified by XPath. If the target object model
* does not support the semantics of a particular axis, an
* {@link UnsupportedAxisException} is to be thrown.
*
*
* @author bob mcwhirter ([email protected])
* @author James Strachan
*/
public interface Navigator extends Serializable
{
// ------------------------------------------------------------
// ------------------------------------------------------------
// Axis Iterators
// ------------------------------------------------------------
// ------------------------------------------------------------
/** Retrieve an Iterator matching the child
* xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getChildAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the descendant
* xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getDescendantAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the parent xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getParentAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the ancestor
* xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getAncestorAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the
* following-sibling xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getFollowingSiblingAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the
* preceding-sibling xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getPrecedingSiblingAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the following
* xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getFollowingAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the preceding xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getPrecedingAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the attribute
* xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getAttributeAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the namespace
* xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getNamespaceAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the self xpath
* axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getSelfAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the
* descendant-or-self xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getDescendantOrSelfAxisIterator(Object contextNode) throws UnsupportedAxisException;
/** Retrieve an Iterator matching the
* ancestor-or-self xpath axis.
*
* @param contextNode The origin context node.
*
* @return An Iterator capable of traversing the axis.
*
* @throws UnsupportedAxisException is the semantics of this axis are
* not supported by this object model.
*/
Iterator getAncestorOrSelfAxisIterator(Object contextNode) throws UnsupportedAxisException;
// ------------------------------------------------------------
// ------------------------------------------------------------
// Extractors
// ------------------------------------------------------------
// ------------------------------------------------------------
/** Loads a document from the given URI
*
* @param uri is the URI of the document to load
*
* @throws FunctionCallException if the document could not be loaded
*/
Object getDocument(String uri) throws FunctionCallException;
/** Returns the document node that contains the given context node.
*
* @param object The context node.
*
* @return The document of the context node.
*
* @see #isDocument(Object)
*/
Object getDocumentNode(Object contextNode);
/** Returns the parent of the given context node.
*
*
* The parent of any node must either be a document
* node or an element node.
*
*
* @param object The context node.
*
* @return The parent of the context node.
*
* @see #isDocument
* @see #isElement
*/
Object getParentNode(Object contextNode) throws UnsupportedAxisException;
/** Retrieve the namespace URI of the given element node.
*
* @param element The context element node.
*
* @return The namespace URI of the element node.
*/
String getElementNamespaceUri(Object element);
/** Retrieve the name of the given element node.
*
* @param element The context element node.
*
* @return The name of the element node.
*/
String getElementName(Object element);
/** Retrieve the QName of the given element node.
*
* @param element The context element node.
*
* @return The QName of the element node.
*/
String getElementQName(Object element);
/** Retrieve the namespace URI of the given attribute node.
*
* @param element The context attribute node.
*
* @return The namespace URI of the attribute node.
*/
String getAttributeNamespaceUri(Object attr);
/** Retrieve the name of the given attribute node.
*
* @param element The context attribute node.
*
* @return The name of the attribute node.
*/
String getAttributeName(Object attr);
/** Retrieve the QName of the given attribute node.
*
* @param element The context attribute node.
*
* @return The QName of the attribute node.
*/
String getAttributeQName(Object attr);
/** Retrieve the target of a processing-instruction.
*
* @param pi The context processing-instruction node.
*
* @return The target of the processing-instruction node.
*/
String getProcessingInstructionTarget(Object pi);
/** Retrieve the data of a processing-instruction.
*
* @param pi The context processing-instruction node.
*
* @return The data of the processing-instruction node.
*/
String getProcessingInstructionData(Object pi);
// ------------------------------------------------------------
// ------------------------------------------------------------
// isXXX testers
// ------------------------------------------------------------
// ------------------------------------------------------------
/** Returns whether the given object is a document node. A document node
* is the node that is selected by the xpath expression /.
*
* @param object The object to test.
*
* @return true if the object is a document node,
* else false
*/
boolean isDocument(Object object);
/** Returns whether the given object is an element node.
*
* @param object The object to test.
*
* @return true if the object is an element node,
* else false
*/
boolean isElement(Object object);
/** Returns whether the given object is an attribute node.
*
* @param object The object to test.
*
* @return true if the object is an attribute node,
* else false
*/
boolean isAttribute(Object object);
/** Returns whether the given object is a namespace node.
*
* @param object The object to test.
*
* @return true if the object is a namespace node,
* else false
*/
boolean isNamespace(Object object);
/** Returns whether the given object is a comment node.
*
* @param object The object to test.
*
* @return true if the object is a comment node,
* else false
*/
boolean isComment(Object object);
/** Returns whether the given object is a text node.
*
* @param object The object to test.
*
* @return true if the object is a text node,
* else false
*/
boolean isText(Object object);
/** Returns whether the given object is a processing-instruction node.
*
* @param object The object to test.
*
* @return true if the object is a processing-instruction node,
* else false
*/
boolean isProcessingInstruction(Object object);
// ------------------------------------------------------------
// ------------------------------------------------------------
// String-Value extractors
// ------------------------------------------------------------
// ------------------------------------------------------------
/** Retrieve the string-value of a comment node.
*
* @param comment The comment node.
*
* @return The string-value of the node.
*/
String getCommentStringValue(Object comment);
/** Retrieve the string-value of an element node.
*
* @param element The comment node.
*
* @return The string-value of the node.
*/
String getElementStringValue(Object element);
/** Retrieve the string-value of an attribute node.
*
* @param attr The attribute node.
*
* @return The string-value of the node.
*/
String getAttributeStringValue(Object attr);
/** Retrieve the string-value of a namespace node.
*
* @param attr The namespace node.
*
* @return The string-value of the node.
*/
String getNamespaceStringValue(Object ns);
/** Retrieve the string-value of a text node.
*
* @param attr The text node.
*
* @return The string-value of the node.
*/
String getTextStringValue(Object txt);
// ------------------------------------------------------------
// ------------------------------------------------------------
// General utilities
// ------------------------------------------------------------
// ------------------------------------------------------------
/** Retrieve the namespace prefix of a namespace node.
*
* @param ns The namespace node.
*
* @return The prefix associated with the node.
*/
String getNamespacePrefix(Object ns);
/** Translate a namespace prefix to a namespace URI, possibly
* considering a particular element node.
*
*
* Strictly speaking, prefix-to-URI translation should occur
* irrespective of any element in the document. This method
* is provided to allow a non-conforming ease-of-use enhancement.
*
*
* @param prefix The prefix to translate.
* @param element The element to consider during translation.
*
* @return The namespace URI associated with the prefix.
*
* @see NamespaceContext
*/
String translateNamespacePrefixToUri(String prefix, Object element);
/** Returns a parsed form of the given xpath string, which will be suitable
* for queries on documents that use the same navigator as this one.
*
* @param xpath The xpath expression.
*
* @return A new XPath expression object.
*
* @see XPath
*/
XPath parseXPath(String xpath) throws SAXPathException;
/**
* Returns the element whose ID is given by elementId.
* If no such element exists, returns null.
* Attributes with the name "ID" are not of type ID unless so defined.
* Implementations that do not know whether attributes are of type ID or
* not are expected to return null.
*
* @param contextNode a node from the document in which to look for the
* id
* @param elementId id to look for
*
* @return element whose ID is given by elementId, or null if no such
* element exists in the document or if the implementation
* does not know about attribute types
*/
Object getElementById(Object contextNode, String elementId);
/** Returns a number that identifies the type of node that the given
* object represents in this navigator.
*
* @see org.jaxen.pattern.Pattern
*/
short getNodeType(Object node);
}
© 2015 - 2025 Weber Informatics LLC | Privacy Policy