001: /*
002: * The contents of this file are subject to the Sapient Public License
003: * Version 1.0 (the "License"); you may not use this file except in compliance
004: * with the License. You may obtain a copy of the License at
005: * http://carbon.sf.net/License.html.
006: *
007: * Software distributed under the License is distributed on an "AS IS" basis,
008: * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
009: * the specific language governing rights and limitations under the License.
010: *
011: * The Original Code is The Carbon Component Framework.
012: *
013: * The Initial Developer of the Original Code is Sapient Corporation
014: *
015: * Copyright (C) 2003 Sapient Corporation. All Rights Reserved.
016: */
017:
018: package org.sape.carbon.core.component.lifecycle;
019:
020: import org.sape.carbon.core.component.Component;
021: import org.sape.carbon.core.component.ComponentConfiguration;
022:
023: /**
024: * Defines the operations exposed by a lifecycle managing decorating filter.
025: *
026: * Copyright 2003 Sapient
027: * @since carbon 2.0
028: * @author Chris Herron, January 2002
029: * @version $Revision: 1.8 $($Author: dvoet $ / $Date: 2003/05/05 21:21:13 $)
030: */
031: public interface LifecycleInterceptor {
032:
033: /**
034: * <code>getLifecycleState</code> implies a property "LifecycleState".
035: * Note the lack of a corresponding mutator method - this property is
036: * read-only to external entities.
037: *
038: * @return the enum state of the assisted component
039: */
040: LifecycleStateEnum getLifecycleState();
041:
042: /**
043: * Returns the string version of the state of the assisted component
044: * @return the string state of the assisted component
045: */
046: String getLifecycleStateString();
047:
048: /**
049: * Run only once during the life of a Component, immediately after the
050: * Component is created.
051: *
052: * <p>Valid Entry States: CREATING </p>
053: * <p>Interim State: INITIALIZING</p>
054: * <p>Exit State: STOPPED</p>
055: *
056: * @param thisComponent component being initialized
057: * @throws InvalidStateException When the entry state is not allowed
058: * @throws OperationNotSupportedException When component does not support
059: * the requested operation
060: * @throws StateTransitionException When an error occured while trying to
061: * complete the lifecycle operation
062: */
063: void initializeComponent(Component this Component)
064: throws InvalidStateException,
065: OperationNotSupportedException, StateTransitionException;
066:
067: /**
068: * Tells the Component to begin providing its service.
069: *
070: * <p>Valid Entry States: STOPPED</p>
071: * <p>Interim State: STARTING</p>
072: * <p>Exit State: RUNNING</p>
073: *
074: * @throws InvalidStateException When the entry state is not allowed
075: * @throws OperationNotSupportedException When component does not support
076: * the requested operation
077: * @throws StateTransitionException When an error occured while trying to
078: * complete the lifecycle operation
079: */
080: void startComponent() throws InvalidStateException,
081: OperationNotSupportedException, StateTransitionException;
082:
083: /**
084: * Tells the Component to cease providing its service.
085: * This is an opportunity for the Component to complete outstanding
086: * work.
087: *
088: * <p>Valid Entry States: RUNNING or SUSPENDED</p>
089: * <p>Interim State: STOPPING</p>
090: * <p>Exit State: STOPPED</p>
091: *
092: * @throws InvalidStateException When the entry state is not allowed
093: * @throws OperationNotSupportedException When component does not support
094: * the requested operation
095: * @throws StateTransitionException When an error occured while trying to
096: * complete the lifecycle operation
097: *
098: */
099: void stopComponent() throws InvalidStateException,
100: OperationNotSupportedException, StateTransitionException;
101:
102: /**
103: * Tells the Component to suspend its service. This is an opportunity for
104: * the Component to sensibly pause its outstanding work.
105: *
106: * <p>Valid Entry States: RUNNING</p>
107: * <p>Interim State: SUSPENDING</p>
108: * <p>Exit State: SUSPENDED</p>
109: *
110: * @throws InvalidStateException When the entry state is not allowed
111: * @throws OperationNotSupportedException When component does not support
112: * the requested operation
113: * @throws StateTransitionException When an error occured while trying to
114: * complete the lifecycle operation
115: */
116: void suspendComponent() throws InvalidStateException,
117: OperationNotSupportedException, StateTransitionException;
118:
119: /**
120: * Tells the Component to resume its service. The Component can now continue
121: * its outstanding work.
122: *
123: * <p>Valid Entry States: SUSPENDED</p>
124: * <p>Interim State: RESUMING</p>
125: * <p>Exit State: RUNNING</p>
126: *
127: * @throws InvalidStateException When the entry state is not allowed
128: * @throws OperationNotSupportedException When component does not support
129: * the requested operation
130: * @throws StateTransitionException When an error occured while trying to
131: * complete the lifecycle operation
132: */
133: void resumeComponent() throws InvalidStateException,
134: OperationNotSupportedException, StateTransitionException;
135:
136: /**
137: * Provides a Component with its Configuration. A component can be
138: * configured if it is STOPPED or SUSPENDED. As a convenience, if the
139: * component is RUNNING, it will automatically be suspended prior to
140: * being configured, then resumend once configuring is complete.
141: *
142: * <p>Valid Entry States: STOPPED, SUSPENDED, RUNNING</p>
143: * <p>Interim State: CONFIGURING</p>
144: * <p>
145: * Exit States: STOPPED, SUSPENDED, RUNNING (should match entry state)
146: * </p>
147: *
148: * @param configuration configuration for the component
149: * @throws InvalidStateException When the entry state is not allowed
150: * @throws OperationNotSupportedException When component does not support
151: * the requested operation
152: * @throws StateTransitionException When an error occured while trying to
153: * complete the lifecycle operation
154: */
155: void configureComponent(ComponentConfiguration configuration)
156: throws InvalidStateException,
157: OperationNotSupportedException, StateTransitionException;
158:
159: /**
160: * Tells the Component prepare to die. This is an opportunity for the
161: * developer to do some sensible housekeeping to aid Garbage Collection,
162: * relinquish resources etc. Once in the DESTROYED state, a Component
163: * cannot be revived.
164: *
165: * <p>Valid Entry States: any</p>
166: * <p>Interim State: DESTROYING</p>
167: * <p>Exit State: DESTROYED</p>
168: *
169: * @throws OperationNotSupportedException When component does not support
170: * the requested operation
171: * @throws StateTransitionException When an error occured while trying to
172: * complete the lifecycle operation
173: */
174: void destroyComponent() throws OperationNotSupportedException,
175: StateTransitionException;
176:
177: }
|