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.0.4 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 }