org.crosswire.common.util
Class Reporter

java.lang.Object
  extended by org.crosswire.common.util.Reporter

public class Reporter
extends Object

This package looks after Exceptions and messages as they happen. It would be nice not to need this class - the principle being that any library that encounters an error can throw an exception to indicate that there is a problem. However this is not always the case. For example:

  • static class constructors should not throw, unless the class really is of no use given the error, and yet we may want to tell the user that there was a (non-critical) error.
  • Any library routine that works in a loop, applying some (potentially failing) functionality, may want to continue the work without throwing in response to a single error.
  • The class being implemented may implement an interface that disallows nested exceptions and yet does not want to loose the root cause error information. (This is the weakest of the above arguements, but probably still valid.)
  • However in many of the times this class is used, this is the reason:
  • Within UI specific code - to throw up a dialog box (or whatever). Now this use is currently tollerated, however it is probably a poor idea to use GUI agnostic messaging in a GUI specific context. But I'm not bothered enough to change it now. Specifically this use is deprecated because it makes the app more susceptible to the configuration of the things that listen to reports.
  • Distribution Licence:
    JSword is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 2 as published by the Free Software Foundation.
    This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
    The License is available on the internet here, or by writing to: Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
    The copyright to this program is held by it's authors.

    Version:
    $Id: Reporter.java,v 1.5 2004/11/28 21:36:31 joe Exp $
    Author:
    Joe Walker [joe at eireneh dot com]
    See Also:
    Licence

    Nested Class Summary
    static class Reporter.CustomAWTExceptionHandler
              A class to handle AWT caught Exceptions
     
    Field Summary
    private static String AWT_HANDLER_PROPERTY
              The system property name for registering AWT exceptions
    private static EventListenerList LISTENERS
              The list of listeners
    private static Logger log
              The log stream
    private static String OUR_NAME
              The name of the class to register for AWT exceptions
     
    Constructor Summary
    private Reporter()
              Enforce Singleton
     
    Method Summary
    static void addReporterListener(ReporterListener li)
              Add an Exception listener to the list of things wanting to know whenever we capture an Exception
    protected static void fireCapture(ReporterEvent ev)
              Log a message.
    static void grabAWTExecptions(boolean grab)
              Sets the parent of any exception windows.
    static void informUser(Object source, LucidException prob)
              Something has gone wrong.
    static void informUser(Object source, LucidRuntimeException prob)
              Something has gone wrong.
    static void informUser(Object source, MsgBase message)
              Something has happened.
    static void informUser(Object source, MsgBase message, Object param)
              Something has happened.
    static void informUser(Object source, MsgBase message, Object[] params)
              Something has happened.
    static void informUser(Object source, String message)
              Deprecated. Use informUser(Object source, MsgBase message) instead
    static void informUser(Object source, Throwable prob)
              Something has gone wrong.
    static void removeReporterListener(ReporterListener li)
              Remove an Exception listener from the list of things wanting to know whenever we capture an Exception
     
    Methods inherited from class java.lang.Object
    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    AWT_HANDLER_PROPERTY

    private static final String AWT_HANDLER_PROPERTY
    The system property name for registering AWT exceptions

    See Also:
    Constant Field Values

    OUR_NAME

    private static final String OUR_NAME
    The name of the class to register for AWT exceptions


    log

    private static final Logger log
    The log stream


    LISTENERS

    private static final EventListenerList LISTENERS
    The list of listeners

    Constructor Detail

    Reporter

    private Reporter()
    Enforce Singleton

    Method Detail

    informUser

    public static void informUser(Object source,
                                  Throwable prob)
    Something has gone wrong. We need to tell the user or someone, but we can carry on. In general having caught an exception and passed it to Reporter.informUser(), you should not throw another Exception. Called to fire a commandEntered event to all the Listeners

    Parameters:
    source - The cause of the problem, a Component if possible.
    prob - The Exception that was thrown TODO(joe): think about this - isn't this method useful? deprecated use either informUser(Object source, LucidException prob) or informUser(Object source, LucidRuntimeException prob)

    informUser

    public static void informUser(Object source,
                                  LucidException prob)
    Something has gone wrong. We need to tell the user or someone, but we can carry on. In general having caught an exception and passed it to Reporter.informUser(), you should not throw another Exception. Called to fire a commandEntered event to all the Listeners

    Parameters:
    source - The cause of the problem, a Component if possible.
    prob - The Exception that was thrown

    informUser

    public static void informUser(Object source,
                                  LucidRuntimeException prob)
    Something has gone wrong. We need to tell the user or someone, but we can carry on. In general having caught an exception and passed it to Reporter.informUser(), you should not throw another Exception. Called to fire a commandEntered event to all the Listeners

    Parameters:
    source - The cause of the problem, a Component if possible.
    prob - The Exception that was thrown

    informUser

    public static void informUser(Object source,
                                  String message)
    Deprecated. Use informUser(Object source, MsgBase message) instead

    Something has happened. We need to tell the user or someone.

    Parameters:
    source - The cause of the message, a Component if possible.
    message - The message to pass to the user

    informUser

    public static void informUser(Object source,
                                  MsgBase message)
    Something has happened. We need to tell the user or someone.

    Maybe we should have an extra parameter (or even several versions of this method like log*()) that describes the severity of the message. A Sw*ng listener could use this to decide the icon in the OptionPane for example.

    Parameters:
    source - The cause of the message, a Component if possible.
    message - The message to pass to the user

    informUser

    public static void informUser(Object source,
                                  MsgBase message,
                                  Object param)
    Something has happened. We need to tell the user or someone.

    Maybe we should have an extra parameter (or even several versions of this method like log*()) that describes the severity of the message. A Sw*ng listener could use this to decide the icon in the OptionPane for example.

    Parameters:
    source - The cause of the message, a Component if possible.
    message - The message to pass to the user
    param - The parameters to the message

    informUser

    public static void informUser(Object source,
                                  MsgBase message,
                                  Object[] params)
    Something has happened. We need to tell the user or someone.

    Maybe we should have an extra parameter (or even several versions of this method like log*()) that describes the severity of the message. A Sw*ng listener could use this to decide the icon in the OptionPane for example.

    Parameters:
    source - The cause of the message, a Component if possible.
    message - The message to pass to the user
    params - The parameters to the message

    addReporterListener

    public static void addReporterListener(ReporterListener li)
    Add an Exception listener to the list of things wanting to know whenever we capture an Exception


    removeReporterListener

    public static void removeReporterListener(ReporterListener li)
    Remove an Exception listener from the list of things wanting to know whenever we capture an Exception


    fireCapture

    protected static void fireCapture(ReporterEvent ev)
    Log a message.


    grabAWTExecptions

    public static void grabAWTExecptions(boolean grab)
    Sets the parent of any exception windows.


    Copyright ? 2003-2004