KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > sape > carbon > core > config > node > Node


1 /*
2  * The contents of this file are subject to the Sapient Public License
3  * Version 1.0 (the "License"); you may not use this file except in compliance
4  * with the License. You may obtain a copy of the License at
5  * http://carbon.sf.net/License.html.
6  *
7  * Software distributed under the License is distributed on an "AS IS" basis,
8  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
9  * the specific language governing rights and limitations under the License.
10  *
11  * The Original Code is The Carbon Component Framework.
12  *
13  * The Initial Developer of the Original Code is Sapient Corporation
14  *
15  * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
16  */

17
18 package org.sape.carbon.core.config.node;
19
20 import org.sape.carbon.core.config.node.event.NodeEventListener;
21
22 /**
23  * <p>
24  * The base interface of all
25  * objects within the <code>ConfigurationService</code> data structure.
26  * This interface contains methods that all objects within the
27  * <code>ConfigurationService</code> data structure must implement.
28  * </p>
29  *
30  * Copyright 2002 Sapient
31  * @see org.sape.carbon.core.config.ConfigurationService
32  *
33  * @since carbon 1.0
34  * @author Douglas Voet, February 2002
35  * @version $Revision: 1.16 $($Author: dvoet $ / $Date: 2003/10/17 14:40:55 $)
36  */

37 public interface Node {
38
39     /** Delimter use used to separate node names in an absolute node name */
40     char DELIMITER = '/';
41
42     /**
43      * Returns the name of this node. The name should not include
44      * the node's relation to the node heirarchy. The name
45      * can not contain a '<code>/</code>'. The name of the root node is
46      * an empty <code>String</code>(<code>""</code>).
47      *
48      * @return name of the node
49      */

50     String JavaDoc getName();
51
52     /**
53      * Returns the absolute name of the node within the node heirarchy.
54      * This value always begins with a '<code>/</code>' with each
55      * node's name in the heirarchy seperated by a '<code>/</code>' unless
56      * this is the root node in which case it returns
57      * an empty <code>String</code>(<code>""</code>).
58      *
59      * @return Absolute name of the node.
60      */

61     String JavaDoc getAbsoluteName();
62
63     /**
64      * Allows determination of whether or not this node supports children
65      *
66      * @return <code>true</code> if the node can support children,
67      * <code>false</code> otherwise
68      */

69     boolean getAllowsChildren();
70
71     /**
72      * Permanently deletes the node and all of its child nodes from the
73      * backing store returning the total number of nodes deleted.
74      *
75      * @return The total number of nodes deleted. This number should always
76      * be at least '1' when the operation completed successfully.
77      *
78      * @throws NodeRemovalException when the node or one of its children
79      * can not be deleted. When this exception is thrown, some nodes may have
80      * been deleted while other may have not.
81      */

82     int remove() throws NodeRemovalException;
83
84     /**
85      * Gets the parent folder of the node.
86      * @return Folder the parent folder, null if this node is the root
87      */

88     Node getParent();
89
90     /**
91      * Used to tell whether or not the backing data of a node has
92      * been removed.
93      *
94      * @return true if the backing data of a node has been removed
95      */

96     boolean isRemoved();
97
98     /**
99      * Refreshes the Node's underlying cache of data (assuming is has one)
100      */

101     void refresh();
102
103     /**
104      * Returns an array of all children nodes, including standard
105      * <code>ConfigurationDocument</code>s and <code>Folder</code>. If this
106      * particular node does not have any children, an array of length zero
107      * is be returned.
108      *
109      * @return Array of child Nodes. <b>Never</b> null.
110      */

111     Node[] fetchChildren();
112
113     /**
114      * Returns a child <code>Node</code> of the current
115      * <code>Node</code> as defined by <code>childName</code>.
116      *
117      * @param childName The name of the child node to be returned.
118      * @return A child Node of the current node.
119      *
120      * @throws NodeNotFoundException when
121      * <code>childName</code> does not exist in the backing data store
122      */

123     Node fetchChild(String JavaDoc childName) throws NodeNotFoundException;
124
125     /**
126      * Checks if this <code>Folder</code> contains the child specified
127      * by childName
128      * @param childName the name of the child <code>Node</code>
129      * @return boolean true if the child exists, false otherwise.
130      */

131     boolean containsChild(String JavaDoc childName);
132
133     /**
134      * Method addNodeListener.
135      *
136      * @param listener lister for the node
137      * @since carbon 1.1
138      */

139     void addNodeListener(NodeEventListener listener);
140
141 }
Popular Tags