Skip to Content.
Sympa Menu

notify-dpml - svn commit: r2310 - development/main/metro/state/impl/src/main/net/dpml/state/impl

notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

Chronological Thread  
  • From: mcconnell AT dpml.net
  • To: notify-dpml AT lists.ibiblio.org
  • Subject: svn commit: r2310 - development/main/metro/state/impl/src/main/net/dpml/state/impl
  • Date: Mon, 18 Apr 2005 17:14:46 -0400

Author: mcconnell AT dpml.net
Date: Mon Apr 18 17:14:44 2005
New Revision: 2310

Modified:

development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java

development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java

development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java

development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
Log:
javadocing

Modified:
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
==============================================================================
---
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
(original)
+++
development/main/metro/state/impl/src/main/net/dpml/state/impl/AbstractStateManager.java
Mon Apr 18 17:14:44 2005
@@ -58,6 +58,18 @@
*/
public AbstractStateManager( Logger logger, ChangeListener listener,
Object instance )
{
+ if( null == logger )
+ {
+ throw new NullPointerException( "logger" );
+ }
+ if( null == instance )
+ {
+ throw new NullPointerException( "instance" );
+ }
+ if( null == listener )
+ {
+ throw new NullPointerException( "listener" );
+ }
m_instance = instance;
m_listener = listener;
m_logger = logger;
@@ -77,6 +89,10 @@
*/
protected Object getHandler( String key ) throws NoSuchHandlerException
{
+ if( null == key )
+ {
+ throw new NullPointerException( "key" );
+ }
Object handler = m_handlers.get( key );
if( null == handler )
{
@@ -87,6 +103,14 @@

protected void addHandler( String key, Object handler )
{
+ if( null == key )
+ {
+ throw new NullPointerException( "key" );
+ }
+ if( null == handler )
+ {
+ throw new NullPointerException( "handler" );
+ }
if( m_handlers.containsKey( key ) )
{
throw new DuplicateKeyException( key );
@@ -100,9 +124,16 @@
}

/**
- * Initialization of the manager by a controller. This implementation
will attempt assign
- * an initial state declared within the supplied state graph. If no
initial state is present
- * the implementation will return the root state.
+ * Initialization of the manager by a controller. If the state model
+ * declares a terminal root state this methods does nothing and returns.
+ * If the root state is not terminal the implementation will invoke a
+ * transiton named "initalize". If the transition relts in a modified
+ * state, the implementation will continue to recursivly invoke an
+ * an initialize operation until either a condition occurs where
invocation
+ * of the nearest initization transition will not modify the current
state.
+ *
+ * @exception Exception if an error is raised by a handler assigned to
+ * and invoked initialization transiton
*/
public synchronized void initialize() throws Exception
{
@@ -127,9 +158,21 @@
}

/**
- * Retun the current state of execution.
+ * Retun the current state. The current state is the function of
+ * the initialization and subsequent trnaistion actions applied to
+ * the state model. The current state determines the enabled
+ * state chain as the sequence of states from the current state to
+ * root state. Any transitions defined in the active state chain
+ * are candidates for execution. Transitions logically closer to the
+ * current state override transitions declare higher up in the
+ * state chain. This method is exposed via the ServiceManager
+ * interface to the controlling application (possibly the enclossing
+ * component or the model controller). State instances returned from
+ * this method are automatically proxied behind a State invocation
+ * handler thereby ensuring the integrity of the state's state and
+ * non-disclosure of implemetation features.
*
- * @return the state representing the current state of execution
+ * @return the current state
*/
public synchronized State getState()
{
@@ -137,7 +180,8 @@
}

/**
- * Utility method to return the current state implemetation class.
+ * Internal utility method that returns a non-proxied reference to the
+ * current state.
*
* @return the state representing the current state of execution
*/
@@ -158,10 +202,13 @@
/**
* Apply a transition identified by a supplied transition key. The
* implementation will attempt to locate the transition relative to the
current
- * state (taking into account the DefaultState search semantics) fro which
+ * state (taking into account the DefaultState search semantics) from
which
* a invocation handler is resolve and invoked. If the transition is
successful
- * the target tranaistion state declared by the transtion will be
assigned as the
+ * the target transition state declared by the transtion will be assigned
as the
* current current state and all listeners will be notified of a state
change.
+ * If the transition resolved from the supplied key references a target
state
+ * that is the same as the current state the transition will not be
invoked and
+ * the method will return false.
*
* @param key the transition key
* @return TRUE if the transition was executed
@@ -196,6 +243,26 @@
}
}

+ /**
+ * Internal utility method that handles the resolution of a handler based
on
+ * the object assigned to the DefaultTransition handler attribute. If
the
+ * handler is an instance of URI, the following schemes will be evaluated:
+ *
+ * <ol>
+ * <li>part:[key] - invocation of the handle method on the component's
part
+ * referenced by the scheme specific part of the supplied uri</li>
+ * <li>handler:[key] - invocation of the handle method on a class
identified by
+ * the scheme specific part of the uri</li>
+ * <li>method:[key] - invocation of the handle method against the
component
+ * instance</li>
+ * </ol>
+ *
+ * @param handler the object describing the handler
+ * @param state the current state
+ * @param target the target of the transition
+ * @param logger the assigned logging channel
+ * @excetion Exception of an invocation or handler error occurs
+ */
private void execute( Object handler, State state, State target, Logger
logger ) throws Exception
{
if( handler instanceof URI )
@@ -247,8 +314,26 @@
throw new IllegalArgumentException( error );
}
}
+ else
+ {
+ final String error =
+ "Handler class not supported."
+ + "\nClass: " + handler.getClass().getName()
+ + "\nComponent Class: " + m_instance.getClass().getName();
+ throw new IllegalArgumentException( error );
+ }
}

+ /**
+ * Internal utility to populate method arguments using the current state,
target state
+ * assigned logging channel, and the active component instance.
+ *
+ * @param parameters the array of method parameter arguments
+ * @param state the current state
+ * @param target the transition target state
+ * @param logger the assinged logging channel
+ * @return the populated object array
+ */
private Object[] resolveArguments( Class[] parameters, State state,
State target, Logger logger )
{
boolean firstStateAssigned = false;
@@ -329,10 +414,10 @@
}
try
{
- apply( "terminate" );
- if( false == getCurrentState().equals( state ) )
+ boolean flag = true;
+ while( flag )
{
- terminate();
+ flag = apply( "terminate" );
}
}
catch( NoSuchTransitionException e )
@@ -354,6 +439,15 @@
return m_logger;
}

+ /**
+ * Utility to locate athe first public method with the supplied name in
the
+ * supplied class.
+ * @param c the class to introspect
+ * @param operation the method name
+ * @return the first method found
+ * @exception IllegalArgumentException if the class does not delcare the
+ * the named method
+ */
private Method locateMethod( Class c, String operation )
{
Method[] methods = c.getMethods();

Modified:
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
==============================================================================
---
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
(original)
+++
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultState.java
Mon Apr 18 17:14:44 2005
@@ -67,14 +67,23 @@
}

/**
- * Internal constructor for a state instance.
+ * Internal constructor for a state instance. If the parent argument is
null
+ * the created state representing a root state in a state graph. The
terminal
+ * attribute declares the terminal node status of the state. If the
state is
+ * flagged as terminal, no sub-states or transitions may be added or
assigned
+ * to the state.
*
* @paren parent the parent of the created state
* @param name the name that the state is index under
* @param terminal TRUE if this is a terminal state else FALSE
+ * @exception NullPointerException if the name argument is null
*/
private DefaultState( DefaultState parent, String name, boolean terminal
)
{
+ if( null == name )
+ {
+ throw new NullPointerException( "name" );
+ }
m_name = name;
m_parent = parent;
m_terminal = terminal;
@@ -82,7 +91,6 @@
InvocationHandler handler = new DefaultInvocationHandler( this );
ClassLoader classloader = getClass().getClassLoader();
m_proxy = (State) Proxy.newProxyInstance( classloader, new Class[]{
State.class }, handler );
-
}

/**
@@ -114,10 +122,12 @@
}

/**
- * Return the terminal status of this state. If a state is termin if
cannot
- * contain sub-states or transitions.
+ * Return the terminal status of this state. If a state is terminal it
cannot
+ * contain sub-states or transitions. Furthermore, a component declaring
a current
+ * state where the current state is terminal cannot change it's state
without explicit
+ * re-initialization of the componet's service manager.
*
- * @return the terminal status of this state
+ * @return TRUE if this state is a terminal state
*/
public boolean isTerminal()
{
@@ -126,7 +136,10 @@

/**
* Returns an array of transtion names declared in this state and all
- * parent states.
+ * parent states in the active state chain. This method via the
+ * StateManager interface (through exposeure of State) to controlling
+ * applications. The controlling application can apply a tranistion
+ * by invoking the 'apply' operation on the associated ServiceManager.
*
* @return the available transition names
*/
@@ -193,6 +206,10 @@
*/
private DefaultState addState( DefaultState parent, String key, boolean
terminal )
{
+ if( null == key )
+ {
+ throw new NullPointerException( "key" );
+ }
if( m_parent != null )
{
return m_parent.addState( parent, key, terminal );
@@ -242,7 +259,9 @@
}

/**
- * Return an array of local states contained within this state.
+ * Return an array of local states directly contained within this state
+ * instance.
+ *
* @return the local state array
*/
protected DefaultState[] getStates()
@@ -252,6 +271,7 @@

/**
* Return an array of all states contained within the supplied state.
+ *
* @param parent the enclosing parent state
* @return the state array
*/
@@ -271,7 +291,9 @@
}

/**
- * Return a state from the state graph mathcing the supplied key.
+ * Return a state from the state graph matching the supplied key.
+ * The search does not include the root state of the state graph.
+ *
* @param key the state key
* @return the state assigned to the key
* @exception NoSuchStateException if the key does not match a state
@@ -279,6 +301,10 @@
*/
protected DefaultState getState( String key )
{
+ if( null == key )
+ {
+ throw new NullPointerException( "key" );
+ }
if( null != m_parent )
{
return m_parent.getState( key );
@@ -360,6 +386,18 @@
*/
private void addTransition( String key, Object handler, DefaultState
target, boolean system )
{
+ if( null == key )
+ {
+ throw new NullPointerException( "key" );
+ }
+ if( null == handler )
+ {
+ throw new NullPointerException( "handler" );
+ }
+ if( null == target )
+ {
+ throw new NullPointerException( "target" );
+ }
if( isTerminal() )
{
final String error =
@@ -409,6 +447,10 @@
*/
public DefaultTransition getNamedTransition( String key )
{
+ if( null == key )
+ {
+ throw new NullPointerException( "key" );
+ }
DefaultTransition transition = (DefaultTransition)
m_transitions.get( key );
if( null != transition )
{
@@ -444,7 +486,7 @@
{
if( null != m_parent )
{
- return "[state " + m_name + " (in:" + m_parent.getName() + ")]";
+ return "[state " + m_name + " (from:" + m_parent.getName() +
")]";
}
else
{
@@ -490,7 +532,6 @@
return m_name.hashCode();
}

-
/**
* Untility function that returns a string representation of this state
* in the form of a graph.

Modified:
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
==============================================================================
---
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
(original)
+++
development/main/metro/state/impl/src/main/net/dpml/state/impl/DefaultTransition.java
Mon Apr 18 17:14:44 2005
@@ -38,16 +38,34 @@
private final Object m_handler;
private final boolean m_system;

+ /**
+ * Internal utility to construct a new transition instance. This
constructor
+ * is used by the DefaultState state implmentation class as part of it's
transition
+ * factory operations.
+ *
+ * @param handler the object identifying the handler
+ * @param target the transition target state
+ * @param system if TRUE this is a system transition otherwise the
transition
+ * is a user (application) transition
+ */
protected DefaultTransition( Object handler, DefaultState target,
boolean system )
{
+ if( null == handler )
+ {
+ throw new NullPointerException( "handler" );
+ }
+ if( null == target )
+ {
+ throw new NullPointerException( "target" );
+ }
m_handler = handler;
m_target = target;
m_system = system;
}

/**
- * Return the handler associated with this transition.
- * @return the transition handler
+ * Return the handler identifier associated with this transition.
+ * @return the transition handler identfier
*/
public Object getHandler()
{

Modified:
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
==============================================================================
---
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
(original)
+++
development/main/metro/state/impl/src/main/net/dpml/state/impl/NoSuchHandlerException.java
Mon Apr 18 17:14:44 2005
@@ -18,9 +18,8 @@

package net.dpml.state.impl;

-
/**
- * Exception thrown when a request for a handler could not be reoslved.
+ * Exception thrown when a request for a handler could not be resolved.
*
* @author <a href="mailto:dev-dpml AT lists.ibiblio.org";>The Digital Product
Meta Library</a>
*/



  • svn commit: r2310 - development/main/metro/state/impl/src/main/net/dpml/state/impl, mcconnell, 04/18/2005

Archive powered by MHonArc 2.6.24.

Top of Page