Package org.ref_send Description

A pass-by-construction interface.

The ref_send API supports the design of interfaces that work well in a
distributed application. One of the differences between a local application
and a distributed application is the importance of pass-by-copy data. In a
local application, the difference between accessing a variable versus calling
a method may be negligible. In a distributed application, the difference may
be significant since an additional network request may be required for the
method invocation. This network request negatively impacts performance since
an additional network round-trip is required. More importantly though, the
additional network request complicates the client code since it must now cope
with the timing issues and failure modes that come with doing a network
request. Client code is often much simpler when all the data it needs can be
provided as one bundle. To support creating such data bundles, this package
defines an API for declaring a pass-by-construction class. When an object of
such a class is sent in a method invocation, or return, its publicly
accessible state is sent, instead of a remote reference. Similarly, such an
object can be reconstructed when its state is received as part of a method
invocation.

A class can be made pass-by-construction simply by declaring it to be so
and annotating one of its public constructors with information mapping the
class' public fields to its constructor parameters. For example:

The networking code in the Waterken Server automatically recognizes which
invocation arguments are Record objects and produces the
corresponding JSON data for them. You can create an arbitrarily large JSON
document by constructing an arbitrarily deep tree of
Record objects. For example, the class below adds an
address and array of tags:

The value of the "class" member is an array listing the
name of every type implemented by the object, ordered from most specific to
least. If the most specific type of an object is implied by the referring
object, the type declaration is omitted. For example, the object referred
to by the "mailto" member is not annotated with a
"class" member, since the type
org.example.membership.Address is implied by the referring
object's type "org.example.membership.MailingLoyaltyCard".

By making effective use of Record objects, you can
create distributed applications in the document-oriented messaging style. In
such applications, clients and servers coordinate primarily based on the
content of exchanged documents, rather than on expectations about remotely
maintained state. Such designs can sometimes result in fewer dependencies
between clients and servers and so facilitate the creation of interoperable
software. When using the ref_send API, you define the structure of your
exchanged documents by defining a set of Record types.
Each exchanged document is then created by composing an object tree from
these Record types.