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  /***
23   * Classes that implement this interface need initialization before
24   * they can work.
25   *
26   * These classes rely also on an <code>InitableBroker</code> that
27   * ensures that there is only one instance of the class in the system,
28   * and handles dependencies between <code>Initables</code>.
29   *
30   * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
31   * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
32   * @version $Id: Initable.java 534527 2007-05-02 16:10:59Z tv $
33   */
34  public interface Initable
35  {
36      /***
37       * Provides an Initable with a reference to the InitableBroker
38       * that instantiated this object, so that it can access other
39       * Initables.
40       *
41       * @param broker The InitableBroker that instantiated this object.
42       */
43      void setInitableBroker(InitableBroker broker);
44  
45      /***
46       * Performs early initailization of an Initable
47       *
48       * During the startup of the system, different objects may be
49       * passed to your class using this method.  It should ignore any
50       * objects that it doesn't need or understand.
51       *
52       * After the class changes its internal state so that getInit()
53       * returns true, this method will be called no more, and late
54       * initialization will not be performed.
55       *
56       * If your class relies on early initialization, and the object it
57       * expects was not received, you can use late initialization to
58       * throw an exception and complain.
59       *
60       * @param data An Object to use for initialization activities.
61       * @exception InitializationException if initilaization of this
62       * class was not successful.
63       */
64      void init(Object data) throws InitializationException;
65  
66      /***
67       * Performs late initialization of an Initable.
68       *
69       * When your class is being requested from an InitableBroker, it
70       * will call getInit(), and if it returns false, this method will
71       * be invoked.
72       *
73       * @exception InitializationException if initialization of this
74       * class was not successful.
75       */
76      void init() throws InitializationException;
77  
78      /***
79       * Returns an <code>Initable</code> to an uninitialized state.
80       *
81       * <p>This method must release all resources allocated by the
82       * <code>Initable</code> implementation, and resetting its internal state.
83       * You may chose to implement this operation or not. If you support
84       * this operation, getInit() should return false after successful
85       * shutdown of the service.
86       */
87      void shutdown();
88  
89      /***
90       * Returns initialization status of an Initable.
91       *
92       * @return Initialization status of an Initable.
93       */
94      boolean getInit();
95  }