SAMP â Simple Application Messag- ing Protocol Version 1.11 - IVOA

More documents

Recommendations

Info

The concept behind the MType is similar to that of a UCD [9] in that a smallvocabulary is sufficient to describe the expected range of concepts required bya messaging system within the current scope of the SAMP protocol. Developersare free to introduce new MTypes for use within applications withoutrestriction; new MTypes intended to be used for Hub messaging or otheradministrative purposes within the messaging system should be discussedwithin the IVOA for approval as part of the SAMP standard.5.1 The Form of an MTypeMType syntax is formally defined in Section 3.7. Like a UCD, an MType ismade up of atoms. These are not only meaningful to the developer, but formthe central concept of the message. Because the capabilities one applicationis searching for are loosely coupled with the details of what another mayprovide, there is not a rigorous definition of the behavior that an MTypemust provoke in a receiver. Instead, the MType defines a specific semanticmessage such as “display an image”, and it is up to the receiving applicationto determine how it chooses to do the display (e.g. a rendered greyscale imagewithin an application or displaying the image in a web browser might bothbe valid for the recipient and faithful to the meaning of the message).The ordering of the words in an MType SHOULD normally use the objectof the message followed by the action to be performed (or the informationabout that object). For example, the use of “image.display” is preferredto “display.image” in order to keep the number of top-level words (andthus message classes) like ‘image’ small, but still allow for a wide variety ofmessages to be created that can perform many useful actions on an image.If no existing MType exists for the required purpose, developers can agreeto the use of a new MType such as “image.display.extnum” if, e.g., theability to display a specific image extension number warrants a new MType.5.2 The Description of an MTypeIn order that senders and recipients can agree on what is meant by a givenmessage, the meaning of an MType must be clearly documented. This meansthat for a given MType the following information must be available:1. The MType string itself2. A list of zero or more named parameters3. A list of zero or more named returned values4. A description of the meaning of the message32
For each of the named parameters, and each of the returned values, thefollowing information must be provided:• name• data type (map, list or string as described in Section 3.3) and ifappropriate scalar sub-type (see Section 3.4)• meaning• whether it is OPTIONAL (considered REQUIRED unless stated otherwise)• OPTIONAL parameters MAY specify what default will be used if thevalue is not suppliedTogether, this is much the same information as should be given for documentationof a public interface method in a weakly-typed programming language.The parameters and return values associated with each MType form extensiblevocabularies as explained in Section 2.6, except that there is noreserved “samp.” namespace.Note that it is possible for the MType to have no returned values. This isactually quite common if the MType does not represent a request for data. Itis not usually necessary to define a status-like return value (success or failure),since this information can be conveyed as the value of the samp.status entryin the call response as described in Section 3.9.5.3 MType Vocabulary: Extensibility and ProcessThe set of MTypes forms an extensible vocabulary along the lines of Section2.6. The relatively small set of MTypes in the “samp.” namespace isdefined in Section 5.4 of this document, but applications will need to usea wider range of MTypes to exchange useful information. Although clientsare formally permitted to define and use any MTypes outside of the reserved“samp.” namespace, for effective interoperability there must be public agreementbetween application authors on this unreserved vocabulary and its semantics.Since addition of new MTypes is expected to be ongoing, MTypes fromthis broader vocabulary will be documented outside of this document toavoid the administrative overhead and delay associated with the IVOA RecommendationTrack [8]. At time of writing, the procedures for maintainingthe list of publicly-agreed MTypes are quite informal. These proceduresremain under review, however the current list and details of best practicefor adding to it are, and will remain, available in some form from the URLhttp://www.ivoa.net/samp/.33
Page 5 and 6: not discussed further in this docum
Page 7 and 8: Recipient: A Client that receives a
Page 9 and 10: 3. Await client registrations. When
Page 11 and 12: consumers if appropriate. As far as
Page 13 and 14: Although SAMP imposes no maximum on
Page 15 and 16: SAMP operation, but they are there
Page 17 and 18: These keys form the basis of an ext
Page 19 and 20: Figure 2: Notification pattern2. Th
Page 21 and 22: protection from this eventuality; u
Page 23 and 24: Sends a message using the Synchrono
Page 25 and 26: 4.1 Data Type MappingsThe SAMP argu
Page 27 and 28: ::= [a-zA-Z0-9] | "-" | "_" | "." :
Page 29 and 30: string hub-url = readFromLockfile("
Page 31: dummy.version0.1-3The message itsel
Page 35 and 36: samp.hub.event.metadata:Arguments:i
Page 37 and 38: Return Values:noneDescription:Repor
Page 39 and 40: offers benefits such as meaning tha
Page 41: [6] http://plastic.sourceforge.net/

SAMP â Simple Application Messag- ing Protocol Version 1.11 - IVOA

Create successful ePaper yourself

Delete template?

Save as template?

SAMP â Simple Application Messag- ing Protocol Version 1.11 - IVOA