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

[Neil O'Toole <ne...@users.sourceforge.net>]

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);

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

[Stephen Colebourne <sc...@btopenworld.com>]

From: "Neil O'Toole" <ne...@users.sourceforge.net>
> - Decorators for Collection, List, and Set (NotifyingCollection,
> NotifyingList, NotifyingSet).
I would like our end solution to cover the Bag, SortedSet and SortedBag
interfaces too.

> - 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).
My first reaction was that this was covered by Predicated collections that
validate the object being added, but this gives more details.

> - Pluggable events: NotifyingCollections uses a pluggable event
> factory,
...
> 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.
We should supply a simple implementation too.

I think that this has the basis to be a good implementation. Some comments:
1) I dislike that a new instance of the event factory has to be created for
each collection. The factory should be capable of being shared. This can be
done by passing the init() parameters to each of the other methods.

2) The event dispatch sometimes assumes too much. For example the List
addAll() method validates the index as being in range, but the LazyList
implementation expects out of range indices. The modCount in the iterators
could face the same problem.

3) Similar to (2), the boolean result flag cannot be relied on to give
accurate results as to whether the collection has changed.

4) What if I want vetos to have no effect, rather than throw an exception.

5) It is quite hard to get info out about events. Typecasting is always
needed.

6) There are a lot of classes to get your head around - its very OO.

(2) - (5) give me pause to think about an alternative design... See separate
thread.

Stephen


---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org

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

[Neil O'Toole <ne...@users.sourceforge.net>]

--- Michael Heuer <he...@acm.org> wrote:
> On Wed, 4 Jun 2003, Neil O'Toole wrote:
> 
> > 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.
> >
> > <snip>
> 
> As far as I know, the observable collections stuff is still in
> design/discussion phase.

Well, this is a fairly complete (and completed) implementation, and I
believe it facilitates the major design issues discussed in the thread.


> Your submission introduces some new things
> that
> look interesting.

To make it a bit easier to see what's involved, i've posted the javadoc
online at:

 http://nettool.sourceforge.net/nc/api/index.html

In particular please see the package description for o.a.c.c.notifying

http://nettool.sourceforge.net/nc/api/org/apache/commons/collections/notifying/package-summary.html#package_description



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org

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

[Michael Heuer <he...@acm.org>]

On Wed, 4 Jun 2003, Neil O'Toole wrote:

> 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.
>
> <snip>

As far as I know, the observable collections stuff is still in
design/discussion phase.  Your submission introduces some new things that
look interesting.

Attached is an implementation of what was discussed on the list earlier.

   michael