1 package org.apache.turbine.services;
2
3
4 /*
5 * Licensed to the Apache Software Foundation (ASF) under one
6 * or more contributor license agreements. See the NOTICE file
7 * distributed with this work for additional information
8 * regarding copyright ownership. The ASF licenses this file
9 * to you under the Apache License, Version 2.0 (the
10 * "License"); you may not use this file except in compliance
11 * with the License. You may obtain a copy of the License at
12 *
13 * http://www.apache.org/licenses/LICENSE-2.0
14 *
15 * Unless required by applicable law or agreed to in writing,
16 * software distributed under the License is distributed on an
17 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
18 * KIND, either express or implied. See the License for the
19 * specific language governing permissions and limitations
20 * under the License.
21 */
22
23
24 import org.apache.commons.configuration2.Configuration;
25
26 /**
27 * Classes that implement this interface can act as a broker for
28 * <code>Service</code> classes.
29 *
30 * Functionality that <code>ServiceBroker</code> provides in addition
31 * to <code>InitableBroker</code> functionality includes:
32 *
33 * <ul>
34 *
35 * <li>Maintaining service name to class name mapping, allowing
36 * plugable service implementations.</li>
37 *
38 * <li>Providing <code>Services</code> with <code>Properties</code>
39 * based on a system wide configuration mechanism.</li>
40 *
41 * </ul>
42 *
43 * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
44 * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
45 * @author <a href="mailto:dlr@collab.net">Daniel Rall</a>
46 * @author <a href="mailto:hps@intermeta.de">Henning P. Schmiedehausen</a>
47 * @version $Id$
48 */
49 public interface ServiceBroker
50 {
51 /**
52 * Determines whether a service is registered in the configured
53 * <code>TurbineResources.properties</code>.
54 *
55 * @param serviceName The name of the service whose existance to check.
56 * @return Registration predicate for the desired services.
57 */
58 boolean isRegistered(String serviceName);
59
60 /**
61 * Performs early initialization of the specified service.
62 *
63 * @param name The name of the service.
64 * @throws InitializationException if the service is unknown
65 * or can't be initialized.
66 */
67 void initService(String name) throws InitializationException;
68
69 /**
70 * Shutdowns a Service.
71 *
72 * This method is used to release resources allocated by a
73 * Service, and return it to initial (uninitailized) state.
74 *
75 * @param name The name of the Service to be uninitialized.
76 */
77 void shutdownService(String name);
78
79 /**
80 * Shutdowns all Services.
81 *
82 * This method is used to release resources allocated by
83 * Services, and return them to initial (uninitialized) state.
84 */
85 void shutdownServices();
86
87 /**
88 * Returns an instance of requested Service.
89 *
90 * @param name The name of the Service requested.
91 * @return An instance of requested Service.
92 * @throws InstantiationException if the service is unknown or
93 * can't be initialized.
94 */
95 Object getService(String name) throws InstantiationException;
96
97 /**
98 * Returns the configuration of a specific service. Services
99 * use this method to retrieve their configuration.
100 *
101 * @param name The name of the service.
102 * @return Configuration of the requested service.
103 */
104 Configuration getConfiguration(String name);
105
106 /**
107 * Get the application root as set by
108 * the parent application.
109 *
110 * @return String application root
111 */
112 String getApplicationRoot();
113 }