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