001: /*
002: * The contents of this file are subject to the Sapient Public License
003: * Version 1.0 (the "License"); you may not use this file except in compliance
004: * with the License. You may obtain a copy of the License at
005: * http://carbon.sf.net/License.html.
006: *
007: * Software distributed under the License is distributed on an "AS IS" basis,
008: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
009: * the specific language governing rights and limitations under the License.
010: *
011: * The Original Code is The Carbon Component Framework.
012: *
013: * The Initial Developer of the Original Code is Sapient Corporation
014: *
015: * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
016: */
017:
018: package org.sape.carbon.core.config.node;
019:
020: import org.sape.carbon.core.config.node.event.NodeEventListener;
021:
022: /**
023: * <p>
024: * The base interface of all
025: * objects within the <code>ConfigurationService</code> data structure.
026: * This interface contains methods that all objects within the
027: * <code>ConfigurationService</code> data structure must implement.
028: * </p>
029: *
030: * Copyright 2002 Sapient
031: * @see org.sape.carbon.core.config.ConfigurationService
032: *
033: * @since carbon 1.0
034: * @author Douglas Voet, February 2002
035: * @version $Revision: 1.16 $($Author: dvoet $ / $Date: 2003/10/17 14:40:55 $)
036: */
037: public interface Node {
038:
039: /** Delimter use used to separate node names in an absolute node name */
040: char DELIMITER = '/';
041:
042: /**
043: * Returns the name of this node. The name should not include
044: * the node's relation to the node heirarchy. The name
045: * can not contain a '<code>/</code>'. The name of the root node is
046: * an empty <code>String</code>(<code>""</code>).
047: *
048: * @return name of the node
049: */
050: String getName();
051:
052: /**
053: * Returns the absolute name of the node within the node heirarchy.
054: * This value always begins with a '<code>/</code>' with each
055: * node's name in the heirarchy seperated by a '<code>/</code>' unless
056: * this is the root node in which case it returns
057: * an empty <code>String</code>(<code>""</code>).
058: *
059: * @return Absolute name of the node.
060: */
061: String getAbsoluteName();
062:
063: /**
064: * Allows determination of whether or not this node supports children
065: *
066: * @return <code>true</code> if the node can support children,
067: * <code>false</code> otherwise
068: */
069: boolean getAllowsChildren();
070:
071: /**
072: * Permanently deletes the node and all of its child nodes from the
073: * backing store returning the total number of nodes deleted.
074: *
075: * @return The total number of nodes deleted. This number should always
076: * be at least '1' when the operation completed successfully.
077: *
078: * @throws NodeRemovalException when the node or one of its children
079: * can not be deleted. When this exception is thrown, some nodes may have
080: * been deleted while other may have not.
081: */
082: int remove() throws NodeRemovalException;
083:
084: /**
085: * Gets the parent folder of the node.
086: * @return Folder the parent folder, null if this node is the root
087: */
088: Node getParent();
089:
090: /**
091: * Used to tell whether or not the backing data of a node has
092: * been removed.
093: *
094: * @return true if the backing data of a node has been removed
095: */
096: boolean isRemoved();
097:
098: /**
099: * 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 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 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: }
|