Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## josx.robotics
Class Activity

    java.lang.Object
      java.lang.Thread
          josx.robotics.ActivityBase
              josx.robotics.Activity

    public abstract class Activity

extends ActivityBase

An activity that operates in coordination with other activities. Only one activity can run at a time. When an activity of a higher priority wants to run any activities of a lower priority will be suppressed. Furthermore, if there is already an activity of the same or lower priority running, that activity will be stopped.

This is essentially an alternative way of implementing a Behavior or Subsumption architecture. It is totally distinct from the Behavior and Arbitrator classes and does not use either.

It works like this:

1. This class should be sub-classed and the action() method should be implemented to perform the desired action. That may be to respond to a change in a sensor, or it may be to cause the robot to wander around (or anything else). This method should call one of the pause() methods occasionally. In particular if it wants to sleep or yield control it should call pause() instead of sleep() or yield() or wait().
2. An application should create instances of the sub-classes as needed, set their priorities by calling setPriority() and then start them by calling start().
3. If an activity wants to run it should call activity.iWantToRun(), or another class could call it.
4. If there is no higher priority activity running when an activity become runnable, any activities of the same or lower priority will be suppressed. In addition, if an activity was not already running the action() method will be called in its own thread.
5. If an activity is already running when it is run again, pause() throws an InterruptedException. It can do what it wants with that. An activity that is run when a sensor is activated might want to restart action() from the beginning for example. A background activity might just ignore it.
6. If a higher priority activity gets to run, pause() on this activity will throw a StopException. This should not be caught so that the action() method exits with that exception.

Note. A background activity should ensure that something makes it runnable if it is stopped. The easiest way to do that is to override resetRunnable() to call iWantToRun().

Example:

     /**
      * When sensor one is pressed, run the motors in some pattern.
      */
     class ControlMotors extends Activity implements SensorListener
     {
            public ControlMotors()
            {
                    Sensor.S1.addSensorListener(this);
            }

            /**
             * Called when the sensor state changes (in some thread other than this one).
             */
            public void stateChanged(Sensor s, int old, int nu)
            {
                    if (old > nu)
                            return;

                    iWantToRun();
            }

            /**
             * Encapsulates the actual activity we want to perform.
             *
             * @exception StopException if we are forcibly stopped.
             */
            protected void action() throws StopException
            {
                    boolean finished = false;

                    // Sit here until we are finished or we are forcibly halted.
                    while (!finished)
                    {
                            try
                            {
                                    // spin
                                    Motor.C.forward();
                                    Motor.A.backward();

                                    // Wait for 0.25 secs, may throw InterruptedException
                                    pause(250);

                                    // Forward
                                    Motor.A.forward();

                                    // We are finished
                                    finished = true;
                            } catch (InterruptedException ie)
                            {
                                    // pause() was interrupted. Re-start from the beginning
                            }
                    }
            }
     }

Author:
  Paul Andrews

Field Summary

Fields inherited from class josx.robotics.ActivityBase
`monitor`

Fields inherited from class java.lang.Thread
`MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

Constructor Summary
`Activity()`

Method Summary
`protected abstract void` | `action()` Encapsulates the actual activity we want to perform.
`protected void` | `iWantToRun()` Call this if you want this activity to run.
`protected void` | `pause()` Wait until we've either been made runnable or someone else has.
`protected void` | `pause(long time)` Wait at most 'time' milliseconds.
`protected void` | `resetRunnable()` Reset the runnable activity.
`void` | `run()` Thread entry point.

Methods inherited from class java.lang.Thread
`currentThread, getPriority, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, setDaemon, setPriority, sleep, start, yield`

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait`

Constructor Detail

### Activity

    public Activity()

Method Detail

### action

    protected abstract void action()
                            throws StopException

  Encapsulates the actual activity we want to perform. Returns when complete or when stopped.

  Throws:
    `StopException` - when some other activity has stopped this one.

### resetRunnable

    protected void resetRunnable()

  Reset the runnable activity. Normal activities should not override this. Background activities can in order to request that they become runnable.

### iWantToRun

    protected final void iWantToRun()

  Call this if you want this activity to run.

### run

    public final void run()

  Thread entry point. Never returns.

  Specified by:
    `run` in class `Thread`

### pause

    protected final void pause(long time)
                        throws InterruptedException,
                               StopException

  Wait at most 'time' milliseconds. Returning without an exception means continue the activity where it left off.

  Throws:
    `InterruptedException` - if we were made runnable whilst we were running. This might indicate, for example, that a sensor was pressed while we were still reacting to an earlier press. Typically, an activity would want to restart execution of the action() method from the beginning if that happened.
    `StopException` - if we should stop executing altogether.

### pause

    protected final void pause()
                        throws InterruptedException,
                               StopException

  Wait until we've either been made runnable or someone else has.

  Throws:
    `InterruptedException` - if we should restart execution of the action() method from the beginning.
    `StopException` - if we should stop executing altogether.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD