001 /*
002 * Copyright 2005 Stephen J. McConnell.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
013 * implied.
014 *
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019 package net.dpml.state;
020
021 import java.lang.reflect.InvocationTargetException;
022
023 /**
024 * <p>Defintion of the state machine. The state machine handles the maintenance
025 * of a single current state and supports the invocation of transition and operations
026 * relative to the current state. Invocation of transiton and operations are handled
027 * via two mechansims:</p>
028 *
029 * <ol>
030 * <li>triggers</li>
031 * <li>explicit invocation of the 'appply' and 'execute' operations</li>
032 * </ol>
033 *
034 * <p>Triggers, Transitions, and Operations may be declared within any state and enter
035 * active scope when when the enclosing state is within the current state path
036 * (where the current state path is the sequence of state's from the current state to
037 * the root state).</p>
038 *
039 * <p>Transitions and operations available at any given time are a function of
040 * all uniquely named transitions and operations exposed within the current state path.
041 * If multiple instances of a transition or operation share the same name, the instance
042 * closest to the current state takes precedence and the duplicate instance will not be
043 * exposed (equivalent to overriding the characteristics of a super-state).
044 *
045 * <p>Triggers are structures that hold a single action (transition or operation) and
046 * are invoked automatically by a state machine implementation as a part of initialization
047 * and termination requests. If a trigger contains a transition resulting that results in
048 * a change to the current state a state-machine will recursively evaluate triggers in the
049 * new current state path. The process of recursive evaluation of triggers will continue
050 * until a state is reached where no further trigger invocation is possible.</p>
051 *
052 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
053 * @version 1.2.0
054 */
055 public interface StateMachine
056 {
057 /**
058 * Add a property change listener to the state machine.
059 * @param listener the property change listener
060 */
061 //void addPropertyChangeListener( final PropertyChangeListener listener );
062
063 /**
064 * Remove a property change listener from the state machine.
065 * @param listener the property change listener
066 */
067 //void removePropertyChangeListener( final PropertyChangeListener listener );
068
069 /**
070 * Add a state change listener to the state machine.
071 * @param listener the state listener
072 */
073 void addStateListener( final StateListener listener );
074
075 /**
076 * Remove a state listener from the state machine.
077 * @param listener the state listener
078 */
079 void removeStateListener( final StateListener listener );
080
081 /**
082 * Return the current state.
083 * @return the current state
084 */
085 State getState();
086
087 /**
088 * Invoke initialization of the supplied object using the initialization action
089 * declared under the current state path.
090 *
091 * @param object the object to initialize
092 * @return the state established as a side-effect of initialization
093 * @exception InvocationTargetException if an invocation error occurs as a
094 * result of initialization
095 */
096 State initialize( Object object ) throws InvocationTargetException;
097
098 /**
099 * Execute a named operation on the supplied object.
100 * @param name an operation name
101 * @param object the target object
102 * @param args operation argument array
103 * @return the return value
104 * @exception UnknownOperationException if the operation is unknown
105 * @exception InvocationTargetException if an invocation error occurs as a
106 * result of operation execution
107 */
108 Object execute( String name, Object object, Object[] args )
109 throws UnknownOperationException, InvocationTargetException;
110
111 /**
112 * Invoke a management method on the supplied object.
113 * @param object the target object
114 * @param method the method name
115 * @param args method parameter arguments
116 * @return the return value
117 * @exception IllegalStateException if the method is recognized but not available
118 * @exception UnknownOperationException if the operation is unknown
119 * @exception InvocationTargetException if an invocation error occurs as a
120 * result of operation execution
121 */
122 Object invoke( Object object, String method, Object[] args )
123 throws UnknownOperationException, InvocationTargetException, IllegalStateException;
124
125 /**
126 * Apply a named state transition.
127 * @param name the transition name
128 * @param object the object against which any transition handler action are to be applied
129 * @return the state established by the application of the transition
130 * @exception UnknownTransitionException if the transition is unknown
131 * @exception InvocationTargetException if an invocation error occurs as a
132 * result of transition invocation
133 */
134 State apply( String name, Object object )
135 throws UnknownTransitionException, InvocationTargetException;
136
137 /**
138 * Return all of the available transitions relative to the current state.
139 * @return the available transitions
140 */
141 Transition[] getTransitions();
142
143 /**
144 * Return all of the available operations relative to the current state.
145 * @return the available operations
146 */
147 Operation[] getOperations();
148
149 /**
150 * Return all of the available interfaces relative to the current state.
151 * @return the available interface declarations
152 */
153 Interface[] getInterfaces();
154
155 /**
156 * Invoke termination of the supplied object using the termination action
157 * declared under the current state path.
158 *
159 * @param object the object to terminate
160 * @return the state established as a side-effect of the termination
161 */
162 State terminate( Object object );
163
164 /**
165 * Returns the active status of the state machine.
166 * @return TRUE if the state machine has invoked initialization and
167 * termination has not been performed otherwise FALSE
168 */
169 boolean isActive();
170
171 }