001package components.xmltree;
002
003/**
004 * XMLTree component with all its methods. (Note: by package-wide convention,
005 * all references are non-null.) <br/>
006 * <br/>
007 * An XMLTree is modeled by a tree where each node has a label (either a tag or
008 * some text) and if the label is a tag, the node also has a set of (attribute,
009 * value) pairs. <br/>
010 * <br/>
011 * There are two constructors. One takes the name of a file or a URL and a
012 * boolean flag, and constructs an XMLTree corresponding to the XML read from
013 * the file or URL. The boolean flag indicates whether leading/trailing
014 * whitespace should be trimmed from text nodes. The second constructor only
015 * takes the name of a file or a URL and behaves exactly as if the first
016 * constructor was invoked with a true flag (i.e., by default it trims
017 * whitespace).
018 */
019public interface XMLTree {
020
021    /**
022     * Returns the label of the root of {@code this}.
023     *
024     * @return the label of the root of {@code this}
025     * @ensures {@code
026     * label = [the label of the root of this (not including <> for tags)]
027     * }
028     */
029    String label();
030
031    /**
032     * Returns whether the label of the root of {@code this} is a tag.
033     *
034     * @return true iff the label of the root of {@code this} is a tag
035     * @ensures isTag = [the label of the root of this is a tag]
036     */
037    boolean isTag();
038
039    /**
040     * Returns whether the root tag of {@code this} has an attribute called
041     * {@code name}.
042     *
043     * @param name
044     *            the name of the possible attribute
045     * @return true iff the root tag of {@code this} has an attribute called
046     *         {@code name}
047     * @requires [the label of the root of this is a tag]
048     * @ensures <pre>
049     * hasAttribute =
050     *   [label of the root of this has an attribute called name]
051     * </pre>
052     */
053    boolean hasAttribute(String name);
054
055    /**
056     * Returns the value associated with the attribute of the root tag of
057     * {@code this} called {@code name}.
058     *
059     * @param name
060     *            the name of the attribute
061     * @return the value associated to attribute {@code name} of the root tag of
062     *         {@code this}
063     * @requires <pre>
064     * [the label of the root of this is a tag and
065     *    it has an attribute called name]
066     * </pre>
067     * @ensures <pre>
068     * attributeValue =
069     *   [the value associated with attribute name of the root tag of this]
070     * </pre>
071     */
072    String attributeValue(String name);
073
074    /**
075     * Returns the number of subtrees of the root of {@code this}.
076     *
077     * @return the number of subtrees of the root of {@code this}
078     * @requires [the label of the root of this is a tag]
079     * @ensures numberOfChildren = [the number of subtrees of the root of this]
080     */
081    int numberOfChildren();
082
083    /**
084     * Returns the {@code k}-th subtree of the root of {@code this}.
085     *
086     * @param k
087     *            the subtree to return
088     * @return the {@code k}-th subtree of the root of {@code this}
089     * @requires {@code
090     * [the label of the root of this is a tag and
091     *      0 <= k < the number of subtrees of the root of this]
092     * }
093     * @ensures child = [the k-th subtree of the root of this]
094     */
095    XMLTree child(int k);
096
097    /**
098     * Returns an {@code Iterable<String>} of the attribute names of the root of
099     * {@code this}.
100     *
101     * @return an {@code Iterable<String>} of the attribute names of the root of
102     *         {@code this}
103     * @requires [the label of the root of this is a tag]
104     * @ensures {@code
105     * attributeNames =
106     *   [an Iterable<String> of the attribute names of the root of this]
107     * }
108     */
109    Iterable<String> attributeNames();
110
111    /**
112     * Displays {@code this} in a new window with a default title.
113     *
114     * @ensures [this is displayed in a new window]
115     */
116    void display();
117
118    /**
119     * Displays {@code this} in a new window with the given {@code title}.
120     *
121     * @param title
122     *            the window title
123     * @ensures [this is displayed in a new window]
124     */
125    void display(String title);
126
127    /**
128     * Returns the XML string representation of {@code this}.
129     *
130     * @return the XML string representation of {@code this}
131     * @ensures toString = [the XML string representation of this]
132     */
133    @Override
134    String toString();
135
136}