[ApacheDS] [Core] Using Cursors instead of NamingEnumerations

[Alex Karasulu <ak...@apache.org>]

Hi gang,

As many of you know already we're working on cleaning out JNDI from
the core of the server
in the bigbang branch.  In doing so we've come to the conclusion that
it's best that we remove
NamingEnumerations which cause a lot of glue code to result.

A few years ago, around 2002-3, we were using Cursors instead of
NamingEnumerations. The
concept was not properly implemented and was eventually replaced by
NamingEnumerations
to align more with JNDI.

Many of you probably have experienced working with a JDBC ResultSet
which is basically a
Cursor over a set of results which are fetched on demand (streamed
over the network or accessed
from underlying database data structures).  The Cursor construct we're
talking about is pretty
similar.  Cursors unlike Iterators require an advance (forward or
reverse) to a position to read the
data it contains.  Reads are not coupled with advances as they are
with Iterators and Enumerations.
This point is useful to us in many ways:

(1) Data need not be pre-fetched to instantiate a Cursor where it must
be to create an
     Iterator or an [Naming]Enumeration.  Fetching is handled
separately on Cursor.next()
     and Cursor.previous().  The read operation is a get().

(2) NamingEnumerations use a hierarchy of NamingExceptions where most
of the core
     operations are directly against disk data structures that emit
IOExceptions.  It's much
     more coherent to defer wrapping IOExceptions in NamingExceptions
until execution
     reaches the a JNDI wrapper.  This isolates the translation in one
place and makes things
     more efficient and clear.  The Cursor interface proposed will use
IOException as the root
     of any exception hierarchy that may result.

(3) NamingEnumerations are nasty in that they extend from Enumeration
and so have two
     copies of the same methods: ones that throw no exceptions from
the Enumeration super
     interface and ones that throw NamingExceptions.  This mixture can
result in unusual
     behavior for exception handling depending on whether the
NamingEnumeration methods
     are used or the Enumeration methods are used.  We don't need the ambiguity.

(4) Although not as important NamingEnumerations like many JNDI
interfaces do not support
     generics so the code looks less appealing.

So if NamingEnumeration does not fit, throws the wrong exceptions (or
none at all), makes us
have to do more work than we need to and looks ugly then it's worth
getting rid of it.  It's one
less JNDI interface we need to depend on.  We can express exactly what
we mean without
ambiguity using Cursors instead of adapting our code to work properly
with NamingEnumerations.

I have mocked up some interfaces and a simple implementation which
wraps a List as the
backing.  If no one has objections we may begin replacing
NamingEnumerations and Attributes
as early as next week.  Here's a link to the Cursor interface:

     http://aheey.notlong.com

Also folks might want to take a peek at what will eventually replace
the use of JNDI Attributes:

     http://piege.notlong.com

Looking forward to hearing what others think.

Thanks,
Alex