Migrate from GitHub to SourceForge with this tool. Check out all of SourceForge's recent improvements.
Close

Event based Collections

Event based Collections

In this section you can read about the features provided by event-based-cololections like Set, List, Map. The event-decorators can decorate any collections types, thus the events will be fired if any elements will be removed or added. The programer can register custom ActionListeners and listening to fired events. The events enable the programer to control the program-flow by canceling the remove or add operation or executing custom logic, which can be implemented in an ActionListener.

Event types

Before-event allows to cancel any operation. For example to cancel modification of the collection. For example if the element should be added to the collection, but the programmer registered BeforeAdd-event, then the programmer can check the new object, which should be added and decide to cancel the add-operation. The after-event notifies that something has happened. All event-decorators for any collections have always an before and an after event. See table below:

  • EventColection
  • EventList
  • EventSet
  • EventSortedSet
  • BeforeGet, AfterGet
  • BeforeAdd, AfterAdd
  • BeforeRemove, AfterRemove
  • BeforeClear, AfterClear
  • BeforeModify, AfterModify
  • EventMap
  • EventSortedMap
  • BeforeGet, AfterGet
  • BeforePut, AfterPut
  • BeforeRemove, AfterRemove
  • BeforeClear, AfterClear
  • BeforeModify, AfterModify

There are different event-types, which can be fired by event-decorators. The events will be fired only if any ActionListeners are registered and listen for them, thus the event-based programming style is very efficient and avoid any additional overhead. Below is presented the table with event types and its description:

  • Get Event
Will be fired if any elements will be returned by teh collection, by using any mehtos like contains() or just iterating through the collection.
  • Add Event
  • Put Event
Will be fired if any elements will be added to the collection
  • Remove Event
Will be fired if any elements will be removed from the collection
  • Clear Event
Will be fired if the collection will be cleared
  • Modify Event
Will be fired if the collection will be modified in any manner for example by adding or removing any elements

See more examples in the examples section!

EventCollection

The event-decorator extends java.util.Collection, java.util.List, java.util.Set and java.util.Map with events. Thus ActionListeners can be registered on any type of modification operations like remove or add an element. Usually if a modification operation is executing two types of events can be thrown: OnBefore- and OnAfter- modification. Thus it is possible for example to cancel the add or remove operation. Event based types decorate fully the collection types by decorating for example all iterators and even more. The map interface for example has method Map.keySet() where the keys are returned as a set and if any key is removed from the same key is removed from the map. Such situation and all others are supported by EventDecorators. If any stuff will be changed in the decorated collection, then events will be fired!

The implementation of event-decorator is very efficient and produces less overhead. Because of different types of events you can register any events you like directly where you want - this is not so powerful as aspect oriented programming, but much easier and reusable!

Below you can see how the simple Collection can be decorated:

//create event collection by decoration an ArrayList
EventCollection_1x0<String> c = 
    EventCollection_1x0.of(new ArrayList<String>(
            Arrays.asList(new String[]{"A","B","C","D"})
                )
            );

//this event doesn't allow to remove any strings which contains '!' 
c.getOnBeforeRemoveEvent().add(new ActionListener(){

    @Override
    public void actionPerformed(ActionEvent arg0) {
        //here you can proof arguments and cancel the remove operation
        System.out.println("Before remove event!");
    }
});

c.remove("A");

EventSet

The java.util.Set can be decorated by an EventSet, below you can see an example how to decorate a set and register BeforeAdd-event. As you can see the add-operation of any elements can be easily canceled. This is very useful feature for implementing custom rules for elements, which can be added to the set.

EventSet_1x0<Integer> eventSet = EventSet_1x0.of(new HashSet<Integer>());
//register before add event, thus you can check the parameter before it will be added to the set
eventSet.getOnBeforeAddEvent().add(new ActionListenerT_1x0<ActionEventBefore_1x0<Integer>>(){
    @Override
    public void actionPerformedImpl(ActionEventBefore_1x0<Integer> event) {
        Integer playerNumber = event.getData();
        //check the player number
        if(playerNumber<0 || playerNumber==null)
            throw new IllegalArgumentException("The number can't be negative or null");
        //Alternatively you can cancel the add operation
        //event.setCanceled(true);
    }
});

EventList

EventList extends EventCollection and can be used to decorate the java.util.List interface. The event-decorators decorates whole list-implementation, for example if the list will be changed through the iterator by removing any elements the before- and after-remove events will be fired, thus the program can cancel or react on the remove-operation.

//create event collection by decoration an ArrayList
EventList_1x0<String> list = 
    EventList_1x0.of(new ArrayList<String>(
            Arrays.asList(new String[]{"A","B","C","D"})
                )
            );

//register before remove event
list.getOnBeforeRemoveEvent().add(new ActionListenerT_1x0<ActionEventBefore_1x0<String>>(){
    @Override
    public void actionPerformedImpl(ActionEventBefore_1x0<String> event) {
        System.out.println("remove element = " + event.getData());
        //event.setCanceled(true);
    }
});

ListIterator<String> it = list.listIterator();
while (it.hasNext()) {
    String elem = (String) it.next();
    if("C".equals(elem))
        it.remove();//remove "C"
}

EventMap

EventMap decorates fully the java.util.Map type. For example if the AfterRemove event is registered and the keyset of the map will be iterated and the iterator removes an key the map will be changed and the event be fired. The event-decorators decorate any aspects of any decorated types!

//decorate map with event-map
EventMap_1x0<String, Double> eventMap = EventMap_1x0.of(map);
//register after remove event
eventMap.getOnAfterRemoveEvent().add(new ActionListenerT_1x0<ActionEventAfter_1x0<String>>(){
    @Override
    public void actionPerformedImpl(
            ActionEventAfter_1x0<String> event) {
            //...
    }
});

//key set which is backed by the map, so changes to the map are reflected in the set, and vice-versa.
Iterator<String> it = eventMap.keySet().iterator();
//iterate over the set
while (it.hasNext()) {
    String key = (String) it.next();
    //...
    it.remove();//remove all keys, but not "B" and "D"
}

Event Collections examples


Related

Wiki: example-EventCollection (basic)