Code Controls Grace Software JavaLog $Revision: 1.4 $ $Date: 1999/10/28 11:17:23 $

Introduction

One sentence of caution, however: using code to manipulate the logging of events can make ones code less configurable at runtime by the end user. It is best to use these controls such that the end user has control over whether they are called. For example, it is useful for a program with a GUI to be able to enable or disable tracing if the user clicks on a dialog to enable tracing.

Errors, Warnings, Notices, and Traces

    public static void enableErrors(boolean);
    public static void enableWarnings(boolean);
    public static void enableNotices(boolean);
    public static void enableTraces(boolean);

So, at any point in the operation of the program, one can perform the
following bit of logic:

    Log.enableErrors(true);
    Log.error(...);
    Log.enableErrors(false);


One can determine if any of the basic event types are enabled by
calling the eventtypeEnabled() static functions:

    if (Log.tracesEnabled()) Log.enableTraces(false);


The above example only illustrates the use of the
Log.tracesEnabled() function.  One doesn't need to check
whether an event type is enabled or disabled before enabling or
disabling it.

General Event Type Enabling

From within the JVM

One can check and enable or disable any event type using the
calls:

 
    Log log = Log.getInstance();
    if (log.eventTypeEnabled("timing")) {
        log.enableEventType("timing", true);
    }


Notice, since these calls aren't static, they must call the static
getInstance() function to gain access to the singelton
Log object.

Outside the JVM

These functions may also be called from a remote virtual machine.
It's a handy way to control the logging of a server process.  The
following illustrates the steps to accomplish this:

  

  
Start server using -Dlog.server=true -Dlog.name=Foobar

  
From the remote controlling JVM, lookup the server's Distributer in the
  registry under the name "Foobar".  One can use
  java.rmi.Naming("rmi://host/log.distributer.Foobar");
  to find the Distributer in the registry.  One can also use
  grace.util.Registry.lookup("rmi://host/log.distributer.*")
   to find a list of distributers if the specific server name
  is not known.

  
Use the found distributer to call
  distributer.enableEventType(Log.TRACES);

  
   
Regular Expression Event Filtering

Events can also be filtered by regular expression.  This can be
specified by the log.events.include/exclude properties
or in code.  In code, this is done using the calls:

    public void setEventTypesToInclude(String filters);
    public void setEventTypesToExclude(String filters);


In both cases, the filter argument is a string separated list
of regular expressions, each expression acting to either include or
exclude an event.  So the code:

    Log log = Log.getInstance();
    log.setEventTypesToInclude("error warn.* tim.*");
    log.setEventTypesToExclude("timi.*");


will have the following effect on the following event types:

    error included
    warning included
    time included
    timing excluded


Regular Expression Function Filtering

As in the above event case, functions can also be filtered using a
space separated list of regular expressions.  The functions, are:

    public void setFunctionNamesToInclude(String filters);
    public void setFunctionNamesToExclude(String filters);


    Log log = Log.getInstance();
    log.setFunctionNamesToInclude("MyClass\\..*");
    log.setFunctionNamesToExclude("MyClass\\..toString");


will have the following effect on the following events:

    MyClass.doSomething() included
    MyClass.doAnotherThing() included
    MyClass.toString() excluded

   
Setting Different Properties

JavaLog loads its properties from System.getProperties() when it is
statically initialized.  The user can specify a different set of
properties using the call:

    public void loadProperties(java.util.Properties extraProperties);


However, these properties currently only effect the loading of the
above discussed filters.  In other words, they don't affect the
configuration of handlers or formatting, etc.  Eventually, this
functionality will be enabled.