I have a small list of suggestions for javaspace/outrigger, largely
derived from my experience creating a wrapper for space functionality
and direct usage prior to the creation of that wrapper.
Many of these suggestions involve breaking backwards compatibility, so
many tears will be shed and perhaps we'll decide against implementing
any of these. But, I'm hoping this might lead to some discussion and
perhaps some improvements.
---
1) Generic methods.
First, use generics in the method signatures to minimize casting, in
this manner:
public <T extends Entry> T read(T template, Transaction txn, long timeout)
Seems broadly like a win, if use of Java 1.5 idioms is acceptable.
This is the only one I've mentioned before, and the reaction was fairly
positive on this list.
---
2) More collection-like naming of space methods, more consistency.
read, take, readIfExists, takeIfExists, write, snapshot, notify,
registerForAvailabilityEvent all have fine names. That is, they
properly describe the functionality and how the methods themselves
relate to one another.
I do, however, take issue with "contents", "take (with a collection)",
and "write (with a list)".
I would suggest the following renamings:
contents -> readAllExisting
take (with collection) -> takeAny
write (with list) -> writeAll
This would eliminate the awkward overloading of "take" and "write" while
bringing "contents" into a consistent naming plan.
The goal is a naming scheme which clearly communicates functionality:
"exists/existing" suffix = nonblocking call
"any" suffix = one or more templates will be satisfied, multi-return
"all" suffix = all templates will be satisfied, multi-return
If unmodified, standard blocking call.
The clearer naming also points to new functionality we could choose to
support, namely:
readAll - blocking call with all templates
readAny - blocking call on any template
takeAllExisting - nonblocking call with multiple templates.
takeAll - blocking call with all templates
Addendums:
1) I'll admit that "any" is the weakest part of the syntax, as it fails
to connote the multi-return. I was stretching to cover the current
"take (with collection)" semantics, which blocks until at least one
template match is available. Open to better suggestions.
2) Though generally I dislike overloading methods, there is one case I'm
sympathetic to: overloading "all" and "allExisting" methods to take in a
single template or multiple templates. This would save some calls to
Collections.singleton() for our users while maintaining a consistent
return type for the method.
---
3) Collections or remote iterators, not both.
"contents" returns a remote iterator named "MatchSet", while "take (with
collection)" returns a collection. I can understand the argument
behind both use cases, but not necessarily the argument for using both
simultaneously.
---
4) Exception soup.
Javaspace methods return a vast cornucopia of possible exceptions. I
would propose wrapping any Exceptions bubbling up to River users to be
wrapped in RiverException. Those few(?) who have special handlers to
deal with problem conditions can peek into the cause.
From my observation, most libraries are either taking this route (ala
JAXB) or wrapping everything in runtime exceptions (Spring, IIRC).
Presumably this suggestion could be applied to all of River, not just
JavaSpaces.
---
5) Clearer javadocs.
The current Javaspace docs are part protocol specification, part
implementation with some vital bits of information squirreled away in
obscure reaches.
For instance, in the 9 paragraphs describing the behavior of "take (with
collection)":
"If there is at least one matching Entry available in the space, an
invocation of this method must take at least one Entry. If more than one
matching Entry is available, the invocation may take additional entries.
It must not take more than maxEntries, but an implementation may chose
to take fewer entries from the space than the maximum available or the
maximum allowed by maxEntries."
The above is a broad protocol specification to implementers (even
allowing that the method may always return an empty list ;-) ).
Frustrating to users because the definition is so amorphous.
It also takes some doing to track down the fact that the implementation
does, in fact, limit the number of entries returned from a "take (with
collection)". That tidbit is stored within the outrigger *package*
documentation, which reveals the setting and default (only 100).
Aside: In prior discussion, I believe the reason for using that limit
was that the implementation creates an array of size Minimum(limit,
maxEntries)... and I think there's already a JIRA bug to switch from the
array to a collection. When we do, we should be a bit more generous
with the default (or remove the setting).
---
Anyway, hope this stirs some discussion.
I'll be on vacation the rest of the month, so unfortunately my
participation in said discussion will likely be spotty (though I'll try
to look in). I've been meaning to push out these recommendations for
some time, though, so I figured better now than waiting another month.
jamesG
