SAMP draft text
Mark Taylor
m.b.taylor at bristol.ac.uk
Wed Apr 30 03:20:04 PDT 2008
%
% LaTeX of current state of draft SAMP document 30 April 2008.
% PDF is attached to this message.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% For an conversion via cgiprint (HTX):
% See http://vizier.u-strasbg.fr/local/man/cgiprint.htx
\def\ifhtx{\iffalse} % Lines used only for the HTML version
\ifhtx
% . . .
% . . . Definitions in HTX context
% . . .
\else
\documentclass[12pt,notitlepage,onecolumn]{ivoa}
% . . .
% . . . Definitions in LaTeX context
% . . .
\fi
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Comment/uncomment lines below to follow your LateX distribution...
%%
%% If document is processed with latex, dvips and ps2pdf
%%
\ifx\pdftexversion\undefined
\usepackage[dvips]{graphicx}
\DeclareGraphicsExtensions{.eps,.ps}
%% Uncomment following line if you want PDF thumbnails
% \usepackage[ps2pdf]{thumbpdf}
% for old hyperref, use:
\usepackage[ps2pdf]{hyperref}
%% for recent hyperref, use:
% \usepackage[ps2pdf,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,%
% colorlinks,linkcolor=blue,urlcolor=blue]{hyperref}
%%
%% else if document is processed with pdflatex
%%
\else
\usepackage[pdftex]{graphicx} %% graphics for pdftex (supports .pdf .jpg .png)
\usepackage{epstopdf} %% requires epstopdf
%% this is to support .ps files :
\makeatletter
\g at addto@macro\Gin at extensions{,.ps}
\@namedef{Gin at rule@.ps}#1{{pdf}{.pdf}{`ps2pdf #1}}
\makeatother
%% comment above lines if you have included ps files
%\DeclareGraphicsExtensions{.pdf,.jpg,.png}
%% Uncomment following line if you want PDF thumbnails
% \usepackage[pdftex]{thumbpdf}
%% for old hyperref, use:
\usepackage[ps2pdf]{hyperref}
% for recent hyperref, use:
% \usepackage[pdftex,bookmarks=true,bookmarksnumbered=true,hypertexnames=false,breaklinks=true,%
% colorlinks,linkcolor=blue,urlcolor=blue]{hyperref}
\pdfadjustspacing=1
\fi
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% For drawing colored text backgrounds
\usepackage{color}
% Revision history
% ----------------
%
% 16 april 2008 : inclusion of Mike Fitzpatrick's section on MTypes (email Tue, 15 Apr 2008 16:13:51)
% 11 april 2008 : inclusion of Mark Taylor's comments (email Fri, 11 Apr 2008 12:17:46 +0100 (BST))
% 28 april 2008 : overhaul by Mark Taylor incorporating email discussions to date
% 29 april 2008 : additions and edits by Mike Fitzpatrick
%%
%% Header of the document...
%%
% Provide a title for your document
\title{SAMP, Simple Application Messaging Protocol}
% Give date and version number
\date{2008-04-30}
% Choose one document type from below
%\ivoatype{IVOA Note}
\ivoatype{IVOA Working Draft}
%\ivoatype{IVOA Proposed Recommendation}
%\ivoatype{IVOA Recommendation}
\version{1.00}
% Give author list: separate different authors with \\
% You can add email addresses with links \url{mailto:yourname at ivoa.net}
\author{T. Boch - boch at astro.u-strasbg.fr\\
M. Fitzpatrick - fitz at noao.edu\\
M. Taylor - m.b.taylor at bris.ac.uk\\
... \\}
\urlthisversion{\url{http://www.ivoa.net/...}}
\urllastversion{\url{http://www.ivoa.net/...}}
\previousversion{??}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\maketitle % print header in standard form
{\small
\begin{verbatim}
Draft version: $Revision: 1.17 $ $Date: 2008/04/30 10:17:48 $
\end{verbatim}
}
\begin{abstract}
SAMP is a messaging protocol that enables astronomy software tools to
interoperate and communicate.
IVOA members have recognised that building a monolithic tool that attempts to fulfil all
the requirements of all users is impractical, and it is a better use of our
limited resources to enable individual tools to work together better.
One element of this is defining common file formats for the exchange of data
between different applications. Another important component is a messaging
system that enables the applications to share data and take advantage of each
other's functionality. SAMP is intended to build on the success of a prior
messaging protocol, PLASTIC, which has been in use in
over a dozen astronomy applications for two years and has proven popular with
users and developers. SAMP is an IVOA-endorsed standard that builds on this
success. It is also intended to form a framework for more general messaging
requirements.
\end{abstract}
\tableofcontents
\section{Introduction}
\subsection{History}
SAMP is a direct descendent of the PLASTIC protocol, which in turn grew
\textemdash in the VOTech \cite{votech} framework \textemdash
from the interoperability work of the Aladin \cite{2000A&AS..143...33B} and
VisIVO \cite{2007HiA....14..622B} teams. We also note the
contribution of the team behind the earlier XPA protocol \cite{xpa}. For more information
on PLASTIC's history and purpose see the IVOA note {\em PLASTIC --- a protocol for
desktop application interoperability} \cite{plastic}.
SAMP has similar aims to PLASTIC, but
incorporates lessons learnt from two years of practical experience and ideas
from partners who were not involved in PLASTIC's initial design.
Broadly speaking, SAMP is an abstract framework for
loosely coupled asynchronous RPC-like and/or event-based communication
with extensible message semantics
using structured but weakly-typed data and based on a central service
providing multi-directional publish/subscribe message brokering.
These concepts are expanded on below.
It attempts to make as few assumptions as possible about the transport
layer or programming language with which it is used.
It also defines a ``Standard Profile'' which specifies how to
implement this framework using XML-RPC as the transport layer.
The result of combining this Standard Profile with the rest of the SAMP
standard is deliberately similar in design to PLASTIC, and the intention is
that existing PLASTIC applications can be modified to speak SAMP
instead without great effort.
\subsection{Requirements and Scope}
SAMP aims to be a simple and extensible protocol that is platform and language
neutral.
The emphasis is on a
simple protocol with a very shallow learning curve in order to encourage
as many application authors as possible to adopt it.
In other words SAMP is intended to do what you need most of the time. The SAMP authors
believe that this is the best way to foster innovation and collaboration in
astronomy applications.
It is important to note therefore that SAMP's scope is reasonably modest; it is
not intended to be the perfect messaging solution for all situations.
In particular SAMP itself has
no support for transactions, guaranteed message delivery, message integrity or
messaging beyond a single machine.
However, by layering the SAMP architecture on top of suitable
messaging infrastructures such capabilities could be provided.
These possibilities are not discussed further in this document,
but the intention is to provide an architecture which is sufficiently
open to allow for such things in the future with little change to the
basics.
\subsection{Types of Messaging}
\label{sect:typeOfMsging}
SAMP is currently limited to inter-application desktop messaging
with the idea that the basic framework presented here is extensible to meet
future needs, and so it is beyond the scope of this document to outline the
many types of messaging systems in use today (these are covered in detail
in many other documents). While based on established messaging models,
SAMP is in many ways a hybrid of several basic messaging concepts; the
protocol is however flexible enough that later versions should be able to
interact fairly easily with other messaging systems because of the shared
messaging models.
The messaging concepts used within SAMP include:
\begin{description}
\item[Publish/Subscribe Messaging:]
A publish/subscribe (pub/sub) messaging system supports an event driven
model where information consumers and producers participate in message
passing. SAMP applications ``publish'' a message, while consumer
applications ``subscribe'' to messages of interest and consume events.
Sending applications associate messages with a specific meaning, and
the underlying messaging system routes messages to consumers based on
the message types in which an applications has registered an interest.
\item[Point-to-Point Messaging:]
In point to point messaging systems, messages are routed to an
individual consumer which maintains a queue of ``incoming'' messages. In
a traditional message queue, applications send messages to a specified
queue and clients retrieve them. In SAMP, the message system manages
the delivery and routing of messages, but also permits the concept of a
directed message meant for delivery to a specific application. SAMP
does not, however, guarantee the order of message delivery as with a
traditional message queue.
\item[Event-based Messaging:]
Event-based systems are systems in which producers deliver events, and in
which messaging middleware delivers events to consumers based upon a
previously specified interest. One typical usage pattern of these systems
is the publish-subscribe paradigm, however these systems are also widely
used for integrating loosely coupled application components. SAMP allows
for the concept that an ``event'' occurred in the system and that these
message types may have requirements different from messages where the
sender is trying to invoke some action in the network of applications.
\item[Synchronous vs. Asynchronous Messaging:]
As the term is used in this document, a ``synchronous'' message is one
which blocks the sending application from further processing until a
reply is received. However, SAMP messaging is based on ``asynchronous''
message and response in that the delivery of a message and its
subsequent response are handled as separate activities by the
underlying system. With the exception of the synchronous message
pattern supported by the system, sending or replying to a message using
SAMP allows an application to return to other processing while the
details of the delivery are handled separately.
\end{description}
\subsection{About this document}
This document contains the following main sections describing the SAMP protocol
and how to use it.
Section \ref{sect:architecture}
covers the requirements, basic concepts and overall architecture of SAMP.
Section \ref{sect:apis} defines abstract (i.e.\ independent of language,
platform and transport protocol) interfaces which clients and hubs
must offer to participate in SAMP messaging, along with data types
and encoding rules required to use them, including an abstract API.
Section \ref{sect:profile}
explains how the abstract API can be mapped to specific network operations
to form an interoperable messaging system, and defines the ``Standard Profile'',
based on XML-RPC, which gives a particular set of such mappings.
Section \ref{sect:mtypes}
describes the use of the MType keys used to denote message semantics,
and outlines an MType vocabulary.
The key words ``MUST'', ``MUST NOT'', ``REQUIRED'', ``SHALL'', ``SHALL NOT'',
``SHOULD'', ``SHOULD NOT'', ``RECOMMENDED'', ``MAY'', and ``OPTIONAL''
in this document are to be interpreted as described in RFC 2119.
\section{Architectural Overview}
\label{sect:architecture}
This section provides a high level view of the SAMP protocol.
\subsection{Nomenclature}
In the text that follows these terms are used:
\begin{description}
\item[Client:]
An application that understands SAMP. Could be a
Sender, Recipient, or both.
\item[Hub:]
A broker service for routing SAMP Messages.
\item[Sender:]
A Client that can send SAMP Messages to
Recipients via the Hub.
\item[Recipient:]
A Client that can receive SAMP Messages from
the hub. These may have originated from other Clients or be from the
hub itself.
\item[Message:]
A communication sent from a Sender to a Recipient
via a SAMP Hub. May or may not provoke a Response.
\item[Response:]
A communication which may be returned from a Recipient to a Sender
in reply to a previous Message. A Response may be either a return value
or an error object. In the terminology of this document,
a Response is not itself a Message. A Response is also known as a
{\em reply} in this document.
\item[MType:]
A key defining the semantics of a Message and of its arguments and
return values (if any). Every Message contains exactly one MType,
and a Message is only delivered to Clients subscribed to that MType.
\item[Subscribed Client:]
A Client is said to be subscribed to a given MType if it has
declared to the Hub that it is prepared to receive Messages
with that MType.
\item[Callable Client:]
A Client to which the Hub is capable of performing callbacks.
Clients are not obliged to be Callable if they wish only to send
messages, and not to receive messages or asynchronous replies.
\item[Broadcast:]
To send a SAMP Message to all subscribed clients.
\item[Profile:]
A set of rules which map the abstract API defined by SAMP to a set of
network operations which may be used by Clients to send and receive
actual Messages.
\end{description}
\subsection{Messaging Topology}
SAMP has a hub-based architecture (see Figure~\ref{fig:samp-archi}). The hub is a single service used to route all
messages between clients. This makes application discovery more
straightforward in that each client only needs to locate the hub, and the services
provided by the hub are intended to simplify the actions of the client. A disadvantage of this
architecture is that the hub may be a message bottleneck and the hub may be the single point of failure.
However, it is not anticipated that message traffic will be such that the
former is an issue,
and the latter may be mitigated by an appropriate strategy for hub restart
if failure is likely.
\begin{figure}
\begin{center}
\includegraphics[scale=0.5]{samp-archi}
\caption{The SAMP hub architecture}
\label{fig:samp-archi}
\end{center}
\end{figure}
Note that the hub is defined as a service interface which may have any of
a number of implementations. It may be an independent application running as
a daemon, an adapter interface layered on top of an existing messaging
infrastructure, or a service provided by an application which is itself
one of the hub's clients. The only requirement is that exactly one hub
must be running (per user-id) at a time for messaging to take place.
\subsection{The Life cycle of a Client}
A SAMP client goes through the following phases:
\begin{enumerate}
\item Determine whether a hub is running by using the appropriate hub discovery
mechanism
\item If so, use hub discovery mechanism to work out how to communicate
with the hub.
\item Register with the hub.
\item Store metadata such as client name, description and icon in the
hub.
\item Subscribe to a list of MTypes to define messages which may be
received.
\item Interrogate the hub for metadata of other clients.
\item Send and/or receive messages to/from other clients via the hub.
\item Unregister with the hub.
\end{enumerate}
Phases 4--7 are all optional and may be repeated in any order.
\subsection{The Life cycle of a Hub}
A SAMP hub goes through the following phases:
\begin{enumerate}
\item Locate any existing hub by using the appropriate hub discovery mechanism.
\begin{enumerate}
\item Check whether the existing hub is alive.
\item If so, exit.
\end{enumerate}
\item If no hub is running, or a hub is found but is not
functioning, write/overwrite the hub discovery record and start up.
\item Await client registrations. When a client makes a legal
registration, assign it a public id,
and add the application to the table of registered
clients under the public id. Broadcast a message [ref to messages
section here] to all subscribed clients announcing the registration of a
new client.
\item When a client stores metadata in the hub, broadcast a message
[...] to all candidate clients and make the metadata available.
\item When a client updates its list of subscribed MTypes, broadcast a
message[...] to all subscribed clients.
\item When the hub receives a message for relaying, pass it on to
appropriate recipients which are subscribed to the message's MType.
Broadcast messages are sent to all
subscribed clients except the sender, messages with a specified recipient
are sent to that recipient if it is subscribed.
\item Await client unregistrations. When a client unregisters, broadcast
a message [...] to all subscribed clients announcing the unregistration
and remove the client from the table of registered clients.
\item If the hub is unable to communicate with a client, it may
unregister it as described in phase 7.
\item When the hub is about to shutdown, broadcast a message[...] to
all subscribed clients.
\item Delete the hub discovery record.
\end{enumerate}
Phases 3--8 are responses to events which may occur
multiple times and in any order.
Readers should note that, given this scheme, race conditions may occur. We could
have for instance a client trying to register with a hub which has just shut down,
or an attempt to send to a recipient which has already unregistered.
Specific profiles MAY define best-practice rules in order to manage at best these
conditions,
but in general clients should be aware that in the absence of guaranteed
message delivery and timing, unexpected conditions are possible.
\subsection{Sending and Receiving messages}
\label{sect:delivery-outline}
Messages can be sent according to three patterns:
\begin{enumerate}
\item Notification
\item Asynchronous Call/Response
\item Synchronous Call/Response
\end{enumerate}
The Notification pattern allows a sender to send messages to one or more
receivers without expecting a response. A typical use is for
broadcasting events when the receiver is not expected to generate any
data or perform any specific action as a result.
The Call/Response pattern allows a sender to receive responses back
from one or
more subscribed receivers in reply to a message, and also to find
out whether and when the receiver completed processing the message.
Under the hood, the pattern
is asynchronous, but the Hub provides a convenience method that simulates
synchronous calls. The purpose of this is to simplify the use of the protocol
in such situations as scripting environments which cannot easily handle
asynchronicity. However, it is recommended to use the asynchronous pattern
where possible due to its greater robustness.
\subsection{Use of Profiles}
\label{sect:profiles}
The design of SAMP is based on the abstract interfaces
defined in Section~\ref{sect:apis}. On its own however, this does
not include the detailed instructions required by application developers
to achieve interoperability. To achieve that, application developers
must know how to map the operations in the abstract SAMP interfaces
to specific I/O
(in most cases, network) operations. It is these I/O operations
which actually form the communication between applications.
The rules defining this mapping from interface to I/O operations
are what constitute a SAMP ``Profile''
(the term ``Implementation'' was considered for this purpose, but rejected
because it has too many overlapping meanings in this context).
There are two ways in which such a Profile can be specified as far as
client application developers are concerned:
\begin{enumerate}
\item By describing exactly what bytes are to be sent using what wire
protocols for each SAMP interface operation
\item By providing one or more language-specific libraries with calls
which equate to those of the SAMP interface
\end{enumerate}
Although either is possible, SAMP is well-suited for approach (1) above
given a suitable low-level transport library.
This is the case since the operations are quite low-level,
so client applications can easily
perform them without requiring an independently developed SAMP library.
This has the additional advantages that central effort does not have to
be expended in producing language-specific libraries, and that there
are no problems for application developers using ``unsupported'' languages.
Section~\ref{sect:profile} describes a Profile along the lines of (1) above,
based on XML-RPC,
which can be used directly by client and hub developers,
in conjunction with the abstract interface description
in Section~\ref{sect:apis} to write interoperable applications.
This is at present the only SAMP Profile which has been defined.
Although splitting the abstract interface and Profile descriptions
in this way complicates the document
a little, it separates the basic design principles from the details
of how to apply them, and it opens the door for other Profiles
serving other use cases in the future.
\section{Abstract APIs and Data Types}
\label{sect:apis}
\subsection{Hub Discovery Mechanism}
\label{sect:hub-discovery}
In order to keep track of which hub is running, a hub discovery mechanism, capable
of storing information about how to determine the existence of and communicate with
a running hub, is needed. This is a Profile-specific matter and
a specific prescription will be described in \ref{sect:lockfile}.
\subsection{Communicating with the hub}
The details of how a client communicates with the hub are Profile-specific
and will be covered in section \ref{sect:profile}.
\subsection{Registering with the hub}
A client registers with the hub to:
\begin{enumerate}
\item establish communication with the hub
\item advertise its presence to the hub and to other clients
\end{enumerate}
Immediately following registration, the client will typically
perform some or all of the following optional operations:
\begin{enumerate}\setcounter{enumi}{2}
\item supply the hub with metadata about itself, using the
{\tt setMetadata()} call
\item tell the hub how it wishes the hub to communicate with it,
if at all (the mechanism for this is profile-dependent, and it may
be implicit in registration)
\item inform the hub which MTypes it wishes to receive, using the
{\tt setMtypes()} call
\end{enumerate}
\subsection{SAMP Data Types}
\label{sect:samp-data-types}
For all hub/client communication, including the actual content of messages,
SAMP uses three conceptual data types:
\begin{enumerate}
\item {\tt string} --- a scalar value consisting of a sequence of characters;
each character may be in the range 0x01--0x7f
\item {\tt list} --- an ordered array of data items
\item {\tt map} --- an unordered associative array of string-data item
key-value pairs
\end{enumerate}
These types can in principle be nested to any level, so that the elements
of a list or the values of a map may themselves be strings, lists or maps.
There is no reserved representation for a null value, and it is
illegal to send a null value in a SAMP context even if the underlying
transport protocol permits this. However a zero-length
string or an empty list or map may where appropriate be used to mean null.
Although SAMP imposes no maximum on the length of a string,
particular transport protocols or implementation considerations
may effectively do so; in general hub and client implementations
are not expected to deal with data items of unlimited size.
General purpose MTypes should therefore be specified so that
bulk data is not sent within the message --- in general it is
preferred to define a message parameter as the URL (or filename)
of a potentially
large file rather than as the inline text of the file itself.
At the protocol level there is no provision for typing of scalars;
unlike many RPC protocols SAMP does not distinguish syntactically
between strings, integers, floating point values, booleans etc.
This minimizes the restrictions on what underlying transport
protocols may be used, and avoids a number of problems associated with
using typed values from untyped languages such as
Python and Perl.
Some MTypes will however wish to define parameters or return
values which have non-string semantics,
and conventions for encoding these as {\tt string}s
are therefore in practice required.
Such conventions only need to be understood by the sender and
recipient of a given message and so can be established on a per-MType basis,
but to avoid unnecessary duplication of effort some commonly-used
type encoding conventions are defined in the following section.
\subsection{Scalar type encoding conventions}
\label{sect:scalar-types}
The following BNF productions are used in the type encoding conventions
below:
\begin{verbatim}
<digit> ::= "0" | "1" | "2" | "3" | "4" | "5" | "6" |
"7" | "8" | "9"
<digits> ::= <digit> | <digits> <digit>
<decimal_digits> ::= <digits> | <digits> "." | "." <digits>
| <digits> "." <digits>
<sign> ::= "+" | "-"
\end{verbatim}
\begin{itemize}
\item \verb,<SAMP int> ::= [ <sign> ] <digits>,\\
An integer value is encoded using its decimal representation with
an optional preceding sign and with no
leading, trailing or embedded whitespace.
There is no guarantee about the largest or smallest values which can
be represented, since this will depend on the processing environment
at decode time.
%
\item \verb,<SAMP float> ::= [ <sign> ] <decimal_digits>,\\
\verb, [ "e" | "E" [ <sign> ] <digits> ],\\
A floating point value is encoded as a mantissa with an optional
preceding sign followed by an optional exponent part
introduced with the character ``{\tt e}'' or ''{\tt E}''.
There is no guarantee about the largest or smallest values which can
be represented or about the number of digits of precision which are
significant, since these will depend on the processing environment
at decode time.
%
\item \verb,<SAMP boolean> ::= "0" | "1",\\
A boolean value is represented as an integer: zero represents false,
and any other value represents true.
1 is the recommended value to represent true.
\end{itemize}
The numeric types are based on the syntax of the C programming language,
since this syntax forms the basis for typed data syntax in many other
languages.
This list may be extended in the future if required.
Particular MType definitions may use these conventions or devise
their own as required. Where the conventions in this list are used,
message documentation should make it clear using a form of
words along the lines ``this parameter contains a {\em SAMP int\/}''.
\subsection{Application Metadata}
\label{sect:app-metadata}
A client may store metadata in the form of a {\tt map} of key-value pairs in the hub
for retrieval by other clients. Typical metadata will be the human-readable
name of the application, a description and a URL to its icon, but other values
are permitted. The following keys are defined for well-known metadata items:
\begin{description}
\item[{\tt samp.name}] - A one word title for the application.
\item[{\tt samp.description.text}] - A short description of the
application, in plain text.
\item[{\tt samp.description.html}] - A description of the application,
in HTML.
\item[{\tt samp.icon.url}] - The URL of an icon in png, gif or jpeg format.
\item[{\tt samp.documentation.url}] - The URL of a documentation web page.
\end{description}
All of the above are OPTIONAL, but {\tt samp.name} is strongly RECOMMENDED.
\\
\textcolor{magenta}{[?? should others be RECOMMENDED ??]}
\\
Applications may store metadata under any keys, except that keys beginning
`{\tt samp.}'' may only be used as described here.
\subsection{What is a message?}
\label{sect:msgdef}
A message is an abstract container for the information we wish to send
to another application. The message itself is that data which should
arrive at the receiving application. It may be transmitted along
with some external items (e.g.\ sender/recipient/message identifiers)
required to ensure proper delivery or handling.
A message contains at least the following parts:
\begin{description}
\item[An MType:] a string which defines the meaning of the message,
for instance the instruction to load a table.
It also, via external documentation, defines the names, types and
meanings of any parameters as well as the type and meaning of the
return value. MTypes are discussed in more detail in
Section~\ref{sect:mtypes}.
\item[Parameters:] zero or more named values giving the data required
for the receiver to act on the message, for instance the URL of a
particular table. The names and semantics of these parameters are
determined by the MType.
\end{description}
It may also contain other items, for instance a timestamp, but such items
are not currently described by this standard.
\textcolor{magenta}{[?? ref-id ??]}
% \item \verb|ref-id| - An ID assigned by an application that can be used
% to reference some specific data object known only to the receiving
% application (e.g.\ a table subset created by an earlier message).
% The \verb|ref-id| MAY be an attribute of a Response message if the
% application can accept subsequent Request messages requiring a
% specific reference to be unambiguous. When supplied in a Request
% message, the message is assumed to apply only to the object
% referenced by the \verb|ref-id| (e.g.\ plot the columns of the table
% subset and not the parent table).
%
% \textcolor{magenta}{[???? This was somewhat controversial in earlier
% discussions and admittedly part of the generalized messaging concept.
% It may not be used in PLASTIC-like applications, but I would like
% to keep it in the initial spec for later use. ]}
It is legal to include parameters in the parameter object which are
not documented by the MType. Any parameters whose name a receiver
does not recognise in the context of the given MType should be ignored.
The intention is that MTypes can evolve by having new parameters added
which provide additional functionality if the need is identified during
use. Although in some cases such refinement will require a redesign
with completely different parameters (and a new MType),
it is often the case that
MTypes can be improved by adding new optional parameters which can
be harmlessly ignored by clients only familiar with the older version.
Some common MTypes and their parameter objects are described in section
\ref{sect:mtypes}.
\subsection{Message and Response Encoding}
\label{sect:msg-encoding}
A message as described in Section~\ref{sect:msgdef}
may be encoded in the terms of the datatypes described in
Section~\ref{sect:samp-data-types} as a {\tt map}.
The defined keys and their associated values are as follows:
\begin{description}
\item[{\tt mtype}]
The value is a {\tt string} giving the MType for the message.
\item[{\tt params}]
The value is a {\tt map} giving the parameter values for the message.
Each parameter is represented by a key-value pair in which the
key is the documented name of the parameter, and the value is
its value, with the type as documented by the MType.
\end{description}
No other keys are currently defined.
Keys which are not defined here are not illegal,
but if an application encounters keys which it does not understand,
it should generally ignore them.
The response to a message, if one is expected, is a {\tt map} and
may be one of two things:
\begin{enumerate}
\item a return value (successful completion)
\item an error object (failure)
\end{enumerate}
A flag is passed with the response object to indicate which of these it is;
clients do not have to examine the object to find out whether it represents
a return value or an error.
In the case of a return value, the type and meaning of any data contained
in it as key-value pairs SHOULD be documented by the MType.
In the case of an error response, the map may contain
entries with the following keys:
\begin{description}
\item[{\tt errortxt}] (REQUIRED) ---
A short string describing what went wrong.
This will typically be delivered to the user of the sender application.
\item[{\tt usertxt}] (OPTIONAL) ---
A free-form string containing any additional text an application wishes
to return. This may be a more verbose error description meant to be
appended to the errortxt string, however it is undefined how this string
should be handled when received.
\item[{\tt debugtxt}] (OPTIONAL) ---
A longer string which may contain more detail on what went wrong.
This is typically intended for debugging purposes, and may for instance
be a stack trace.
\item[{\tt code}] (OPTIONAL) ---
A string containing a numeric or textual code identifying the error.
\end{description}
No other keys are currently defined.
Keys which are not defined here are not illegal,
but if an application encounters keys which it does not understand,
it should generally ignore them.
\textcolor{magenta}{[?? should these keys be {\tt samp.mtype} etc, with
{\tt samp.*} a reserved part of the namespace and others available for
public use ??]}
\subsection{Sending and Receiving Messages}
\label{sect:delivery}
As outlined in Section~\ref{sect:delivery-outline},
three messaging patterns are supported, differing
according to whether and how the response is returned to the sender.
For a given MType
there may be a messaging pattern that is most typically used, but there is
nothing in the protocol that ties a particular MType to a particular messaging
pattern.
>From the point of view of the sender, there are three ways in which a message
may be sent,
and from the point of view of the recipient there are two ways in which
one may be received. These are described as follows.
\begin{description}
\item[Notification:] In the notification pattern, communication is only
in one direction:
\begin{enumerate}
\item The sender sends a message to the hub for delivery to one or more
recipients.
\item The hub forwards them to those requested recipients which are subscribed
\item No reply from the recipients is expected or possible
\end{enumerate}
Notifications can be sent to a given recipient or broadcast to all
recipients. The notification pattern for a single recipient is illustrated in
Figure~\ref{fig:notification}.
\begin{figure}[!h]
\begin{center}
\includegraphics[scale=0.5]{samp-notification}
\caption{Notification pattern}
\label{fig:notification}
\end{center}
\end{figure}
%
\item[Asynchronous Call/Response:]
In the asynchronous call pattern, {\em message IDs} are used
to tie together messages and their replies:
\begin{enumerate}
\item The sender sends a message to the hub for delivery to one or more
recipients, supplying along with the message an ID string,
{\em sender-msg-id}.
\item The hub forwards the message to the appropriate recipients,
supplying along with the message an ID string, {\em hub-msg-id}.
\item Each recipient processes the message, and sends its response
back to the hub along with the ID string {\em hub-msg-id}.
\item Using a callback, the hub passes the response back to the
original sender along with the ID string {\em sender-msg-id}.
\end{enumerate}
The sender is free to use any value for the {\em sender-msg-id}.
There is no requirement on the form of the {\em hub-msg-id\/}
(it is not intended to be parsed by the recipient), but it must be
sufficient for the hub to pair messages with their responses reliably,
and to pass the correct {\em sender-msg-id\/} back with the response
to the sender\footnote{
This can be achieved by the hub generating a new unique {\em hub-msg-id\/}
for each asynchronous call, and keeping an internal record of which
{\em sender-msg-id\/} the {\em hub-msg-id\/} corresponds to until the
replies are all received.
More cunningly, the hub can generate its {\em hub-msg-id\/} by combining
the {\em sender-msg-id\/} with a newly generated unique string in
such a way that the {\em sender-msg-id\/} can be recovered when the
response is received, thus obviating the need to retain perhaps long-lived
message state internally.
The sender may be able to use similar tricks in generating
{\em sender-msg-id\/} to avoid storing per-message
state until the response arrives.
}.
Asynchronous calls may be sent to a given recipient or broadcast to all
recipients. In the latter case, the sender should be prepared to deal
with multiple responses to the same call.
The asynchronous pattern is illustrated in Figure~\ref{fig:async}.
\begin{figure}[!h]
\begin{center}
\includegraphics[scale=0.45]{samp-asynchronous}
\caption{Asynchronous pattern}
\label{fig:async}
\end{center}
\end{figure}
%
\item[Synchronous Call/Response]
A synchronous utility method is provided by the hub, mainly for script
environments where dealing with asynchronicity might be a problem.
The hub will provide synchronous behaviour to the sender,
interacting with the receiver in exactly the same way as for the
asynchronous case above.
\begin{enumerate}
\item The sender sends a message to the hub for delivery to a given recipient.
This call blocks until the response is available.
\item The hub forwards the message to the recipient,
supplying along with the message an ID string, {\em hub-msg-id}.
\item The recipient processes the message, and sends its response
back to the hub along with the ID string {\em hub-msg-id}.
\item The hub sends the response as the return value from the original
blocking call made by the sender.
\end{enumerate}
There is no broadcast counterpart for the synchronous call.
This pattern is illustrated in Figure~\ref{fig:sync}.
\begin{figure}[!h]
\begin{center}
\includegraphics[scale=0.45]{samp-synchronous}
\caption{Synchronous pattern}
\label{fig:sync}
\end{center}
\end{figure}
%
\end{description}
\subsection{Operations a hub must support}
\label{sect:hubOps}
This section describes the operations that a hub must support and the associated
data that must be sent and received.
Message and response arguments are encoded as {\tt map} objects as
described in Section~\ref{sect:msg-encoding}.
The precise details of how these operations
map onto method names and signatures is Profile-dependent.
The mapping for the Standard Profile is given in section \ref{sect:mappingXMLRPC}.
\begin{itemize}
\item \verb|register()|\\
Method called by a client wishing to register
with the hub.
Note that the form of this call may vary according to the requirements
of the particular Profile in use. For instance authentication tokens
may be passed in one or both directions to complete registration.
\\
\item \verb|unregister()|\\
Method called by a client wishing to unregister from the hub
\\
\item \verb|setMetadata(map metadata)|\\
Method called
by a client to declare its metadata (name, icon, description, etc --- see
section~\ref{sect:app-metadata} for details).
May be called zero or more times to update hub state; the most recent
call is the one which defines the client's currently declared metadata.
\\
\item \verb|map metadata = getMetadata(string client-id)|\\
Returns the metadata
information for the client whose public id is {\tt client-id}.
\\
\item \verb|setMTypes(list mtypes)|\\
Method called by
a callable client to declare the MTypes it wishes to subscribe to.
May be called zero or more times to update hub state; the most recent
call is the one which defines the client's currently subscribed MTypes.
\\ \textcolor{magenta}{[?? possibly wildcarding allowed here ??]}
\\
\item \verb|list mtypes = getMTypes(string client-id)|\\
Returns the array of
subscribed MTypes for the client whose public id is {\tt client-id}.
\\
\item \verb|list client-ids = getRegisteredClients()|\\
Returns the list of public ids of other registered clients.
The caller's id is not included.
\\
\item \verb|list client-ids = getSubscribedClients(string mtype)|\\
Returns the list of public ids of all other registered clients who are
subscribed to the MType {\tt mtype}.
The caller's id is not included, even if it is subscribed.
\\
\item \verb|string client-id = getHubId()|\\
Returns the client-id which
identifies the hub itself as a client. This is the id which the hub
uses for instance to send administration messages to other candidate
clients.
\\
\item \verb|notify(string recipient-id, map message)|\\
Method called
by a client wishing to send a notification to a given recipient.
\\
\item \verb|notifyAll(map message)|\\
Method called by a client
wishing to broadcast a notification to all recipients.
\\
\item \verb|call(string recipient-id, map message, string msg-id)|\\
Method called by a callable client wishing to send an asynchronous call to
a given recipient.
\\
\item \verb|callAll(map message, string msg-id)|\\
Method called by a callable client wishing to broadcast an asynchronous
call to all recipients.
\\
\item \verb|map response = callAndWait(string recipient-id, map message)|\\
Method
called by a client wishing to make a synchronous call to a given
recipient.
\\
\item \verb|reply(string msg-id, string success, map response)|\\
Method
called by a client to send its response to a given message.
{\tt success} is a SAMP boolean (``{\tt 1}'' for successful completion
or ``{\tt 0}'' for an error). In the case of success, {\tt response} is the
return value as documented for the MType of the message.
In the case of failure, {\tt response} is an error object as
described in \ref{sect:msg-encoding}.
\end{itemize}
All these operations with the exception of {\tt callAndWait()} should complete, and where
appropriate return a result, quickly.
\subsection{Operations a hub may call on a client}
\label{sect:clientOps}
We list in this section the operations which may be called on a callable client.
Note that not all clients may be callable; special (Profile-dependent) steps
may be required for a client to inform the hub how it may be contacted,
and thus become callable. Clients which are not callable are unable to
receive messages or use the asynchronous call/response pattern.
Message and response arguments are encoded as {\tt map} objects as
described in Section~\ref{sect:msg-encoding}.
The precise details of how these operations
map onto method names and signatures is Profile-dependent.
The mapping for the Standard Profile is given in section \ref{sect:mappingXMLRPC}.
\begin{itemize}
\item \verb|receiveNotification(string sender-id, map message)|\\
Method called by the hub when dispatching a notification to its
recipient.
\\
\item \verb|receiveCall(string sender-id, string msg-id, map message)|\\
Method called by the hub when dispatching a call to its recipient. The client
MUST at some later time make a matching call to {\tt reply()} on the hub.
\\
\item \verb|receiveResponse(string responder-id, string msg-id,|\\
\verb| string success, map response)|\\
Method used by the hub to dispatch to the sender the response of an
earlier asynchronous call.
{\tt success} is a SAMP boolean (``{\tt 1}'' for successful completion
or ``{\tt 0}'' for an error). In the case of success, {\tt response} is the
result value as documented for the MType of the original message.
In the case of failure, {\tt response} is an error object as
described in \ref{sect:msg-encoding}.
\end{itemize}
All these operations should complete quickly.
\subsection{General error processing}
\label{sect:faults}
Hubs and clients should use the usual error reporting mechanisms
of the transport protocol in use in the case of bad calls of
the operations defined in Sections \ref{sect:hubOps} and \ref{sect:clientOps},
for instance
use of syntactically invalid parameter types.
Errors produced by clients when processing call-type SAMP messages
themselves (in response to a syntactically legal {\tt receiveCall()}
operation) should be signalled in the way the matching {\tt reply()}
call is made. In case of an error, the {\tt success} flag should be
set to ``{\tt 0}'' and the {\tt response} object should be filled in
with error information as described in Section~\ref{sect:msg-encoding}.
%% Mark Taylor's part %%
\section{Standard Profile}
\label{sect:profile}
Section \ref{sect:architecture} defines the concepts and operations
used in SAMP messaging. As explained in Section~\ref{sect:profiles},
in order to implement this architecture some concrete choices about
how to instantiate these concepts are required.
This section gives the details of a SAMP Profile based on the
XML-RPC specification \cite{xmlrpc}.
Hub discovery is via a lockfile in the user's home directory.
XML-RPC is a simple general purpose Remote Procedure Call
protocol based on sending XML documents over HTTP
(it resembles a very lightweight version of SOAP).
Since the mappings from SAMP concepts
such as API calls and data types to their XML-RPC equivalents is very
straightforward, it is easy for application authors to write
compliant code without use of any SAMP-specific library code.
An XML-RPC library, while not essential, will make coding much easier;
such libraries are available for many languages.
\subsection{Data Type Mappings}
The SAMP argument and return value data types described in
Section \ref{sect:samp-data-types} map straightforwardly onto XML-RPC
data types as follows:
\begin{center}
\begin{tabular}{lcl}
SAMP type & & XML-RPC element \\
\hline
{\tt string} & $\longleftrightarrow$ & {\tt <string>} \\
{\tt list} & $\longleftrightarrow$ & {\tt <array>} \\
{\tt map} & $\longleftrightarrow$ & {\tt <struct>} \\
\end{tabular}
\end{center}
The {\tt <value>} children of {\tt <array>} and {\tt <struct>} elements
themselves contain children of type {\tt <string>}, {\tt <array>} or
{\tt <struct>}.
\subsection{API Mappings}
\label{sect:mappingXMLRPC}
The operation names in the SAMP hub and client abstract APIs
(Sections \ref{sect:hubOps} and \ref{sect:clientOps}) very nearly
have a one to one mapping with those in the Standard Profile XML-RPC APIs.
The differences are as follows:
\begin{enumerate}
\item The XML-RPC method names (i.e.\ the contents of the XML-RPC
{\tt <methodName>} elements) are formed by
prefixing the hub and client abstract API operation names with
``{\tt samp.hub.}'' or ``{\tt samp.client.}'' respectively.
\item The {\tt register()} operation takes the {\tt samp.secret} value
read from the lockfile (see Section~\ref{sect:lockfile})
as an argument, and returns a
new {\tt private-key} string generated by the hub.
\item {\em All\/} other hub and client methods take the
{\tt private-key} as their first argument.
\item A new method, {\tt setXmlrpcCallback()} is added to the hub API.
This informs the hub of the XML-RPC endpoint on which the client
is listening for calls from the hub.
The client is not considered Callable intil it has invoked this method.
\item Another new method, {\tt isAlive()} is added to the hub API.
This may be called by registered or unregistered applications
(as a special case the {\tt private-key} argument may be omitted),
and can be used to determine whether the hub is responding to requests.
Any non-error return indicates that the hub is running.
\end{enumerate}
The {\tt private-key} string referred to above serves two purposes.
First it identifies the client in hub/client communications.
Some such identifier is required, since XML-RPC calls have no other way of
identifying the sender's identity.
Second, it prevents application spoofing, since the private key is
never revealed to other applications, so that one application cannot
pose as another in making calls to the hub.
The usual XML-RPC fault mechanism is used to respond to invalid
calls as described in \ref{sect:faults}.
The XML-RPC fault's {\tt <faultString>} element should contain a
user-directed message as appropriate and the {\tt <faultCode>} value
has no particular significance.
\subsection{Lockfile and Hub Discovery}
\label{sect:lockfile}
Hub discovery is performed by examining a lockfile in a well-known location.
This has the consequence that in normal operation each user may run
only one hub, and users do not share hubs. The name of the lockfile
is ``{\tt .samp}'' in the user's home directory.
On Unix-like systems this directory can be retrieved from the
{\tt \$HOME} environment variable.\\
\textcolor{red}{TODO : decide something for Windows OS...}
% [?? Windows - what to do? For a java viewpoint on this see
% http://bugs.sun.com/bugdatabase/view\_bug.do?bug\_id=4787931.]
The format of the file is given by the following BNF productions:
\begin{verbatim}
<file> ::= <lines>
<lines> ::= <line> | <lines> <line>
<line> ::= <line-content> <EOL> | <EOL>
<line-content> ::= <comment> | <assignment>
<comment> ::= "#" <any-string>
<assignment> ::= <name> "=" <any-string>
<name> ::= <token-string>
<token-string> ::= <token-char> | <token-string> <token-char>
<any-string> ::= <any-char> | <any-string> <any-char>
<EOL> ::= "\r" | "\n" | "\r" "\n"
<token-char> ::= [a-zA-Z0-9-_.]
<any-char> ::= [\x20-\x7f]
\end{verbatim}
\textcolor{magenta}{[?? are regular expressions OK in BNF? is there some
other reasonably compact way of expressing this??]}
The only parts which are significant to SAMP clients/hubs are
(a) existence of the file and (b) {\tt <assignment>} lines.
A legal lockfile must provide (in any order) unique assignments for the
following tokens:
\begin{itemize}
\item {\tt samp.secret}
An opaque text string which must be passed to the hub to permit
registration.
\item {\tt samp.hub.xmlrpc.url}
The XML-RPC endpoint for communication with the hub.
\item {\tt samp.profile.version}
The version of the SAMP Standard Profile implemented by the hub
(``1.0'' for the version described by this document).
\end{itemize}
it may optionally include other blank, comment or assignment lines,
but tokens beginning ``{\tt samp.}'' may only be assigned as described here.
The lockfile should normally be created with permissions which allow
only its owner to read it. This provides a measure of security in
that only processes with the same permissions as the hub process
(hence presumably running under the same user ID) will be able to
register with the hub, since only they will be able to provide the
{\tt samp.secret} required for registration. Thus under normal
circumstances all participants in a SAMP conversation can be
presumed owned by the same user, and therefore not malicious.\footnote{
Of course they may be owned by the same user and still be malicious,
but in this case SAMP represents no additional security risk.
}
An example lockfile might therefore look like this:
\begin{verbatim}
# SAMP lockfile written 2008-29-02T17:45:01
# Required keys:
samp.secret=734144fdaab8400a1ec2
samp.hub.xmlrpc.url=http://andromeda.star.bris.ac.uk:8001/xmlrpc
samp.profile.version=1.0
# Info stored by hub for some private reason:
com.yoyodyne.hubid=c80995f1
\end{verbatim}
The existence of the file MAY be taken (e.g.\ by a hub deciding whether
to start or not) to indicate that a hub is running.
However it is RECOMMENDED to attempt to contact the hub
at the given XML-RPC URL (e.g.\ by calling {\tt isAlive()})
to determine whether it is actually alive.
The hub discovery sequences are therefore as follows:
\begin{itemize}
\item Client startup:
\begin{itemize}
\item Determine hub existence as above
\item If no hub, client MAY start its own hub
\item Acquire {\tt samp.secret} value from lockfile
\item If pre-existing or own hub is running, call {\tt register()} and
zero or more of {\tt setXmlrpcCallback()}, {\tt setMetadata()},
{\tt setMTypes()}
\end{itemize}
\item Hub startup:
\begin{itemize}
\item Determine hub existence as above
\item If hub is running, exit
\item Otherwise, start up XML-RPC server
\item Write lockfile with mandatory assignments including XML-RPC endpoint
\end{itemize}
\item Hub shutdown:
\begin{itemize}
\item Notify candidate clients that shutdown will occur
\item Remove lockfile (it is RECOMMENDED to first check that this
is the lockfile written by self)
\item Shut down services
\end{itemize}
\end{itemize}
Hub implementations SHOULD make their best effort to perform the
shutdown sequence above even if they terminate as a result of some
error condition.
Note that manipulation of a file is not atomic, so that race conditions
are possible. For instance a client or hub examining the lockfile
may read it after it has been created but before it has been populated
with the mandatory assignments, or two hubs may look for a lockfile
simultaneously, not find one, and both decide that they should
therefore start up, one presumably overwriting the other's lockfile.
Hub and client implementations should be aware of such possibilities,
but may not be able to guarantee to avoid them or their consequences.
In general this is the sort of risk that SAMP and its
Standard Profile are prepared to take --- an eventuality which will occur
sufficiently infrequently that it is not worth significant
additional complexity to avoid.
In the worst case a SAMP session may fail in some way, and will have
to be restarted.
\subsection{Examples}
Here is an example in pseudo-code of how an application might locate and
register with a hub, and send a message requiring no response to other
registered clients.
\begin{verbatim}
# Read information from lockfile to locate and register with hub.
string hub-url = readFromLockfile("samp.hub.xmlprc.url");
string samp-secret = readFromLockfile("samp.secret");
# Establish XML-RPC connection with hub (uses some generic XML-RPC library)
xmlrpcServer hub = xmlrpcConnect(hub-url);
# Register with hub.
string private-key = hub.xmlrpcCall("samp.hub.register", samp-secret);
# Store metadata in hub for use by other applications.
map metadata = ("samp.name" -> "dummy",
"samp.description" -> "Test Application",
"dummy.version" -> "0.1-3");
hub.xmlrpcCall("samp.hub.setMetadata", private-key, metadata);
# Send a message requesting file load to all other registered clients,
# not wanting any response.
map loadParams = ("filename" -> "/tmp/foo.bar");
map loadMsg = ("mtype" -> "file.load",
"params" -> loadParams");
hub.xmlrpcCall("samp.hub.notifyAll", private-key, loadMsg);
# Unregister
hub.xmlrpcCall("samp.hub.unregister", private-key);
\end{verbatim}
The first few XML-RPC documents sent over the wire for this exchange
would look something like the following.
The registration call from the client to the hub:
\begin{verbatim}
POST /xmlrpc HTTP/1.0
User-Agent: Java/1.5.0_10
Content-Type: text/xml
Content-Length: 189
<?xml version="1.0"?>
<methodCall>
<methodName>samp.hub.register</methodName>
<params>
<param><value><string>734144fdaab8400a1ec2</string></value></param>
</params>
</methodCall>
\end{verbatim}
which leads to the response:
\begin{verbatim}
HTTP/1.1 200 OK
Connection: close
Content-Type: text/xml
Content-Length: 148
<?xml version="1.0"?>
<methodResponse>
<params>
<param><value><string>app-id:1a52fdf-2</string></value></param>
</params>
</methodResponse>
\end{verbatim}
The client might then declare its metadata:
the response to this call has no useful content so can be ignored or discarded.
\begin{verbatim}
POST /xmlrpc HTTP/1.0
User-Agent: Java/1.5.0_10
Content-Type: text/xml
Content-Length: 596
<?xml version="1.0"?>
<methodCall>
<methodName>samp.hub.setMetadata</methodName>
<params>
<param><value><string>app-id:1a52fdf-2</string></value></param>
<param><value><struct>
<member>
<name>samp.name</name>
<value><string>dummy</string></value>
</member>
<member>
<name>samp.description</name>
<value><string>Test application</string></value>
</member>
<member>
<name>dummy.version</name>
<value><string>0.1-3</string></value>
</member>
</struct></value></param>
</params>
</methodCall>
\end{verbatim}
Calls from the hub to the client are along similar lines.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{MTypes: Message Semantics and Vocabulary}
\label{sect:mtypes}
As stated earlier, a message contains an {\em mtype} string that
defines the semantic meaning of the message, for example a request for
another application to load a table. It also has other attributes and
optional parameters to form the complete message that we will outline
below. These messages also play a number of roles in a messaging system,
although not every message is appropriate for every role. Below we will
discuss the types of messages used in SAMP and see how specific {\em
mtypes} are used.
In this section we will also discuss the form and required elements
of a message, and the types of messages needed by many common desktop
applications. This discussion is by no means complete; within the rules
of how messages are defined here and the delivery mechanisms described,
developers are free to create message types and usage patterns not detailed
here. New messages affecting the messaging system itself (e.g.\ those used
in communications with the Hub or those needed to ensure interoperability
such as a return status code) should be formalized for wider use later
using a (TBD) procedure outlined below. Application message types, e.g.
those that expose some functionality of a particular application, are
entirely open-ended and require no formal process to be adopted by
developers.
\subsection{The MType of a Message}
\label{sect:mtypeMsg}
A key concept of a message is the {\em Mtype} attribute that
defines the semantic meaning of the message. The concept behind the Mtype
is similar to that of a UCD in that a small vocabulary is sufficient to
describe the expected range of concepts required by a messaging system
within the current scope of the SAMP protocol. As noted earlier,
developers are free to introduce new MTypes for use within applications
without restriction; new MTypes intended to be used for Hub messaging or
other administrative purposes within the messaging system should be discussed
within the IVOA for approval as part of the SAMP standard. The details and
policy for adopting new standard MTypes are TBD.
\subsubsection{The Form of an Mtype}
Like a UCD, an Mtype is made up of {\em atoms}.
These are not only meaningful to the developer, but form the central
concept of the message. Because we wish to loosely couple the capabilities
one application is searching for from the details of what another may
provide, we don't create a rigorous definition of the {\em behavior} that
an MType must provoke in a receiver. Instead, the Mtype defines a specific
semantic message such as ``display an image'', it is up to the receiving
application to determine how it chooses to do the display (e.g.\ a rendered
greyscale image within an application or displaying the image in a web
browser might both be valid for the recipient and faithful to the meaning
of the message).
The ordering of the words in an Mtype should normally use the
object of the message followed by the action to be performed (or the
information about that object). For example, the use of ``image.display''
is preferred to ``display.image'' in order to keep the number of toplevel
words (and thus message classes) like `image' small, but still allow for a
wide variety of messages to be created that can perform many useful actions
on an image. If no existing MType exists for the required purpose,
developers can agree to the use of a new Mtype such as
`image.display.extnum' if e.g.\ the ability to display a specific image
extension number warrants a new Mtype.
The syntax of an MType is given by the following BNF:
\begin{verbatim}
<mchar> ::= [0-9a-z] | "-" | "_"
<atom> ::= <mchar> | <atom> <mchar>
<period> ::= "."
<mtype> ::= <atom> | <atom> <period> <atom>
\end{verbatim}
\subsubsection{The Description of an MType}
In order that senders and recipients can agree on what is meant by
a given message, the meaning of an MType must be clearly documented.
This means that for a given MType the following information must be
available:
\begin{itemize}
\item The MType string itself.
\item A list of zero or more parameters. For each one:
\begin{itemize}
\item name
\item data type ({\tt map}, {\tt list} or {\tt string}
as described in \ref{sect:samp-data-types}) and if appropriate
scalar sub-type (see \ref{sect:scalar-types})
\item meaning
\item whether it is REQUIRED or OPTIONAL
\item OPTIONAL parameters MAY specify what default will be used
if the value is not supplied
\end{itemize}
\item A list of zero or more returned values. For each one:
\begin{itemize}
\item name
\item data type ({\tt map}, {\tt list} or {\tt string}
as described in \ref{sect:samp-data-types}) and if appropriate
scalar sub-type (see \ref{sect:scalar-types})
\item meaning
\item whether it is REQUIRED or OPTIONAL
\item OPTIONAL return values MAY specify what default is intended
if the value is not supplied
\end{itemize}
\item A description of the meaning of the message.
This should convey the semantic meaning of the message, e.g.\ that
an event of some type has occurred, or that a specific request is
is being made.
\end{itemize}
This is just the same information as one ought to supply for
documentation of public interface method in a weakly-typed programming
language.
Note that it is possible for the MType to have no returned values.
This is actually quite common if the MType does not represent a
request for data. It is not usually necessary to define a status-type
return value (success or failure), since a sender which is interested
in whether the message processing was successful can wait to see whether
the response from the message is an error or not (the client
{\tt receiveResponse()} method has a {\tt success} flag set).
So return values only need to be defined if there is data to return.
If there is not, the response object will be a {\tt map} with no entries.
As explained in Section~\ref{sect:msgdef}, parameters and returned values
which are not described in the MType may be passed as well as those
which are. Clients which do not recognise these should usually ignore them.
\subsection{Mtype Vocabulary}
In the description below the {\em mtype} attribute of the message
is constructed from the toplevel and secondary words. Any arguments
required by the message MUST be encoded in the message {\em params}
attribute. The Mtypes presented here are intended to be suggestions that
we hope will be adopted by developers; concepts and Mtypes not shown here
may also be used and may appear in later versions of this document if
they become widely accepted.
% define command for describing an MType.
% arguments are:
% qualified name,
% parameter list,
% description,
% example use
\newcommand{\mtypedef}[4]{
\begin{description}
\item[{\tt #1}:]\mbox\\
\begin{description}
\item[Arguments:]\mbox\protect\\ #2
\item[Description:]\mbox\protect\\ #3
\item[Example Use:]\mbox\protect\\ #4
\end{description}
\end{description}
}
% define command for describing an MType argument.
% arguments are:
% name,
% type,
% short description
\newcommand{\mtypearg}[3]{
{\tt #2 #1} --- #3
}
\newcommand{\mtypenoargs}{
{\em none}
}
\begin{verbatim}
mtype args returns meaning
----- ---- ------- -------
\end{verbatim}
\subsubsection{Application Messages}
These message types have the toplevel word ``{\tt app}''.
They are intended to convey some change in the state of a sending application.
\begin{verbatim}
app
event
register id app has registered
unregister id app has unregistered
starting id app starts processing
stopping id app stops processing
mtype mtypes app declares new mtype
id
metadata meta app declares new metadata
id
status(??)
ok app executing normally
error app encountered error
???
\end{verbatim}
\subsubsection{Set/Get Messages}
These message types have the toplevel word ``{\tt set}'' or `{\tt get}''.
They are intended to provide a general mechanism for setting/getting
values from a remote application beyond the scope of what is available
using either the Client or the Hub.
\begin{verbatim}
set
mtype mtype set list of mtypes
metadata meta set list of metadata
param param set parameter to value
value
get
mtype mtypes get list of supported mtypes
metadata param value get metadata item from client
param param value
\end{verbatim}
\subsubsection{Status Messages}
These message types have the toplevel word ``{\tt status}''.
They are intended to convey information about the state of an application,
or its response to a Request message.
\begin{verbatim}
status
ok message processed normally
invalid message invalid (badly formed)
unknown message unknown (bad mtype)
delivery stat_str delivery status
progress
percent percent percentage completed (float)
timeLeft time est. time remaining (sec)
error err_str error message
\end{verbatim}
\subsubsection{File Messages}
These message types have the toplevel word ``{\tt file}''.
They are intended to perform some action on a file regardless of format.
\begin{verbatim}
file
event
load filename the 'filename' was loaded
save filename the 'filename' was saved
load filename load this file 'filename'
save filename save to 'filename'
\end{verbatim}
\subsubsection{Image Messages}
These messages have the toplevel word ``{\tt image}''.
They are intended to invoke operations on image data objects.
\begin{verbatim}
image
event
load imname the 'imname' was loaded
save imname the 'imname' was saved
load imname load image 'imname'
save imname save image to 'imname'
display imname display image in 'imname'
panTo x, y pan display (arb coords)
pixel x, y pan display to pixel coords
sky ra, dec pan display to sky coords
zoom level zoom to given level (+/-N level)
highlight
pixel x, y highlight point at pixel coords
sky ra, dec highlight point at sky coords
\end{verbatim}
\subsubsection{Query Messages}
These message types have the toplevel word ``{\tt query}''.
They are intended to perform some action on
a query object. Queries will typically be ADQL, but
no specification is made about the format of a query.
\begin{verbatim}
query
exec
adql adql_str result execute the ADQL query
sql sql_str result execute the SQL query
expr expr_str result evaluate the expression
\end{verbatim}
\subsubsection{Spectrum Messages}
These message types have the toplevel word ``{\tt spectrum}''.
They are intended to invoke operations on spectrum data objects.
\begin{verbatim}
spectrum
event
load specname the 'tblname' was loaded
table spectable the given table was loaded
image specimage the given image was loaded
save specname the 'tblname' was saved
table spectable table was saved to fname
fname
image specimage image saved to imname
imname
load specname load table 'tblname'
table spectable table was loaded
image specimage image was loaded
save specname spectrum saved to 'specname'
table spectable table saved to 'fname'
fname
image specimage image saved to 'imname'
imname
\end{verbatim}
\subsubsection{Table Messages}
These message types have the toplevel word ``{\tt table}''.
They are intended to invoke operations on table (any format) data objects.
\begin{verbatim}
table
event
load tblname the 'tblname' was loaded
save tblname the 'tblname' was saved
load tblname load table 'tblname'
save tblname save table to 'tblname'
highlight
row row highlight specified row
col col highlight specified column
cell row, col highlight cell at position
select
row row select (subset) named row
col col select (subset) named column
rowList rows select (subset) named rows
colList cols select (subset) named columns
\end{verbatim}
\subsubsection{URL Messages}
These message types have the toplevel word ``{\tt url}''.
They are intended to perform some action on a URL.
\begin{verbatim}
url
event
load url 'url' was loaded
save url 'url' was saved to 'filename'
filename
load url load url at 'url'
save url save 'url' to 'filename'
filename
\end{verbatim}
\subsubsection{Coordinate Messages}
These message types have the toplevel word ``{\tt coord}''.
They are intended to provide a general
method for using coordinates. Specific behavior
depends on the application.
\begin{verbatim}
\end{verbatim}
\newpage
\appendix
% Annexe 1 : differences with PLASTIC protocol (no more Java-RMI dependency,
% hub can be written in any language, separation between registration and
% metadata declaration)
\section{Changes from PLASTIC document}
In order to facilitate the transition from PLASTIC to SAMP protocol from
applications' developers point of view, we summarize in this appendix the main
changes - arranged in order of decreased importance - between the two
documents, ie the main updates from PLASTIC to SAMP.
\begin{enumerate}
\item \verb|Transport choice| - The main drawback of PLASTIC was the
Java dependency for hub writers. In SAMP, Java RMI as transport mechanism
has been dropped, which allows hubs to be written in virtually any language.\\
\item \verb|Refactoring of registration API| - Registration, declaration
of metadata, and declaration of understood messages are clearly separated
steps in SAMP, whereas they were mixed in PLASTIC.\\
\item \verb|Application identity|
\end{enumerate}
\textcolor{red}{TODO : complete this list. Not so easy to sort the importance of
changes !!!}
% Annexe 2 : discuss how we can make SAMP-compatible and PLASTIC-compatible
% applications talk together
\section{SAMP/PLASTIC interoperability}
This section will detail how interoperability between SAMP-compatible and
PLASTIC-compatible clients can be achieved, using hubs able to translate PLASTIC
messages into SAMP Mtypes.
%%%%%%%% Bibliography %%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% include all references
\nocite{*}
% unsorted style for bibliography (?)
\bibliographystyle{unsrt}
% bibliography file is called samp-bibliography[.bib]
\bibliography{samp-bibliography}
\end{document}
% $Id: samp.tex,v 1.17 2008/04/30 10:17:48 mbt Exp mbt $
-------------- next part --------------
A non-text attachment was scrubbed...
Name: samp.pdf
Type: application/pdf
Size: 282750 bytes
Desc: PDF of SAMP draft
URL: <http://ivoa.cacr.caltech.edu/pipermail/apps-samp/attachments/20080430/00e33c28/attachment-0001.pdf>
More information about the apps-samp
mailing list