MType vocabulary design principles

[Luigi Paioro]

Dear Mark and all,

   I'm a bit confused concerning the meaning of samp.app.status and 
samp.app.status.progress MTypes and I think this comes from a more 
general misunderstanding on my part.

Just a few definitions to let me understand better:

When we talk about an application in practice we mean a persistent 
stateful object registered to the SAMP Hub. An application can support a 
set of MTypes sent using call or notify hub methods. From another point 
of view we can see a _call_ with a certain MType (I'm not considering 
the notifications now) as a call to a specific method belonging to a 
specific interface and supported by the persistent object (very similar 
to what happens in DBus).

An example:

If I perform a call to an application MyApp sending the MType app.echo 
(it is supposed to be supported) it is exactly the same to perform a 
call to MyApp.echo() method of a generic class that implements:

   Interface                    Interface                        Class
  +---------+             +--------------------+               +-------+
  | Samp  O |<--inherits--|       App        O |<--implements--| MyApp |
  +---------+             +--------------------+               +-------+
                          | +echo(txt: string) |
                          +--------------------+

isn't it? At least this is more or less what I would do if I had to 
build up an SAMP application at design level. Then, in my mind, I figure 
out the MType chain of words (xxx.yyy.zzzz) as a sort of interface 
inheritance (in UML terms) that ends with the operation name. The 
additional benefit of the MType system is that it allows an application 
to choose to implement only certain operations (methods) of certain 
interfaces among those defined in this mailing list (instead in Java 
when a class implements an interface it must implement all its methods).

This is just to explain my point of view (that could be completely 
wrong... but that's it).

Said this, I understand samp.app.status MType as an operation that 
returns an information on the application status (the status of the 
stateful persistent object registered to the Hub).

Since we get a msg-id (in general) only when we use the call hub method, 
we can intend such msg-id as a call-id, and in practice they are 
synonymous (am I wrong?). Then, what we want to trace with the 
samp.app.status.progress actually is the call status progress, not the 
application status progress (which means nothing).

Then I would rather have (two possibilities):

MType:
   samp.app.msg.status.progress or samp.app.call.status.progress
Parameters:
   msgid (or callid): message ID (or callid) of a previously sent message
                      (or of a previously operation called) (REQUIRED)
   txt: textual indication of progress (REQUIRED)
   percent: numerical percentage indication of progress (OPTIONAL)
   timeLeft: estimated time to completion in seconds (OPTIONAL)
Return values:
   none
Description:
   Reports progress on a previously sent message (or operation called).


Does it makes sense?

Luigi



>    MType:
>       samp.app.status
>    Parameters:
>       txt: textual indication of status (REQUIRED)
>    Return values:
>       none
>    Description:
>       General purpose message to indicate application status.
> 
>    MType:
>       samp.app.status.progress
>    Parameters:
>       msgid: message ID of a previously sent message (REQUIRED)
>       txt: textual indication of progress (REQUIRED)
>       percent: numerical percentage indication of progress (OPTIONAL)
>       timeLeft: estimated time to completion in seconds (OPTIONAL)
>    Return values:
>       none
>    Description:
>       Reports progress on a previously sent message.
> 
> (though looking at this again, I'm more persuaded that these ought to
> have a ".event." in their names, since if we wanted an MType to mean
> "what is your status?" what would that be called?  However I don't insist
> on that since as long as the definitions are right I'm not too bothered
> about the names)
> 
> Mark