Service


1   package org.apache.fulcrum;
2   
3   /* ====================================================================
4    * The Apache Software License, Version 1.1
5    *
6    * Copyright (c) 2001-2002 The Apache Software Foundation.  All rights
7    * reserved.
8    *
9    * Redistribution and use in source and binary forms, with or without
10   * modification, are permitted provided that the following conditions
11   * are met:
12   *
13   * 1. Redistributions of source code must retain the above copyright
14   *    notice, this list of conditions and the following disclaimer.
15   *
16   * 2. Redistributions in binary form must reproduce the above copyright
17   *    notice, this list of conditions and the following disclaimer in
18   *    the documentation and/or other materials provided with the
19   *    distribution.
20   *
21   * 3. The end-user documentation included with the redistribution,
22   *    if any, must include the following acknowledgment:
23   *       "This product includes software developed by the
24   *        Apache Software Foundation (http://www.apache.org/)."
25   *    Alternately, this acknowledgment may appear in the software itself,
26   *    if and wherever such third-party acknowledgments normally appear.
27   *
28   * 4. The names "Apache" and "Apache Software Foundation" and
29   *    "Apache Turbine" must not be used to endorse or promote products
30   *    derived from this software without prior written permission. For
31   *    written permission, please contact apache@apache.org.
32   *
33   * 5. Products derived from this software may not be called "Apache",
34   *    "Apache Turbine", nor may "Apache" appear in their name, without
35   *    prior written permission of the Apache Software Foundation.
36   *
37   * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38   * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39   * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40   * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41   * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44   * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45   * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47   * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48   * SUCH DAMAGE.
49   * ====================================================================
50   *
51   * This software consists of voluntary contributions made by many
52   * individuals on behalf of the Apache Software Foundation.  For more
53   * information on the Apache Software Foundation, please see
54   * <http://www.apache.org/>.
55   */
56  
57  import org.apache.commons.configuration.Configuration;
58  import org.apache.log4j.Category;
59  
60  /**
61   * <code>Services</code> are <code>Initables</code> that have a name,
62   * and a set of properties.
63   *
64   * @author <a HREF="mailto:greg@shwoop.com">Greg Ritter</a>
65   * @author <a HREF="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
66   * @author <a HREF="mailto:burton@apache.org">Kevin Burton</a>
67   * @author <a HREF="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
68   * @author <a HREF="mailto:dlr@collab.net">Daniel Rall</a>
69   * @author <a HREF="mailto:leonardr@collab.net">Leonard Richardson</a>
70   * @author <a HREF="mailto:jvanzyl@apache.org">Jason van Zyl</a>
71   * @author <a HREF="mailto:mpoeschl@marmot.at">Martin Poeschl</a>
72   * @version $Id: Service.java,v 1.1 2004/11/12 10:25:48 epugh Exp $
73   */
74  public interface Service
75  {
76      /**
77       * The name of this service.
78       */
79      public static final String   SERVICE_NAME = "Service";
80  
81      /**
82       * Performs late initialization of an Initable.
83       *
84       * When your class is being requested from an InitableBroker, it
85       * will call isInitialized(), and if it returns false, this method
86       * will be invoked.  A typical implementation for classes
87       * extending {@link org.apache.fulcrum.BaseService} will look
88       * something like the following:
89       *
90       * <blockquote><code><pre>
91       * if (!isInitialized())
92       * {
93       *     try
94       *     {
95       *         // Your initialization activities ...
96       *         setInit(true);
97       *     }
98       *     catch (Exception e)
99       *     {
100      *         throw new InitializationException("Something bad happened " +
101      *                                           "during " +
102      *                                           Service.SERVICE_NAME +
103      *                                           " initialization: " +
104      *                                           e.getMessage());
105      *     }
106      * }
107      * </pre></code></blockquote>
108      *
109      * @exception InitializationException, if initialization of this
110      * class was not successful.
111      */
112     public void init( ) throws InitializationException;
113 
114     /**
115      * Returns a <code>Service</code> to an uninitialized state.
116      *
117      * <p>This method must release all resources allocated by the
118      * <code>Initable</code> implementation, and resetting its
119      * internal state.  You may chose to implement this operation or
120      * not. If you support this operation, {@link #isInitialized()}
121      * should return false after successful shutdown of the service.
122      */
123     public void shutdown();
124 
125     /**
126      * Returns initialization state.
127      *
128      * @return Whether the service has been initialized.
129      */
130     public boolean isInitialized();
131 
132     /**
133      * Provides a Service with a reference to the ServiceBroker that
134      * instantiated this object, so that it can ask for its properties
135      * and access other Services.
136      *
137      * @param broker The ServiceBroker that instantiated this object.
138      */
139     public void setServiceBroker( ServiceBroker broker );
140 
141     /**
142      * ServiceBroker uses this method to pass a Service its name.
143      * Service uses its name to ask the broker for an apropriate set
144      * of Properties.
145      *
146      * @param name The name of this Service.
147      */
148     public void setName( String   name );
149 
150     /**
151      * Returns the Configuration of this Service.  Every Service has at
152      * least one property, which is "classname", containing the name
153      * of the class implementing this service.  Note that the service
154      * may chose to alter its configuration, therefore they may be
155      * different from those returned by ServiceBroker.
156      *
157      * @return The configuration of this <code>Service</code>.
158      */
159     public Configuration getConfiguration();
160 
161     /**
162      * Given a relative paths, gets the real path.
163      */
164     public String   getRealPath(String   path);
165 
166     /**
167      * Gets the default logger for this service.
168      */
169     public Category getCategory();
170 
171     /**
172      * Returns text describing the status of this Service instance.
173      *
174      * @return Text describing service status.
175      */
176     public String   getStatus() throws ServiceException;
177 }
178
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags