#d2d 2.0 text using mtdocpage : webpage #title Classes and Concepts for User Messaging #htmlTitle bandm metatools: messages and locations #lang en #tableOfContents // ========================================================================= #h1 #title Basic Concepts for User Messaging // ========================================================================= #p In the context of #mt, all messaging is done by creating and passing on objects of class #link 2/eu/bandm/tools/message/Message.html#text #src message.Message #/link. This type is abstract and needs to be specialized. #p Up to now, one single simple instantiation of this type was sufficient for all situations (in #mt themselves and in many applications), namely #link 2/eu/bandm/tools/message/SimpleMessage.html #text #src message.SimpleMessage #/link. #p There is a whole zoo of #emph message receiving (and possibly propagating) objects#/. They all are generic over the type of message they can receive. They all implement #link 2/eu/bandm/tools/message/MessageReceiver.html #text #src message.MessageReceiver #/link. Those which propagate a message to one single receiver extend #link 2/eu/bandm/tools/message/SingleSender.html #text #src message.SingleSender #/link. #p For identifying positions in documents there is the class #link 2/eu/bandm/tools/message/Location.html #text #src message.Location #/link. #p#kind internal (( There is also an older class called #link 2/eu/bandm/tools/message/Locator.html #text #src message.Locator #/link which is currently (091025) still widely used in #mt, but which is #bold deprecated #/. )) #p The class #src!Location! and the class #src!Message! and all of its sub-classes provided in metatools have all #bold algebraic#/ semantics w.r.t #src!equal()!, and are #bold immutable#/. #p The package #link 2/eu/bandm/tools/muli/package-summary.html #text #src muli #/link 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. // ========================================================================= #h1 #title Details on #src Message#/ and #src MessageReceiver#/ s // ========================================================================= #p The abstract type #link 4/message/Message.html #text Message#/ is the base class for all message types, and only defines three(3) fields: #table #tr #td #src protected #link 4/message/Message.Kind.html#text Message.Kind #td #src kind #tr #td #src protected long #td #src timestamp #tr #td #src protected #link 5/java/lang/RuntimeException.html?is-external=true #text java.lang.RuntimeException#/link #td the "cause" of the message #/table The #src timestamp#/ is set automatically, memoizing the moment in real-time of construction, and the #src cause #emph!may! be specified, to encapsulate a caught #java exception. #p The #src kind #emph!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: #table #tr #td Error #td an exceptional behaviour caused by some ("wrong") user input. It is part of the normal work that this happens (frequently !-) #tr #td Failure #td an internal error of the software which should #emph!not! happen. This is caused by a programming bug/flaw, either by the coder of the software, or of the underlying "virtual machine", etc. #tr #td Warning #td is issued to the user for convenience, indicating critical input which might have unintended effect. #tr #td Hint #td similar to warning, but gives more information for remedy. Possible as additional message to a preceding warning. #tr #td Log #td indicates some processing progress, or documents decisions the application has taken. #tr #td LogStart/LogEnd #td indicate that the application has started/conpleted a certain phase of processing. #/table #p Messages are constructed and then passed through a pipeline of #link 4/message/MessageReceiver.html#text MessageReceivers#/. This pipeline must be constructed by the programmer explicitly. It may be dynamic, i.e. it may change during execution. #p 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 #bold crash with a null pointer exception#/bold. 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. #p Furthermore, the message processing pipeline should be #emph cycle free#/. (Cycles cannot be detected automatically: just imagine "#link 4/message/MessageCatcher.html #text MessageCatcher#/", which propagates to a "#link 4/message/MessageAsync.html #text MessageAsync#/", which propagates to a "#link 4/message/MessageThrower.html #text MessageThrower#/". #nl Or even better: do #emph!not! imagine !-) #p The classes implementing #src!MessageReceiver! perform very different and useful things with messages, e.g. filtering, sorting, counting, storing (incl. visualization), disposing, etc. Please refer to #link 4/message/MessageReceiver.html #text the API doc of #src message.MessageReceiver #/link, or to the #link 4/message/package-summary.html #text class list of the package documentation#/link. #p As mentioned above, we work with a very simple instantiation of #src abstract Message#/, namely #link 4/message/SimpleMessage.html #text SimpleMessage#/. This only defines two new fields and their getter methods: #table #tr #td #src protected #link 4/message/Location.html #text Location #td #src getLocation() #tr #td #src protected String #td #src getText() #/table The parameter "" is the most general document identifier supported by the location class. #p The class itself provides a whole zoo of #src static#/ factory methods, for convenient constructor calls with many different combinations of parameters. #p The subclass #link 4/message/SimpleMessage.Ping.html #text SimpleMessage.Ping#/ is originally intended for the typical co-operation with a #link 4/message/MessagePrinter.Indenting.html #text MessagePrinter.Indenting#/. Such a printer will show an increasing row of dots on a terminal, one dot for each received #src!Ping! message. #p The #link 4/message/SimpleMessage.html #loc toString() #text toString()#/ method of #src!SimpleMessage! is compatible to the #src next-error function of #src XEmacs . #p The overall zoo of message processing classes is shown in the following picture in a simplified way. For the exact relations please refer to #link 4/message/package-tree.html #text the package's class tree#/: #source +--------------+ .drain +-----------------+ | SingleSender |-----------------------------> | MessageReceiver | +--------------+ ---> +-----------------+ +--------------+ / -.> +-----------------+ /\ .drains / / -> /\ /__\ |/ / /__\ | | / | +---------------+-----+ +---------+----- |/ -------------+-----+ | | | | | | | | | +------------+ | | | | | MessageTee |--+ | | | | +------------+ | | +-------------+ +--------------+ |Primitive | +--------------+ |SimpleMessage| | MessageAsync |-----+ | MessageDemux| +--|MessageCounter| |.Generator |--+ +--+-----------+ | +------/\-----* | +--------------+ +-------------+ | |MessageKindFilter|-+ /__\ |MessageDisposer|-+ |MessageCatcher | +-----------------+ | | +---------------+ | +---------------+ | MessagePasser |-+ +------------+ | MessagePrinter |-+ +----------------+ | |MessageDemux| +----------------+ | | MessageSync | +------------+ +-| MessageStore | +---------------+ | +----------------+ +----|MessageThrower | | +----------------+ | TrafficLight | +--------------+ #/source // ========================================================================= #h1 #title Details on #src Location // ========================================================================= #p The class #link 2/eu/bandm/tools/message/Location.html #text #src message.Location #/link 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 #link 4/message/XMLDocumentIdentifier.html #text #src message.XMLDocumentIdentifier #/link. #p#kind internal (( There is also an older class called #link 2/eu/bandm/tools/message/Locator.html #text #src message.Locator #/link which is currently (091025) still widely used in #mt, but which is #bold deprecated #/. )) #p Please refer to #link 4/message/Location.html#text the API doc#/ for further information. #p#kind missing more to come ?? // ========================================================================= #h2 #title The Parametrization Chain and Methods for Easier Handling #p In fact, the message receivers, as employed in the #mt code itself, are currently our "deepest" practical experience with parametrization in java. The chain of type parameters is e.g. as follows: #source MessageReceiver contains Location > #/source #p 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. #p The are based on the #link 4/ops/Function.html#text ops.Function#/link class, as described in #link ops.html#/link. #p In detail we have #list #i #link 4/message/Location.html #loc liftMapDocumentId(eu.bandm.tools.ops.Function) #text Location.liftMapDocumentId(Function(A,B)) #/link which lifts a function which maps document ids to a function which maps locations. #i #link 4/message/SimpleMessage.html #loc liftMapLocation(eu.bandm.tools.ops.Function) #text SimpleMessage.liftMapLocation(Function(A,B)) #/link which lifts a function which maps locations to a function which maps SimpleMessages. #i #link 4/message/MessageMapper.html #loc lift(eu.bandm.tools.ops.Function) #text MessageMapper.lift(Function(A,B)) #/link which lifts a function which maps simple messages into a function which maps message receivers (contra-variantly, e.g. from B to A!) #/list The co-operation of these lift-methods is illustrated by the following code snippet: #source static { final MessageReceiver> rcv = null ; final MessageReceiver> hmm = MessageMapper.lift (SimpleMessage.liftMapLocation (Location.liftMapDocumentId(XMLDocumentIdentifier.getSystemId))).apply(rcv) ; } #/source // ========================================================================= #h1 #title Details on the #src!muli! Package // ========================================================================= #label txt_muli #p The #src!muli! package provides means for maintaining translation tables, and advanced translation look-up. Please refer to #link 4/muli/package-summary.html #text the API doc.#/link #p The main datastructures are #link 4/muli/MuLi.html#text MuLi#/link for one single entry in several languages, #link 4/muli/Catalog.html #text Catalog#/link realizing a map with versatile access methods, and #link 4/muli/MuLi.TextFound.html #text MuLi.TextFound#/link which represents look-up results. #p All entries can be added programmatically, but also read incrementally from a translation file. This is an XML document, following #link 0/bandm.eu/doctypes/muli.dtd#/. #p Furthermore such a file can be compiled to Java constant initialization, which can stil be mixed freely with the other definition methods. #p The language codes used are currently not restricted, but they should follow the common practice as with #src!xml:lang!, i.e. follow RFC 4646 / RFC 4647 / "[IETF BCP 47], Tags for the Identification of Languages". #p (( Currently, we refer to ISO 639-2, as listed e.g. in #cite isolanguage , instead, because the URL for IETF BCP 47 as referred to at the end of #cite xml is BROKEN !!)) #p So it can also take forms like #ldots #source Please mind your baggage Please mind your luggage Januar Jänner #/source #eof