KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > hp > hpl > jena > util > xml > SimpleXMLPath


1 /*****************************************************************************
2  * Source code information
3  * -----------------------
4  * Original author Ian Dickinson, HP Labs Bristol
5  * Author email ian.dickinson@hp.com
6  * Package Jena 2
7  * Web http://sourceforge.net/projects/jena/
8  * Created 04-Dec-2003
9  * Filename $RCSfile: SimpleXMLPath.java,v $
10  * Revision $Revision: 1.3 $
11  * Release status $State: Exp $
12  *
13  * Last modified on $Date: 2005/02/21 12:20:33 $
14  * by $Author: andy_seaborne $
15  *
16  * (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
17  * [See end of file]
18  *****************************************************************************/
19
20 // Package
21 ///////////////
22 package com.hp.hpl.jena.util.xml;
23
24
25 // Imports
26 ///////////////
27 import java.util.*;
28
29 import org.w3c.dom.*;
30
31 import com.hp.hpl.jena.util.iterator.*;
32 import com.hp.hpl.jena.util.iterator.ExtendedIterator;
33
34
35 /**
36  * <p>
37  * A simple path evaluator for traversing XML DOM trees. The simplicity arises from
38  * handling only a few types of XML nodes: document, element and attribute. Support
39  * for XML namespaces is currently missing.
40  * </p>
41  *
42  * @author Ian Dickinson, HP Labs (<a HREF="mailto:Ian.Dickinson@hp.com" >email</a>)
43  * @version CVS $Id: SimpleXMLPath.java,v 1.3 2005/02/21 12:20:33 andy_seaborne Exp $
44  */
45 public class SimpleXMLPath
46 {
47     // Constants
48 //////////////////////////////////
49
50     // Static variables
51 //////////////////////////////////
52
53     // Instance variables
54 //////////////////////////////////
55
56     /** The list of path components that comprises this path */
57     protected List m_path = new ArrayList();
58     
59     // Constructors
60 //////////////////////////////////
61
62     /**
63      * <p>Construct a simple XML path. Additional traversals
64      * may be added with {@link #append}.
65      */
66     public SimpleXMLPath() {
67         this( false );
68     }
69     
70     
71     /**
72      * <p>Construct a simple XML path, optionally starting with a
73      * default document path. Additional traversals
74      * may be added with {@link #append}.
75      * @param documentRoot If true, the first traversal on the path
76      * is to extract the document element from a DOM document node.
77      * If false, no initial traversal is created.
78      */
79     public SimpleXMLPath( boolean documentRoot ) {
80         if (documentRoot) {
81             appendDocumentPath();
82         }
83     }
84     
85     
86     // External signature methods
87 //////////////////////////////////
88
89     /**
90      * <p>Append the given traversal to the end of this path, and return
91      * the path object so that further traversals can be appended.</p>
92      * @param path The path component to add to the end of the path
93      * @return The extended path itself
94      */
95     public SimpleXMLPath append( SimpleXMLPathComponent path ) {
96         m_path.add( path );
97         return this;
98     }
99     
100     
101     /**
102      * <p>Convenience method for appending to this path the path component that
103      * selects the document element.</p>
104      * @return This path itself
105      */
106     public SimpleXMLPath appendDocumentPath() {
107         return append( new SimpleXMLPathDocument() );
108     }
109     
110     
111     /**
112      * <p>Convenience method for appending to this path the path component that
113      * selects the given element.</p>
114      * @param elemName The name of the element to select
115      * @return This path itself
116      */
117     public SimpleXMLPath appendElementPath( String JavaDoc elemName ) {
118         return append( new SimpleXMLPathElement( elemName ) );
119     }
120     
121     
122     /**
123      * <p>Convenience method for appending to this path the path component that
124      * selects the given attribute.</p>
125      * @param attrName The name of the attribute to select
126      * @return This path itself
127      */
128     public SimpleXMLPath appendAttrPath( String JavaDoc attrName ) {
129         return append( new SimpleXMLPathAttr( attrName ) );
130     }
131     
132     /**
133      * <p>Answer the list of components of this path</p>
134      * @return The path components list
135      */
136     public List getPathComponents() {
137         return m_path;
138     }
139     
140     
141     /**
142      * <p>Answer the i'th component of this path</p>
143      * @param i An index, starting from zero
144      * @return The simple path component at that index
145      */
146     public SimpleXMLPathComponent getPathComponent( int i ) {
147         return (SimpleXMLPathComponent) m_path.get( i );
148     }
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 doc 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 doc
159      */
160     public ExtendedIterator getAll( Document doc ) {
161         return WrappedIterator.create( new SimpleXMLPathIterator( this, doc ) );
162     }
163
164     
165     /**
166      * <p>Answer an iterator that traverses this path from the given document
167      * node, and answers all possible values. This is thus a search evaluation
168      * of the path wrt the given document as a starting point.</p>
169      *
170      * @param elem The XML document to begin evaluating the path from
171      * @return An iterator over all of the leaf values that match this path, starting
172      * at elem
173      */
174     public ExtendedIterator getAll( Element elem ) {
175         return WrappedIterator.create( new SimpleXMLPathIterator( this, elem ) );
176     }
177     
178     
179     // Internal implementation methods
180 //////////////////////////////////
181
182     //==============================================================================
183 // Inner class definitions
184 //==============================================================================
185
186 }
187
188
189 /*
190  * (c) Copyright 2001, 2002, 2003, 2004, 2005 Hewlett-Packard Development Company, LP
191  * All rights reserved.
192  *
193  * Redistribution and use in source and binary forms, with or without
194  * modification, are permitted provided that the following conditions
195  * are met:
196  * 1. Redistributions of source code must retain the above copyright
197  * notice, this list of conditions and the following disclaimer.
198  * 2. Redistributions in binary form must reproduce the above copyright
199  * notice, this list of conditions and the following disclaimer in the
200  * documentation and/or other materials provided with the distribution.
201  * 3. The name of the author may not be used to endorse or promote products
202  * derived from this software without specific prior written permission.
203  *
204  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
205  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
206  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
207  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
208  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
209  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
210  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
211  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
212  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
213  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
214  */
215
Popular Tags