notify-dpml AT lists.ibiblio.org

Subject: DPML Notify

List archive

svn commit: r1697 - in development/laboratory/planet/components/fsm: . api/src/main/net/dpml/fsm docs docs/src docs/src/docs docs/src/docs/examples

From: niclas AT netcompartner.com
To: notify-dpml AT lists.ibiblio.org
Subject: svn commit: r1697 - in development/laboratory/planet/components/fsm: . api/src/main/net/dpml/fsm docs docs/src docs/src/docs docs/src/docs/examples
Date: Wed, 02 Feb 2005 11:14:01 +0100

Author: niclas
Date: Wed Feb 2 11:14:00 2005
New Revision: 1697

Added:
development/laboratory/planet/components/fsm/docs/
development/laboratory/planet/components/fsm/docs/src/
development/laboratory/planet/components/fsm/docs/src/docs/
development/laboratory/planet/components/fsm/docs/src/docs/examples/

development/laboratory/planet/components/fsm/docs/src/docs/examples/index.xml
(contents, props changed)

development/laboratory/planet/components/fsm/docs/src/docs/examples/navigation.xml
(contents, props changed)

development/laboratory/planet/components/fsm/docs/src/docs/examples/trafficlight.xml
(contents, props changed)
development/laboratory/planet/components/fsm/docs/src/docs/index.xml
(contents, props changed)
development/laboratory/planet/components/fsm/docs/src/docs/navigation.xml
(contents, props changed)
Modified:

development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/AbstractState.java

development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/StateMachine.java

development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
development/laboratory/planet/components/fsm/index.xml
development/laboratory/planet/components/fsm/module.xml
Log:
Adding more javadocs.

Modified:
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/AbstractState.java
==============================================================================
---
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/AbstractState.java
(original)
+++
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/AbstractState.java
Wed Feb 2 11:14:00 2005
@@ -21,10 +21,6 @@
import java.util.Locale;
import java.util.ResourceBundle;

-import net.dpml.fsm.AbstractState;
-import net.dpml.fsm.State;
-import net.dpml.fsm.StateMachine;
-
import net.dpml.lang.NullArgumentException;

@@ -52,12 +48,19 @@
public abstract class AbstractState
implements State
{
+ /** The Identity of the State. */
private String m_identity;

+ /** Constructor for the AbstractState.
+ * The AbstractState requires an Identity, which muct be unique, as it is
+ * by default the sole discriminator in the equals() and hashCode()
methods.
+ * @param identity the Identity of the State under construction.
+ * @exception NullArgumentException if the identity is null or empty
string.
+ */
public AbstractState( String identity )
throws NullArgumentException
{
- if( identity == null )
+ if( identity == null || identity.length() == 0 )
{
throw new NullArgumentException( "identity" );
}
@@ -65,11 +68,22 @@
m_identity = identity;
}

+ /** Returns the Identity of this State.
+ * @return the Identity of this State. The Identity must be unique, as
it is
+ * by default the only discriminator between States.
+ */
public String getIdentity()
{
return m_identity;
}

+ /** Returns the Name of the State in the provided Locale.
+ * @param locale the Locale used to locate the Name of the State.
+ * @param cl the Classloader to load the ResouceBundle with.
+ * @return the Name of the State in the provided Locale. The given
classloader
+ * will be use to locate the resource bundle, and the name is
looked
+ * by adding a ".name" suffix to the Identity.
+ */
public String getName( Locale locale, ClassLoader cl )
{
String name = StateMachine.BUNDLE_NAME;
@@ -77,6 +91,13 @@
return bundle.getString( m_identity + ".name" );
}

+ /** Returns the Description of the State in the provided Locale.
+ * @param locale the Locale used to locate the description of the State.
+ * @param cl the Classloader to load the ResouceBundle with.
+ * @return the Description of the State in the provided Locale. The given
+ * classloader will be use to locate the resource bundle, and the
+ * name is looked by adding a ".description" suffix to the
Identity.
+ */
public String getDescription( Locale locale, ClassLoader cl )
{
String name = StateMachine.BUNDLE_NAME;
@@ -84,11 +105,19 @@
return bundle.getString( m_identity + ".description" );
}

+ /**
+ * @return the overridden toString() value, which is
"State["+identity+"]".
+ */
public String toString()
{
return "State[" + m_identity + "]";
}

+ /**
+ * @param o the object to compare with.
+ * @return true if and only if the given object is an instance of the
State
+ * interface, and its Identity is equal to this object's
Identity.
+ */
public boolean equals( Object o )
{
if( o == null )
@@ -96,7 +125,7 @@
System.out.println( "fail null" );
return false;
}
- if( ! (o instanceof State) )
+ if( !( o instanceof State ) )
{
System.out.println( "fail instanceof" );
return false;
@@ -105,11 +134,20 @@
return m_identity.equals( other.getIdentity() );
}

+ /**
+ * @return the hashCode of this object. The hashCode of Identity is the
only
+ * thing used.
+ */
public int hashCode()
{
int idHash = m_identity.hashCode();
- int hash = idHash + ( ( idHash & 31 ) * 621836151 );
+ int hash = idHash + ( ( idHash & HASHCODE_MASK ) *
HASHCODE_MULTIPLIER );
return hash;
}

+ /** Hashcode constant */
+ private static final int HASHCODE_MASK = 31;
+
+ /** Hashcode constant */
+ private static final int HASHCODE_MULTIPLIER = 621836151;
}

Modified:
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/StateMachine.java
==============================================================================
---
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/StateMachine.java
(original)
+++
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/StateMachine.java
Wed Feb 2 11:14:00 2005
@@ -31,7 +31,7 @@
*/
public interface StateMachine
{
-
+ /** Resource Bundle name. */
final String BUNDLE_NAME = "net.dpml.fsm.Resources";

/**

Modified:
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
==============================================================================
---
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
(original)
+++
development/laboratory/planet/components/fsm/api/src/main/net/dpml/fsm/TransitionEvent.java
Wed Feb 2 11:14:00 2005
@@ -30,16 +30,25 @@
public class TransitionEvent
implements Serializable
{
+ /** SerialVersionUID for this class. */
static final long serialVersionUID = 1L;

+ /** The Transition that triggered this event. */
private Transition m_transition;
+
+ /** The Statemachine that this event happened in. */
private StateMachine m_stateMachine;
+
+ /** The object that called the trigger() method in the StateMachine. */
private Object m_source;
- private Date m_TransitionDate;
+
+ /** The time when this event was created. */
+ private Date m_transitionDate;

/** Normal constructor.
* <p/>
- * NOTE: Only StateMachine implementations should be instantiating
TransitionEvents.
+ * NOTE: Only StateMachine implementations should be instantiating
+ * TransitionEvents.
*
* @param source The source that is passed to the
<code>StateMachine.trigger()</code> method.
* @param transition The Transition that was performed.
@@ -51,7 +60,7 @@
m_transition = transition;
m_stateMachine = machine;
m_source = source;
- m_TransitionDate = new Date();
+ m_transitionDate = new Date();
}

/**
@@ -96,7 +105,7 @@
*/
public Date getTransitionDate()
{
- return m_TransitionDate;
+ return m_transitionDate;
}

/** Overridden equals() method.
@@ -124,7 +133,7 @@
{
return false;
}
- if( !m_TransitionDate.equals( event.m_TransitionDate ) )
+ if( !m_transitionDate.equals( event.m_transitionDate ) )
{
return false;
}
@@ -141,10 +150,10 @@
}

/** Overridden hashCode() method.
- *
- * Two TransitionEvent instances can be equal() even though they are
not the same JVM instance,
- * by the means of Serialization. By overriding the equals() and
hashCode() methods we ensure
- * that TransitionEvents can be serialized and yet compared properly.
+ * Two TransitionEvent instances can be equal() even though they are not
+ * the same JVM instance, by the means of Serialization. By overriding
the
+ * equals() and hashCode() methods we ensure that TransitionEvents can be
+ * serialized and yet compared properly.
*
* @return a hash value.
*/
@@ -154,14 +163,15 @@
result = m_transition.hashCode();
result = 29 * result + m_stateMachine.hashCode();
result = 29 * result + m_source.hashCode();
- result = 29 * result + m_TransitionDate.hashCode();
+ result = 29 * result + m_transitionDate.hashCode();
return result;
}

// Serialization overrides.

- /** This method is used by the object serialization framework, and is
accessed through
- * reflection. See the Serialization specification for details.
+ /** This method is used by the object serialization framework, and is
+ * accessed through reflection.
+ * See the Serialization specification for details.
* The ObjectInputStream is read and the members are assigned. If the
* StateMachine and/or the Source memeber were not Serializable during
the
* writeObject invocation, the restored instance of this class will have
@@ -176,14 +186,14 @@
throws IOException, ClassNotFoundException
{
m_transition = (Transition) in.readObject();
- m_TransitionDate = (Date) in.readObject();
+ m_transitionDate = (Date) in.readObject();
Object placeholder = in.readObject();
if( placeholder instanceof StateMachine )
{
m_stateMachine = (StateMachine) placeholder;
}
placeholder = in.readObject();
- if( ! (placeholder instanceof Boolean ) )
+ if( !( placeholder instanceof Boolean ) )
{
m_source = placeholder;
}
@@ -202,7 +212,7 @@
throws IOException
{
out.writeObject( m_transition );
- out.writeObject( m_TransitionDate );
+ out.writeObject( m_transitionDate );
if( m_stateMachine instanceof Serializable )
{
out.writeObject( m_stateMachine );
@@ -221,5 +231,4 @@
out.writeObject( Boolean.FALSE );
}
}
-
}

Added:
development/laboratory/planet/components/fsm/docs/src/docs/examples/index.xml
==============================================================================
--- (empty file)
+++
development/laboratory/planet/components/fsm/docs/src/docs/examples/index.xml
Wed Feb 2 11:14:00 2005
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="niclas AT hedhman.org">Niclas Hedhman</author>
+ <title>DPML Components</title>
+ </properties>
+
+ <body>
+ <section name="FSM - Examples">
+
+ <ol>
+ <li>
+ <a href="trafficlight.html" >Traffic Light Simulation</a> - a
simple
+ console program that shows one of the most simple state machines
out
+ there, the standard strett traffic light.
+ </li>
+ </ol>
+ </section>
+ </body>
+</document>
+

Added:
development/laboratory/planet/components/fsm/docs/src/docs/examples/navigation.xml
==============================================================================
--- (empty file)
+++
development/laboratory/planet/components/fsm/docs/src/docs/examples/navigation.xml
Wed Feb 2 11:14:00 2005
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+<project>
+
+ <title>DPML</title>
+
+ <body>
+
+ <menu>
+ <item name="Overview" href="index.html"/>
+ <item name="Traffic Light Simulation" href="trafficlight.html"/>
+ </menu>
+ </body>
+
+</project>

Added:
development/laboratory/planet/components/fsm/docs/src/docs/examples/trafficlight.xml
==============================================================================
--- (empty file)
+++
development/laboratory/planet/components/fsm/docs/src/docs/examples/trafficlight.xml
Wed Feb 2 11:14:00 2005
@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="niclas AT hedhman.org">Niclas Hedhman</author>
+ <title>DPML Components</title>
+ </properties>
+
+ <body>
+ <section name="FSM Example - Traffic Light Simulation">
+
+<source>
+cd examples/trafficlight
+ant
+metro artifact:block:
+</source>
+ </section>
+ </body>
+</document>
+

Added: development/laboratory/planet/components/fsm/docs/src/docs/index.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/fsm/docs/src/docs/index.xml
Wed Feb 2 11:14:00 2005
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+
+<document>
+ <properties>
+ <author email="niclas AT hedhman.org">Niclas Hedhman</author>
+ <title>DPML Components</title>
+ </properties>
+
+ <body>
+ <section name="Finite State Machine">
+
+ <p role="intro">
+ The Finite State Machine (FSM) is a simplified FSM designed to be
+ flexible, extendable and fairly easy to use, both in pure Metro
+ applications as well as any Java application.
+ </p>
+
+ <subsection name="Principles" >
+ <p>
+ The FSM has strong separation of interface and implementation, and
+ fairly strong separation of concerns (SoC) as well. Inversion of
+ Control (IoC) is kind of optional, as it is possible to override it
+ when IoC containers are not present. The API is rather pure, except
+ that there is an AbstractState convenience class available.
+ </p>
+ <p>
+ No formal FSM guidelines or specification has been followed, as
they
+ typically involves far more 'concerns' than we think is adviceable.
+ Instead, these concerns, such as state change conditions, are added
+ external to the state machine itself, either through the
+ <code>net.dpml.fsm.TransitionListener</code> interface or by
+ implementing the <code>net.dpml.fsm.State</code> interface and add
+ functionality in the <code>entry</code> and <code>exit</code>
+ methods.
+ </p>
+ </subsection>
+
+ </section>
+ </body>
+</document>
+

Added:
development/laboratory/planet/components/fsm/docs/src/docs/navigation.xml
==============================================================================
--- (empty file)
+++ development/laboratory/planet/components/fsm/docs/src/docs/navigation.xml
Wed Feb 2 11:14:00 2005
@@ -0,0 +1,32 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+
+<project>
+
+ <title>DPML</title>
+
+ <body>
+
+ <menu>
+ <item name="About" href="index.html"/>
+ <item name="Examples" href="examples/index.html"/>
+ </menu>
+ </body>
+
+</project>

Modified: development/laboratory/planet/components/fsm/index.xml
==============================================================================
--- development/laboratory/planet/components/fsm/index.xml (original)
+++ development/laboratory/planet/components/fsm/index.xml Wed Feb 2
11:14:00 2005
@@ -23,17 +23,9 @@
<import uri="artifact:module:dpml/magic/dpml-magic#SNAPSHOT"/>
<import uri="artifact:module:dpml/transit/dpml-transit#SNAPSHOT"/>

- <resource>
- <info>
- <group>jgraph</group>
- <name>jgraph</name>
- <version>5.3.1</version>
- </info>
- </resource>
-
<project file="module.xml">
<info>
- <group>dpml/fsm</group>
+ <group>dpml/components/fsm</group>
<name>dpml-fsm</name>
<version>1.0.0</version>
<type>module</type>
@@ -50,7 +42,7 @@

<project basedir="api">
<info>
- <group>dpml/fsm</group>
+ <group>dpml/components/fsm</group>
<name>dpml-fsm-api</name>
<version>1.0.0</version>
</info>
@@ -63,7 +55,7 @@

<project basedir="basic">
<info>
- <group>dpml/fsm</group>
+ <group>dpml/components/fsm</group>
<name>dpml-fsm-basic</name>
<version>1.0.0</version>
</info>
@@ -83,29 +75,9 @@
</plugins>
</project>

- <project basedir="view">
- <info>
- <group>dpml/fsm</group>
- <name>dpml-fsm-view</name>
- <version>1.0.0</version>
- </info>
- <dependencies>
- <include key="dpml-composition-api" />
- <include key="dpml-context-api" />
- <include key="dpml-parameters-api" />
- <include key="dpml-service-api" />
- <include key="dpml-fsm-api" />
- <include key="dpml-service-api" />
- <include key="jgraph" />
- </dependencies>
- <plugins>
- <include key="dpml-meta-tools"/>
- </plugins>
- </project>
-
<project basedir="demo/trafficlight">
<info>
- <group>dpml/fsm/demo</group>
+ <group>dpml/components/fsm/demo</group>
<name>dpml-trafficlight</name>
<version>1.0.0</version>
</info>

Modified: development/laboratory/planet/components/fsm/module.xml
==============================================================================
--- development/laboratory/planet/components/fsm/module.xml (original)
+++ development/laboratory/planet/components/fsm/module.xml Wed Feb 2
11:14:00 2005
@@ -34,7 +34,7 @@
</x:module>
</target>

- <target name="docs" depends="install"> 
+ <target name="docs" depends="install, checkstyle, junit-report">
<x:javadoc>
<link href="http://java.sun.com/j2se/1.4/docs/api"/>
<group title="Public API">

svn commit: r1697 - in development/laboratory/planet/components/fsm: . api/src/main/net/dpml/fsm docs docs/src docs/src/docs docs/src/docs/examples, niclas, 02/02/2005