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  ;
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   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   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   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   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  /*<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  /*<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  /*<String>*/ getAttributeNames(String   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   lookupObject(String   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   bindingName, Object   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   getAttribute(String   bindingName, String   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   bindingName, String   attributeName, String   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags