View Javadoc

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