java.lang.Object
   |
   +--java.util.logging.Logger

Deklaration

Beschreibung

• Benannnte Protokollierer
• Anonyme Protokollierer

Benannte Protokollierer werden vom Log-Manager in einem hierarchischen Namensraum verwaltet. Auf sie kann man jederzeit wieder über den Namen aus verschiedenen Klassen der Anwendung zugreifen. Ein Name besteht aus einer Zeichenkette, die durch Punkte in verschiedene Bereiche unterteilt wird, analog zur Struktur der Package-Namen in Java. Oft werden Package-Namen als Basis für die Namen der Protokollierer verwendet.

Anonyme Protokollierer werden einmal erzeugt und die Anwendung ist selbst dafür verantwortlich, den Protokollierer innerhalb der Anwendung weiter zu reichen.

Ein Protokollierer reicht die ihm übergebenen Protokolleinträge an die registrierten Handler weiter. Die Handler können eine bedingte Verarbeitung der Einträge durchführen (durch Filter) und unternehmen weitere Schritte (z. B. Speichern des Eintrags in einer Datei oder Verschicken des Eintrags über ein Netzwerk). Ein Protokollierer kann selbst nur eine Filterung nach Log-Ebene durchführen.

Jeder Protokollierer hält einen Verweis auf den in der Hierarchie übergeordneten Protokollierer. Von ihm können einige Einstellungen übernommen werden.

Zur Lokalisierung von Protokolleinträgen sind mit jedem Protokollierer Lokalisierungs-Ressourcen assoziiert. Die Nachricht selbst kann einen Schlüssel darstellen, oder Platzhalter enthalten die mit Parametern belegt werden. Bei der Verwendung von Parametern wird in der Regel die Formatierung mit java.text.MessageFormat durchgeführt.

Insgesamt stellt ein Protokollierer fünf Gruppen von Methoden zur Protokollierung bereit: The logging methods are grouped in five main categories:

• log()-Methoden bekommen die Log-Ebene, Nachricht und optionale Parameter übergeben.
• logp()-Methoden sind wie die log()-Methoden aufgebaut, bekommen zusätzlich die Namen von Klasse und Methode übergeben, in denen Eintrag erzeugt wird.
• logrb()-Methoden sind wie die logp()-Methoden aufgebaut, besitzen aber außerdem einen Parameter zur übergabe der Lokalisierungs-Ressourcen.
• Für jede Log-Ebene ist gibt es eine Methode, die denselben Namen trägt und der Einfachheit halber benutzt werden kann, um einen Protokolleintrag mit einer bestimmten Log-Ebene zu erzeugen. So kann man z. B. mit der Methode warning() einen Protokolleintrag mit der Log-Ebene Level.WARNING erzeugen. Als Argument erwarten diese Methoden lediglich eine Nachricht.
• Zu Debugging-Zwecken wurden außerdem die Methoden entering() und exiting() definiert. Sie sollten benutzt werden, zum Erzeugen eines Eintrags beim Betreten bzw. Verlassen einer Methode.

Datenelemente im Detail

public final static Logger global

Dieses Attribut enthält einen Verweis auf einen globalen Protokollierer, der unter dem Namen »global« beim Log-Manager registriert wurde.

Konstruktoren im Detail

protected Logger(String name, String resourceBundleName)

Erzeugt einen benannten Protokollierer, dem der Name name und die Lokalisierungs-Ressourcen resourceBundleName zugeordnet sind. Die Log-Ebene ist nach der Initialisierung nicht gesetzt und die übergeordneten Handler werden per Voreinstellungen benutzt.

Methoden im Detail

public synchronized void addHandler(Handler handler)

Registriert einen Handler, durch den Protokolleinträge verarbeitet werden. Per Voreinstellung schicken Protokollierer die Protokolleinträge an ihre übergeordneten Protokollierer. Die Protokollierer des Root-Handlers stellen somit die Default-Handler für alle Protokollierer dar.

Exception: SecurityException

• Wenn ein SecurityManager gesetzt ist und der Aufruf keine LoggingPermission("control" besitzt.

public void config(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.CONFIG. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public void entering(String sourceClass, String sourceMethod)

Erzeugt einen Protokolleintrag der zu Debugging-Zwecken eingesetzt wird, um den Aufruf einer Methode zu dokumentieren. Die Einträge haben die Log-Ebene Level.FINER, die Nachricht "ENTRY" und die übergebenen Methoden- und Klassennamen.

public void entering(String sourceClass, String sourceMethod, Object param1)

Erzeugt einen Protokolleintrag der zu Debugging-Zwecken eingesetzt wird, um den Aufruf einer Methode mit einem Parameter zu dokumentieren. Die Einträge haben die Log-Ebene Level.FINER, die Nachricht "ENTRY {0}" und die übergebenen Methoden- und Klassennamen und Parameter.

public void entering(String sourceClass, String sourceMethod, Object[] params)

Erzeugt einen Protokolleintrag der zu Debugging-Zwecken eingesetzt wird, um den Aufruf einer Methode mit beliebigen Parametern zu dokumentieren. Die Einträge haben die Log-Ebene Level.FINER, die Nachricht "ENTRY {1} ... {N}" und die übergebenen Methoden- und Klassennamen und Parameter.

public void exiting(String sourceClass, String sourceMethod)

Erzeugt einen Protokolleintrag der zu Debugging-Zwecken eingesetzt wird, um das Beenden einer Methode zu dokumentieren. Die Einträge haben die Log-Ebene Level.FINER, die Nachricht "RETURN" und die übergebenen Methoden- und Klassennamen.

public void exiting(String sourceClass, String sourceMethod, Object result)

Erzeugt einen Protokolleintrag der zu Debugging-Zwecken eingesetzt wird, um das Beenden einer Methode mit einem Ergebnis zu dokumentieren. Die Einträge haben die Log-Ebene Level.FINER, die Nachricht "RETURN {0}" und die übergebenen Methoden- und Klassennamen und Ergebnis.

public void fine(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.FINE. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public void finer(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.FINER. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public void finest(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.FINEST. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public static synchronized Logger getAnonymousLogger()

Erzeugt einen anonymen Protokollierer, der nicht im Namensraum beim Log-Manager registriert wird. Auf diese Weise werden üblicherweise Protokollierer zur Verwendung in Applets erzeugt, da der Protokollierer nicht zwischen Klassen unterschiedlicher Herkunft geteilt werden kann (kein globaler Zugriff über den Namen). Ein solcher Protokollierer bekommt den Root-Protokollierer als übergeordneten Protokollierer zugewiesen so dass per Voreinstellung die zugewiesene Log-Ebene und Handler vom Root-Protokollierer vererbt werden.

public static synchronized Logger getAnonymousLogger(String resourceBundleName)

Erzeugt einen anonymen Protokollierer, der nicht im Namensraum beim Log-Manager registriert wird. Auf diese Weise werden üblicherweise Protokollierer zur Verwendung in Applets erzeugt, da der Protokollierer nicht zwischen Klassen unterschiedlicher Herkunft geteilt werden kann (kein globaler Zugriff über den Namen). Ein solcher Protokollierer bekommt den Root-Protokollierer als übergeordneten Protokollierer zugewiesen so dass per Voreinstellung die zugewiesene Log-Ebene und Handler vom Root-Protokollierer vererbt werden.

public Filter getFilter()

Liefert den aktuellen Filter dieses Protokollierers zurück.

public synchronized Handler[] getHandlers()

Liefert die Handler zurück, die Protokolleinträge von diesem Protokollierer verarbeiten.

public Level getLevel()

Liefert die Log-Ebene, die für diesen Protokollierer gesetzt ist. Liefert die Methode den Wert null zurück, bedeutet das, dass die Log-Ebene vom übergeordneten Protokollierer vererbt wird.

public static synchronized Logger getLogger(String name)

Liefert den Protokollierer mit dem Namen name zurück. Wenn bereits ein Protokollierer mit diesem namen existiert, wird er zurückgeliefert, ansonsten wird ein neuer Protokollierer erzeugt, im Namensraum unter dem Namen registriert und anschließend zurück geliefert. Per Voreinstellung werden die Handler vom übergeordneten Protokollierer vererbt.

public static synchronized Logger getLogger(String name, String resourceBundleName)

Liefert den Protokollierer mit dem Namen name zurück. Wenn bereits ein Protokollierer mit diesem namen existiert, wird er zurückgeliefert, ansonsten wird ein neuer Protokollierer erzeugt, im Namensraum unter dem Namen registriert und anschließend zurück geliefert. Per Voreinstellung werden die Handler vom übergeordneten Protokollierer vererbt.

Wenn der Protokollierer schon existiert und noch keine Lokalisierungs-Ressourcen zugewiesen wurden, werden die Ressourcen gesetzt. Wenn dem existenten Protokollierer bereits andere Ressourcen zugewiesen wurde, wird eine IllegalArgumentException ausgelöst.

public String getName()

Liefert den Namen dieser Protokollierers zurück.

public Logger getParent()

Liefert den übergeordneten Protokollierer zurück. Der übergeordnete Protokollierer ist derjenige, der im Namensraum sich im Namensraum am nächsten befindet, d. h. er muß nicht direkt übergeordnet sein. Zu einem Protokollierer mit dem Namen de.dpunkt.log.Logger wäre der Protokollierer Protokollierer mit dem Namen de.dpunkt übergeordnet, wenn kein Protokollierer mit dem Namen de.dpunkt.log existiert.

public ResourceBundle getResourceBundle()

Liefert die Lokalisierungs-Ressourcen für diesen Protokollierer in der aktuellen Default-Lokalisierung zurück. Wenn die Methode null als Ergebnis zurückliefert, dann werden die Ressourcen vom übergeordneten Protokollierer vererbt.

public String getResourceBundleName()

Liefert den Namen der Ressourcen, die zur Durchführung der Lokalisierung benutzt wird. Wenn die Methode null als Ergebnis liefert, wird der Name der Ressourcen vom übergeordneten Protokollierer vererbt.

public synchronized boolean getUseParentHandlers()

Gibt true zurück, wenn dieser Protokollierer seine Ausgabe auch an die übergeordneten Handler schickt.

public void info(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.INFO. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public boolean isLoggable(Level level)

Prüft, ob eine Nachricht mit der übergebenen Log-Ebene derzeit verarbeitet werden würde. Bei Bedarf wird die Log-Ebene des übergeordneten Protokollierers für diese Prüfung berücksichtigt.

public void log(LogRecord record)

Legt einen neuen Protokolleintrag an. Diese Methode wird intern von allen anderen Protokollierungs-Methoden verwendet. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge der gesetzten Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void log(Level level, String msg)

Legt einen neuen Protokolleintrag an. Log-Ebene und Nachricht werden als Parameter übergeben. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void log(Level level, String msg, Throwable thrown)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht und ein Throwable-Exemplar werden als Parameter übergeben. Diese Methode kann somit benutzt werden, wenn aufgrund einer Fehlersituation ein neuer Eintrag erzeugt werden soll. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void log(Level level, String msg, Object[] params)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht und Parameter werden der Methode übergeben. Die Parameter können bei der Formatierung in die Nachricht eingebaut werden. Sie werden in der Nachricht in der Form "{0}" referenziert, wobei die Zahl in den geschweiften Klammern die Nummer des Parameters angibt. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void log(Level level, String msg, Object param1)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht und ein Parameter werden der Methode übergeben. Der Parameter kann bei der Formatierung in die Nachricht eingebaut werden. Er wird in der Nachricht in der Form "{0}" referenziert. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logp(Level level, String sourceClass, String sourceMethod, String msg)

Legt einen neuen Protokolleintrag an. Log-Ebene und Nachricht sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden übergeben. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logp(Level level, String sourceClass, String sourceMethod, String msg, Object param1)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, ein Parameter sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Der Parameter kann bei der Formatierung in die Nachricht eingebaut werden. Er wird in der Nachricht in der Form "{0}" referenziert. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logp(Level level, String sourceClass, String sourceMethod, String msg, Object[] params)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, Parameter sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Die Parameter können bei der Formatierung in die Nachricht eingebaut werden. Sie werden in der Nachricht in der Form "{0}" referenziert, wobei die Zahl in den geschweiften Klammern die Nummer des Parameters angibt. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logp(Level level, String sourceClass, String sourceMethod, String msg, Throwable thrown)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, einThrowable-Exemplar sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Diese Methode kann benutzt werden, wenn aufgrund einer Fehlersituation ein neuer Eintrag erzeugt werden soll. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, der Name der Lokalisierungs-Ressourcen sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg, Object param1)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, ein Parameter, der Name der Lokalisierungs-Ressourcen sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Der Parameter kann bei der Formatierung in die Nachricht eingebaut werden. Er wird in der Nachricht in der Form "{0}" referenziert. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg, Throwable thrown)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, Parameter, ein Throwable-Exemplar, der Name der Lokalisierungs-Ressourcen sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public void logrb(Level level, String sourceClass, String sourceMethod, String bundleName, String msg, Object[] params)

Legt einen neuen Protokolleintrag an. Log-Ebene, Nachricht, Parameter, der Name der Lokalisierungs-Ressourcen sowie die Namen von Klasse und Methode, in denen der Eintrag erzeugt wurde, werden der Methode übergeben. Die Parameter können bei der Formatierung in die Nachricht eingebaut werden. Sie werden in der Nachricht in der Form "{0}" referenziert, wobei die Zahl in den geschweiften Klammern die Nummer des Parameters angibt. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, wird er an alle registrierten Handler-Objekte weitergeleitet.

public synchronized void removeHandler(Handler handler)

Entfernt einen Handler. Der Aufrufer bekommt keine Rückmeldung, wenn der übergebene Handler nicht gefunden wird.

Exception: SecurityException

• Wenn ein SecurityManager gesetzt ist und der Aufruf keine LoggingPermission"control" besitzt.

public void setFilter(Filter newFilter)

Setzt einen Filter, der die Verarbeitung einzelner Einträge unterbinden kann.

Exception: SecurityException

• Wenn ein SecurityManager gesetzt ist und der Aufruf keine LoggingPermission"control" besitzt.

public void setLevel(Level newLevel)

Setzt die Log-Ebene. Alle Protokolleinträge mit derselben oder einer höheren Log-Ebene als newLevel werden von diesem Protokollierer verarbeitet. Mit der Log-Ebene Level.OFF wird die Protokollierung aller Protokolleinträge unterbunden, der Wertnull bedeutet, dass die Log-Ebene vom übegeordneten Protokollierer vererbt wird.

Exception: SecurityException

• Wenn ein SecurityManager gesetzt ist und der Aufruf keine LoggingPermission"control" besitzt.

public void setParent(Logger parent)

Setzt den übergeordneten Protokollierer. Diese Methode sollte nicht von einer Anwendung aufgerufen werden. Sie wird vom Log-Manager benutzt, wenn Änderungen am Namensraum durchgeführt werden, in denen die Protokollierer verwaltet werden.

public synchronized void setUseParentHandlers(boolean useParentHandlers)

Gibt an, ob dieser Protokollierer seine Protokolleinträge an die Handler des übergeordneten Protokollierers schicken soll.

public void severe(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.SEVERE. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public void throwing(String sourceClass, String sourceMethod, Throwable thrown)

Erzeugt einen Protokolleintrag. Der neue Protokolleintrag besitzt die Log-Ebene Level.FINER. Ein Throwable-Exemplar sowie die Namen von Klasse und Methoden, in denen der Protokolleintrag erzeugt wurde, werden der Methode übergeben. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.

public void warning(String msg)

Erzeugt einen Protokolleintrag mit der Log-Ebene Level.WARNING. Wenn der Protokollierer derart konfiguriert ist, dass die Protokolleinträge dieser Ebene verarbeitet werden, werden sie an alle registrierten Handler-Objekte weitergeleitet.