001: /*****************************************************************************
002: * Source code information
003: * -----------------------
004: * Original author Ian Dickinson, HP Labs Bristol
005: * Author email ian.dickinson@hp.com
006: * Package Jena 2
007: * Web http://sourceforge.net/projects/jena/
008: * Created 04-Dec-2003
009: * Filename $RCSfile: SimpleXMLPath.java,v $
010: * Revision $Revision: 1.6 $
011: * Release status $State: Exp $
012: *
013: * Last modified on $Date: 2008/01/02 12:09:42 $
014: * by $Author: andy_seaborne $
015: *
016: * (c) Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
017: * [See end of file]
018: *****************************************************************************/package com.hp.hpl.jena.util.xml;
019:
020: // Imports
021: ///////////////
022: import java.util.*;
023:
024: import org.w3c.dom.*;
025:
026: import com.hp.hpl.jena.util.iterator.*;
027: import com.hp.hpl.jena.util.iterator.ExtendedIterator;
028:
029: /**
030: * <p>
031: * A simple path evaluator for traversing XML DOM trees. The simplicity arises from
032: * handling only a few types of XML nodes: document, element and attribute. Support
033: * for XML namespaces is currently missing.
034: * </p>
035: *
036: * @author Ian Dickinson, HP Labs (<a href="mailto:Ian.Dickinson@hp.com" >email</a>)
037: * @version CVS $Id: SimpleXMLPath.java,v 1.6 2008/01/02 12:09:42 andy_seaborne Exp $
038: */
039: public class SimpleXMLPath {
040: // Constants
041: //////////////////////////////////
042:
043: // Static variables
044: //////////////////////////////////
045:
046: // Instance variables
047: //////////////////////////////////
048:
049: /** The list of path components that comprises this path */
050: protected List m_path = new ArrayList();
051:
052: // Constructors
053: //////////////////////////////////
054:
055: /**
056: * <p>Construct a simple XML path. Additional traversals
057: * may be added with {@link #append}.
058: */
059: public SimpleXMLPath() {
060: this (false);
061: }
062:
063: /**
064: * <p>Construct a simple XML path, optionally starting with a
065: * default document path. Additional traversals
066: * may be added with {@link #append}.
067: * @param documentRoot If true, the first traversal on the path
068: * is to extract the document element from a DOM document node.
069: * If false, no initial traversal is created.
070: */
071: public SimpleXMLPath(boolean documentRoot) {
072: if (documentRoot) {
073: appendDocumentPath();
074: }
075: }
076:
077: // External signature methods
078: //////////////////////////////////
079:
080: /**
081: * <p>Append the given traversal to the end of this path, and return
082: * the path object so that further traversals can be appended.</p>
083: * @param path The path component to add to the end of the path
084: * @return The extended path itself
085: */
086: public SimpleXMLPath append(SimpleXMLPathComponent path) {
087: m_path.add(path);
088: return this ;
089: }
090:
091: /**
092: * <p>Convenience method for appending to this path the path component that
093: * selects the document element.</p>
094: * @return This path itself
095: */
096: public SimpleXMLPath appendDocumentPath() {
097: return append(new SimpleXMLPathDocument());
098: }
099:
100: /**
101: * <p>Convenience method for appending to this path the path component that
102: * selects the given element.</p>
103: * @param elemName The name of the element to select
104: * @return This path itself
105: */
106: public SimpleXMLPath appendElementPath(String elemName) {
107: return append(new SimpleXMLPathElement(elemName));
108: }
109:
110: /**
111: * <p>Convenience method for appending to this path the path component that
112: * selects the given attribute.</p>
113: * @param attrName The name of the attribute to select
114: * @return This path itself
115: */
116: public SimpleXMLPath appendAttrPath(String attrName) {
117: return append(new SimpleXMLPathAttr(attrName));
118: }
119:
120: /**
121: * <p>Answer the list of components of this path</p>
122: * @return The path components list
123: */
124: public List getPathComponents() {
125: return m_path;
126: }
127:
128: /**
129: * <p>Answer the i'th component of this path</p>
130: * @param i An index, starting from zero
131: * @return The simple path component at that index
132: */
133: public SimpleXMLPathComponent getPathComponent(int i) {
134: return (SimpleXMLPathComponent) m_path.get(i);
135: }
136:
137: /**
138: * <p>Answer an iterator that traverses this path from the given document
139: * node, and answers all possible values. This is thus a search evaluation
140: * of the path wrt the given document as a starting point.</p>
141: *
142: * @param doc The XML document to begin evaluating the path from
143: * @return An iterator over all of the leaf values that match this path, starting
144: * at doc
145: */
146: public ExtendedIterator getAll(Document doc) {
147: return WrappedIterator.create(new SimpleXMLPathIterator(this ,
148: doc));
149: }
150:
151: /**
152: * <p>Answer an iterator that traverses this path from the given document
153: * node, and answers all possible values. This is thus a search evaluation
154: * of the path wrt the given document as a starting point.</p>
155: *
156: * @param elem The XML document to begin evaluating the path from
157: * @return An iterator over all of the leaf values that match this path, starting
158: * at elem
159: */
160: public ExtendedIterator getAll(Element elem) {
161: return WrappedIterator.create(new SimpleXMLPathIterator(this ,
162: elem));
163: }
164:
165: // Internal implementation methods
166: //////////////////////////////////
167:
168: //==============================================================================
169: // Inner class definitions
170: //==============================================================================
171:
172: }
173:
174: /*
175: * (c) Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 Hewlett-Packard Development Company, LP
176: * All rights reserved.
177: *
178: * Redistribution and use in source and binary forms, with or without
179: * modification, are permitted provided that the following conditions
180: * are met:
181: * 1. Redistributions of source code must retain the above copyright
182: * notice, this list of conditions and the following disclaimer.
183: * 2. Redistributions in binary form must reproduce the above copyright
184: * notice, this list of conditions and the following disclaimer in the
185: * documentation and/or other materials provided with the distribution.
186: * 3. The name of the author may not be used to endorse or promote products
187: * derived from this software without specific prior written permission.
188: *
189: * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
190: * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
191: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
192: * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
193: * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
194: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
195: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
196: * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
197: * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
198: * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
199: */
|