Navigable Set and Map improvements

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Navigable Set and Map improvements

Doug Lea
One of the good things about our putting out APIs and code
ourselves is that people get a chance to evaluate usages before they
are frozen into J2SE releases. While classes can usually evolve,
interfaces inside the java.* packages never can, so it's important
to get them right for the first time for major releases.

Various engineers at Google have been using over the past year our
jsr166x package versions of NavigableSet, NavigableMap,
ConcurrentNavigableMap, and the Tree and ConcurrentSkipList
implementations. And they started noticing things that they
wanted to do but weren't supported. So we are trying to get
some enhancements into Mustang while there is still a chance.
In particular:

1. Exposing descending iterators and keySets didn't allow
people to treat the descending version of a set or map
as itself a set or map. So, we add:
   NavigableMap.descendingMap();
   NavigableSet.descendingSet();
(Taking away the now-useless NavigableMap.descendingEntrySet).

2. The old Sorted{Set,Map} conventions about allowing only inclusive
lower bounds and only exclusive upper bounds were too inflexible,
so we allow you to specify all combinations of inclusion/exclusion,
as in:
   NavigableMap.subMap(K lo, boolean loInclusive, K hi, boolean hiIinclusive)

The main impact on those who have already been using these APIs
in Mustang betas is that anyone using descendingEntrySet will
need to replace with descendingMap().entrySet(). We don't feel that
it is a bad idea to kill this because anyone using it surely
wished they had a descendingMap anyway, and were working around its
absence.

You can find APIs and code in the usual places. Any comments
would be appreciated.

API specs:
   http://gee.cs.oswego.edu/dl/jsr166/dist/docs/
CVS sources:
   http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/src/main/java/util/

(Disclaimer: We aren't sure that these will actually make it into Mustang.)

-Doug

_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://altair.cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Navigable Set and Map improvements

Thomas Hawtin
Doug Lea wrote:
>
> 1. Exposing descending iterators and keySets didn't allow
> people to treat the descending version of a set or map
> as itself a set or map. So, we add:
>   NavigableMap.descendingMap();
>   NavigableSet.descendingSet();
> (Taking away the now-useless NavigableMap.descendingEntrySet).

Those method names indicate idempotency. It may return a map that,
considered on its own, is ascending. map.descendingMap() looks as if it
is just the same as map.descendingMap().descendingMap(). reversed,
asReverse or reverseOrder seem more obvious to me, and in keeping with
Collections and Arrays.

> 2. The old Sorted{Set,Map} conventions about allowing only inclusive
> lower bounds and only exclusive upper bounds were too inflexible,
> so we allow you to specify all combinations of inclusion/exclusion,
> as in:
>   NavigableMap.subMap(K lo, boolean loInclusive, K hi, boolean
> hiIinclusive)

I find boolean literals random sprinkled in method calls a tad opaque.
At least use enums. Preferably four methods (the best argument against
that seems to be that JavaDoc handling is very poor).


Having a quick look at the CVS, it looks as if sub-maps break
serialisation compatibility.


Also the API documentation (currently in mustang) for Map.Entry seems to
be out of date. It does not indicate the valid life time of entries
acquired by means other than entrySet.

Tom Hawtin
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://altair.cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Navigable Set and Map improvements

Doug Lea
Thomas Hawtin wrote:

> Doug Lea wrote:
>>
>> 1. Exposing descending iterators and keySets didn't allow
>> people to treat the descending version of a set or map
>> as itself a set or map. So, we add:
>>   NavigableMap.descendingMap();
>>   NavigableSet.descendingSet();
>> (Taking away the now-useless NavigableMap.descendingEntrySet).
>
> Those method names indicate idempotency. It may return a map that,
> considered on its own, is ascending. map.descendingMap() looks as if it
> is just the same as map.descendingMap().descendingMap(). reversed,
> asReverse or reverseOrder seem more obvious to me, and in keeping with
> Collections and Arrays.

Thanks! This a good thought; we hadn't considered that some
people might interpret "descending" as an absolute term.
We'll mull it over.

>
>> 2. The old Sorted{Set,Map} conventions about allowing only inclusive
>> lower bounds and only exclusive upper bounds were too inflexible,
>> so we allow you to specify all combinations of inclusion/exclusion,
>> as in:
>>   NavigableMap.subMap(K lo, boolean loInclusive, K hi, boolean
>> hiIinclusive)
>
> I find boolean literals random sprinkled in method calls a tad opaque.

We did discuss this. We think the ability to use boolean
expressions here is useful, rather than having to write, for example,
complement as:
  (d == NavigableMap.INCLUSIVE)? NavigableMap.EXCLUSIVE : NavigableMap.INCLUSIVE
instead of just
   !d
And inclusive==true seems pretty intuitive, at least considering
the audience for this kind of functionality.

> Having a quick look at the CVS, it looks as if sub-maps break
> serialisation compatibility.

Not as of a few checkins ago.

>
> Also the API documentation (currently in mustang) for Map.Entry seems to
> be out of date. It does not indicate the valid life time of entries
> acquired by means other than entrySet.
>

Thanks. I'll look into it.

-Doug


_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://altair.cs.oswego.edu/mailman/listinfo/concurrency-interest
Reply | Threaded
Open this post in threaded view
|

Re: Navigable Set and Map improvements

Thomas Hawtin
Doug Lea wrote:
>
> We did discuss this. We think the ability to use boolean
> expressions here is useful, rather than having to write, for example,
> complement as:
>  (d == NavigableMap.INCLUSIVE)? NavigableMap.EXCLUSIVE :
> NavigableMap.INCLUSIVE
> instead of just
>   !d

     d.invert()

I guess naming of the binary operations is tricky.

Tom Hawtin
_______________________________________________
Concurrency-interest mailing list
[hidden email]
http://altair.cs.oswego.edu/mailman/listinfo/concurrency-interest