[collections][lang] submission: NotifyingCollections (observable) / o.a.c.l.event

[Neil O'Toole]

You go away on vacation for two weeks and it's all change around here.
I read with interest the thread on observable collections, an
implementation of which I have been working on for some time.  Attached
is a submission for a new package,
org.apache.commons.collections.notifying. This package
("NotifyingCollections") provides event-based notification as per the
"observable" thread of discussion. Please see the javadoc for
more information (in particular the package descriptions). A brief
overview of the functionality:

- Decorators for Collection, List, and Set (NotifyingCollection,
NotifyingList, NotifyingSet).

- Two types of notification: "post-modification" (or 'historical')
notification, and "pre-modification" (or 'vetoable') notification.
Pre-modification events can be vetoed before the actual modification
occurs (similar to the bean VetoableChangeListener).

- Pluggable events: NotifyingCollections uses a pluggable event
factory, thus removing dependence on any one event hierarchy. Hopefully
this will put to rest the arguements over whether a heavyweight or
lightweight event mechanism is best. The reality of the matter is that
each has its appropriate uses. A default event package is provided, in
the org.apache.commons.collections.notifying.detailed package. This
"detailed" event package is a quite heavyweight event system that
provides detailed information on modifications to the collection. This
includes being able to access the items added/removed to the
collection, and (for list events) being able to get the indices of said
items. 


In a supporting role:

- A new package org.apache.commons.lang.event. I suppose the proposed
package location is slightly problematic, as this introduces a
dependency on lang, which the consensus view seems to regard as akin to
catching the plague ;) So the package name is quite up for debate. This
package defines an inteface EventDispatcher and an implementation of
same, SynchronousEventDispatcher. These can be used quite independently
of NotifyingCollections, and I do think the correct location for these
is in lang. There is also an interface EventFilter, which is used to
transform or filter events.


There are a reasonable amount of tests included, and the classes all
pass the standard collections tests. I believe the classes are ready
for general use.

The best place to learn more is in the javadoc (though it needs more
work), but very brief useage is below. Your feedback please.

- Neil

** This submission is too big for the mail system, so it's been broken
up into three parts which will be emailed separately.

 src-org.apache.commons.collections.notifying
   - the main classes for NotifyingCollections and o.a.c.l.event

 src-org.apache.commons.collections.notifying.detailed
   - the "detailed" subpackage

 test-org.apache.commons.collections.notifying
   - test cases for both of the above


* Note: there are three utility methods in XCollectionUtils that need
to be moved to an appropriate location (probably
o.a.c.c.CollectionUtils).


Basic useage:
// ###################################################


// decorate a list
NotifyingList nl = NotifyingCollectionUtils.notifyingList( list );


CollectionListener listener = new CollectionListener()
{
        public void collectionEventOccurred(CollectionEvent event)
        {
                System.out.println( "CollectionEvent occurred: " + event.toString()
);
        }
};


nl.addCollectionListener( listener );

// make a modification, will cause an event to be fired
nl.add( "hello" );



// ###############################

// using the veto mechanism

NotifyingCollection nc = NotifyingCollectionUtils.notifyingCollection(
list );

nc.addVetoingCollectionListener(new VetoingCollectionListener()
{
        public void
vetoableCollectionModificationOccurring(ModifyingCollectionEvent event)
throws CollectionModificationVetoException
        {
                throw new CollectionModificationVetoException(this, event);
        }
});

try
{
        nc.add("veto me");
        fail("Should raise a veto exception.");
}
catch (CollectionModificationVetoException e)
{

}

assertTrue(nc.size() == 0);

src-org.apache.commons.collections.notifying.zip
Description: src-org.apache.commons.collections.notifying.zip

---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]