Class PuaClient

  • All Implemented Interfaces:
    java.lang.AutoCloseable

    public class PuaClient
    extends java.lang.Object
    implements java.lang.AutoCloseable
    Schnittstelle des Clients zu Protokolle und Auswertungen. Vereinfacht das das Stellen von Anfragen an Pua.
    • Field Detail

      • CURRENT_PROTOCOL_VERSION

        public static final int CURRENT_PROTOCOL_VERSION
        Unterstütze Protokoll-Version des Clients
        See Also:
        Constant Field Values
      • INVALID_STATUS

        public static final byte INVALID_STATUS
        Status der Protokollerstellung konnte nicht abgefragt werden.
        See Also:
        Constant Field Values
      • recentlyCreatedScript

        public de.bsvrz.dav.daf.main.config.DynamicObject recentlyCreatedScript
        Zuletzt automatisch angelegtes Skriptobjekt. Wird von createScript(DynamicObject,AtlBase,String) und createNewScriptObject(String,String) gesetzt.
    • Constructor Detail

      • PuaClient

        public PuaClient​(de.bsvrz.dav.daf.main.ClientDavInterface dav,
                         de.bsvrz.dav.daf.main.config.ConfigurationAuthority configAuth)
                  throws ScopeException,
                         de.bsvrz.dav.daf.main.config.ConfigurationException
        Parameters:
        dav - Verbindung zum Datneverteiler.
        configAuth - Konfigurationsverantwortlicher, der verwendet wird.
        Throws:
        ScopeException - Anfrage wird vom Konfigurationsverantwortlichen nicht unterstützt.
        de.bsvrz.dav.daf.main.config.ConfigurationException - Fehler bei der Kommunikation mit der Konfiguration
    • Method Detail

      • setTimeout

        public void setTimeout​(long timeout)
        Maximale Wartezeit in ms, bis eine Antwort eingetroffen sein muss. Default: 60s.
        Parameters:
        timeout - Maximale Wartezeit, bis eine Antwort eingetroffen sein muss.
      • createProtocol

        public ProtocolResultStream createProtocol​(ProcessingParameter pp)
                                            throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Stößt die Protokollerstellung an. Fängt alle(!) Exceptions ab.
        Parameters:
        pp - Auftragsparameter
        Returns:
        Objekt zum Abfragen der Antwort.
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Fehler beim Absetzen der Anfrage.
      • addProtocolListener

        public ProtocolRequestResult addProtocolListener​(ProtocolListenerEx listener)
                                                  throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Meldet einen Empfänger an, der über fertiggestellte Protokolle informiert wird
        Parameters:
        listener - Empfänger
        Returns:
        Rückmeldung auf die Anfrage zur Prüfung ob die Operation fehlerfrei durchgeführt wurde
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Exception
      • removeProtocolListener

        public ProtocolRequestResult removeProtocolListener​(ProtocolListenerEx listener)
                                                     throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Meldet einen Empfänger ab, der über fertiggestellte Protokolle informiert wurde
        Parameters:
        listener - Empfänger
        Returns:
        Rückmeldung auf die Anfrage zur Prüfung ob die Operation fehlerfrei durchgeführt wurde
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Exception
      • addProtocolListener

        public ProtocolRequestResult addProtocolListener​(ProtocolListener listener)
                                                  throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Meldet einen Empfänger an, der über fertiggestellte Protokolle informiert wird
        Parameters:
        listener - Empfänger. Für erweiterte Benachrichtigungen kann und sollte hier eine Instanz von ProtocolListenerEx statt ProtocolListener verwendet werden.
        Returns:
        Rückmeldung auf die Anfrage zur Prüfung ob die Operation fehlerfrei durchgeführt wurde
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Exception
      • addStatusListener

        public boolean addStatusListener​(StatusListener listener)
        Fügt einen Listener hinzu, mit dem sich der Anwender über Änderungen am Verfügbarkeitszustand von PuA und dem von PuA verwendeten Archivsystem informieren kann. Der Listener wird direkt nach dem Anmelden über den aktuellen Zustand informiert.
        Parameters:
        listener - Listener-Interface (nicht null)
        Returns:
        true wenn der Listener hinzugefügt wurde. False: Der Listener war bereits angemeldet.
      • removeStatusListener

        public boolean removeStatusListener​(StatusListener listener)
        Entfernt einen, mit dem sich der Anwender über Änderungen am Verfügbarkeitszustand von PuA und dem von PuA verwendeten Archivsystem informieren kann
        Parameters:
        listener - Listener-Interface (nicht null)
        Returns:
        true wenn der Listener entfernt wurde. False: Der Listener war noch nicht angemeldet.
      • removeProtocolListener

        public ProtocolRequestResult removeProtocolListener​(ProtocolListener listener)
                                                     throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Meldet einen Empfänger ab, der über fertiggestellte Protokolle informiert wurde
        Parameters:
        listener - Empfänger
        Returns:
        Rückmeldung auf die Anfrage zur Prüfung ob die Operation fehlerfrei durchgeführt wurde
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Exception
      • getSavedProtocol

        public ProtocolResultStream getSavedProtocol​(long protocolId)
                                              throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Fragt ein bereits gespeichertes Protokoll ab.
        Parameters:
        protocolId - Protokoll-Id des gespeicherten Protokolls.
        Returns:
        Objekt zum Abfragen der Antwort.
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Fehler beim Absetzen der Anfrage.
      • getUnreadProtocol

        public ProtocolResultStream getUnreadProtocol​(long protocolId)
                                               throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Fragt ein noch nicht abgerufenes gespeichertes Protokoll ab.
        Parameters:
        protocolId - Protokoll-Id des gespeicherten Protokolls.
        Returns:
        Objekt zum Abfragen der Antwort.
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Fehler beim Absetzen der Anfrage.
      • getProtocol

        public ProtocolResultStream getProtocol​(long protocolId,
                                                boolean read)
                                         throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Fragt ein bereits gespeichertes bzw. noch nicht abgerufenens Protokoll ab.
        Parameters:
        protocolId - Protokoll-Id des gespeicherten Protokolls.
        read - true gespeicherte Protokolle abrufen. false noch nicht abgerufene Protokolle senden.
        Returns:
        Objekt zum Abfragen der Antwort.
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Fehler beim Absetzen der Anfrage.
      • suspendProtocol

        @Deprecated
        public ProtocolRequestResult suspendProtocol​(long jobId)
                                              throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Deprecated.
        Diese Methode war zur Flusskontrolle gedacht und wird nicht mehr benötigt, weil mittlerweile eine automatische Flusskontrolle zwischen PuA-Server und -Client implementiert ist.
        Hält eine protokollbezogene Operation an. Gültige Operationen für diese Methode sind:
        • Erstellung von Protokollen
        • Abruf von gespeicherten Protokollen
        • Abruf von ungelesenen Protokollen
        Parameters:
        jobId - Auftrags-ID des anzuhaltenden Auftrags. Bei Protokollerstellungsaufträgen identisch mit Protokoll-ID. Die Auftrags-ID kann über ProtocolResultStream.getJobId() oder getJobList(de.bsvrz.pua.prot.util.ProtocolRequestResult) abgerufen werden.
        Returns:
        Informationen über das Absetzen der Anfrage.
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Fehler bei der Kommunikation mit der Konfiguration.
      • resumeProtocol

        @Deprecated
        public ProtocolRequestResult resumeProtocol​(long jobId)
                                             throws de.bsvrz.sys.funclib.losb.exceptions.FailureException
        Deprecated.
        Diese Methode war zur Flusskontrolle gedacht und wird nicht mehr benötigt, weil mittlerweile eine automatische Flusskontrolle zwischen PuA-Server und -Client implementiert ist.
        Setzt eine protokollbezogene Operation fort. Gültige Operationen für diese Methode sind:
        • Erstellung von Protokollen
        • Abruf von gespeicherten Protokollen
        • Abruf von ungelesenen Protokollen
        Parameters:
        jobId - Auftrags-ID des fortzusetzenden Auftrags. Bei Protokollerstellungsaufträgen identisch mit Protokoll-ID. Die Auftrags-ID kann über ProtocolResultStream.getJobId() oder getJobList(de.bsvrz.pua.prot.util.ProtocolRequestResult) abgerufen werden.
        Returns:
        Informationen über das Absetzen der Anfrage.
        Throws:
        de.bsvrz.sys.funclib.losb.exceptions.FailureException - Fehler bei der Kommunikation mit der Konfiguration.
      • abortProtocol

        public ProtocolRequestResult abortProtocol​(long jobId)
        Bricht eine protokollbezogene Operation ab. Gültige Operationen für diese Methode sind:
        • Erstellung von Protokollen
        • Abruf von gespeicherten Protokollen
        • Abruf von ungelesenen Protokollen
        ProtocolResultStream.take() liefert nach dem Abbrechen null und ProtocolResultStream.hasNext() true zurück.
        Parameters:
        jobId - Auftrags-ID des abzubrechenden Auftrags. Bei Protokollerstellungsaufträgen identisch mit Protokoll-ID. Die Auftrags-ID kann über ProtocolResultStream.getJobId() oder getJobList(ProtocolRequestResult) abgerufen werden.
        Returns:
        Informationen über das Absetzen der Anfrage. Positive Quittung nur dann, wenn die Protokollerstellung abgebrochen wurde.
      • abortProtocol

        public ProtocolRequestResult abortProtocol​(long jobId,
                                                   boolean resumeSaving)
        Bricht eine protokollbezogene Operation ab. Gültige Operationen für diese Methode sind:
        • Erstellung von Protokollen
        • Abruf von gespeicherten Protokollen
        • Abruf von ungelesenen Protokollen
        ProtocolResultStream.take() liefert nach dem Abbrechen null und ProtocolResultStream.hasNext() true zurück.
        Parameters:
        jobId - Auftrags-ID des abzubrechenden Auftrags. Bei Protokollerstellungsaufträgen identisch mit Protokoll-ID. Die Auftrags-ID kann über ProtocolResultStream.getJobId() oder getJobList(ProtocolRequestResult) abgerufen werden.
        resumeSaving - Falls es sich um einen Auftrag zur Protokollerstellung handelt: Soll das Protokoll trotzdem gespeichert werden? Es wird dann nur die Übertragung des Protokolls abgebrochen. True wird nur von PuA-Versionen ab 2.9.0 unterstützt.
        Returns:
        Informationen über das Absetzen der Anfrage. Positive Quittung nur dann, wenn die Protokollerstellung abgebrochen wurde.
      • getIsActive

        @Deprecated
        public boolean getIsActive​(ProtocolRequestResult resultInfo)
        Deprecated.
        Kann durch die Funktionen isPuaOnline() und isArchiveOnline() ersetzt werden, die detaillierte Informationen bieten
        Prüft ob PuA aktiv ist und das Archivsystem erreichbar ist, also ob Protokollanfragen gestellt werden können.
        Parameters:
        resultInfo - Ergebnis der Anfrage, seit PuA 2.9.0 immer erfolgreich
        Returns:
        true wenn alles in Ordnung ist und Anfragen gestellt werden können, false wenn PuA nicht erreichbar ist oder das Archivsystem von PuA nicht erreichbar ist
      • isPuaOnline

        public boolean isPuaOnline()
        Gibt true zurück, wenn PuA erreichbar ist
        Returns:
        true, wenn PuA erreichbar ist, sonst false
      • isArchiveOnline

        public boolean isArchiveOnline()
        Gibt true zurück, wenn PuA erreichbar ist und PuA das Archiv erreichen kann. Wenn PuA nicht läuft bzw. nicht erreichbar ist, gibt diese Methode immer false zurück, da diese Methode prüft, ob PuA das von PuA verwendete Archivsystem erreichen kann und nicht, ob irgendein Archivsystem läuft.
        Returns:
        true, wenn PuA erreichbar ist und PuA das Archiv erreichen kann, sonst false
      • getSavedProtocolList

        public de.bsvrz.sys.funclib.losb.util.Tuple<java.lang.Long,​ProcessingParameter>[] getSavedProtocolList​(ProtocolRequestResult resultInfo,
                                                                                                                     java.lang.String user)
        Liefert eine Liste der gespeicherten Protokolle und Protokollinformationen.
        Parameters:
        resultInfo - In diesem Objekt werden Fehlermeldungen abgelegt.
        user - Benutzer, für den die Anfrage ausgeführt wird. (kann null oder ein Leerstring sein, dann werden keine benutzerspezifischen Skripte zurückgegeben)
        Returns:
        Array mit Ids der gespeicherten Protokolle oder null bei Fehler.
      • getUnreadProtocolList

        public de.bsvrz.sys.funclib.losb.util.Tuple<java.lang.Long,​ProcessingParameter>[] getUnreadProtocolList​(ProtocolRequestResult resultInfo,
                                                                                                                      java.lang.String user)
        Liefert eine Liste der noch nicht abgerufenen Protokolle und Protokollinformationen.
        Parameters:
        resultInfo - In diesem Objekt werden Fehlermeldungen abgelegt.
        user - Benutzer, für den die Anfrage ausgeführt wird. (kann null oder ein Leerstring sein, dann werden keine benutzerspezifischen Protokolle zurückgegeben)
        Returns:
        Array mit Ids der gespeicherten Protokolle oder null bei Fehler.
      • deleteSaveProtocol

        public ProtocolRequestResult deleteSaveProtocol​(long protocolId)
        Löscht ein gespeichertes Protokoll.
        Parameters:
        protocolId - Protokoll das gelöscht werden soll.
        Returns:
        Informationen über den Ausgang des Löschvorgangs.
      • createScript

        public ProtocolRequestResult createScript​(java.lang.String pid,
                                                  java.lang.String name,
                                                  de.bsvrz.sys.funclib.losb.datk.AtlBase baseInfo,
                                                  java.lang.String source)
        Sendet den Auftrag 'Skript anlegen/editieren'. Wartet auf eine Antwort von PuA. Behandelt alle(!) Exceptions. Wertet nur die erste Antwort aus, und beendet danach den Empfang von Daten. Es wird zweimal versucht, die Anfrage an PuA zu senden. Dies hat den Grund, dass, falls von createScript auch das dynamische Skriptobjekt erzeugt wurde, PuA eine gewisse Zeit gegeben werde muss, um sich als Empfänger auf dieses Skriptobjekt anzumelden. Das Skriptobjekt wird zudem in recentlyCreatedScript abgelegt.
        Parameters:
        pid - Pid des Skriptobjekts, das angelegt / editiert werden soll. Sollte nicht null sein. Existiert noch kein Skriptobjekt mit der übergebenen pid, so wird eins angelegt.
        name - Name des Skripts.
        baseInfo - Grundinformationen.
        source - Skript Quelltext.
        Returns:
        Ergebnis der Anfrage.
      • createScript

        public ProtocolRequestResult createScript​(de.bsvrz.dav.daf.main.config.DynamicObject script,
                                                  de.bsvrz.sys.funclib.losb.datk.AtlBase baseInfo,
                                                  java.lang.String source)
        Sendet den Auftrag 'Skript anlegen/editieren'. Wartet auf eine Antwort von PuA. Behandelt alle(!) Exceptions. Wertet nur die erste Antwort aus, und beendet danach den Empfang von Daten. Es wird zweimal versucht, die Anfrage an PuA zu senden. Dies hat den Grund, dass, falls von createScript auch das dynamische Skriptobjekt erzeugt wurde, PuA eine gewisse Zeit gegeben werde muss, um sich als Empfänger auf dieses Skriptobjekt anzumelden.
        Parameters:
        script - Skriptobjekt das angelegt / editiert werden soll. Kann null sein. Dann wird ein neues Skriptobjekt erzeugt. Der Name des erzeugten Skriptobjekts ist das aktuelle Datum + Zeit. Auf das Skriptobjekt kann durch recentlyCreatedScript zugegriffen werden.
        baseInfo - Grundinformationen.
        source - Skript Quelltext.
        Returns:
        Ergebnis der Anfrage.
      • getSource

        public ProtocolRequestResult getSource​(de.bsvrz.dav.daf.main.config.DynamicObject script,
                                               java.lang.StringBuffer source,
                                               de.bsvrz.sys.funclib.losb.datk.AtlMeta meta)
        Liefert den Quelltext eines Skripts zurück. Blockiert, bis die Antwort eintrifft. Sendet die Anfrage als einfacher Sender.
        Parameters:
        script - Skriptobjekt dessen Quelltext geliefert werden soll.
        source - Buffer, in den der Skriptquelltext abgelegt wird.
        meta - Metainformationen über das Skript.
        Returns:
        Ergebnis der Operation.
      • getDefaults

        public ProtocolRequestResult getDefaults​(de.bsvrz.dav.daf.main.config.DynamicObject script,
                                                 de.bsvrz.sys.funclib.losb.datk.AtlDefaults defaults,
                                                 de.bsvrz.sys.funclib.losb.datk.AtlMeta meta)
        Liefert die Standardwerte und die definierbaren Aspekte/Aliase eines Skripts zurück. Blockiert, bis die Antwort eintrifft. Sendet die Anfrage als einfacher Sender.
        Parameters:
        script - Skriptobjekt dessen Standardwerte geliefert werden sollen.
        defaults - Hier werden die Standardwerte abgelegt. Es ist ein leeres AtlDefaults-Objekt zu übergeben.
        meta - Hier werden die Metainformationen über das Skript abgelegt. Es ist ein leeres AtlMeta-Objekt zu übergeben.
        Returns:
        Ergebnis der Operation.
      • deleteScript

        public ProtocolRequestResult deleteScript​(de.bsvrz.dav.daf.main.config.DynamicObject script)
        Entfernt ein Skriptobjekt und den zugehörigen Skriptquelltext. Löscht Skript aus der Menge der Skriptobjekte.
        Parameters:
        script - Skriptobjekt das gelöscht wird.
        Returns:
        Ergebnis der Anfrage
      • getJobList

        public java.util.List<JobInProgress> getJobList​(ProtocolRequestResult resultInfo)
        Ruft eine liste mit aktuell in Bearbeitung befindlichen Aufträgen ab.
        Parameters:
        resultInfo - Wird mit Ergebnis der Operation belegt. Darf null sein.
        Returns:
        Liste mit allen protokollbezogenen Aufträgen, die sich PuA-seitig in der Warteschlange oder in Bearbeitung befinden. Für jeden Auftral ist eine Auftrags-ID (JobId) abrufbar, mit der Auftrag z. B. mit abortProtocol(long) abgebrochen werden kann.
      • getFlowControlWindowSize

        public int getFlowControlWindowSize()
        Gibt die Größe des "Sliding Window" für die automatische Flusskontrolle zurück
        Returns:
        die Größe des "Sliding Window" für die automatische Flusskontrolle, d.h. die maximale Anzahl der Datensätze, die gleichzeitig übertragen werden.
      • setFlowControlWindowSize

        public void setFlowControlWindowSize​(int flowControlWindowSize)
        Setzt die Größe des "Sliding Window" für die automatische Flusskontrolle. Der PuaClient verwendet beim Protokollabruf zur Flusskontrolle ein einfaches "Sliding Window"-Verfahren, dass die Anzahl der Protokolldatensätze, die gleichzeitig übertragen werden beschränkt. Hierzu teilt der Client dem PuA-Server regemäßig mit, wie viele Protokolldatensätze er bereits empfangen hat, plus wie viele der PuA-Server zusätzlich senden soll.
        Parameters:
        flowControlWindowSize - Maximale Anzahl Protokoll-Ergebnis-Datensätze, die gleichzeitig von PuA-Server bis zum PuaClient gesendet werden. Auf 0 setzen um Flusskontrolle abzuschalten.
      • close

        public void close()
        Gibt belegte Ressourcen frei und meldet Datenverteiler-Anmeldungen ab. Nach dem Aufruf dieser methode sollte diese Instanz nicht weiter verwendet werden.
        Specified by:
        close in interface java.lang.AutoCloseable
      • getServerProtocolVersion

        public int getServerProtocolVersion()
        Gibt die vom Server aktuell unterstützte Protokollversion zurück. Die Protokollversion wird nach dem Erstellen des PuaClients ausgehandelt, sodass die präzise Version möglicherweise erst wenige Sekunden nach der Initialisierung dieser Klasse zur Verfügung steht.
        Returns:
        Aktuell vom Server unterstützte Protokollversion
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object