KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > registry > BasicContext


1 /*
2  * The contents of this file are subject to the terms of the Common Development
3  * and Distribution License (the License). You may not use this file except in
4  * compliance with the License.
5  *
6  * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7  * or http://www.netbeans.org/cddl.txt.
8  *
9  * When distributing Covered Code, include this CDDL Header Notice in each file
10  * and include the License file at http://www.netbeans.org/cddl.txt.
11  * If applicable, add the following below the CDDL Header, with the fields
12  * enclosed by brackets [] replaced by your own identifying information:
13  * "Portions Copyrighted [year] [name of copyright owner]"
14  *
15  * The Original Software is NetBeans. The Initial Developer of the Original
16  * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17  * Microsystems, Inc. All Rights Reserved.
18  */

19
20 package org.netbeans.spi.registry;
21
22 import org.netbeans.api.registry.ContextException;
23 import org.netbeans.api.registry.ContextListener;
24
25 import java.util.Collection JavaDoc;
26
27 /**
28  * This interface represents a basic context which consists of a set of
29  * name-to-object bindings. It contains methods for examining and
30  * updating these bindings. The contexts are composed into
31  * hierarchical collection which form configuration system. The
32  * configuration system allows applications to store and retrieve
33  * data.
34  *
35  * <p>The hierarchical collection of contexts is similar to folders
36  * in a hierarchical file system. There exist a root context containing
37  * all the contexts. The name of this context is <i>"/"</i>
38  * and it is also absolute name of the context. The names
39  * of individual contexts cannot be empty, but does not have to
40  * be unique. However, absolute name of the context must be
41  * unique. Children of the root context have absolute names of
42  * <i>"/" + context name</i>. All other contexts have absolute names of
43  * <i>parent's context absolute name + "/" + context name</i>.
44  *
45  * <p>All of the methods that modify context data are permitted to
46  * store changes asynchronously; they may fire change events
47  * and return immediatelly and propagate changes to backing store lazily.
48  *
49  * <p>At minimum the implementation must support persistence of
50  * all primitive data types and basic object types for which there
51  * are getters and setters in {@link org.netbeans.api.registry.Context} class.
52  * It is also recommended to provide a way for storage of other Object types
53  * (for example by using Java Serialization or other mechanism for
54  * persistence of objects). If provided it must be properly documented
55  * and explained to clients.
56  *
57  * <p>The context can contain the subcontext and binding with the same name
58  * and they will coexist without problems.
59  *
60  * <p>TBD: Names restrictions: length, valid characters, etc.
61  * The context name nor binding name cannot contain "/" character.
62  *
63  * <p>See also {@link ResettableContext} which is
64  * extensions of the basic context and {@link org.netbeans.api.registry.Context}
65  * which is API for bindings manipulation.
66  *
67  * @author David Konecny
68  */

69 public interface BasicContext {
70     
71     ///////////////////////////
72
// BasicContext related methods:
73
///////////////////////////
74

75     /**
76      * Gets root context. Method #
77      *
78      * @return root context
79      * @since 1.7
80      */

81     BasicContext getRootContext();
82     
83     /**
84      * Name of the context.
85      *
86      * @return name of the context
87      */

88     String JavaDoc getContextName();
89     
90     /**
91      * Retrieve direct subcontext of the given name.
92      *
93      * @param subcontextName subcontext name to retrieve; cannot be null
94      * @return Context or null if subcontext does not exist
95      */

96     BasicContext getSubcontext(String JavaDoc subcontextName);
97     
98     /**
99      * Retrieve parent context.
100      *
101      * @return parent context or null in case of root context
102      */

103     BasicContext getParentContext();
104     
105     /**
106      * Create subcontext of the given name.
107      *
108      * @param subcontextName valid name of nonexisting subcontext
109      * @return created context
110      * @throws ContextException thrown when subcontext cannot be create or
111      * context with this name already exist
112      */

113     BasicContext createSubcontext(String JavaDoc subcontextName) throws ContextException;
114     
115     /**
116      * Destroy subcontext of the given name. Destroying context deletes
117      * also all its data recursively, ie. all bindings, attributes
118      * and its subcontexts.
119      *
120      * @param subcontextName name of existing subcontext
121      * @throws ContextException thrown when subcontext cannot be deleted or
122      * context with this name does not exist
123      */

124     void destroySubcontext(String JavaDoc subcontextName) throws ContextException;
125
126
127     ///////////////////////////////
128
// Context enumeration methods:
129
///////////////////////////////
130

131     /**
132      * Retrieve names of all subcontexts of this context.
133      *
134      * @return collection of Strings, ie. names of all subcontexts in the context;
135      * cannot be null
136      */

137     Collection JavaDoc/*<String>*/ getSubcontextNames();
138
139     /**
140      * Get names of all bindings in this context.
141      *
142      * @return collection of Strings, ie. names of all bindings in the context;
143      * cannot be null
144      */

145     Collection JavaDoc/*<String>*/ getBindingNames();
146
147     /**
148      * Get names of all attributes in this context.
149      *
150      * @return collection of Strings, ie. names of all attribute in the context;
151      * cannot be null
152      */

153     Collection JavaDoc/*<String>*/ getAttributeNames(String JavaDoc bindingName);
154
155     
156     ///////////////////////////////
157
// Bindings related methods:
158
///////////////////////////////
159

160     /**
161      * Retrieve named object from the context.
162      *
163      * @param bindingName the name of the object to lookup; cannot be empty
164      * @return found object or null when no binding exist
165      * @throws ContextException thrown when object cannot be recreated
166      */

167     Object JavaDoc lookupObject(String JavaDoc bindingName) throws ContextException;
168
169     /**
170      * Binds a name to an object and store the object in context.
171      * Binding is deleted by passing null as object value.
172      *
173      * @param bindingName the name to bind; cannot be empty
174      * @param object the object to bind; null is allowed and means
175      * deletion of the binding
176      * @throws ContextException thrown when object cannot be bound
177      */

178     void bindObject(String JavaDoc bindingName, Object JavaDoc object) throws ContextException;
179
180
181     ////////////////////////////////////
182
// Attributes related methods:
183
////////////////////////////////////
184

185     /**
186      * Retrieve value of the attribute. Attributes can be specified
187      * on binding or context.
188      *
189      * @param bindingName name of the binding for binding attribute
190      * or null for context attribute
191      * @param attributeName name of the attribute to retrieve; cannot be null
192      * @return value of the attribute or null if attribute does not exist
193      * @throws ContextException thrown when attribute cannot be read
194      */

195     String JavaDoc getAttribute(String JavaDoc bindingName, String JavaDoc attributeName) throws ContextException;
196     
197     /**
198      * Modify value of the attribute. Attributes can be specified
199      * on binding or context. Attribute is deleted by passing null as attribute value.
200      *
201      * @param bindingName name of the binding for binding attribute
202      * or null for context attribute
203      * @param attributeName name of the attribute to modify; cannot be null
204      * @param value new value of the attribute; null is allowed and means
205      * deletion of attribute
206      * @throws ContextException thrown when object cannot be stored
207      */

208     void setAttribute(String JavaDoc bindingName, String JavaDoc attributeName, String JavaDoc value) throws ContextException;
209
210     
211     //////////////////////////////
212
// Listeners related methods:
213
//////////////////////////////
214

215     /**
216      * Add listener for receiving events about
217      * context and all its descendant subcontext changes.
218      *
219      * The listener must be notified about added/removed subcontext,
220      * added/modified/removed binding and added/modified/removed
221      * context or binding attribute in this context and all its subcontexts.
222      *
223      * @param listener listener to add
224      */

225     void addContextListener(ContextListener listener);
226     
227     /**
228      * Remove listener for receiving events about
229      * context and all its descedndant subcontexts changes.
230      *
231      * @param listener listener to remove
232      */

233     void removeContextListener(ContextListener listener);
234
235 }
236
Popular Tags