LifecycleInterceptor


1   /*
2    * The contents of this file are subject to the Sapient Public License
3    * Version 1.0 (the "License"); you may not use this file except in compliance
4    * with the License. You may obtain a copy of the License at
5    * http://carbon.sf.net/License.html.
6    *
7    * Software distributed under the License is distributed on an "AS IS" basis,
8    * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
9    * the specific language governing rights and limitations under the License.
10   *
11   * The Original Code is The Carbon Component Framework.
12   *
13   * The Initial Developer of the Original Code is Sapient Corporation
14   *
15   * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
16   */
17  
18  package org.sape.carbon.core.component.lifecycle;
19  
20  import org.sape.carbon.core.component.Component;
21  import org.sape.carbon.core.component.ComponentConfiguration;
22  
23  /**
24   * Defines the operations exposed by a lifecycle managing decorating filter.
25   *
26   * Copyright 2003 Sapient
27   * @since carbon 2.0
28   * @author Chris Herron, January 2002
29   * @version $Revision: 1.8 $($Author: dvoet $ / $Date: 2003/05/05 21:21:13 $)
30   */
31  public interface LifecycleInterceptor {
32  
33      /**
34       * <code>getLifecycleState</code> implies a property "LifecycleState".
35       * Note the lack of a corresponding mutator method - this property is
36       * read-only to external entities.
37       *
38       * @return the enum state of the assisted component
39       */
40      LifecycleStateEnum getLifecycleState();
41  
42      /**
43       * Returns the string version of the state of the assisted component
44       * @return the string state of the assisted component
45       */
46      String   getLifecycleStateString();
47  
48      /**
49       * Run only once during the life of a Component, immediately after the
50       * Component is created.
51       *
52       * <p>Valid Entry States: CREATING </p>
53       * <p>Interim State: INITIALIZING</p>
54       * <p>Exit State: STOPPED</p>
55       *
56       * @param thisComponent component being initialized
57       * @throws InvalidStateException When the entry state is not allowed
58       * @throws OperationNotSupportedException When component does not support
59       *   the requested operation
60       * @throws StateTransitionException When an error occured while trying to
61       *   complete the lifecycle operation
62       */
63      void initializeComponent(Component thisComponent)
64          throws
65              InvalidStateException,
66              OperationNotSupportedException,
67              StateTransitionException;
68  
69      /**
70       * Tells the Component to begin providing its service.
71       *
72       * <p>Valid Entry States: STOPPED</p>
73       * <p>Interim State: STARTING</p>
74       * <p>Exit State: RUNNING</p>
75       *
76       * @throws InvalidStateException When the entry state is not allowed
77       * @throws OperationNotSupportedException When component does not support
78       *   the requested operation
79       * @throws StateTransitionException When an error occured while trying to
80       *   complete the lifecycle operation
81       */
82      void startComponent()
83          throws
84              InvalidStateException,
85              OperationNotSupportedException,
86              StateTransitionException;
87  
88      /**
89       * Tells the Component to cease providing its service.
90       * This is an opportunity for the Component to complete outstanding
91       * work.
92       *
93       * <p>Valid Entry States: RUNNING or SUSPENDED</p>
94       * <p>Interim State: STOPPING</p>
95       * <p>Exit State: STOPPED</p>
96       *
97       * @throws InvalidStateException When the entry state is not allowed
98       * @throws OperationNotSupportedException When component does not support
99       *   the requested operation
100      * @throws StateTransitionException When an error occured while trying to
101      *   complete the lifecycle operation
102      *
103      */
104     void stopComponent()
105         throws
106             InvalidStateException,
107             OperationNotSupportedException,
108             StateTransitionException;
109 
110     /**
111      * Tells the Component to suspend its service. This is an opportunity for
112      * the Component to sensibly pause its outstanding work.
113      *
114      * <p>Valid Entry States: RUNNING</p>
115      * <p>Interim State: SUSPENDING</p>
116      * <p>Exit State: SUSPENDED</p>
117      *
118      * @throws InvalidStateException When the entry state is not allowed
119      * @throws OperationNotSupportedException When component does not support
120      *   the requested operation
121      * @throws StateTransitionException When an error occured while trying to
122      *   complete the lifecycle operation
123      */
124     void suspendComponent()
125         throws
126             InvalidStateException,
127             OperationNotSupportedException,
128             StateTransitionException;
129 
130     /**
131      * Tells the Component to resume its service. The Component can now continue
132      * its outstanding work.
133      *
134      * <p>Valid Entry States: SUSPENDED</p>
135      * <p>Interim State: RESUMING</p>
136      * <p>Exit State: RUNNING</p>
137      *
138      * @throws InvalidStateException When the entry state is not allowed
139      * @throws OperationNotSupportedException When component does not support
140      *   the requested operation
141      * @throws StateTransitionException When an error occured while trying to
142      *   complete the lifecycle operation
143      */
144     void resumeComponent()
145         throws
146             InvalidStateException,
147             OperationNotSupportedException,
148             StateTransitionException;
149 
150     /**
151      * Provides a Component with its Configuration. A component can be
152      * configured if it is STOPPED or SUSPENDED.  As a convenience, if the
153      * component is RUNNING, it will automatically be suspended prior to
154      * being configured, then resumend once configuring is complete.
155      *
156      * <p>Valid Entry States: STOPPED, SUSPENDED, RUNNING</p>
157      * <p>Interim State: CONFIGURING</p>
158      * <p>
159      *   Exit States: STOPPED, SUSPENDED, RUNNING (should match entry state)
160      * </p>
161      *
162      * @param configuration configuration for the component
163      * @throws InvalidStateException When the entry state is not allowed
164      * @throws OperationNotSupportedException When component does not support
165      *   the requested operation
166      * @throws StateTransitionException When an error occured while trying to
167      *   complete the lifecycle operation
168      */
169     void configureComponent(ComponentConfiguration configuration)
170         throws
171             InvalidStateException,
172             OperationNotSupportedException,
173             StateTransitionException;
174 
175     /**
176      * Tells the Component prepare to die. This is an opportunity for the
177      * developer to do some sensible housekeeping to aid Garbage Collection,
178      * relinquish resources etc. Once in the DESTROYED state, a Component
179      * cannot be revived.
180      *
181      * <p>Valid Entry States: any</p>
182      * <p>Interim State: DESTROYING</p>
183      * <p>Exit State: DESTROYED</p>
184      *
185      * @throws OperationNotSupportedException When component does not support
186      *   the requested operation
187      * @throws StateTransitionException When an error occured while trying to
188      *   complete the lifecycle operation
189      */
190     void destroyComponent()
191         throws
192             OperationNotSupportedException,
193             StateTransitionException;
194 
195 }
196
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags