Roblet®-Development-Kit
1.3 (11Sep10)
API für Module

genRob.genControl.modules
Interface Module


public interface Module

Um ein Modul für den Roblet®-Server bereitzustellen, muß man diesen Typ implementieren.  Eine solche Implementierung kann dann Einheiten für Roblets® über den Server bereitstellen.  Der Server erzeugt zur Laufzeit eine Instanz der Modulklasse.

Beim Start des Servers ist der Name Module-Klasse (einschließlich möglicher package-Namen) anzugeben.  Der Server lädt dann die Modul-Klasse und erzeugt über den parameterlosen Konstruktor (der auch dann für eine Klasse vom Compiler erzeugt wurde, wenn er nicht definiert wurde) eine Instanz.  Diese Instanz stellt daraufhin das Modul innerhalb des Servers dar.

Es wird zur Laufzeit des Servers nur eine Instanz (pro angegebenen Modul bei den Startparametern) erzeugt.

Der Standard-Konstruktor der Modul-Klasse und static-Initialisierer sollte nicht zu komplex sein.  Die eigentliche Initialisierung eines Moduls soll in moduleInit(Supervisor,Use) erfolgen.

Ausgaben kann ein Modul mit dem Log machen.


Method Summary
 Registry getRegistry()
          Deprecated. Wird zukünftig entfallen und sollte null zurückgeben.
 Unit getUnit(Class clazz)
          Deprecated. Wird nicht mehr benutzt.
 Unit getUnit4Slot(Class clazz, Use use, Slot slot)
          Gibt eine Einheiten-Instanz heraus.
 void moduleDone()
          Ermöglicht ein abschließendes Aufräumen eines Modules.
 void moduleInit(Supervisor supervisor, Use use)
          Initialisiert ein Modul.
 boolean resetUnit4Slot(Unit unit)
          Soll die Ressourcen einer Einheiten-Instanz zurücksetzen.
 

Method Detail

moduleInit

public void moduleInit(Supervisor supervisor,
                       Use use)
                throws Exception
Initialisiert ein Modul.  Diese Methode wird vom Roblet®-Server einmal aufgerufen, nachdem die Modul-Klasse erfolgreich instanziiert worden ist.

Initialisierungen sollten hier erfolgen, anstatt in einem argumentlosen Konstruktor oder statischen Initialisierern.  Bei Aufruf dieser Methode existieren noch keine Roblets®.  In der Praxis hat sich bewährt, daß die Modul-Klasse gar keinen Konstruktor hat und alle zu initialisierenden Instanz-Variablen in dieser Methode erzeugt werden.

Wenn die Initialisierung aus irgendeinem Grunde fehlschlägt, sollte eine Ausnahme mit einer informativen Nachricht geworfen werden.  In einem solchen Fall wird der Server enden und die Ausnahme dem Administrator präsentieren.

Die Initialisierung kann prinzipiell beliebig lange erfolgen.  Über den Supervisor kann auf das Log zugegriffen werden, um gegebenenfalls Informationen über den Stand auszugeben.

Parameters:
supervisor - Verwalter der Module der u.a. Zugang auf das Log ermöglicht
use - <nicht mehr benutzt>
Throws:
Exception - falls das Modul sich nicht korrekt initialisieren kann
See Also:
moduleDone()

moduleDone

public void moduleDone()
Ermöglicht ein abschließendes Aufräumen eines Modules.  Bevor ein Server endet, wird für alle Module diese Methode einmal aufgerufen.  Bei Aufruf dieser Routine existieren keine Roblets® mehr.

Diese Methode erlaubt dem Modul benutzte Resourcen freizugeben bzw. in einen guten Zustand zurückzuversetzen.

Wenn hier ein Problem auftritt, so sollte dennoch ohne Ausnahme zurückgekehrt werden, um anderen Modulen das Aufräumen zu ermöglichen. Gegebenenfalls sind Informationen über den Fehler über das Log auszugeben.

Das Aufräumen kann prinzipiell beliebig lange erfolgen.  Gegebenenfalls sind Informationen über den Stand über das Log auszugeben.

See Also:
moduleInit(Supervisor,Use)

getUnit

public Unit getUnit(Class clazz)
Deprecated. Wird nicht mehr benutzt.

Parameters:
clazz - <unbenutzt>
Returns:
...

getUnit4Slot

public Unit getUnit4Slot(Class clazz,
                         Use use,
                         Slot slot)
Gibt eine Einheiten-Instanz heraus.  Es handelt sich dabei um die Instanz der Implementierung zur angegebenen Einheiten-Definition.  Wenn ein Roblet® um eine Einheiten-Instanz bittet, so wird vom Server bei allen Modulen nacheinander einmal diese Methode aufgerufen, bis es eine Instanz, d.h. nicht null, erhält.

Jedes Roblet®, d.h. Instanz einer Roblet®-Klasse, benötigt eine eigene Instanz der Einheiten-Implementierung.  Pro Roblet® ist dabei der Nutzungszähler eindeutig.

Die zurückgegebene Einheit muß den als Parameter übergebenen Nutzungszähler benutzen, damit der Server gegebenenfalls feststellen kann, wann der letzte Thread des Roblets® das Modul verlassen hat.  (try-finally-Mechanismus)

Diese Methode sollte schnell zurückkehren, da u.a. zwischenzeitlich das anfragende Roblet® nicht beendet werden kann.

Ausnahmen dürfen hier nicht zurückgegeben werden - einzig null als Behelf.  Probleme mit Ressourcen sind immer durch die Einheiten-Implementierung zu melden - nie an dieser Stelle.

Parameters:
clazz - Einheiten-Definition, zu dem die Einheiten-Instanz benötigt wird
use - Nutzungszähler von der zurückgegebenen Einheiten-Instanz zu benutzen ist
slot - Fach, in dem das Roblet® läuft, welches die Einheit angefordert hat
Returns:
Instanz der Implementierung zum angegebenen Einheiten-Definition oder null, falls das Modul zur Definition keine Implementierung hat
See Also:
resetUnit4Slot(Unit)

resetUnit4Slot

public boolean resetUnit4Slot(Unit unit)
Soll die Ressourcen einer Einheiten-Instanz zurücksetzen.  Bei Aufruf dieser Methode durch den Roblet®-Server existiert das Roblet®, welches die übergebene Einheiten-Instanz einmal bekommen hat, nicht mehr.

Diese Methode muß true ergeben, wenn dem Modul die übergebene Instanz bekannt war.  Dadurch weiß dann der Server, daß keine weiteren Module zu befragen sind.

Diese Methode kann verzögert zurückkehren, aber es ist zu beachten, daß zwischenzeitlich kein neues Roblet® im gleichen Fach zum Laufen kommen kann.

Ausnahmen dürfen hier nicht zurückgegeben werden.

Parameters:
unit - Einheiten-Instanz, die zurückzusetzen ist
Returns:
true wenn die Instanz von diesem Modul stammt
See Also:
getUnit4Slot(Class,Use,Slot)

getRegistry

public Registry getRegistry()
Deprecated. Wird zukünftig entfallen und sollte null zurückgeben.

An dieser Stelle kann ein moduleigenes Grundbuch zurückgegeben werden.

Achtung:  Das Grundbuchkonzept wird in Zukunft entfallen und sollte deshalb für neue Module nicht mehr verwendet werden.  Diese Funktion sollte null zurückliefern, wenn das Grundbuchkonzept nicht benutzt wird.

Returns:
Grundbuch

Roblet®-Development-Kit
1.3 (11Sep10)
API für Module

Copyright © 2001-2010, roblet®.org, Hagen Stanek, http://roblet.org/rdk