001: /*
002: * Copyright (C) 2004, 2005 Joe Walnes.
003: * Copyright (C) 2006, 2007 XStream Committers.
004: * All rights reserved.
005: *
006: * The software in this package is published under the terms of the BSD
007: * style license a copy of which has been included with this distribution in
008: * the LICENSE.txt file.
009: *
010: * Created on 07. March 2004 by Joe Walnes
011: */
012: package com.thoughtworks.xstream.io;
013:
014: import com.thoughtworks.xstream.converters.ErrorWriter;
015:
016: import java.util.Iterator;
017:
018: /**
019: * @author Joe Walnes
020: */
021: public interface HierarchicalStreamReader {
022:
023: /**
024: * Does the node have any more children remaining that have not yet been read?
025: */
026: boolean hasMoreChildren();
027:
028: /**
029: * Select the current child as current node.
030: * A call to this function must be balanced with a call to {@link #moveUp()}.
031: */
032: void moveDown();
033:
034: /**
035: * Select the parent node as current node.
036: */
037: void moveUp();
038:
039: /**
040: * Get the name of the current node.
041: */
042: String getNodeName();
043:
044: /**
045: * Get the value (text content) of the current node.
046: */
047: String getValue();
048:
049: /**
050: * Get the value of an attribute of the current node.
051: */
052: String getAttribute(String name);
053:
054: /**
055: * Get the value of an attribute of the current node, by index.
056: */
057: String getAttribute(int index);
058:
059: /**
060: * Number of attributes in current node.
061: */
062: int getAttributeCount();
063:
064: /**
065: * Name of attribute in current node.
066: */
067: String getAttributeName(int index);
068:
069: /**
070: * Names of attributes (as Strings).
071: */
072: Iterator getAttributeNames();
073:
074: /**
075: * If any errors are detected, allow the reader to add any additional information that can aid debugging
076: * (such as line numbers, XPath expressions, etc).
077: */
078: void appendErrors(ErrorWriter errorWriter);
079:
080: /**
081: * Close the reader, if necessary.
082: */
083: void close();
084:
085: /**
086: * Return the underlying HierarchicalStreamReader implementation.
087: *
088: * <p>If a Converter needs to access methods of a specific HierarchicalStreamReader implementation that are not
089: * defined in the HierarchicalStreamReader interface, it should call this method before casting. This is because
090: * the reader passed to the Converter is often wrapped/decorated by another implementation to provide additional
091: * functionality (such as XPath tracking).</p>
092: *
093: * <p>For example:</p>
094: * <pre>MySpecificReader mySpecificReader = (MySpecificReader)reader; <b>// INCORRECT!</b>
095: * mySpecificReader.doSomethingSpecific();</pre>
096:
097: * <pre>MySpecificReader mySpecificReader = (MySpecificReader)reader.underlyingReader(); <b>// CORRECT!</b>
098: * mySpecificReader.doSomethingSpecific();</pre>
099: *
100: * <p>Implementations of HierarchicalStreamReader should return 'this', unless they are a decorator, in which case
101: * they should delegate to whatever they are wrapping.</p>
102: */
103: HierarchicalStreamReader underlyingReader();
104:
105: }
|