View Javadoc

1   package org.apache.turbine.services;
2   
3   /*
4    * Copyright 2001-2005 The Apache Software Foundation.
5    *
6    * Licensed under the Apache License, Version 2.0 (the "License")
7    * you may not use this file except in compliance with the License.
8    * You may obtain a copy of the License at
9    *
10   *     http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing, software
13   * distributed under the License is distributed on an "AS IS" BASIS,
14   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15   * See the License for the specific language governing permissions and
16   * limitations under the License.
17   */
18  
19  /***
20   * Classes that implement this interface need initialization before
21   * they can work.
22   *
23   * These classes rely also on an <code>InitableBroker</code> that
24   * ensures that there is only one instance of the class in the system,
25   * and handles dependencies between <code>Initables</code>.
26   *
27   * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
28   * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
29   * @version $Id: Initable.java 264148 2005-08-29 14:21:04Z henning $
30   */
31  public interface Initable
32  {
33      /***
34       * Provides an Initable with a reference to the InitableBroker
35       * that instantiated this object, so that it can access other
36       * Initables.
37       *
38       * @param broker The InitableBroker that instantiated this object.
39       */
40      void setInitableBroker(InitableBroker broker);
41  
42      /***
43       * Performs early initailization of an Initable
44       *
45       * During the startup of the system, different objects may be
46       * passed to your class using this method.  It should ignore any
47       * objects that it doesn't need or understand.
48       *
49       * After the class changes its internal state so that getInit()
50       * returns true, this method will be called no more, and late
51       * initialization will not be performed.
52       *
53       * If your class relies on early initialization, and the object it
54       * expects was not received, you can use late initialization to
55       * throw an exception and complain.
56       *
57       * @param data An Object to use for initialization activities.
58       * @exception InitializationException if initilaization of this
59       * class was not successful.
60       */
61      void init(Object data) throws InitializationException;
62  
63      /***
64       * Performs late initialization of an Initable.
65       *
66       * When your class is being requested from an InitableBroker, it
67       * will call getInit(), and if it returns false, this method will
68       * be invoked.
69       *
70       * @exception InitializationException if initialization of this
71       * class was not successful.
72       */
73      void init() throws InitializationException;
74  
75      /***
76       * Returns an <code>Initable</code> to an uninitialized state.
77       *
78       * <p>This method must release all resources allocated by the
79       * <code>Initable</code> implementation, and resetting its internal state.
80       * You may chose to implement this operation or not. If you support
81       * this operation, getInit() should return false after successful
82       * shutdown of the service.
83       */
84      void shutdown();
85  
86      /***
87       * Returns initialization status of an Initable.
88       *
89       * @return Initialization status of an Initable.
90       */
91      boolean getInit();
92  }