Message API

Introduction

API Version 0.1.0

A Message is a way of communication between the server and a client. The main purpose is to inform the clients about errors which occured during transactions, issue warnings when entities have a certain state or just explicitly confirm that a transaction was successful. Messages represents information that is not persistent or just the reproducible outcome of a transaction. Messages are not stored aside from logging.

Message Classes And Their Properties

Message (generic super class)

A Message must be either a Server Message or a Client Message.

A Message must have a description. A description is a string and a human-readable explanation of the meaning and/or purpose of the message. The description must not have leading or trailing whitespaces. The description should be kept in English. For the time being there is no mechanism to indicate that the description is written in other languages. This could be changed in later versions of this API.

Server Message

A Server Message is a Message issued by the server. It must not be issued by clients.

A Server Message may be either a Standard Server Message or a Non-Standard Server Message

Standard Server Message

A Standard Server Message is one of a set of predefined messages with a certain meaning. The set of these Standard Server Messages is maintained and documented in the Java code of the server. There should be a server resource for these definitions in order to have a always up-to-date documentation of the messages on every server.

A Standard Server Message must have an id. An id is a non-empty string that uniquely identifies a standard server message. An id should consist only of ASCII compliant upper-case Latin alphabetic letters from A to Z and the underscore character _. An id of a Standard Server Message must not start with the string NSSM_.

A Standard Server Message must have a type. A type is one these strings: Info, Warning, Error, or Success.

Error Message

A Server Message with type Error is also called Error Message and sometimes just Error. An Error Message indicates that a request has failed. It informs about the reasons for that failure or the nature of the problems which occurred. The description of each error message should explain the error and indicate if and how the client can remedy the problems with her request.

Warning Message

A Server Message with type Error is also called Warning Message and sometime just Warning. A Warning Message indicates that certain irregularities occurred during the processing of the request or that the client requested something that is not recommended but not strictly forbidden.

Info Message

A Server Message with type Info is also called Info Message and sometimes just Info. An Info Message is a means to inform the client about arbitrary events which occurred during the processing of the request and which are not to be considered erroneous or non-recommended. These info messages are primarily intended to make the processing of the request more understandable for the client. Info messages are not meant to be used for debugging.

Success Message

A Server Message with type Success is also called a Success Message. A Success Message indicates the successful state change due to portions of a request or the whole request. A success message must not be issued if the request fails.

Non-Standard Server Message

A Non-Standard Server Message may be issued by any non-standard server plugin or extension. It is a placeholder for extensions to the Message API.

A Non-Standard Server Message may have an id. An id is a non-empty string. It should consist only of ASCII compliant upper-case Latin alphabetic letters from A to Z and the underscore character _. However, the id should not be equal to any id from the set of predefined standard server messages. Furthermore, the id of a non-standard server message should start with the string NSSM_.

A Non-Standard Server Message may have a type. A type is a non-empty string. It should consist only of ASCII compliant upper-case or lower-case Latin alphabetic letters from a to z, from A to Z, and the underscore character _. If the type is equal to one of the above-mentioned types, it must have the same meaning and the same effects on the request as the respective type from above. Especially, a message with type Error must not be issued unless the request actually fails. Likewise a Success must not be issued unless the request actually caused a state change of the server.

Client Message

A Client Message may have an ignore flag. The ignore flag can have one of these values: no, yes, warn, silent

A Client Message is a message issued by a client. It should not be issued by the server. A Client Message may be completely ignored by clients. A client message must not be ignored by the server. A Client Message which cannot be understood by the server must result in an error, unless the ignore flag states otherwise.

Ignore Flag

If the ignore flag is set to no the server must not ignore the client message. If the server cannot understand the client message an error must be issued. This will cause the transaction to fail.

If the ignore flag is set to yes the server must ignore the client message.

If the ignore flag is set to warn the server should not ignore the message. If the server cannot understand the client message, a warning must be issued. The transaction will not fail due to this warning.

Message Parameters

A Message may have zero or more parameters. A Message Parameter is a a triple of a key, a value. It is intended to facilitate the processing and representation of messages by clients and the server. For example, consider an Error Message which states that a certain server state cannot be reached and the reason be that there is an entity with certain features. Then it is useful to refer to the entity via the parameters. A client can now resolve the entity and just show it or generate a URI for this entity.

A key is a non-empty string which should consist only of ASCII compliant lower-case Latin alphabetic letters from a to z and the minus character -. A key must be unique among the keys of the message parameters.

A value is a possibly empty, arbitrary string which must not have leading or trailing white spaces.

A Message Parameter may have a type. The type of a Message Parameter is also called a Message Parameter Type. A Message Parameter Type is a non-empty string which should consist only of ASCII compliant lower-case Latin alphabetic letters from a to z and the minus character -. A message parameter type may be one these string: entity-id, entity-name, entity-cuid, property-index, parent-id, parent-name.

A Message Parameter with a type which begins with entity- is also called an Entity Message Parameter. The value of an Entity Message Parameter must refer to an entity—via its id, name, or cuid, respectively.

A Message Parameter with a type which begins with property- is also called a Property Message Parameter. The value of such a parameter must refer to an entity’s property. In the case of the property-index type the value refers to a property via a zero-based index (among the list of properties of that entity). The list of properties in question must belong to the Message Bearer which must in turn be an Entity.

A Message Parameter with a type which begins with parent- is also called a Parent Message Parameter. The value of such a parameter must refer to an entity’s parent via its id or name, respectively.

Message Bearer

A Message must have a single Message Bearer, or, equivalently, a Message belongs to a single Message Bearer. The message is usually considered to carry information about the message bearer if not stated otherwise. The message’s subject should be the message bearer itself, so to speak. Although, possibly indicated by a Message Parameter the message may be additionally or solely concerned with other things than the message bearer. Please note: The message bearer may also indicate the context of evaluation of the message parameters, e.g. when the type of the message parameter is property-index.

A Message Bearer may be an Entity, a Property, a Container, a Request, a Response, or a Transaction.

Representation and Serialization

Messages can be serialized, deserialized by the means of XML.

XML Representation

A Message is serialized into a single XML Element Node (hereafter the root element with zero or more Child Nodes.

Root Element Tag

The root element’s tag of a Server Message must be equal to its type if and only if the type is equal to one of the allowed types of a Standard Server Message (even if it is a Non-Standard Server Message). Otherwise the root tag is just ‘ServerMessage’.

<Error/><!--an Error Message-->
<Warning/><!--a Warning Message-->
<Info/><!--an Info Message-->
<Success/><!--a Success Message-->
<ServerMessage/> <!--a Non-Standard Server Message with a non-standard type-->

The root element’s tag of a Client Message must be ‘ClientMessage’. E.g.

<ClientMessage/><!--a Client Message-->

Root Element Attributes

The root element must have the attributes nodes id, and/or ignore if and only if the messages have corresponding properties. The root element must have a ‘type’ attribute only if the message has a type property and if the type is not equal to the root element’s tag. The values of the attributes must equal the corresponding properties. E.g.

<Error id="ENTITY_DOES_NOT_EXIST" type="Error"/><!--this and the next element are equivalent-->
<Error id="ENTITY_DOES_NOT_EXIST"/>
<ServerMessage type="CustomType"/><!--has no id-->
<ServerMessage id="NSSM_MY_ID"/><!--has no type-->

or

<ClientMessage id="CM_MY_ID" ignore="warn"/>

All other Attributes should be ignored.

Description Element

The root element must have exactly one Child Element Node with tag ‘Description’ if and only if the message has a description property. The string value of the message’s description must be the first Child Text Node of the ‘Description’ Element. E.g.

<ServerMessage>
  <Description>This is a description.</Description>
</ServerMessage>

Please note: Any leading or trailing whitespaces of the Text Node must be stripped during the deserialization.

All other Attributes and Child Nodes should be ignored.

Parameters Element

The root element must have exactly one Child Element Node with tag ‘Parameters’ if the message has at least one parameter. The ‘Parameters’ Element in turn must have a single Child Element Node for each parameter which are called Parameter Elements.

A Parameter Element must have a tag equal to the key of the parameter. It must have a type attribute equal to the type property of the parameter if and only if the parameter has a type. And it must have a first Child Text Node which is equal to the parameter’s value. E.g.

<ClientMessage>
  <Parameters>
    <param-one type="entity-name">Experiment</param-one><!--One parameter with key="param-one", value="Experiment", and type="entity-name"-->
  </Parameters>
</ClientMessage>

Please note: Any leading or trailing whitespaces of the Text Node must be stripped during the deserialization.

All other Attributes and Child Nodes below the ‘Parameters’ Element should be ignored.