introduction	bandm meta_tools	format

Classes and Concepts for User Messaging

(related API documentation: package message,    package muli   )

1          Basic Concepts for User Messaging
2          Details on Message and MessageReceivers
3          Details on Location
3.1          The Parametrization Chain and Methods for Easier Handling
4          Details on the muli Package

^{^ToC} 1 Basic Concepts for User Messaging

In the context of ^meta_tools , all messaging is done by creating and passing on objects of class message.Message . This type is abstract and needs to be specialized.

Up to now, one single simple instantiation of this type was sufficient for all situations (in ^meta_tools themselves and in many applications), namely message.SimpleMessage .

There is a whole zoo of message receiving (and possibly propagating) objects. They all are generic over the type of message they can receive. They all implement message.MessageReceiver . Those which propagate a message to one single receiver extend message.SingleSender .

For identifying positions in documents there is the class message.Location .

The class Location and the class Message and all of its sub-classes provided in metatools have all algebraicsemantics w.r.t equal(), and are immutable.

The package muli provides means for internationalization of text messages: advanced look-up methods and means for maintaining tables of translations, dynamically as well as by code generation.

^{^ToC} 2 Details on Message and MessageReceivers

The abstract type Message is the base class for all message types, and only defines three(3) fields:

The timestamp is set automatically, memoizing the moment in real-time of construction, and the cause may be specified, to encapsulate a caught Java exception.

The kind must be specified explicitly by the caller of the constructor. It reflects the different roles a message can play in the context of a running application or server process:

Messages are constructed and then passed through a pipeline of MessageReceivers. This pipeline must be constructed by the programmer explicitly. It may be dynamic, i.e. it may change during execution.

Please note that this pipeline must be configured correctly: Not specifiying a message receiver at any place where it is expected will make the attempt to send a message crash with a null pointer exception. Of course this should never happen in cleanly written programs! There is intentionally no default behaviour foreseen by the authors in case of missing message receivers, --- if the messaging pipeline is not reliable, then the program hardly is.

Furthermore, the message processing pipeline should be cycle free. (Cycles cannot be detected automatically: just imagine "MessageCatcher", which propagates to a "MessageAsync", which propagates to a "MessageThrower".
Or even better: do not imagine !-)

The classes implementing MessageReceiver perform very different and useful things with messages, e.g. filtering, sorting, counting, storing (incl. visualization), disposing, etc. Please refer to the API doc of message.MessageReceiver , or to the class list of the package documentation.

As mentioned above, we work with a very simple instantiation of abstract Message, namely SimpleMessage<D>. This only defines two new fields and their getter methods:

The parameter "<D>" is the most general document identifier supported by the location class.

The class itself provides a whole zoo of static factory methods, for convenient constructor calls with many different combinations of parameters.

The subclass SimpleMessage.Ping is originally intended for the typical co-operation with a MessagePrinter.Indenting. Such a printer will show an increasing row of dots on a terminal, one dot for each received Ping message.

The toString()method of SimpleMessage is compatible to the next-error function of XEmacs .

The overall zoo of message processing classes is shown in the following picture in a simplified way. For the exact relations please refer to the package's class tree:

          
          +--------------+      .drain                   +-----------------+
          | SingleSender |-----------------------------> | MessageReceiver |
          +--------------+                          ---> +-----------------+
          +--------------+                         / -.> +-----------------+
                 /\                       .drains / / ->         /\  
                /__\			          |/ /    	/__\ 
                  |  				  | /             |  
  +---------------+-----+        +---------+----- |/ -------------+-----+
  |                     |        |         |      |                     |
  |                     |        |       +------------+                 |
  |                     |        |       | MessageTee |--+              |
  |                     |        |       +------------+  |              |
+-------------+    +--------------+        |Primitive    |     +--------------+ 
|SimpleMessage|    | MessageAsync |-----+  | MessageDemux|  +--|MessageCounter|
|.Generator   |--+ +--+-----------+     |  +------/\-----*  |  +--------------+   
+-------------+  |    |MessageKindFilter|-+      /__\       |MessageDisposer|-+ 
 |MessageCatcher |    +-----------------+ |        |        +---------------+ |
 +---------------+       | MessagePasser  |-+ +------------+ | MessagePrinter |-+
                         +----------------+ | |MessageDemux| +----------------+ |
                            | MessageSync   | +------------+ +-| MessageStore   |
                            +---------------+                | +----------------+
                                                        +----|MessageThrower  |
                                                        |    +----------------+
                                                        | TrafficLight |
                                                        +--------------+

^{^ToC} 3 Details on Location

The class message.Location is the means for identifying positions in documents. It supports a sophisticated algebra, between "points", "ranges" and "set of ranges". It must be instantiated with some class which serves for identifying documents as a whole. For this you can use message.XMLDocumentIdentifier .

Please refer to the API doc for further information.

^{^ToC} 3.1 The Parametrization Chain and Methods for Easier Handling

In fact, the message receivers, as employed in the ^meta_tools code itself, are currently our "deepest" practical experience with parametrization in java. The chain of type parameters is e.g. as follows:

   MessageReceiver
     <SimpleMessage               --> contains Location
         <DocumentIdentifier>>                   <DocumentIdentifier>

In practice, there are cases where you have messages without any location information. Whenever a stream of such messages shall be joined with a second, which does have, translation functions must be applied. This can soon become very tedious, because for changing something deeply nested you normally have to de-compose, update and re-construct it. To make this easier there is a collection of "lift" methods, which are spread over the different class definitions, but intended to co-operate.

The are based on the ops.Function class, as described in ops.html.

In detail we have

1. Location.liftMapDocumentId(Function(A,B)) which lifts a function which maps document ids to a function which maps locations.
2. SimpleMessage.liftMapLocation(Function(A,B)) which lifts a function which maps locations to a function which maps SimpleMessages.
3. MessageMapper.lift(Function(A,B)) which lifts a function which maps simple messages into a function which maps message receivers (contra-variantly, e.g. from B to A!)

The co-operation of these lift-methods is illustrated by the following code snippet:

  static {
    final MessageReceiver<SimpleMessage<String>> rcv = null ;
    final MessageReceiver<SimpleMessage<XMLDocumentIdentifier>> hmm 
      = MessageMapper.lift
      (SimpleMessage.liftMapLocation
       (Location.liftMapDocumentId(XMLDocumentIdentifier.getSystemId))).apply(rcv) ;
  }

^{^ToC} 4 Details on the muli Package

The muli package provides means for maintaining translation tables, and advanced translation look-up. Please refer to the API doc.

The main datastructures are MuLi for one single entry in several languages, Catalog realizing a map with versatile access methods, and MuLi.TextFound which represents look-up results.

All entries can be added programmatically, but also read incrementally from a translation file. This is an XML document, following http://bandm.eu/doctypes/muli.dtd.

Furthermore such a file can be compiled to Java constant initialization, which can stil be mixed freely with the other definition methods.

The language codes used are currently not restricted, but they should follow the common practice as with xml:lang, i.e. follow RFC 4646 / RFC 4647 / "[IETF BCP 47], Tags for the Identification of Languages".

(( Currently, we refer to ISO 639-2, as listed e.g. in [isolanguage] , instead, because the URL for IETF BCP 47 as referred to at the end of [xml] is BROKEN !!))

So it can also take forms like ...

<entry key="bomb_warning_on_an_international_airport">
  <text lang="en-us">Please mind your baggage</text>
  <text lang="en-uk">Please mind your luggage</text>
</entry>

<entry key="month1">
  <text lang="de">Januar</text>
  <text lang="de-au">Jänner</text>
</entry>

introduction	bandm meta_tools	format

made    2018-12-30_10h52   by    lepper   on    linux-q699.site       

produced with eu.bandm.metatools.d2d    and    XSLT    FYI view page d2d source text