Patrick Wright wrote:
The Javadocs are excellent and the
specification is actually helpful for solving real problems :).
Let's not get carried away.
The javadocs aren't the worst I've seen, but there's a real problem in
that the javadocs sometimes wax theoretic on what a method may or may
not do.
Take this gem from JavaSpace05.take(), for instance:
"an implementation may chose to take fewer entries from the space than
the maximum available or the maximum allowed by maxEntries."
Swell.
I know, you're thinking, that's just because it's the interface (even
though very wishy-washy even for that level); the reference
implementation holds the answers.
Nope, undocumented.
Well, then by the principle of least surprise, surely the "take" method
will simply do maxEntries (or at least Integer.MAX_VALUE, the upper
limit of the collection it returns). Why, this is even how the code reads.
Nope, swing and a miss. Thanks for playing. You should have looked
in the package documentation for com.sun.jini.outrigger. There you
would have learned that there's a server-imposed limit that governs what
the client could possibly return. And that limit defaults to 100 entries.
That said, I was able to find out what was going on through the mailing
list when some of the original implementors replied to explain what was
happening. So there is at least that fall-back when the documentation
lets you down.
James
