KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > geronimo > kernel > config > ConfigurationManager


1 /**
2  * Licensed to the Apache Software Foundation (ASF) under one or more
3  * contributor license agreements. See the NOTICE file distributed with
4  * this work for additional information regarding copyright ownership.
5  * The ASF licenses this file to You under the Apache License, Version 2.0
6  * (the "License"); you may not use this file except in compliance with
7  * the License. You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.geronimo.kernel.config;
18
19 import java.io.IOException JavaDoc;
20 import java.util.List JavaDoc;
21 import org.apache.geronimo.kernel.repository.Artifact;
22 import org.apache.geronimo.kernel.repository.ArtifactResolver;
23 import org.apache.geronimo.kernel.repository.Version;
24 import org.apache.geronimo.gbean.AbstractName;
25
26 /**
27  * Encapsulates logic for dealing with configurations.
28  *
29  * Configurations have a lifecycle with three states: installed, loaded, and
30  * running. Installed means that the configuration is present in the server's
31  * repository. Loaded means that the Configuration GBean (including the
32  * configuration's ClassLoader) is running. Running means that all the GBeans
33  * in the Configuration are running.
34  *
35  * From a user perspective, there's not much difference between installed and
36  * loaded if the configuration has not been started (it still shows up as not
37  * running). However, certain operations will cause a configuration to be
38  * loaded but not started. For example, if ModuleA depends on ModuleB, then
39  * when ModuleA is distributed ModuleB will normally be loaded (to fire up the
40  * ClassLoader and validate ModuleA). But ModuleB will not be started at that
41  * point. It can be started manually or it will be started automatically when
42  * ModuleA is started.
43  *
44  * When a Configuration is not loaded, only its ConfigurationData is available
45  * for inspection. It's normally not possible to inspect the GBeans in the
46  * configuration because there's no ClassLoader that could be used to load the
47  * classes needed by the GBeanDatas in the configuration. Once the
48  * configuration has been loaded, it's ClassLoader is available so the
49  * GBeanDatas can be loaded and inspected. But the GBean instances are not
50  * instantiated and started until the configuration is started.
51  *
52  * @version $Rev: 476049 $ $Date: 2006-11-16 23:35:17 -0500 (Thu, 16 Nov 2006) $
53  */
54 public interface ConfigurationManager {
55     /**
56      * Is the specified configuration installed into the server
57      * environment? That is, does it exist in the configuration store,
58      * regardless of whether it's loaded or running? Note that this
59      * always returns false if the argument does not represent a
60      * configuration (e.g. if it's for a plain JAR).
61      *
62      * @param configurationId the configuration identifier, which must be
63      * fully resolved (isResolved() == true)
64      *
65      * @return true if the configuration has been loaded; false otherwise
66      */
67     boolean isInstalled(Artifact configurationId);
68
69     /**
70      * Is the specified configuration loaded into the kernel? Note that this
71      * always returns false if the argument does not represent a
72      * configuration (e.g. if it's for a plain JAR).
73      *
74      * @param configurationId the configuration identifier, which must be
75      * fully resolved (isResolved() == true)
76      *
77      * @return true if the configuration has been loaded; false otherwise
78      */
79     boolean isLoaded(Artifact configurationId);
80
81     /**
82      * Is the specified configuation running? Note that this
83      * always returns false if the argument does not represent a
84      * configuration (e.g. if it's for a plain JAR).
85      *
86      * @param configurationId the configuration identifier, which must be
87      * fully resolved (isResolved() == true)
88      *
89      * @return true if the configuration is running, false otherwise
90      */
91     boolean isRunning(Artifact configurationId);
92
93     /**
94      * Given an artifact that's not fully resolved (e.g. some parts are
95      * missing), check whether there are any instances installed into
96      * the server environment. That is, are there any matches in the
97      * configuration store, regardless of whether they're loaded or running?
98      * Note that this always returns an empty array if the argument does not
99      * represent a configuration (e.g. if it's for a plain JAR).
100      *
101      * @param query The partially-complete artifact name to check for
102      *
103      * @return All matching artifacts that are loaded in the server
104      */
105     Artifact[] getInstalled(Artifact query);
106
107     /**
108      * Given an artifact that's not fully resolved (e.g. some parts are
109      * missing), check whether there are any instances loaded.
110      * Note that this always returns an empty array if the argument does not
111      * represent a configuration (e.g. if it's for a plain JAR).
112      *
113      * @param query The partially-complete artifact name to check for
114      *
115      * @return All matching artifacts that are loaded in the server
116      */
117     Artifact[] getLoaded(Artifact query);
118
119     /**
120      * Given an artifact that's not fully resolved (e.g. some parts are
121      * missing), check whether there are any instances running.
122      * Note that this always returns an empty array if the argument does not
123      * represent a configuration (e.g. if it's for a plain JAR).
124      *
125      * @param query The partially-complete artifact name to check for
126      *
127      * @return All matching artifacts that are loaded in the server
128      */
129     Artifact[] getRunning(Artifact query);
130
131     /**
132      * Gets a List>ConfigurationInfo< of every of every available configuation.
133      * This includes all configurations installed, regardless of whether they are
134      * currently loaded or running.
135      */
136     List JavaDoc listConfigurations();
137
138     /**
139      * Return a list of the stores this manager knows about.
140      *
141      * @return a List>AbstractName< of the stores this manager controls
142      */
143     List JavaDoc listStores();
144
145     /**
146      * Get all the ConfigurationStores known to this manager at present
147      */
148     ConfigurationStore[] getStores();
149
150     /**
151      * Gets the configuration store responsible for the specified
152      * configuration, or null if there is none. The configuration need not be
153      * loaded or running; this just checks which store holds the data for it.
154      *
155      * @param configuration The unique ID for the configuration to check for,
156      * which must be fully resolved (isResolved() == true)
157      *
158      * @return The ConfigurationStore for this configuration, or null if the
159      * configuration was not found in any configuration store.
160      */
161     ConfigurationStore getStoreForConfiguration(Artifact configuration);
162
163     /**
164      * Return a list of the configurations in a specific store.
165      *
166      * @param store the store to list
167      *
168      * @return a List>ConfigurationInfo< of all the configurations in the store
169      *
170      * @throws NoSuchStoreException if the store could not be located
171      */
172     List JavaDoc listConfigurations(AbstractName store) throws NoSuchStoreException;
173
174     /**
175      * Is the specified artifact a configuration?
176      *
177      * @param artifact the ID of the artifact to check, which must be fully
178      * resolved (isResolved() == true)
179      *
180      * @return true if the artifact is a configuration available in the
181      * server (regardless of whether it has been loaded/started)
182      */
183     boolean isConfiguration(Artifact artifact);
184
185     /**
186      * Gets a loaded Configuration (does not see unloaded configurations).
187      *
188      * @param configurationId the unique ID of the configuration to get, which
189      * must be fully resolved (isResolved() == true)
190      *
191      * @return the specified configuration or null if the configuration has not been loaded
192      */
193     Configuration getConfiguration(Artifact configurationId);
194
195     /**
196      * Load the specified configuration (from a config store) and all
197      * configurations it depends on into the kernel. This causes the
198      * configuration gbean to be loaded and started, but does not load any of
199      * the gbeans contained within the configuration.
200      *
201      * @param configurationId the configuration identifier, which must be fully
202      * resolved (isResolved() == true)
203      *
204      * @return the results of the operation
205      *
206      * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
207      * @throws LifecycleException if there is a problem loading the configuration
208      */
209     LifecycleResults loadConfiguration(Artifact configurationId) throws NoSuchConfigException, LifecycleException;
210
211     /**
212      * Load the specified configurationData and all configurations it depends
213      * on (from a config store) into the kernel. This causes the configuration
214      * gbean to be loaded and started, but does not load any of the gbeans
215      * contained within the configuration.
216      *
217      * @param configurationData the configuration to load
218      *
219      * @return the results of the operation
220      *
221      * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
222      * @throws LifecycleException if there is a problem loading the configuration
223      */
224     LifecycleResults loadConfiguration(ConfigurationData configurationData) throws NoSuchConfigException, LifecycleException;
225
226     /**
227      * Load the specified configuration (from a config store) and all
228      * configurations it depends on into the kernel. This causes the
229      * configuration gbean to be loaded and started, but does not load any of
230      * the gbeans contained within the configuration.
231      *
232      * @param configurationId the configuration identifier, which must be fully
233      * resolved (isResolved() == true)
234      * @param monitor the monitor that should receive events as the operation is carried out
235      *
236      * @return the results of the operation
237      *
238      * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
239      * @throws LifecycleException if there is a problem loading the configuration
240      */
241     LifecycleResults loadConfiguration(Artifact configurationId, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
242
243     /**
244      * Load the specified configurationData and all configurations it depends
245      * on (from a config store) into the kernel. This causes the configuration
246      * gbean to be loaded and started, but does not load any of the gbeans
247      * contained within the configuration.
248      *
249      * @param configurationData the configuration to load
250      * @param monitor the monitor that should receive events as the operation is carried out
251      *
252      * @return the results of the operation
253      *
254      * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
255      * @throws LifecycleException if there is a problem loading the configuration
256      */
257     LifecycleResults loadConfiguration(ConfigurationData configurationData, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
258
259     /**
260      * Stops and unloads the configuration. This causes all contained gbeans
261      * to be stopped and unloaded, and the configuration gbean is stopped and
262      * unloaded. This operation causes all configurations that have a class
263      * or service dependency on the specified configuration to be stopped and
264      * unloaded.
265      *
266      * @param configurationId the configuration identifier, which must be fully
267      * resolved (isResolved() == true)
268      *
269      * @return the results of the operation
270      *
271      * @throws NoSuchConfigException if the configuration is not loaded
272      */
273     LifecycleResults unloadConfiguration(Artifact configurationId) throws NoSuchConfigException;
274
275     /**
276      * Stops and unloads the configuration. This causes all contained gbeans
277      * to be stopped and unloaded, and the configuration gbean is stopped and
278      * unloaded. This operation causes all configurations that have a class
279      * or service dependency on the specified configuration to be stopped and
280      * unloaded.
281      *
282      * @param configurationId the configuration identifier, which must be fully
283      * resolved (isResolved() == true)
284      * @param monitor the monitor that should receive events as the
285      * operation is carried out
286      *
287      * @return the results of the operation
288      *
289      * @throws NoSuchConfigException if the configuration is not loaded
290      */
291     LifecycleResults unloadConfiguration(Artifact configurationId, LifecycleMonitor monitor) throws NoSuchConfigException;
292
293     /**
294      * Loads and starts all of the gbeans contained within the configuration.
295      * If any of the gbeans fails to fully start, all gbeans will be unloaded
296      * and an exception will be thrown. This operation causes all
297      * configurations that the specified configuration has a service dependency
298      * on to be started.
299      *
300      * @param configurationId the configuration identifier, which must be fully
301      * resolved (isResolved() == true)
302      *
303      * @return the results of the operation
304      *
305      * @throws NoSuchConfigException if the configuration is not loaded
306      */
307     LifecycleResults startConfiguration(Artifact configurationId) throws NoSuchConfigException, LifecycleException;
308
309     /**
310      * Loads and starts all of the gbeans contained within the configuration.
311      * If any of the gbeans fails to fully start, all gbeans will be unloaded
312      * and an exception will be thrown. This operation causes all
313      * configurations that the specified configuration has a service dependency
314      * on to be started.
315      *
316      * @param configurationId the configuration identifier, which must be fully
317      * resolved (isResolved() == true)
318      * @param monitor the monitor that should receive events as the operation is carried out
319      *
320      * @return the results of the operation
321      *
322      * @throws NoSuchConfigException if the configuration is not loaded
323      */
324     LifecycleResults startConfiguration(Artifact configurationId, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
325
326     /**
327      * Stop the gbeans contained within the configuration. This operation
328      * causes all configurations that have a service dependency on the
329      * specified configuration to be stopped.
330      *
331      * @param configurationId the configuration identifier, which must be fully
332      * resolved (isResolved() == true)
333      *
334      * @return the results of the operation
335      *
336      * @throws NoSuchConfigException if the configuration is not loaded
337      */
338     LifecycleResults stopConfiguration(Artifact configurationId) throws NoSuchConfigException;
339
340     /**
341      * Stop the gbeans contained within the configuration. This operation
342      * causes all configurations that have a service dependency on the
343      * specified configuration to be stopped.
344      *
345      * @param configurationId the configuration identifier, which must be fully
346      * resolved (isResolved() == true)
347      * @param monitor the monitor that should receive events as the operation is carried out
348      *
349      * @return the results of the operation
350      *
351      * @throws NoSuchConfigException if the configuration is not loaded
352      */
353     LifecycleResults stopConfiguration(Artifact configurationId, LifecycleMonitor monitor) throws NoSuchConfigException;
354
355     /**
356      * Restarts the specified configuration and all configurations that have a
357      * service dependency on the specified configuration
358      *
359      * @param configurationId the configuration identifier, which must be fully
360      * resolved (isResolved() == true)
361      *
362      * @return the results of the operation
363      *
364      * @throws NoSuchConfigException if the configuration is not loaded
365      * @throws LifecycleException if there is a problem loading the configuration
366      */
367     LifecycleResults restartConfiguration(Artifact configurationId) throws NoSuchConfigException, LifecycleException;
368
369     /**
370      * Restarts the specified configuration and all configurations that have a
371      * service dependency on the specified configuration
372      *
373      * @param configurationId the configuration identifier, which must be fully
374      * resolved (isResolved() == true)
375      * @param monitor the monitor that should receive events as the operation is carried out
376      *
377      * @return the results of the operation
378      *
379      * @throws NoSuchConfigException if the configuration is not loaded
380      * @throws LifecycleException if there is a problem loading the configuration
381      */
382     LifecycleResults restartConfiguration(Artifact configurationId, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
383
384     /**
385      * Reloads the specified configuration and all configurations that have a
386      * dependency on the specified configuration
387      *
388      * @param configurationId the configuration identifier, which must be fully
389      * resolved (isResolved() == true)
390      *
391      * @return the results of the operation
392      *
393      * @throws NoSuchConfigException if the configuration is not loaded
394      * @throws LifecycleException if there is a problem loading the configuration
395      */
396     LifecycleResults reloadConfiguration(Artifact configurationId) throws NoSuchConfigException, LifecycleException;
397
398     /**
399      * Reloads the specified configuration and all configurations that have a
400      * dependency on the specified configuration
401      *
402      * @param configurationId the configuration identifier, which must be fully
403      * resolved (isResolved() == true)
404      * @param monitor the monitor that should receive events as the operation is carried out
405      *
406      * @return the results of the operation
407      *
408      * @throws NoSuchConfigException if the configuration is not loaded
409      * @throws LifecycleException if there is a problem loading the configuration
410      */
411     LifecycleResults reloadConfiguration(Artifact configurationId, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
412
413     /**
414      * Reloads the specified configuration and all configurations that have a
415      * dependency on the specified configuration
416      *
417      * @param configurationId the configuration identifier, which must be fully
418      * resolved (isResolved() == true)
419      * @param version new version to load from the config store
420      *
421      * @return the results of the operation
422      *
423      * @throws NoSuchConfigException if the configuration is not loaded
424      * @throws LifecycleException if there is a problem loading the configuration
425      */
426     LifecycleResults reloadConfiguration(Artifact configurationId, Version version) throws NoSuchConfigException, LifecycleException;
427
428     /**
429      * Reloads the specified configuration and all configurations that have a
430      * dependency on the specified configuration
431      *
432      * @param configurationId the configuration identifier, which must be fully
433      * resolved (isResolved() == true)
434      * @param monitor the monitor that should receive events as the operation is carried out
435      * @param version new version to load from the config store
436      *
437      * @return the results of the operation
438      *
439      * @throws NoSuchConfigException if the configuration is not loaded
440      * @throws LifecycleException if there is a problem loading the configuration
441      */
442     LifecycleResults reloadConfiguration(Artifact configurationId, Version version, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
443
444     /**
445      * Reloads the specified configuration and all configurations that have a
446      * dependency on the specified configuration
447      *
448      * @param configurationData the configuration to load
449      *
450      * @return the results of the operation
451      *
452      * @throws NoSuchConfigException if the configuration is not loaded
453      * @throws LifecycleException if there is a problem loading the configuration
454      */
455     LifecycleResults reloadConfiguration(ConfigurationData configurationData) throws NoSuchConfigException, LifecycleException;
456
457     /**
458      * Reloads the specified configuration and all configurations that have a
459      * dependency on the specified configuration
460      *
461      * @param configurationData the configuration to load
462      * @param monitor the monitor that should receive events as the operation is carried out
463      *
464      * @return the results of the operation
465      *
466      * @throws NoSuchConfigException if the configuration is not loaded
467      * @throws LifecycleException if there is a problem loading the configuration
468      */
469     LifecycleResults reloadConfiguration(ConfigurationData configurationData, LifecycleMonitor monitor) throws NoSuchConfigException, LifecycleException;
470
471     /**
472      * Unstalls the specified configuration from the server. This operation
473      * can not be reversed.
474      *
475      * @param configurationId the configuration identifier, which must be fully
476      * resolved (isResolved() == true)
477      *
478      * @throws IOException if there was a problem removing the configuration
479      * @throws NoSuchConfigException if the configuration is not loaded
480      */
481     void uninstallConfiguration(Artifact configurationId) throws IOException JavaDoc, NoSuchConfigException;
482
483     /**
484      * Gets the common ArtifactResolver in case the caller wants to use this
485      * directly. It is configured for all the repositories known to this
486      * configuration manager, etc.
487      */
488     ArtifactResolver getArtifactResolver();
489
490     /**
491      * Online means full functionality. Offline typically means that configurations will never be started,
492      * although they may be marked in the persistent configuration list.
493      *
494      * @return online status of ConfigurationManager
495      */
496     boolean isOnline();
497     void setOnline(boolean online);
498 }
499
Popular Tags