.. _TARGETREGISTRY:

TargetRegistry
##############

Die TargetRegistry dient zum Registrieren von Targets. Das ist die Voraussetzung für den
Empfang von Messages. 

TargetRegistries sind immer an einen Namespace gebunden, oder anders herum, jeder Namespace besitzt eine TargetRegistry.

Registrieren von Targets
========================

Beim Registrieren bekommen Targets eine ID zugeteilt; entweder ihre Wunsch-ID, die beim Registrieren mitgegeben wird,
oder eine zufällige ID. 
Letzteres ist empfehlenswert, denn wenn beim Anmelden eine Kollisionen mit einem schon registrierten
Target festgestellt wird, so wird ohne Rückmeldung eine zufällige ID generiert.

Zusätzlich zu einer Wunsch-ID kann man eine Queue-ID angeben. 
In diesem Fall wird das Target an die MessageQueue dieser ID gebunden.
Fehlt die QID, so wird das Target an die erste Queue des Namespaces gebunden. 
Das ist der Normalfall, da Namespace meist nur eine Queue besitzen.
In jedem Fall wird das Target alle Messages, die es bekommt, im Thread dieser Queue empfangen.
Das sorgt für einfaches Daten-Handling ohne Rücksicht auf Probleme der Nebenläufigkeit.
Es ist empfehlenswert, alle Targets, die untereinander Daten (ohne Message) teilen, im selben Namespace
in der selben Queue anzumelden.

Für die Anmeldung stehen folgende Methoden zur Verfügung::

    // Default QID, "zufällige" TID
    void registerTarget(ITarget aTarget) throws CException;
    
    // Default QID
    void registerTarget(ITarget aTarget,
                        IId aTID) throws CException;

    void registerTarget(ITarget aTarget,
                        IId aTID,
                        IId aQID) throws CException;

Deregistrierung von Targets
===========================
                        
Folgende Methoden sind für die Abmeldung zuständig::

    void deregisterTarget(IId aTID) throws CException;
    
    void deregisterTarget(ITarget aTarget) throws CException;
    
    void deregisterTarget(ITargetAddress aAddress) throws CException;
    
Zugriff auf Targets
===================

Registrierte Targets können ermittelt werden::

    // Über die TID
    ITarget getTarget(IId aTID);
    
Es können auch Details geholt werden, über die synchrone Methode oder über eine Request-Message::

    // Details
    void getTargetInfo(IId aTID,
                       CRecord aRecord) throws CException;
                       
Der ausgefüllte Record ist vom Typ ``CRecordGetTargetInfo``.
Die Request-Message ist die ``CRecordGetTargetInfo``, siehe JavaDoc.                       
    
Eine Liste aller Targets eines Namespaces erhält man über::

    IId[] getTIDs();

Möchte man die Liste auf eine bestimmte Message-Queue einschränken, wählt man folgende Methode::

    IId[] getTIDs(IId aQID);
    
Eine Exist-Methode gibt es auch::

    boolean isTargetRegistered(IId aTID);
    
    
Message-Queues von Targets
==========================

Die Message-Queues von Targets können einfach ermittelt werden::

    IMessageQueue getQueue(IId aTID);
    
    IId getQueueId(IId aTID);
    
Target-Monitore
===============

Um das An- und Abmelden von bestimmten Targets zu monitoren, bieten sich
Target-Monitore an::

    void registerTargetMonitor(IId aTID,
                               ITargetAddress aObserver) throws CException;

    void deregisterTargetMonitor(IId aTID,
                                 ITargetAddress aObserver);

Klienten bekommen dann die Nachrichten 

    * CRecordNotifyTargetRegistered.ID beim Anmelden des Targets
    * CRecordNotifyTargetDeregistered.ID beim Abmelden des Targets.
                                        
Allgemeiner gehalten sind die Target Listener, welche bei jedem Target,
was registriert oder deregistriert wird, eine Nachricht erhalten::

    ITargetAddress[] registerTargetListener(ITargetAddress aAddress);

    void deregisterTargetListener(ITargetAddress aAddress);
    
Interne Methoden
================

Folgende Methoden werden vom Framework selber aufgerufen.

Wenn ein Target nicht vorhanden ist, könnte es sein, das die Nachricht, welche das 
Target erstellt, noch nicht eingetroffen ist (Priorität, Verzögerung).
Daher wird eine kurze Zeit die Message, die an ein nicht existierendes Target gerichtet ist,
zurückgehalten. Wenn in dieser Zeit das Target registriert wird, bekommt das Target die wartende
Message zugestellt. Läuft die Zeit aber ab, so wird die Nachricht mit Fehlercode 
zurückgeschickt.

Intern wird diese Methode für das zurückstellen der Message aufgerufen::

    void addPendingMessage(CMessage aMsg);    
    
Eine andere Methode informiert die TargetRegistry darüber, dass eine Queue abgemeldet wurde.
Alle Targets, die zu dieser Queue gehören, werden abgemeldet.    
    
    void notifyQueueDeregistered(IId aQueueId);