com.azalient.api
Class BasePlugin

java.lang.Object
  com.azalient.base.BaseInternals
      com.azalient.api.BasePlugin

All Implemented Interfaces:

IBasePlugin, IPlugin, IPluginIdentifier, SimulationEventListener, StatusListener

public abstract class BasePlugin
extends com.azalient.base.BaseInternals
implements IPluginIdentifier, StatusListener, SimulationEventListener

A template for a Commuter Plugin, using a listener/event model.

To create a plugin:

• Write the code for the plugin, using the template below, adding appropriate event listeners from com.azalient.api.event.model.*
• Edit the file C:/Azalient/Commuter/commuter.plugins.csv to specify a display name and the full path name of your plugin class. For example: "TTT,Test Plugin,com/mydomain/test/TestPlugin". The 3-letter code is historical, it is not important.
• Compile the class, then put into a jar file, and copy that jar file into the directory C:/Azalient/Commuter/bin/ beside the other jar files. It will be automatically discovered here by the commuter.exe loader.
• Start commuter.exe and go to the Plugin tab on the left hand pane
• You should see the name of your plugin at the bottom of the list - click connect to open your plugin. This will also raise the window you have defined in your plugin. If you now save your model, this plugin will be opened next time you open that model.
• Click on the name of the plugin any time you want to raise the window for your plugin.

public class TestPlugin  extends BasePlugin
             implements ModelEventViewLegend     // implement the event handlers corresponding to the events you want to be sent to this plugin
{
    // In the constructor, register for the events you want to be sent to this plugin. 
    // There are both model events, corresponding to significant transitions in the model loading and handling cycle, 
    // and agent events, which correspond to significant events in the life cycle of an agent (vehicle, pedestrian) 
    // in any  simulation

    private JFrame frame = new XFrame("Test Plugin User Interface");

    public TestPlugin()
    {
        // This is an example of a listener - it does not have to be included
        addModelEventViewLegendListener(this);

        frame.getContentPane().add(new JLabel("Add your own controls here, to allow user interaction with your plugin."));
        frame.pack();
    }


    // This is the implementation of the event handler registered above 
    public void viewLegend(IDrawing drw)
    {
        drw.colour(Color.WHITE.getRGB());
        drw.string("Test Plugin", 0.5, 0.5, 0, 0.5);
    }

    // This is called for all plugins, after the model "document" has been loaded 
    public void pluginOpen()
    {

    }

    // called when a network document" is closed 
    public void pluginClose()
    {
        frame.setVisible(false);
        frame.dispose();
    }

    //  called when "File/Save" is selected, to save any data in the plugin
    public void pluginSave() {}

    // called when the "Configure..." button is pressed on the Plugins tab 
    public Window pluginWindow()
    {
        return frame;
    }
}

Field Summary

Fields inherited from class com.azalient.base.BaseInternals

PKG_PLUGIN

Fields inherited from interface com.azalient.api.event.StatusListener

BAD, N, OK, STARTED, UNKNOWN

Method Summary

void	addAgentEventArriveListener(AgentEventArrive listener) Call this in the constructor to register your plugin, so that it is notified when an agent arrives at its destination.
void	addAgentEventDepartListener(AgentEventDepart listener) Call this in the constructor to register your plugin, so that it is notified when an agent departs from its origin.
void	addAgentEventLaneListener(AgentEventLane listener) Call this in the constructor to register your plugin, so that it is notified when a vehicle changes lane
void	addAgentEventLinkListener(AgentEventLink listener) Call this in the constructor to register your plugin, so that it is notified when a vehicle changes link
void	addAgentEventLoopListener(AgentEventLoop listener) Call this in the constructor to register your plugin, so that it is notified when a vehicle changes the state of a loop.
void	addAgentEventMoveListener(AgentEventMove listener) Call this in the constructor to register your plugin, so that it is notified for every agent at every simulation time step, when it moves.
void	addAgentEventOccupantInListener(AgentEventOccupantIn listener) Call this in the constructor to register your plugin, so that it is notified when a driver or passenger gets into a private vehicle
void	addAgentEventOccupantOutListener(AgentEventOccupantOut listener) Call this in the constructor to register your plugin, so that it is notified when a driver or passenger gets out of a private vehicle
void	addAgentEventPassengerOffListener(AgentEventPassengerOff listener) Call this in the constructor to register your plugin, so that it is notified when a passenger gets off a public transport vehicle
void	addAgentEventPassengerOnListener(AgentEventPassengerOn listener) Call this in the constructor to register your plugin, so that it is notified when a passenger gets onto a public transport vehicle
void	addAgentEventSignListener(AgentEventSign listener) Call this in the constructor to register your plugin, so that it is notified when a vehicle passes a sign.
void	addAgentEventStandListener(AgentEventStand listener) Call this in the constructor to register your plugin, so that it is notified when a public transport vehicle arrives at a stand.
void	addAgentEventStopListener(AgentEventStop listener) Call this in the constructor to register your plugin, so that it is notified when a vehicle stops, where stopping is defined by calibration parameters
void	addAgentEventTestArrivalListener(AgentEventTestArrival listener) Call this in the constructor to register your plugin, so that it can be an active plugin that influences destination choice.
void	addAgentEventTestRouteListener(AgentEventTestRoute listener) Call this in the constructor to register your plugin, so that it can be an active plugin that influences route choice.
void	addAgentEventTimeStepListener(AgentEventTimeStep listener) Call this in the constructor to register your plugin, so that it is notified for every agent at every simulation time step.
void	addAgentEventUnreleasedListener(AgentEventUnreleased listener) Call this in the constructor to register your plugin, so that it is notified when an agent departs from its origin.
void	addAgentEventWalkwayListener(AgentEventWalkway listener) Call this in the constructor to register your plugin, so that it is notified when a person joins or leaves a walkway
void	addModelEventActionSelectionListener(ModelEventActionSelection listener) Call this in the constructor to register your plugin, so that it is notified when the user makes a selection .
void	addModelEventGenericListener(ModelEventGeneric listener) Call this in the constructor to register your plugin, so that it receives generic event notifications .
void	addModelEventResultListener(ModelEventResult listener) Call this in the constructor to register your plugin, so that it is notified when results are saved .
void	addModelEventTimeCompleteListener(ModelEventTimeComplete listener) Call this in the constructor to register your plugin, so that it is notified when the simulation completes its term.
void	addModelEventTimeRewindListener(ModelEventTimeRewind listener) Call this in the constructor to register your plugin, so that it is notified when the simulation time is rewound to the beginning of the the simulation term .
void	addModelEventTimeSecListener(ModelEventTimeSec listener) Call this in the constructor to register your plugin, so that it is notified on each whole second of simulation time .
void	addModelEventTimeStepListener(ModelEventTimeStep listener) Call this in the constructor to register your plugin, so that it is notified on each simulation time step .
void	addModelEventViewLegendListener(ModelEventViewLegend listener) Call this in the constructor to register your plugin, so that it is notified when drawing engine draws in GL_PROJECTION mode, for a legend or a key that does not move with the view .
void	addModelEventViewModelListener(ModelEventViewModel listener) Call this in the constructor to register your plugin, so that it is notified when drawing engine draws in GL_MODELVIEW mode, the world view of the model .
boolean	agentEvent(IAgent agent, AgentEvent event, Object data) This is called by the simulation to fire an agent event.
void	centralStatusListener(StatusListener sl) Set the pointer to the central status listener that is updated when the status of this plugin chages
void	closeWindow()
void	deiconifyWindow()
void	enable(boolean v) Toggle to enable this plugin
static Window	featureNotLicensed(String message)
static int	generateUniqueIndex()
void	iconifyWindow()
boolean	isEnabled() Returns true if this listener is enabled
static int	mainProcessUniqueIndex()
static int	maxUniqueIndex()
boolean	modelEvent(ModelEvent event, Object data) This is called by the simulation to fire a model event.
void	moduleChanged(PageType module) This is called when a module is changed.
IModule[]	moduleDependencies() Deprecated.
PageType[]	moduleTypeDependencies() Return an array of module page types on which this plugin depends.
void	raiseWindow() Override this to raise a UI window for your Plugin.
String	status() A message describing the current status
void	status(Object source, int status) This is called when the status of a process changes
void	status(Object source, int status, String description) This is called when the status of a process changes
int	uniqueIndex() Each plugin when it is created gives itself a unique index, which can be used to differentiate calls to the userData functions

Methods inherited from class com.azalient.base.BaseInternals

plugin, pluginIndex, plugins, raiseWindow, readPluginDescriptions, rebuildController, setPluginIndex, showController, unload

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.azalient.api.b.plugins.IPlugin

pluginClose, pluginOpen, pluginSave

Methods inherited from interface com.azalient.api.a.IBasePlugin

pluginClose, pluginOpen, pluginWindow

Method Detail

moduleDependencies

public IModule[] moduleDependencies()

Deprecated.

Specified by:

moduleDependencies in interface IPlugin

moduleTypeDependencies

public PageType[] moduleTypeDependencies()

Description copied from interface: IPlugin

Return an array of module page types on which this plugin depends. This will cause moduleChanged() to be called if the module is changed. Return null to be notified for all plugins, or PageType.ZERO if you want no module change notifications.

Specified by:

moduleTypeDependencies in interface IPlugin

moduleChanged

public void moduleChanged(PageType module)

Description copied from interface: IPlugin

This is called when a module is changed. The default action is to call pluginClose() followed by pluginOpen() but you should also call destroy() on any tables you may have to remove any references to the old network and reduce memory leakage. if you have a UI window, you should dispose() of it in pluginClose().

Specified by:

moduleChanged in interface IPlugin

raiseWindow

public void raiseWindow()

Override this to raise a UI window for your Plugin.

Specified by:

raiseWindow in interface IBasePlugin

deiconifyWindow

public void deiconifyWindow()

iconifyWindow

public void iconifyWindow()

closeWindow

public void closeWindow()

centralStatusListener

public void centralStatusListener(StatusListener sl)

Description copied from interface: IBasePlugin

Set the pointer to the central status listener that is updated when the status of this plugin chages

Specified by:

centralStatusListener in interface IBasePlugin

status

public void status(Object source,
                   int status,
                   String description)

Description copied from interface: StatusListener

This is called when the status of a process changes

Specified by:

status in interface StatusListener

Parameters:

source - the source of the status change

status - The new status

description - a text message description of the new status, for example a reason for failure

status

public void status(Object source,
                   int status)

Description copied from interface: StatusListener

This is called when the status of a process changes

Specified by:

status in interface StatusListener

Parameters:

source - the source of the status change

status - The new status

status

public String status()

Description copied from interface: IBasePlugin

A message describing the current status

Specified by:

status in interface IBasePlugin

enable

public void enable(boolean v)

Description copied from interface: IBasePlugin

Toggle to enable this plugin

Specified by:

enable in interface IBasePlugin

isEnabled

public boolean isEnabled()

Description copied from interface: SimulationEventListener

Returns true if this listener is enabled

Specified by:

isEnabled in interface IBasePlugin

Specified by:

isEnabled in interface SimulationEventListener

mainProcessUniqueIndex

public static int mainProcessUniqueIndex()

generateUniqueIndex

public static int generateUniqueIndex()

maxUniqueIndex

public static int maxUniqueIndex()

uniqueIndex

public int uniqueIndex()

Each plugin when it is created gives itself a unique index, which can be used to differentiate calls to the userData functions

Specified by:

uniqueIndex in interface IPluginIdentifier

addModelEventTimeCompleteListener

public final void addModelEventTimeCompleteListener(ModelEventTimeComplete listener)

Call this in the constructor to register your plugin, so that it is notified when the simulation completes its term.

You will also need to implement the listener interface in the plugin, the listener cannot be a separate class.

Example code:

 public class MyPlugin extends BasePlugin implements ModelEventTimeComplete
 {
   
     public MyPlugin()
     {
       // ...
       
      // in constructor
       addModelEventTimeCompleteListener(this);
    }
 }
 
 public void timeComplete()
 {
      // add code here that will be executed when the event occurs 
 }
 

addModelEventTimeRewindListener

public final void addModelEventTimeRewindListener(ModelEventTimeRewind listener)

Call this in the constructor to register your plugin, so that it is notified when the simulation time is rewound to the beginning of the the simulation term .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventTimeStepListener

public final void addModelEventTimeStepListener(ModelEventTimeStep listener)

Call this in the constructor to register your plugin, so that it is notified on each simulation time step .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventTimeSecListener

public final void addModelEventTimeSecListener(ModelEventTimeSec listener)

Call this in the constructor to register your plugin, so that it is notified on each whole second of simulation time .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventActionSelectionListener

public final void addModelEventActionSelectionListener(ModelEventActionSelection listener)

Call this in the constructor to register your plugin, so that it is notified when the user makes a selection .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventViewLegendListener

public final void addModelEventViewLegendListener(ModelEventViewLegend listener)

Call this in the constructor to register your plugin, so that it is notified when drawing engine draws in GL_PROJECTION mode, for a legend or a key that does not move with the view .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventViewModelListener

public final void addModelEventViewModelListener(ModelEventViewModel listener)

Call this in the constructor to register your plugin, so that it is notified when drawing engine draws in GL_MODELVIEW mode, the world view of the model .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventResultListener

public final void addModelEventResultListener(ModelEventResult listener)

Call this in the constructor to register your plugin, so that it is notified when results are saved .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addModelEventGenericListener

public final void addModelEventGenericListener(ModelEventGeneric listener)

Call this in the constructor to register your plugin, so that it receives generic event notifications .

For an example, see {addModelEventTimeCompleteListener(ModelEventTimeComplete)

addAgentEventArriveListener

public final void addAgentEventArriveListener(AgentEventArrive listener)

Call this in the constructor to register your plugin, so that it is notified when an agent arrives at its destination.

You will also need to implement the listener interface in the plugin, the listener cannot be a separate class.

Example code:

 public class MyPlugin extends BasePlugin implements AgentEventArrive
 {
   
     public MyPlugin()
     {
       // ...
       
      // in constructor
       addAgentEventArriveListener(this);
    }
 }
 
 public void arrive(IAgent agent, IPlace place)
 {
      // add code here that will be executed when the event occurs 
 }
 

addAgentEventDepartListener

public final void addAgentEventDepartListener(AgentEventDepart listener)

Call this in the constructor to register your plugin, so that it is notified when an agent departs from its origin.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventUnreleasedListener

public final void addAgentEventUnreleasedListener(AgentEventUnreleased listener)

Call this in the constructor to register your plugin, so that it is notified when an agent departs from its origin.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventTimeStepListener

public final void addAgentEventTimeStepListener(AgentEventTimeStep listener)

Call this in the constructor to register your plugin, so that it is notified for every agent at every simulation time step.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventMoveListener

public final void addAgentEventMoveListener(AgentEventMove listener)

Call this in the constructor to register your plugin, so that it is notified for every agent at every simulation time step, when it moves.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventLoopListener

public final void addAgentEventLoopListener(AgentEventLoop listener)

Call this in the constructor to register your plugin, so that it is notified when a vehicle changes the state of a loop.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventSignListener

public final void addAgentEventSignListener(AgentEventSign listener)

Call this in the constructor to register your plugin, so that it is notified when a vehicle passes a sign.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventStandListener

public final void addAgentEventStandListener(AgentEventStand listener)

Call this in the constructor to register your plugin, so that it is notified when a public transport vehicle arrives at a stand.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventStopListener

public final void addAgentEventStopListener(AgentEventStop listener)

Call this in the constructor to register your plugin, so that it is notified when a vehicle stops, where stopping is defined by calibration parameters

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventPassengerOnListener

public final void addAgentEventPassengerOnListener(AgentEventPassengerOn listener)

Call this in the constructor to register your plugin, so that it is notified when a passenger gets onto a public transport vehicle

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventPassengerOffListener

public final void addAgentEventPassengerOffListener(AgentEventPassengerOff listener)

Call this in the constructor to register your plugin, so that it is notified when a passenger gets off a public transport vehicle

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventOccupantInListener

public final void addAgentEventOccupantInListener(AgentEventOccupantIn listener)

Call this in the constructor to register your plugin, so that it is notified when a driver or passenger gets into a private vehicle

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventOccupantOutListener

public final void addAgentEventOccupantOutListener(AgentEventOccupantOut listener)

Call this in the constructor to register your plugin, so that it is notified when a driver or passenger gets out of a private vehicle

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventWalkwayListener

public final void addAgentEventWalkwayListener(AgentEventWalkway listener)

Call this in the constructor to register your plugin, so that it is notified when a person joins or leaves a walkway

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventLaneListener

public final void addAgentEventLaneListener(AgentEventLane listener)

Call this in the constructor to register your plugin, so that it is notified when a vehicle changes lane

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventLinkListener

public final void addAgentEventLinkListener(AgentEventLink listener)

Call this in the constructor to register your plugin, so that it is notified when a vehicle changes link

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventTestRouteListener

public final void addAgentEventTestRouteListener(AgentEventTestRoute listener)

Call this in the constructor to register your plugin, so that it can be an active plugin that influences route choice. A plugin that registers for this event is notified each time step and asked which route exit an agent should choose from its current location. Unlike most other events, this is not just a notification, but an opportunity to change the behaviour of the agent.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

addAgentEventTestArrivalListener

public final void addAgentEventTestArrivalListener(AgentEventTestArrival listener)

Call this in the constructor to register your plugin, so that it can be an active plugin that influences destination choice. A plugin that registers for this event is notified each time step and asked if an agent is about to arrive at its destination. Unlike most other events, this is not just a notification, but an opportunity to change the behaviour of the agent.

For an example, see {addAgentEventArriveListener(AgentEventArrive)

modelEvent

public final boolean modelEvent(ModelEvent event,
                                Object data)

Description copied from interface: SimulationEventListener

This is called by the simulation to fire a model event. It is not recommend that plugins call this method.

Specified by:

modelEvent in interface SimulationEventListener

agentEvent

public final boolean agentEvent(IAgent agent,
                                AgentEvent event,
                                Object data)

Description copied from interface: SimulationEventListener

This is called by the simulation to fire an agent event. It is not recommend that plugins call this method.

Specified by:

agentEvent in interface SimulationEventListener

featureNotLicensed

public static Window featureNotLicensed(String message)