All events, that were issued in a simulation-run, should be passed along to an instance of the class org.matsim.evens.Events. This is done by creating a new event and then calling computeEvent() method of your instance of Events.

Example:

Events myEventManager = new Events();
EventLinkEnter test = new EventLinkEnter(time,  agentId,  linkId);
Events.computeEvent(test);

The Events instance will then take the event and forward it to every EventHandler, that wants to receive events of this kind.

To receive events out of the simulation, you have to write your own event-handler as described below.

Building an event handler

Building a new eventhandler that uses already existing events

If you just want to receive any of the already defined events, it is an easy task:

1. Simlpy write your own EventHandler class, that implements every EventHandler...I interface that you want to get to know about.
2. Then you have to make a new instance of your handler-class and add it to your Events instance by using Events.addHandler(EventHandlerI handler).
3. We are ready now, Events will call your EventHandler for every event that he listenes to.

Hazard: Be aware, that if you overload some special EventHandler ...I interfaces and the BasicEventHandlerI than the special interfaces will receive the appropriate events and the handleEvent(BasicEvent event) receives the SAME event a second time. This will get optionally in a later verion.

Remark: Instead of overloading several EventHandler...I interfaces it sometimes might be easier just to overload BasicEventHandlerI and to check the events in an if clause like this:

if(event.getClass() == EventAgentNoRoute.class)  {
  ...
} else if(event.getClass() == EventAgentArrival.class)  {
  ...
} else if(event.getClass() == EventLinkLeft.class)  {
  ...
}

Example:

class CountLinkTravelTimes implements
        EventLinkEnterHandlerI,
        EventHandlerLinkLeft {
  public void handleEvent (EventLinkEnter event) {
    ...
    id = event.linkId; // do something with it
    ...
  }
  public void handleEvent (EventLinkLeft event) {
    ...
    id = event.linkId; // do something with it
    ...
  }
}
...
Events myevent = new Events();
CountLinkTravelTimes myhandler = new CountLinkTravelTimes();
myevents.addHandler(myhandler);
EventLinkEnter test = new EventLinkEnter(time,  agentId,  linkId);
Events.computeEvent(test);

Building your own specialized event

Building your own specialized event based on an existing event:

Now we have to additionally define a specialized event class, let's say

class EventAgentStuckAndReplanning extends EventAgentStuck {
  private double replanning_probability;
  // some other special things...
}

Now we are ready to receive this Event from all EventHandlerAgentStuckI! We can check for this special event by the means of

if(event.getClass() == EventAgentStuckAndReplanning.class) {...}

If for some reasons we want to write a handler that only receives this special Event StuckAndReplanning, we would have to add a new interface that extends EventHandlerI

e.g.

public interface  EventHandlerAgentSuckAndReplanningI extends EventHandlerI {
  handleEvent(EventAgentSutckAndReplanning event);
}

and ready you are... just implement that interface in your Handler and the handler will start receiveing only the appropriate events!

Building your own specialized event based on nothing at all:

It is simply as above, only that you inherit from BasicEvent. All Events should inherit from BasicEvent, which only defines, that there has to be a time and an agentId. One might think of events that don't even have an agentId, maybe you would leave this field blank (e.g. Integer.MIN_VALUE) or whatever. We included agentId into BasicEvent as the wast majority of events will need an agentID.