Callable clients mandatory operations

Thu Apr 1 10:14:12 PDT 2010

Luigi,

for this one, I don't agree.

I believe that the sender is in the best position to decide whether 
a reply is required from a message, not the recipient, and not the
MType designer.

Using call rather than notification serves (or has the potential to
serve) at least four distinct purposes:

   1. retrieve a return value, if the MType defines one (often it does not)
   2. determine whether the recipient has processed the message successfully
   3. receive details of an error if one has occurred
   4. delay further relevant processing until receipt has completed

In fact, in my experience it is quite common for MTypes to be used
by some senders in Call mode and by others in Notification mode,
often where a message looks like a notification (has no return value)
but to serve one of the other three purposes above.

Consider the MType table.load.votable.

A simple tool which simply generates a table might want to let 
other clients know that a table is available to load, but not 
really care whether they do so or not.

A more complex tool might want to send a table to a specific 
partner client, and need to know whether it completes so that 
for instance it can inform the user (with human-readable
error diagnostics) if failure has occurred, or so that it
can decide to send or not send subsequent table.highlight.row 
messages relating to it.

Even for a logging MType, one can imagine an application that
wants to use Call mode to determine whether completion is
successful, so that it can be aware whether the logging 
machinery has broken down, and perhaps notify a user or cease
operation if logging is considered a critical function.
I admit that this would not be a common case, but I think 
that the decision about whether it's appropriate is better 
taken by the message sender than by the MType designer.
Another example is that some middleware might want to
turn all notifications into calls in order to monitor response times 
(I'm considering adding this as an option into the JSAMP hub).

I admit it's hard to think of a realistic case (except testing)
in which something like client.env.get would be used in Notify mode,
but some response-bearing messages might also have side-effects.

As far as the burden on the implementor goes, I don't believe it's
significant enough to warrant the changes you suggest to the
existing one-size-fits-all situation.  The mapping between
receiveNotification and receiveCall is straightforward,
and is suitable for handling by library code.  For instance in
JSAMP the most straightforward way to implement handling for
a given MType is by subclassing a class
(http://software.astrogrid.org/doc/p/jsamp/1.0/apidocs/index.html)
and implementing the single method

   abstract Map processCall( HubConnection connection,
                             String senderId, Message message )

the library then invokes this same method in order to process
either a call or a notification; it just throws away the return
value in the latter case.  I think library code in other languages 
should be able to do something similar.

Mark

On Thu, 1 Apr 2010, Luigi Paioro wrote:

> Dear All,
> 
> with this e-mail I propose you a second change/improvement to the SAMP
> protocol, submitting it to your evaluation. In this case I start from a real
> use case:
> 
> I have a service application (named Logger) that receives logging messages
> from the other applications, and store them in a file or database.
> 
> Logger subscribes to logging.* messages in order to receive these MTypes:
> 
>   logging.critical
>   logging.error
>   logging.warning
>   logging.info
>   logging.debug
> 
> all accepting these parameters:
> 
>   origin: a string with the name of the program origin of the message
>   message: the logging message content
> 
> 
> Logger is a very simple application, being callable just to receive the
> logging messages notifications, and nothing more. Implementing it with SAMPy
> pythonic API I just wrote the single function used to handle the notification
> messages and bound it to the SAMP client instance. However, if I had to
> implement a client from scratch I would have to implement two functions, one
> mapping the receiveNotification operation and another (useless) mapping the
> receiveCall operation. This because the protocol specifies that either
> operations MUST be implemented.
> 
> On the other hand there is no way to distinguish a priori whether an MType is
> supposed to be used for events notification or a call, and in principle I
> might use, e.g., logging.info for a call. In my opinion this is an excess of
> freedom in the protocol considering that, in practice, the MTypes are always
> defined thinking to an event-MType or call-MType (at least this is my
> experience). I have never seen (so far) MTypes used for notifications and
> calls at the same time. And actually only those MType not returning a response
> parameter set can be reasonably used for notifications.
> 
> Thus:
> 
> - on one hand the protocol obliges the client implementors to support either
> calls and notifications, even if only one of them is really needed;
> - and on the other hand we have MTypes that are implicitly supposed to be use
> for calls only (or events only), but this is not clearly stated.
> 
> So this is my proposal in two points:
> 
> 1. add to the MType a Scope ("call" or "event"). This can be just an entry in
> the wiki page (and in SAMP document for the administrative MTypes), as for
> "Arguments", "Return Values", "Description". Optionally an additional
> "samp.scope" = "call" | "event" could be added to the SAMP messages (as for
> "samp.mtype" and "samp.params"); this could be useful for a preliminary check
> of the messages by the Hub.
> 
> 2. allow the clients to implement AT LEAST one of the two operations that a
> callable client MUST support, and not necessarily both.
> 
> 
> The two point here above should grant the backward compatibility of the
> protocol itself and of the software that already exists.
> 
> Thanks in advance for any comment or opinion.
> 
> Regards,
> 
>   Luigi
> 
> 
> -- 
> 
> Luigi Paioro
> 
> INAF - IASF Milano
> Via Bassini 15, I-20133 Milano, Italy
> 
> Phone  (+39) 02 23 699 470
> Fax    (+39) 02 26 660 17
> Site   http://cosmos.iasf-milano.inaf.it/luigi/

--
Mark Taylor   Astronomical Programmer   Physics, Bristol University, UK
m.b.taylor at bris.ac.uk +44-117-928-8776 http://www.star.bris.ac.uk/~mbt/