Roblet®-Development-Kit
2.1 (01Mrz12)
API für Anwendungen

genRob.genControl.client
Class Client

java.lang.Object
  extended by genRob.genControl.client.Client

public class Client
extends Object

Eine Instanz dieser Klasse stellt einen Klienten für einen Roblet®-Server dar.

Die Benutzung dieser Klasse in einer Anwendung ist denkbar einfach (Beispiele weiter unten):

Alle von den Klassen der Bibliothek verwalteten Threads sind Dämonen und haben eine Priorität gleich des Klient-initialisierenden Threads.  Allerdings ist es möglich, daß von dieser Bibliothek benutzte fremde Bibliotheken (z.B. RMI) Threads mit anderen Prioritäten und Dämon-Eigenschaften erzeugen.

Beispiel für das Senden eines Roblets® auf einen namentlich bekannten Server

Der Server soll roblet.org sein.  Dort läuft für diese Zwecke ein Test-Server an Standard-Port 2001.
 import  genRob.genControl.client.Client;
 import  java.io.Serializable;
 import  java.util.Date;
 import  org.roblet.Roblet;
 import  org.roblet.Robot;
 
 // Anwendungsimplementierung
 public class  DateApp
 {
 
     // Methode läuft natürlich lokal als Teil der Anwendung
     public static void  main (String[] args)
         throws Exception
     {
         Client  client = new Client ();
 
         String  servername = "roblet.org";
         try
         {
             Roblet  roblet = new DateRoblet ();
             Date  date = (Date) client. getServer (servername).
                                   getSlot (). run (roblet);
 
             System.out.println ("Date"
                                     + " of " + servername
                                     + " is " + date);
         }
         catch (Exception e) {   e. printStackTrace ();  }
 
         client. close ();
     }
 
     // Roblet®-Implementierung
     private static class  DateRoblet
         implements Roblet, Serializable
     {
         // Interface Roblet
         // Methode läuft fern im Server (!)
         public Object  execute (Robot rRobot)
         {
             return new Date ();
         }
     }
 
 }
 
Vorausgesetzt, daß alle Java™-Archive des RDK insbesondere org.roblet.jar im gleichen Verzeichnis wie DateApp.java liegen, kann mit folgendem kompiliert werden (Unix®/MacOS™/Linux, JDK 6):
 javac  -classpath org.roblet.jar:.  DateApp.java
 
Und unter Windows™:
 javac  -classpath org.roblet.jar;.  DateApp.java
 
Will man es nun das Beispiel laufen lassen, gibt man folgendes ein (Unix®/MacOS™/Linux, JDK 6):
 java  -classpath org.roblet.jar:.  DateApp
 
Und unter Windows™:
 java  -classpath org.roblet.jar;.  DateApp
 

Beispiel für das Senden eines Roblets® auf unbekannte Server

 import  genRob.genControl.client.Client;
 import  genRob.genControl.client.Nominee;
 import  genRob.genControl.client.NomineeListener;
 import  java.io.Serializable;
 import  java.util.Date;
 import  org.roblet.Roblet;
 import  org.roblet.Robot;
 
 // Anwendungsimplementierung
 public class  DateAppAll
 {
 
     // Methode läuft natürlich lokal als Teil der Anwendung
     public static void  main (String[] args)
         throws Exception
     {
         Client  client = new Client ();
 
         client. addListener
         (
             new NomineeListener ()
             {
                 public void  addedNominee (Nominee nominee)
                 {
                     try
                     {
                         String  servername = nominee. toString ();
                         Roblet  roblet = new DateRoblet ();
                         Date  date = (Date) nominee. getServer ().
                                             getSlot (). run (roblet);
 
                         System.out.println ("Server date"
                                                 + " of " + servername
                                                 + " is " + date);
                     }
                     catch (Exception e) {   e. printStackTrace ();  }
                 }
                 public void  removedNominee (Nominee nominee)   {}
             }
         );
 
         System.out.println ("<Enter> zum Abbrechen");
         System.in.read ();
 
         client. close ();
     }
 
     // Roblet®-Implementierung
     private static class  DateRoblet
         implements Roblet, Serializable
     {
         // Interface Roblet
         // Methode läuft fern im Server (!)
         public Object  execute (Robot rRobot)
         {
             return new Date ();
         }
     }
 
 }
 
Diese Anwendung kompiliert man genauso (s.o.).  Auch die Ausführung sieht gleich aus.  Vor der Ausführung muß allerdings ein Verzeichnisdienst im lokalen Netz laufen (in separatem Terminal;  im RDK-Verzeichnis;  JDK 6):
 java  -jar org.roblet.jar  directory
 
Außerdem sollten in diesem Verzeichnisdienst ein Server sichtbar sein bzw. man muß einen Server starten (in separatem Terminal;  im RDK-Verzeichnis;  JDK 6):
 java  -jar org.roblet.jar  server
 

See Also:
Server, NomineeListener, Nominee, Sieve, Slot

Constructor Summary
Client()
          Erzeugt einen Klienten, wie er normalerweise benötigt wird - dabei wird kein Logging ermöglicht, aber der Zugriff auf Verzeichnisdienste aktiviert.
Client(Log log)
          Erzeugt einen Klienten, bei dem das Logging über die mitgegebene Instanz ermöglicht und der Zugriff auf Verzeichnisdienste aktiviert wird.
Client(Log log, boolean directories)
          Erzeugt einen Klienten, welcher Log-Informationen generieren und auf Verzeichnisdienste zugreifen kann.
 
Method Summary
 void addListener(NomineeListener listener)
          Fügt einen Interessenten an Roblet®-Server-Kandidaten (Nominee's) hinzu.
 void close()
          Schließt den Klienten und gibt Hilfsressourcen wieder frei.
protected  void finalize()
          Wird vom "garbage collector" aufgerufen und stellt sicher, für den Klienten sicher, daß close() aufgerufen wird, nachdem die Instanz nicht mehr referenziert wird.
 Server getServer(Identity identity)
          Gibt eine Server-Repräsentanz zur angegebenen Identität zur Benutzung zurück.
 Server getServer(String servername)
          Gibt eine Server-Repräsentanz zum angegebenen Server-Namen zur Benutzung zurück.
 void removeListener(NomineeListener listener)
          Entfernt einen Interessenten an Roblet®-Server-Kandidaten (Nominee's).
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Client

public Client()
       throws ClientException
Erzeugt einen Klienten, wie er normalerweise benötigt wird - dabei wird kein Logging ermöglicht, aber der Zugriff auf Verzeichnisdienste aktiviert.  Ein Klient sollte mit close() geschlossen werden, wenn er nicht mehr benötigt wird.

Ein Aufruf entspricht

  Client(null,true)
 

Throws:
ClientException - Fehler beim Erzeugen der RMI-Requisiten, beim Hinzufügen des Verzeichnisdienst-Zugriffs oder bei gesetzter Java™-Eigenschaft genRob.genControl.client.protocol.RMI
See Also:
Client(Log,boolean), Verzeichnisdienst

Client

public Client(Log log)
       throws ClientException
Erzeugt einen Klienten, bei dem das Logging über die mitgegebene Instanz ermöglicht und der Zugriff auf Verzeichnisdienste aktiviert wird.  Ein Klient sollte mit close() geschlossen werden, wenn er nicht mehr benötigt wird.

Ein Aufruf entspricht

  Client(log,true)
 

Parameters:
log - Instanz zur Verarbeitung von Log-Informationen oder null, wenn keine solche Information erzeugt werden soll
Throws:
ClientException - Fehler beim Erzeugen der RMI-Requisiten, beim Hinzufügen des Verzeichnisdienst-Zugriffs oder bei gesetzter Java™-Eigenschaft genRob.genControl.client.protocol.RMI
See Also:
Client(Log,boolean), Verzeichnisdienst

Client

public Client(Log log,
              boolean directories)
       throws ClientException
Erzeugt einen Klienten, welcher Log-Informationen generieren und auf Verzeichnisdienste zugreifen kann.  Wurde für einen Klienten der Zugriff auf Verzeichnisdienste aktiviert, so muß er mit close() geschlossen werden, um alle verwendeten Ressourcen wieder freizugeben.

Wird der Zugriff auf Verzeichnisdienst nicht aktiviert, so werden auch keine RMI-Requisiten initialisiert.

Beim Zugriff auf Verzeichnisdienste bekommen alle im folgenden von der Bibliothek intern gestarteten Threads die gleiche Priorität, wie die des aufrufenden Threads.  Ebenso wird die zugehörige ThreadGroup benutzt, um darin eine ebensolche mit Namen client#x (x laufende Nummer) für die zu startenen Threads zu erzeugen.  Für den Zugriff auf Verzeichnisdienste werden einige RMI-Requisiten initialisiert.  Zu beachten ist, daß RMI seine Threads an anderer Stelle einhängt und die Prioritäten nach eigenen Regeln setzt.  Alle gestarteten Threads des Klienten sind als Dämon gekennzeichnet;  RMI hier wieder mit Ausnahmen.

Als Teil der RMI-Requisiten wird ein eigener SecurityManager gesetzt, sofern in der Anwendung noch keiner gesetzt war.  Dieser erlaubt alles.  Wenn das nicht gewünscht ist, so muß vor der Erzeugung eines Klienten ein eigener SecurityManager gesetzt werden.

Weiterhin wird zur Unterstützung von RMI ein HTTP-Server gestartet, der am nächsten freien Port lauscht.  Anfragen werden über den bei Aufruf dieses Konstruktors gesetzten Kontext-Klassenladers (Thread.getContextClassLoader()) befriedigt.  Ist keiner gesetzt, so wird der Klassenlader der Klasse desselben Threads und sofern dieser null ist, der System-Klassenlader (ClassLoader.getSystemClassLoader()) eingesetzt. Für RMI wird passend die Java™-Eigenschaft java.rmi.server.codebase gesetzt.

Parameters:
log - Instanz zur Verarbeitung von Log-Informationen oder null, wenn keine solche Information erzeugt werden soll
directories - Wenn true werden Verzeichnisdienste verwendet, um Roblet®-Server aufzufinden.  Ansonsten werden die Dienste nicht kontaktiert und gleichzeitig auch keine RMI-Umgebung initialisiert.
Throws:
ClientException - Fehler beim Erzeugen der RMI-Requisiten, beim Hinzufügen des Verzeichnisdienst-Zugriffs oder bei gesetzter Java™-Eigenschaft genRob.genControl.client.protocol.RMI
See Also:
Client(), Verzeichnisdienst
Method Detail

close

public void close()
Schließt den Klienten und gibt Hilfsressourcen wieder frei.  Laufende Hilfsthreads werden angehalten.  Der Sicherheitsverwalter wird zurückgesetzt, sofern er von dieser Instanz eingangs gesetzt war und ungeändert gesetzt ist.

Ein mehrfacher Aufruf dieser Methode ist ungefährlich.

Schließt man den Klienten nicht, so endet die JVM solange nicht, bis explizit ein Aufruf von System.exit(int) erfolgt.

See Also:
finalize()

getServer

public Server getServer(String servername)
                 throws InterruptedException
Gibt eine Server-Repräsentanz zum angegebenen Server-Namen zur Benutzung zurück.  Diese Aktion ist mit Netzwerkaktivität verbunden und kann daher unbestimmte Zeit in Anspruch nehmen.  Es wird also nicht mit einem timeout gearbeitet, jedoch der Thread, der diese Methode aufruft, kann jederzeit unterbrochen werden.

Extrahiert Host-Name und Port-Nummer aus dem angegebenen Server-Namen.  Ist kein Doppelpunkt im Server-Namen, so wird der Standard-Port 2001 angenommen.  Ist der Server-Name null, so wird die Loopback-Schnittstelle des lokalen Rechners mit Standard-Port 2001 angenommen.

ACHTUNG:  Die Aufspaltung nach Host-Name und Port-Nummer erfolgt einfach anhand des Doppelpunktes ohne weitere Handlungen.  Der Aufrufer muß selbst sicherstellen, daß Host-Name und Port-Nummer den Konventionen (DNS, IPv4, IPv6 etc.) bzw. dem Bereich (normalerweise 1 bis 65535) entsprechen, also der Server-Name tatsächlich einen existierenden Server anspricht.  Einzig für den Fall, daß nach dem Doppelpunkt keine ganze Zahl steht, wird der Host-Name gleich dem Server-Namen gesetzt und das Port als 2001 angenommen.

Es wird eine Verbindung zum Roblet®-Server aufgebaut, um dessen Identität festzustellen, da möglicherweise bereits eine Verbindung unter einem anderen Namen besteht.  Ist letzteres der Fall, so wird die bereits bekannte Repräsentanz zurückgegeben.  Pro Klient (Client) wird für einen Server immer die gleiche Repräsentanz (Instanz) zurückgegeben.  Man kann also bei Bedarf direkt auf Gleichheit prüfen.

Mehrmalige Aufrufe dieser Methode kann in bestimmten Fällen die Rückgabe verschiedener Server-Repräsentanzen zur Folge haben.  Gründe dafür können Load-Balancer und Änderungen im DNS sein, welches andere Server sichtbar werden läßt.

Parameters:
servername - Name des Roblet®-Servers in der Form host:port oder host, wobei host ein DNS-Name oder direkt eine IP-Adresse sein kann und port im Bereich von 1 bis 65535 liegen muß; ohne Port-Angabe oder bei Unverständlichkeit wird Standard-Port 2001 angenommen;  ein Wert von null spricht die Loopback-Netzwerkschnittstelle auf 2001 an
Returns:
zugehörige Server-Repräsentanz
Throws:
InterruptedException - falls der aufrufende Thread beim Warten auf den Roblet®-Server durch die Anwendung zum Unterbrechen aufgefordert wird oder bereits vorher sein Unterbrechungssignal (interrupt flag) gesetzt war
See Also:
getServer(Identity), addListener(NomineeListener)

getServer

public Server getServer(Identity identity)
                 throws InterruptedException
Gibt eine Server-Repräsentanz zur angegebenen Identität zur Benutzung zurück.  Diese Aktion ist mit Netzwerkaktivität verbunden und kann daher unbestimmte Zeit in Anspruch nehmen.  Es wird also nicht mit einem timeout gearbeitet, jedoch der Thread, der diese Methode aufruft, kann jederzeit unterbrochen werden.

Es wird eine Verbindung zum Roblet®-Server aufgebaut, um dessen Identität festzustellen, da möglicherweise bereits eine Verbindung unter einem anderen Namen besteht.  Ist letzteres der Fall, so wird die bereits bekannte Repräsentanz zurückgegeben.  Pro Klient (Client) wird für einen Server immer die gleiche Repräsentanz (Instanz) zurückgegeben.  Man kann also bei Bedarf direkt auf Gleichheit prüfen.

Parameters:
identity - Identität des Roblet®-Servers
Returns:
zugehörige Server-Repräsentanz
Throws:
InterruptedException - falls der aufrufende Thread beim Warten auf den Roblet®-Server durch die Anwendung zum Unterbrechen aufgefordert wird oder bereits vorher sein Unterbrechungssignal (interrupt flag) gesetzt war
See Also:
getServer(String), addListener(NomineeListener)

addListener

public void addListener(NomineeListener listener)
Fügt einen Interessenten an Roblet®-Server-Kandidaten (Nominee's) hinzu.  Dieser Interessent wird über alle bereits gefundenen und zukünftige Server-Kandidaten informiert.

Diese Methode ist nur dann von Wirkung, wenn der Klient für Verzeichnisdienste aktiviert wurde (vgl. ). 

Parameters:
listener - Interessent an Roblet®-Server-Kandidaten
See Also:
removeListener(NomineeListener), getServer(String)

removeListener

public void removeListener(NomineeListener listener)
Entfernt einen Interessenten an Roblet®-Server-Kandidaten (Nominee's).  Fortan erhält er keine Informationen mehr.

Ist der angegebene Interessent gar nicht eingemeldet gewesen, so passiert nichts.

Parameters:
listener - Interessent an Roblet®-Server-Kandidaten
See Also:
addListener(NomineeListener)

finalize

protected void finalize()
Wird vom "garbage collector" aufgerufen und stellt sicher, für den Klienten sicher, daß close() aufgerufen wird, nachdem die Instanz nicht mehr referenziert wird.

Overrides:
finalize in class Object

Roblet®-Development-Kit
2.1 (01Mrz12)
API für Anwendungen

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