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 */
017 package org.apache.geronimo.kernel.config;
018
019 import java.io.IOException;
020 import java.util.List;
021 import org.apache.geronimo.kernel.repository.Artifact;
022 import org.apache.geronimo.kernel.repository.ArtifactResolver;
023 import org.apache.geronimo.kernel.repository.Version;
024 import org.apache.geronimo.gbean.AbstractName;
025
026 /**
027 * Encapsulates logic for dealing with configurations.
028 *
029 * Configurations have a lifecycle with three states: installed, loaded, and
030 * running. Installed means that the configuration is present in the server's
031 * repository. Loaded means that the Configuration GBean (including the
032 * configuration's ClassLoader) is running. Running means that all the GBeans
033 * in the Configuration are running.
034 *
035 * From a user perspective, there's not much difference between installed and
036 * loaded if the configuration has not been started (it still shows up as not
037 * running). However, certain operations will cause a configuration to be
038 * loaded but not started. For example, if ModuleA depends on ModuleB, then
039 * when ModuleA is distributed ModuleB will normally be loaded (to fire up the
040 * ClassLoader and validate ModuleA). But ModuleB will not be started at that
041 * point. It can be started manually or it will be started automatically when
042 * ModuleA is started.
043 *
044 * When a Configuration is not loaded, only its ConfigurationData is available
045 * for inspection. It's normally not possible to inspect the GBeans in the
046 * configuration because there's no ClassLoader that could be used to load the
047 * classes needed by the GBeanDatas in the configuration. Once the
048 * configuration has been loaded, it's ClassLoader is available so the
049 * GBeanDatas can be loaded and inspected. But the GBean instances are not
050 * instantiated and started until the configuration is started.
051 *
052 * @version $Rev: 476049 $ $Date: 2006-11-16 23:35:17 -0500 (Thu, 16 Nov 2006) $
053 */
054 public interface ConfigurationManager {
055 /**
056 * Is the specified configuration installed into the server
057 * environment? That is, does it exist in the configuration store,
058 * regardless of whether it's loaded or running? Note that this
059 * always returns false if the argument does not represent a
060 * configuration (e.g. if it's for a plain JAR).
061 *
062 * @param configurationId the configuration identifier, which must be
063 * fully resolved (isResolved() == true)
064 *
065 * @return true if the configuration has been loaded; false otherwise
066 */
067 boolean isInstalled(Artifact configurationId);
068
069 /**
070 * Is the specified configuration loaded into the kernel? Note that this
071 * always returns false if the argument does not represent a
072 * configuration (e.g. if it's for a plain JAR).
073 *
074 * @param configurationId the configuration identifier, which must be
075 * fully resolved (isResolved() == true)
076 *
077 * @return true if the configuration has been loaded; false otherwise
078 */
079 boolean isLoaded(Artifact configurationId);
080
081 /**
082 * Is the specified configuation running? Note that this
083 * always returns false if the argument does not represent a
084 * configuration (e.g. if it's for a plain JAR).
085 *
086 * @param configurationId the configuration identifier, which must be
087 * fully resolved (isResolved() == true)
088 *
089 * @return true if the configuration is running, false otherwise
090 */
091 boolean isRunning(Artifact configurationId);
092
093 /**
094 * Given an artifact that's not fully resolved (e.g. some parts are
095 * missing), check whether there are any instances installed into
096 * the server environment. That is, are there any matches in the
097 * configuration store, regardless of whether they're loaded or running?
098 * Note that this always returns an empty array if the argument does not
099 * 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 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 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 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, 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 }