001: /**
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. See the NOTICE file distributed with
004: * this work for additional information regarding copyright ownership.
005: * The ASF licenses this file to You under the Apache License, Version 2.0
006: * (the "License"); you may not use this file except in compliance with
007: * the License. You may obtain a copy of the License at
008: *
009: * http://www.apache.org/licenses/LICENSE-2.0
010: *
011: * Unless required by applicable law or agreed to in writing, software
012: * distributed under the License is distributed on an "AS IS" BASIS,
013: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014: * See the License for the specific language governing permissions and
015: * limitations under the License.
016: */package org.apache.geronimo.kernel.config;
017:
018: import java.io.IOException;
019: import java.util.List;
020: import java.util.Collection;
021: import java.util.LinkedHashSet;
022:
023: import org.apache.geronimo.kernel.repository.Artifact;
024: import org.apache.geronimo.kernel.repository.ArtifactResolver;
025: import org.apache.geronimo.kernel.repository.Version;
026: import org.apache.geronimo.kernel.repository.Repository;
027: import org.apache.geronimo.kernel.repository.MissingDependencyException;
028: import org.apache.geronimo.gbean.AbstractName;
029:
030: /**
031: * Encapsulates logic for dealing with configurations.
032: *
033: * Configurations have a lifecycle with three states: installed, loaded, and
034: * running. Installed means that the configuration is present in the server's
035: * repository. Loaded means that the Configuration GBean (including the
036: * configuration's ClassLoader) is running. Running means that all the GBeans
037: * in the Configuration are running.
038: *
039: * From a user perspective, there's not much difference between installed and
040: * loaded if the configuration has not been started (it still shows up as not
041: * running). However, certain operations will cause a configuration to be
042: * loaded but not started. For example, if ModuleA depends on ModuleB, then
043: * when ModuleA is distributed ModuleB will normally be loaded (to fire up the
044: * ClassLoader and validate ModuleA). But ModuleB will not be started at that
045: * point. It can be started manually or it will be started automatically when
046: * ModuleA is started.
047: *
048: * When a Configuration is not loaded, only its ConfigurationData is available
049: * for inspection. It's normally not possible to inspect the GBeans in the
050: * configuration because there's no ClassLoader that could be used to load the
051: * classes needed by the GBeanDatas in the configuration. Once the
052: * configuration has been loaded, it's ClassLoader is available so the
053: * GBeanDatas can be loaded and inspected. But the GBean instances are not
054: * instantiated and started until the configuration is started.
055: *
056: * @version $Rev: 620729 $ $Date: 2008-02-12 01:19:46 -0800 (Tue, 12 Feb 2008) $
057: */
058: public interface ConfigurationManager {
059: /**
060: * Is the specified configuration installed into the server
061: * environment? That is, does it exist in the configuration store,
062: * regardless of whether it's loaded or running? Note that this
063: * always returns false if the argument does not represent a
064: * configuration (e.g. if it's for a plain JAR).
065: *
066: * @param configurationId the configuration identifier, which must be
067: * fully resolved (isResolved() == true)
068: *
069: * @return true if the configuration has been loaded; false otherwise
070: */
071: boolean isInstalled(Artifact configurationId);
072:
073: /**
074: * Is the specified configuration loaded into the kernel? Note that this
075: * always returns false if the argument does not represent a
076: * configuration (e.g. if it's for a plain JAR).
077: *
078: * @param configurationId the configuration identifier, which must be
079: * fully resolved (isResolved() == true)
080: *
081: * @return true if the configuration has been loaded; false otherwise
082: */
083: boolean isLoaded(Artifact configurationId);
084:
085: /**
086: * Is the specified configuation running? Note that this
087: * always returns false if the argument does not represent a
088: * configuration (e.g. if it's for a plain JAR).
089: *
090: * @param configurationId the configuration identifier, which must be
091: * fully resolved (isResolved() == true)
092: *
093: * @return true if the configuration is running, false otherwise
094: */
095: boolean isRunning(Artifact configurationId);
096:
097: /**
098: * Given an artifact that's not fully resolved (e.g. some parts are
099: * missing), check whether there are any instances installed into
100: * the server environment. That is, are there any matches in the
101: * configuration store, regardless of whether they're loaded or running?
102: * Note that this always returns an empty array if the argument does not
103: * represent a configuration (e.g. if it's for a plain JAR).
104: *
105: * @param query The partially-complete artifact name to check for
106: *
107: * @return All matching artifacts that are loaded in the server
108: */
109: Artifact[] getInstalled(Artifact query);
110:
111: /**
112: * Given an artifact that's not fully resolved (e.g. some parts are
113: * missing), check whether there are any instances loaded.
114: * Note that this always returns an empty array if the argument does not
115: * represent a configuration (e.g. if it's for a plain JAR).
116: *
117: * @param query The partially-complete artifact name to check for
118: *
119: * @return All matching artifacts that are loaded in the server
120: */
121: Artifact[] getLoaded(Artifact query);
122:
123: /**
124: * Given an artifact that's not fully resolved (e.g. some parts are
125: * missing), check whether there are any instances running.
126: * Note that this always returns an empty array if the argument does not
127: * represent a configuration (e.g. if it's for a plain JAR).
128: *
129: * @param query The partially-complete artifact name to check for
130: *
131: * @return All matching artifacts that are loaded in the server
132: */
133: Artifact[] getRunning(Artifact query);
134:
135: /**
136: * Gets a List>ConfigurationInfo< of every of every available configuation.
137: * This includes all configurations installed, regardless of whether they are
138: * currently loaded or running.
139: */
140: List listConfigurations();
141:
142: /**
143: * Return a list of the stores this manager knows about.
144: *
145: * @return a List>AbstractName< of the stores this manager controls
146: */
147: List listStores();
148:
149: /**
150: * Get all the ConfigurationStores known to this manager at present
151: */
152: ConfigurationStore[] getStores();
153:
154: /**
155: * Gets the configuration store responsible for the specified
156: * configuration, or null if there is none. The configuration need not be
157: * loaded or running; this just checks which store holds the data for it.
158: *
159: * @param configuration The unique ID for the configuration to check for,
160: * which must be fully resolved (isResolved() == true)
161: *
162: * @return The ConfigurationStore for this configuration, or null if the
163: * configuration was not found in any configuration store.
164: */
165: ConfigurationStore getStoreForConfiguration(Artifact configuration);
166:
167: /**
168: * Return a list of the configurations in a specific store.
169: *
170: * @param store the store to list
171: *
172: * @return a List>ConfigurationInfo< of all the configurations in the store
173: *
174: * @throws NoSuchStoreException if the store could not be located
175: */
176: List listConfigurations(AbstractName store)
177: throws NoSuchStoreException;
178:
179: /**
180: * Is the specified artifact a configuration?
181: *
182: * @param artifact the ID of the artifact to check, which must be fully
183: * resolved (isResolved() == true)
184: *
185: * @return true if the artifact is a configuration available in the
186: * server (regardless of whether it has been loaded/started)
187: */
188: boolean isConfiguration(Artifact artifact);
189:
190: /**
191: * Gets a loaded Configuration (does not see unloaded configurations).
192: *
193: * @param configurationId the unique ID of the configuration to get, which
194: * must be fully resolved (isResolved() == true)
195: *
196: * @return the specified configuration or null if the configuration has not been loaded
197: */
198: Configuration getConfiguration(Artifact configurationId);
199:
200: /**
201: * Load the specified configuration (from a config store) and all
202: * configurations it depends on into the kernel. This causes the
203: * configuration gbean to be loaded and started, but does not load any of
204: * the gbeans contained within the configuration.
205: *
206: * @param configurationId the configuration identifier, which must be fully
207: * resolved (isResolved() == true)
208: *
209: * @return the results of the operation
210: *
211: * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
212: * @throws LifecycleException if there is a problem loading the configuration
213: */
214: LifecycleResults loadConfiguration(Artifact configurationId)
215: throws NoSuchConfigException, LifecycleException;
216:
217: /**
218: * Load the specified configurationData and all configurations it depends
219: * on (from a config store) into the kernel. This causes the configuration
220: * gbean to be loaded and started, but does not load any of the gbeans
221: * contained within the configuration.
222: *
223: * @param configurationData the configuration to load
224: *
225: * @return the results of the operation
226: *
227: * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
228: * @throws LifecycleException if there is a problem loading the configuration
229: */
230: LifecycleResults loadConfiguration(
231: ConfigurationData configurationData)
232: throws NoSuchConfigException, LifecycleException;
233:
234: /**
235: * Load the specified configuration (from a config store) and all
236: * configurations it depends on into the kernel. This causes the
237: * configuration gbean to be loaded and started, but does not load any of
238: * the gbeans contained within the configuration.
239: *
240: * @param configurationId the configuration identifier, which must be fully
241: * resolved (isResolved() == true)
242: * @param monitor the monitor that should receive events as the operation is carried out
243: *
244: * @return the results of the operation
245: *
246: * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
247: * @throws LifecycleException if there is a problem loading the configuration
248: */
249: LifecycleResults loadConfiguration(Artifact configurationId,
250: LifecycleMonitor monitor) throws NoSuchConfigException,
251: LifecycleException;
252:
253: /**
254: * Load the specified configurationData and all configurations it depends
255: * on (from a config store) into the kernel. This causes the configuration
256: * gbean to be loaded and started, but does not load any of the gbeans
257: * contained within the configuration.
258: *
259: * @param configurationData the configuration to load
260: * @param monitor the monitor that should receive events as the operation is carried out
261: *
262: * @return the results of the operation
263: *
264: * @throws NoSuchConfigException if no configuration with the given id exists in the configuration stores
265: * @throws LifecycleException if there is a problem loading the configuration
266: */
267: LifecycleResults loadConfiguration(
268: ConfigurationData configurationData,
269: LifecycleMonitor monitor) throws NoSuchConfigException,
270: LifecycleException;
271:
272: /**
273: * Stops and unloads the configuration. This causes all contained gbeans
274: * to be stopped and unloaded, and the configuration gbean is stopped and
275: * unloaded. This operation causes all configurations that have a class
276: * or service dependency on the specified configuration to be stopped and
277: * unloaded.
278: *
279: * @param configurationId the configuration identifier, which must be fully
280: * resolved (isResolved() == true)
281: *
282: * @return the results of the operation
283: *
284: * @throws NoSuchConfigException if the configuration is not loaded
285: */
286: LifecycleResults unloadConfiguration(Artifact configurationId)
287: throws NoSuchConfigException;
288:
289: /**
290: * Stops and unloads the configuration. This causes all contained gbeans
291: * to be stopped and unloaded, and the configuration gbean is stopped and
292: * unloaded. This operation causes all configurations that have a class
293: * or service dependency on the specified configuration to be stopped and
294: * unloaded.
295: *
296: * @param configurationId the configuration identifier, which must be fully
297: * resolved (isResolved() == true)
298: * @param monitor the monitor that should receive events as the
299: * operation is carried out
300: *
301: * @return the results of the operation
302: *
303: * @throws NoSuchConfigException if the configuration is not loaded
304: */
305: LifecycleResults unloadConfiguration(Artifact configurationId,
306: LifecycleMonitor monitor) throws NoSuchConfigException;
307:
308: /**
309: * Loads and starts all of the gbeans contained within the configuration.
310: * If any of the gbeans fails to fully start, all gbeans will be unloaded
311: * and an exception will be thrown. This operation causes all
312: * configurations that the specified configuration has a service dependency
313: * on to be started.
314: *
315: * @param configurationId the configuration identifier, which must be fully
316: * resolved (isResolved() == true)
317: *
318: * @return the results of the operation
319: *
320: * @throws NoSuchConfigException if the configuration is not loaded
321: */
322: LifecycleResults startConfiguration(Artifact configurationId)
323: throws NoSuchConfigException, LifecycleException;
324:
325: /**
326: * Loads and starts all of the gbeans contained within the configuration.
327: * If any of the gbeans fails to fully start, all gbeans will be unloaded
328: * and an exception will be thrown. This operation causes all
329: * configurations that the specified configuration has a service dependency
330: * on to be started.
331: *
332: * @param configurationId the configuration identifier, which must be fully
333: * resolved (isResolved() == true)
334: * @param monitor the monitor that should receive events as the operation is carried out
335: *
336: * @return the results of the operation
337: *
338: * @throws NoSuchConfigException if the configuration is not loaded
339: */
340: LifecycleResults startConfiguration(Artifact configurationId,
341: LifecycleMonitor monitor) throws NoSuchConfigException,
342: LifecycleException;
343:
344: /**
345: * Stop the gbeans contained within the configuration. This operation
346: * causes all configurations that have a service dependency on the
347: * specified configuration to be stopped.
348: *
349: * @param configurationId the configuration identifier, which must be fully
350: * resolved (isResolved() == true)
351: *
352: * @return the results of the operation
353: *
354: * @throws NoSuchConfigException if the configuration is not loaded
355: */
356: LifecycleResults stopConfiguration(Artifact configurationId)
357: throws NoSuchConfigException;
358:
359: /**
360: * Stop the gbeans contained within the configuration. This operation
361: * causes all configurations that have a service dependency on the
362: * specified configuration to be stopped.
363: *
364: * @param configurationId the configuration identifier, which must be fully
365: * resolved (isResolved() == true)
366: * @param monitor the monitor that should receive events as the operation is carried out
367: *
368: * @return the results of the operation
369: *
370: * @throws NoSuchConfigException if the configuration is not loaded
371: */
372: LifecycleResults stopConfiguration(Artifact configurationId,
373: LifecycleMonitor monitor) throws NoSuchConfigException;
374:
375: /**
376: * Restarts the specified configuration and all configurations that have a
377: * service dependency on the specified configuration
378: *
379: * @param configurationId the configuration identifier, which must be fully
380: * resolved (isResolved() == true)
381: *
382: * @return the results of the operation
383: *
384: * @throws NoSuchConfigException if the configuration is not loaded
385: * @throws LifecycleException if there is a problem loading the configuration
386: */
387: LifecycleResults restartConfiguration(Artifact configurationId)
388: throws NoSuchConfigException, LifecycleException;
389:
390: /**
391: * Restarts the specified configuration and all configurations that have a
392: * service dependency on the specified configuration
393: *
394: * @param configurationId the configuration identifier, which must be fully
395: * resolved (isResolved() == true)
396: * @param monitor the monitor that should receive events as the operation is carried out
397: *
398: * @return the results of the operation
399: *
400: * @throws NoSuchConfigException if the configuration is not loaded
401: * @throws LifecycleException if there is a problem loading the configuration
402: */
403: LifecycleResults restartConfiguration(Artifact configurationId,
404: LifecycleMonitor monitor) throws NoSuchConfigException,
405: LifecycleException;
406:
407: /**
408: * Reloads the specified configuration and all configurations that have a
409: * dependency on the specified configuration
410: *
411: * @param configurationId the configuration identifier, which must be fully
412: * resolved (isResolved() == true)
413: *
414: * @return the results of the operation
415: *
416: * @throws NoSuchConfigException if the configuration is not loaded
417: * @throws LifecycleException if there is a problem loading the configuration
418: */
419: LifecycleResults reloadConfiguration(Artifact configurationId)
420: throws NoSuchConfigException, LifecycleException;
421:
422: /**
423: * Reloads the specified configuration and all configurations that have a
424: * dependency on the specified configuration
425: *
426: * @param configurationId the configuration identifier, which must be fully
427: * resolved (isResolved() == true)
428: * @param monitor the monitor that should receive events as the operation is carried out
429: *
430: * @return the results of the operation
431: *
432: * @throws NoSuchConfigException if the configuration is not loaded
433: * @throws LifecycleException if there is a problem loading the configuration
434: */
435: LifecycleResults reloadConfiguration(Artifact configurationId,
436: LifecycleMonitor monitor) throws NoSuchConfigException,
437: LifecycleException;
438:
439: /**
440: * Reloads the specified configuration and all configurations that have a
441: * dependency on the specified configuration
442: *
443: * @param configurationId the configuration identifier, which must be fully
444: * resolved (isResolved() == true)
445: * @param version new version to load from the config store
446: *
447: * @return the results of the operation
448: *
449: * @throws NoSuchConfigException if the configuration is not loaded
450: * @throws LifecycleException if there is a problem loading the configuration
451: */
452: LifecycleResults reloadConfiguration(Artifact configurationId,
453: Version version) throws NoSuchConfigException,
454: LifecycleException;
455:
456: /**
457: * Reloads the specified configuration and all configurations that have a
458: * dependency on the specified configuration
459: *
460: * @param configurationId the configuration identifier, which must be fully
461: * resolved (isResolved() == true)
462: * @param monitor the monitor that should receive events as the operation is carried out
463: * @param version new version to load from the config store
464: *
465: * @return the results of the operation
466: *
467: * @throws NoSuchConfigException if the configuration is not loaded
468: * @throws LifecycleException if there is a problem loading the configuration
469: */
470: LifecycleResults reloadConfiguration(Artifact configurationId,
471: Version version, LifecycleMonitor monitor)
472: throws NoSuchConfigException, LifecycleException;
473:
474: /**
475: * Reloads the specified configuration and all configurations that have a
476: * dependency on the specified configuration
477: *
478: * @param configurationData the configuration to load
479: *
480: * @return the results of the operation
481: *
482: * @throws NoSuchConfigException if the configuration is not loaded
483: * @throws LifecycleException if there is a problem loading the configuration
484: */
485: LifecycleResults reloadConfiguration(
486: ConfigurationData configurationData)
487: throws NoSuchConfigException, LifecycleException;
488:
489: /**
490: * Reloads the specified configuration and all configurations that have a
491: * dependency on the specified configuration
492: *
493: * @param configurationData the configuration to load
494: * @param monitor the monitor that should receive events as the operation is carried out
495: *
496: * @return the results of the operation
497: *
498: * @throws NoSuchConfigException if the configuration is not loaded
499: * @throws LifecycleException if there is a problem loading the configuration
500: */
501: LifecycleResults reloadConfiguration(
502: ConfigurationData configurationData,
503: LifecycleMonitor monitor) throws NoSuchConfigException,
504: LifecycleException;
505:
506: /**
507: * Unstalls the specified configuration from the server. This operation
508: * can not be reversed.
509: *
510: * @param configurationId the configuration identifier, which must be fully
511: * resolved (isResolved() == true)
512: *
513: * @throws IOException if there was a problem removing the configuration
514: * @throws NoSuchConfigException if the configuration is not loaded
515: */
516: void uninstallConfiguration(Artifact configurationId)
517: throws IOException, NoSuchConfigException;
518:
519: /**
520: * Gets the common ArtifactResolver in case the caller wants to use this
521: * directly. It is configured for all the repositories known to this
522: * configuration manager, etc.
523: */
524: ArtifactResolver getArtifactResolver();
525:
526: /**
527: * Online means full functionality. Offline typically means that configurations will never be started,
528: * although they may be marked in the persistent configuration list.
529: *
530: * @return online status of ConfigurationManager
531: */
532: boolean isOnline();
533:
534: void setOnline(boolean online);
535:
536: Collection<? extends Repository> getRepositories();
537:
538: LinkedHashSet<Artifact> sort(List<Artifact> ids,
539: LifecycleMonitor monitor) throws InvalidConfigException,
540: IOException, NoSuchConfigException,
541: MissingDependencyException;
542: }
|