ConfigContext


1   /*
2    * The contents of this file are subject to the terms 
3    * of the Common Development and Distribution License 
4    * (the License).  You may not use this file except in
5    * compliance with the License.
6    * 
7    * You can obtain a copy of the license at 
8    * https://glassfish.dev.java.net/public/CDDLv1.0.html or
9    * glassfish/bootstrap/legal/CDDLv1.0.txt.
10   * See the License for the specific language governing 
11   * permissions and limitations under the License.
12   * 
13   * When distributing Covered Code, include this CDDL 
14   * Header Notice in each file and include the License file 
15   * at glassfish/bootstrap/legal/CDDLv1.0.txt.  
16   * If applicable, add the following below the CDDL Header, 
17   * with the fields enclosed by brackets [] replaced by
18   * you own identifying information: 
19   * "Portions Copyrighted [year] [name of copyright owner]"
20   * 
21   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
22   */
23  
24  package com.sun.enterprise.config;
25  
26  import java.util.ArrayList  ;
27  
28  // <addition> srini@sun.com server.xml verifier
29  import com.sun.enterprise.config.ConfigContextEvent;
30  // </addition> server.xml verifier
31  
32  /**
33   * A configuration context represents a heirarchical view of the configuration
34   * attributes. It reads the configuration attributes from <i> server.xml </i>
35   * The configuration context has a one-to-one realationship with
36   * a configuration file. 
37   *
38   * There is no public constructor. Use ConfigFactory to construct ConfigContext. 
39   *
40   * This object can be made readOnly and autoCommit during creation but these parameters
41   * cannot be changed once the object is created. Note that this object might be shared
42   * by number of threads.
43   *
44   * Here are some examples of code to illustrate lookup:
45   * 1. If you want to specifically locate a Node in the configuration: 
46   *    example:  jms resource in server.xml
47   *  <PRE>
48   *   ConfigBean conBean = 
49   *        ctx.exactLookup("/server/resources/jms-resource[@name='jms1']");
50   *  </PRE>
51   *
52   * Follow the syntax below for creating xpath expression for use in lookup/exactLookup. This is the only
53   *    syntax supported.
54   *  <PRE>
55   *      expression := /tagName | /tagName/tagExpression
56   *      tagExpression := tagName| tagName[@name='value'] | tagName/tagExpression | tagName[@name='value']/tagExpression
57   *  </PRE>
58   *
59   * Config API documentation:
60   * Config API is a powerful set of APIs that handle comples operations like:
61   * <PRE>
62   * 1. Basic Configuration (set and get elements and attributes APIs)
63   * 2. Event Notification
64   * 3. Cloning
65   * 4. XPath support
66   * 5. Change Mananagement (add, update, delete, set)
67   * 6. readonly
68   * 7. Auto Commit
69   * 8. Advanced Configuration (1 API to access attributes--ctx.getAttribute())
70   * 9. Intelligent refresh
71   * 10. Get dtd default values
72   * 11. DOM like API support (appendChild, removeChild)
73   * 12. Find APIs
74   * 13. Support Serialization and DeSerialization
75   * 14. Other Misc APIs (getChildBeansByName, getXPath, etc)
76   * 15. Merge APIs
77   *
78   * </PRE>
79   */
80  public interface ConfigContext {     
81                  
82      /**
83       * gets the url of the file/storage that this configcontext 
84       * is representing. It could be null in the case when the
85       * context has been cloned or deserialized
86       */
87      String   getUrl();
88      
89          /**
90           * returns the list of config changes done to this config context
91           * since the last reset or refresh or flush
92           */
93          public ArrayList   getConfigChangeList();
94              
95          /**
96           * reset config change list. 
97           */
98          public void resetConfigChangeList();
99              
100  
101         
102         /**
103          * Get the config bean for the root of the xml tree.
104          */
105         public ConfigBean getRootConfigBean() throws ConfigException;
106         
107         public void removeConfigChange(ConfigChange change);
108 
109         /**
110          * Retrieves the named object. The parameter passed is a <a href = http://www.w3.org/TR/xpath>
111          * XPath version 1.0</a>
112          * used as the path notation for navigating the hierarchical structure. Only the AbsoluteLocationPath
113          * and Relative LocationPath elements are used.
114          * The code below returns a ConfigBeam representing an application with appId="app1"
115          * <PRE>
116          * ConfigBean cn = conCtx.exactLookup(ServerXPathHelper.getAppIdXpathExpression("app1"));
117          * </PRE>
118          * @return a ConfigBean representing a node in the tree.
119          * 
120          * @param xpath
121          * @throws ConfigException
122          */
123     public ConfigBean exactLookup(String   xpath) throws ConfigException;
124     
125         /**
126          * Note the constraints on xpath
127          */
128         public ConfigBean[] lookup(String   xpath) throws ConfigException;
129         
130     /**
131          * saves all the changes in ConfigContext to storage
132          * Throws ConfigException if there is any problem writing to storage.
133          * or the file has been modified after last read. 
134          * However, if overwrite is true, then it overwrites any manual changes
135          * on disk
136          */
137         public void flush(boolean overwrite) throws ConfigException;
138 
139         /**
140          * is equivalent to flush(false)
141          */
142         public void flush() throws ConfigException;
143         
144         /** discards all the changes and reloads the xml from storage based on the force flag
145          *
146          *  @param force  forces a reload from disk even if dirty bit is not set. 
147          *  throws configexception if force is false and isDirty
148          */        
149         public void refresh(boolean force) throws ConfigException;
150 
151         /** 
152          * is equivalent to refresh(false).
153          */        
154         public void refresh() throws ConfigException;
155         
156         /**
157          * Clone entire config context. Note that configChangeList is not cloned.
158          *
159          */
160         public Object   clone();
161         
162         /**
163          * update this context with a configuration change. Changes done to
164          * configContext are maintained as a list of configChange objects
165          * This method is a convenient way of updating a context with a list
166          * of changes done to another context (may be in another VM)
167          */
168         public void updateFromConfigChange(ConfigChange configChange) throws ConfigException;
169         
170         /**
171          * see updateFromConfigChange(ConfigChange configChange)
172          * This method can be used for updating from a list of changes
173          * It is also used to check last modified so that all of them succeed for fail
174          * due to the changes.
175          * @return ArrayList of all failed updates
176          */
177         public ArrayList   updateFromConfigChange(ArrayList   configChangeList) throws ConfigException;
178         
179         
180         /**
181          * Get the Value of an attribute with One call 
182          * This equivalent of doing an exactLookup to get a bean 
183          * and then a getAttributeValue on that bean
184          * 
185          * @return value of attribute. null if it cannot find exactly 1 element
186          * or that attribute
187          * 
188          */
189         public String   getAttributeValue(String   xpath, String   attributeName);
190         
191         /**
192          * similar to getAttributeValue but returns a boolean
193          *
194          * @return true if it finds 1 element and attributeName has value=true
195          * else returns false.
196          */
197         public boolean getBooleanAttributeValue(String   xpath, String   attributeName);
198         
199         /**
200          * Tells you if this configcontext has changed since it was read in or changes
201          * were reset
202          */
203         public boolean isChanged();
204         
205         /**
206          * returns true if File has changed externally (not by this configcontext)
207          * after the configcontext was created
208          * Depends on whether it is enabled. if disabled, returns false
209          */
210         public boolean isFileChangedExternally();      
211         
212          /*
213          * Add Notification Listener
214          */
215         public void addConfigContextEventListener(ConfigContextEventListener ccel);
216         
217         /*
218          * remove
219          */
220         public void removeConfigContextEventListener(ConfigContextEventListener ccel);
221         
222         /*
223          * cleanup. call this method after you are done using the context
224          */
225         public void cleanup();
226         
227         
228         // FOLLOWING ARE USED ONLY FOR IMPLEMENTATION. FIXME: TO BE CLEANED UP
229         
230         /**
231          * add config update to the ConfigChangeList
232          * @return ConfigChange that was just added to ConfigChangeList
233          */
234         ConfigChange addToConfigChangeList(String   xpath, String   attrName, String   oldValue, String   newValue);
235         /**
236          * add config add to the ConfigChangeList
237          * @return ConfigChange that was just added to ConfigChangeList
238          */
239         ConfigChange addToConfigChangeList(String   xpath, String   childXpath, String   name, ConfigBean cb);
240         /**
241          * add config delete to the ConfigChangeList
242          * @return ConfigChange that was just added to ConfigChangeList
243          */
244         ConfigChange addToConfigChangeList(String   xpath);
245         /**
246          * add config set to the ConfigChangeList
247          * @return ConfigChange that was just added to ConfigChangeList
248          */
249         ConfigChange addToConfigChangeList(String   xpath, String   name, Object   cb, Object  [] cbArray);
250         
251         /**
252          * used only by impl for getting changes
253          */
254         // <addition> srini@sun.com server.xml verifier
255         //void preChange(String type);
256         void preChange(ConfigContextEvent ccce);
257         // </addition> server.xml verifier
258         
259         /**
260          * used only by impl for getting changes
261          */ 
262         // <addition> srini@sun.com server.xml verifier
263         //void postChange(String type);
264         void postChange(ConfigContextEvent ccce);
265         // </addition>  server.xml verifier
266 }
267
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags