<?xml version='1.0'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 
               "http://docbook.org/xml/4.2/docbookx.dtd"
	       [
	       <!ENTITY copyright SYSTEM "copyright.xml">
	       ]>

<chapter label="Logging" id="20">
<title>
Logging
</title>

  <tocchap>
    <tocentry>
      Contents
    </tocentry>

    <toclevel1>
      <tocentry>
	<ulink url="#Logging"> Logging </ulink>
      </tocentry>
    </toclevel1>
    <toclevel1>
      <tocentry>
	<ulink url="#Logging LookupDiscovery"> Logging LookupDiscovery
	</ulink>
      </tocentry>

    </toclevel1>
  </tocchap>

<abstract>
<para>
This chapter deals with the logging API, which is used by Jini 2.
This can be used for auditing or debugging.
</para>
</abstract>

<sect1>
<title id="Logging">
Logging
</title>

<para>
Jini 2.0 introduced use of the <code>java.util.logging</code> package. This can be 
used for auditing, or possibly for debugging. 
The logging package allows an application to write to named logs. Typically
the name of a log is a package name. For example, the log for 
<code>LookupDiscovery</code> objects is <code>"net.jini.discovery.LookupDiscovery"</code>.
Each object will write a record of its activities to the class log. These messages
will have levels such as <code>SEVERE</code>, <code>INFO</code>, etc, down
to <code>FINEST</code>. For example, <code>LookupDiscovery</code> objects
will write these messages, among others:
<orderedlist>
<listitem>
<code>SEVERE</code> if a network interface is bad or not configured for multicast
</listitem>
<listitem>
<code>INFO</code> when any exception other than an <code>InterruptedIOException</code>
occurs while attempting unicast discovery 
</listitem>
<listitem>
<code>FINEST</code> whenever a discovered, discarded, or changed event is sent
</listitem>
</orderedlist>
</para>

<para>
In order to see what is put into a log, a <code>Handler</code> must be added to
the log. There are several supplied handlers, including:
<orderedlist>
<listitem>
  <code>ConsoleHandler</code>. This handler writes all log messages to the console
  that have <code>INFO</code> level or above. The format is given by the
  <code>SimpleFormatter</code> object, and just gives brief readable messages
</listitem>
<listitem>
  <code>FileHandler</code>. This handler writes all messages to a file, using an
  XML format. If you only want simple messages, this can be set to be a 
  <code>SimpleFormatter</code>
</listitem>
</orderedlist>
</para>

</sect1>


<sect1>
<title id="Logging LookupDiscovery">
Logging LookupDiscovery
</title>

<para>
A program to log activities of a <code>LookupDiscovery</code> object is
given by this program, which just adds logging to the earlier
<code>MulticastRegister</code> program
<programlisting>
<?program "basic/MulticastRegisterLogger.java"?>
</programlisting>
When this is run, a few messages will be printed to the console. A great deal
more will be written to the <code>mylog.txt</code> file, including a line
like
<programlisting>
FINEST:     discovered locator  = jini://jannote.jan.edu.au/
</programlisting>
whenever a lookup locator is found.
</para>
</sect1>


&copyright;
</chapter>
