[cap-talk] Last Call for ref_send API 1.0

[David Wagner]

Tyler Close writes:
>> Record: The Javadoc calls this "A pass-by-construction object.", but
>> I think you mean "An allegedly pass-by-construction object."
>
>The above statements are correct, but they're also correct for all
>interfaces that are not the special org.joe_e.* verified interfaces.
>Do we want to adopt the "allegedly" convention when documenting all
>Joe-E interfaces?

Oh.  Good question.  I don't know.  Now that you mention it, of course
it has to be implicit that they can only be "alleged", given that they
are interfaces which anyone can implement.  Duh.  I don't know how I
missed that.  Is it worthwhile to remind people of this explicitly?
I don't know and I don't have any strong opinions.

>The detach() method is closely related to the List implementation you
>ask about further down. The detach() method provides a hook that the
>orthogonal persistence implementation picks up on. detach() returns a
>promise that defers deserialization of the target object until the
>cast() method of the promise is called. Applications use this method
>to break up a large object graph so that only the parts needed for the
>current operation get deserialized. For example, the List
>implementation stores each element in the list in a detach()'ed
>promise. As a result, you can pop() the first element of a list
>without loading the whole list into memory.

I think I get it.  Deserialization is eager by default but detach()
provides a boundary that is only crossed lazily (upon need).  To coin
a name, it is like some sort of "lazy reference", whose target is
loaded only lazily as needed.  Right?

>> I don't understand what ready() is doing, or what is meant by
>> "the underlying reference implementation".  What is a "reference
>> implementation"?  Does it mean some sample implementation that the
>> ref-send library provides?
>
>Yes. An eventual reference is just a Java proxy wrapped around one of
>the reference implementations documented in org.ref_send.promise. To
>register a when block on the reference, you need to peel off the Java
>proxy to get at the underlying reference implementation. The ready()
>method implements this peeling. The return is guaranteed to be
>anything. I named this method "ready" so that the line:
>
>    x = foo_.bar();
>    _.when(ready(x), new Do...
>
>would read as "when x is ready, do ...", meaning when the bar()
>invocation has been completed, do the following on its return value.
>I'll try to come up with better Javadoc for this method.

Ok.  Got it.

The phrase "reference implementation" could also be parsed as
"an implementation of a reference (e.g., a reference to an object)";
given that Promises are kinda like references, there may be a potential
for confusion here.

>You correctly guessed my intent. I left this potential confusion in
>there because either way of reading it is perfectly fine. If you think
>you can only pass in a org.ref_send.promise.Task, that's fine. I was
>thinking that the first definition you propose above could leave
>someone who doesn't understand generics at a loss for what kind of
>argument they are supposed to provide. The extends syntax is sort of
>an advanced feature of Java generics. The current definition at least
>suggests something that will work. It's only confusing to someone who
>knows a fair bit about Java generics, and they can likely cope, as you
>did.

I see.  It's a pun.  Ok.

I'm not sure whether this is too clever by half, or not half as
clever as it ought to be, so I guess it must be just fine. :-)

Thanks for the explanation.

>The name "Keeper" comes from either Dean or Norm I think. One of them
>created this pattern of having a central piece of code that gets first
>shot at handling errors. The name we use here is not so important
>since it's not something application writers will interact with. The
>interface only gets used by infrastructure code like the Waterken
>Server. I'll defer to Adrian for naming this interface.

I'll defer to Adrian, too.

>If you've got a pure Joe-E implementation of AES, I'll gladly use it
>and deprecate this API. Otherwise, I need this API to safely wrap the
>javax.crypto implementation.

Not laying around, but there are pure-Java implementations of AES,
and I'd expect they ought to be easy to make Joe-E compliant, but I'm
too lazy to do it myself.  I don't know how well they perform.  I don't
see any problem with having this interface.  I guess if I don't care
enough to spend the hour to download and build a pure Joe-E implementation,
obviously I must not care very much at all!

Thanks.