Node


1   package org.sapia.archie;
2   
3   import java.util.Iterator  ;
4   
5   
6   /**
7    * This interface specifies the behavior of "nodes". Nodes hold child nodes that are bound
8    * to their parent with a given name. Nodes also hold values, that are arbitrary objects
9    * also bound to their parent node using a given name. 
10   * 
11   * @author Yanick Duchesne
12   * <dl>
13   * <dt><b>Copyright:</b><dd>Copyright &#169; 2002-2003 <a HREF="http://www.sapia-oss.org">Sapia Open Source Software</a>. All Rights Reserved.</dd></dt>
14   * <dt><b>License:</b><dd>Read the license.txt file of the jar or visit the
15   *        <a HREF="http://www.sapia-oss.org/license.html">license page</a> at the Sapia OSS web site</dd></dt>
16   * </dl>
17   */
18  public interface Node {
19    /**
20     * Returns this node's value.
21     *
22     * @return an <code>Object</code>, or <code>null</code> if this node has
23     * no value.
24     */
25    public Object   getValue(NamePart name);
26    
27    /**
28     * Internally removes the value that this node holds
29     * and returns it.
30     *  
31     * @return an <code>Object</code>, or <code>null</code> if this node has
32     * no value.
33     */
34    public Object   removeValue(NamePart name);
35  
36    /**
37     * Put a value into this node; overwrites the existing value - if any.
38     *
39     * @param name the name under which to bind the given value.
40     * @param value an <code>Object</code>.
41     * @param overwrite if <code>true</code>, overwrites the already existing value
42     * for the given name - it such is the case.
43     *
44     * @return <code>true</code> if the given value was added. Returns <code>false</code>
45     * if <code>overwrite</code> is <code>false</code> and a value already exists for the
46     * given name.
47     */
48    public boolean putValue(NamePart name, Object   value, boolean overwrite);
49  
50    /**
51     * Returns the names of this instance's values.
52     *
53     * @return an <code>Iterator</code> of <code>NamePart</code>s.
54     */
55    public Iterator   getValueNames();
56  
57    /**
58     * Returns the number of values that this instance contains.
59     *
60     * @return the number of values that this instance contains.
61     */
62    public int getValueCount();
63  
64    /**
65     * Sets this node's name and parent node. Client applications <b>must not</b>
66     * use this method - unless they know what they are doing.
67     *
68     * @param parent this instance's parent <code>Node</code>
69     * @param nodeName a <code>NamePart</code>.
70     */
71    public void setUp(Node parent, NamePart nodeName);
72  
73    /**
74     * Returns the full path to this node, starting from the root.
75     *
76     * @return a <code>Name</code>.
77     */
78    public Name getAbsolutePath();
79  
80    /**
81     * Returns this instance's parent.
82     *
83     * @return a <code>Node</code>.
84     */
85    public Node getParent();
86  
87    /**
88     * Return this instance's name.
89     *
90     * @return a <code>NamePart</code>.
91     */
92    public NamePart getName();
93  
94    /**
95     * Creates the node corresponding to the given name and returns it.
96     *
97     * @param name a <code>NamePart</code>
98     * @return a <code>Node</code>.
99     * @throws DuplicateException if a node exists for the given name.
100    */
101   public Node createChild(NamePart name)
102                    throws DuplicateException, ProcessingException;
103 
104   /**
105    * Returns the node with the given name.
106    *
107    * @param name a <code>NamePart</code> corresponding to the name of an
108    * existing child node.
109    *
110    * @return a <code>Node</code> or <code>null</code> if not child exists
111    * for the given name.
112    */
113   public Node getChild(NamePart name);
114   
115   /**
116    * Removes the node with the given name.
117    *
118    * @param name a <code>NamePart</code> corresponding to the name of an
119    * existing child node.
120    *
121    * @return a <code>Node</code> or <code>null</code> if not child exists
122    * for the given name.
123    */
124   public Node removeChild(NamePart name);  
125 
126   /**
127    * Returns this instance's child nodes.
128    *
129    * @return a <code>Iterator</code> of <code>Node</code>s.
130    */
131   public Iterator   getChildren();
132 
133   /**
134    * Returns the number of children that this instance contains.
135    *
136    * @return the number of children that this instance contains.
137    */
138   public int getChildrenCount();
139   
140   /**
141    * @return an <code>Iterator</code> of <code>Entry</code> instances,
142    * corresponding to the bindings that this instance holds.
143    */
144   public Iterator   getEntries();
145 
146   /**
147    * Returns the names of this instance's nodes.
148    *
149    * @return an <code>Iterator</code> of <code>NamePart</code>s.
150    */
151   public Iterator   getChildrenNames();
152 
153   /**
154    * Returns this implementation's name parser.
155    *
156    * @return a <code>NameParser</code>.
157    */
158   public NameParser getNameParser();
159 }
160
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags