Package ptolemy.util

Class MessageHandler

java.lang.Object

ptolemy.util.MessageHandler

All Implemented Interfaces:

java.lang.Thread.UncaughtExceptionHandler

Direct Known Subclasses:

MessageHandler, RecorderMessageHandler, SimpleMessageHandler, UndeferredGraphicalMessageHandler

public class MessageHandler
extends java.lang.Object
implements java.lang.Thread.UncaughtExceptionHandler

This is a class that is used to report errors. It provides a set of static methods that are called to report errors. However, the actual reporting of the errors is deferred to an instance of this class that is set using the setMessageHandler() method. Normally there is only one instance, set up by the application, so the class is a singleton. But this is not enforced.

This base class simply writes the errors to System.err. When an applet or application starts up, it may wish to set a subclass of this class as the message handler, to allow a nicer way of reporting errors. For example, a Swing application will probably want to report errors in a dialog box, using for example the derived class GraphicalMessageHandler.

See ptolemy.gui.GraphicalMessageHandler

Since:

Ptolemy II 4.0

Version:

$Id$

Author:

Edward A. Lee, Steve Neuendorffer, Elaine Cheong

Pt.AcceptedRating:

Green (cxh)

Pt.ProposedRating:

Green (cxh)

Constructor Summary

Constructors

Constructor	Description
MessageHandler()	Create a MessageHandler.

Method Summary

Modifier and Type	Method	Description
protected void	_error(java.lang.String info)	Show the specified error message.
protected void	_error(java.lang.String info, java.lang.Throwable throwable)	Show the specified message and throwable information.
protected void	_message(java.lang.String info)	Display the warning message.
protected void	_warning(java.lang.String info)	Show the specified message.
protected void	_warning(java.lang.String info, java.lang.Throwable throwable)	Display the warning message and throwable information.
protected boolean	_yesNoCancelQuestion(java.lang.String question, java.lang.String trueOption, java.lang.String falseOption, java.lang.String exceptionOption)	Ask the user a question with three possible answers; return true if the answer is the first one and false if the answer is the second one; throw an exception if the user selects the third one.
protected boolean	_yesNoQuestion(java.lang.String question)	Ask the user a yes/no question, and return true if the answer is yes.
static void	error(java.lang.String info)	Defer to the set message handler to show the specified error message.
static void	error(java.lang.String info, java.lang.Throwable throwable)	Defer to the set message handler to show the specified message and throwable information.
static MessageHandler	getMessageHandler()	Return the message handler instance that is used by the static methods in this class.
static boolean	isNonInteractive()	Return true if the current process is a non-interactive session.
static void	message(java.lang.String info)	Defer to the set message handler to show the specified message.
static void	setMessageHandler(MessageHandler handler)	Set the message handler instance that is used by the static methods in this class.
static void	setStatusHandler(StatusHandler handler)	Set the specified status handler, replacing any previously set handler.
static java.lang.String	shortDescription(java.lang.Throwable throwable)	Return a short description of the throwable.
static void	status(java.lang.String message)	Display a status message to the user.
void	uncaughtException(java.lang.Thread thread, java.lang.Throwable exception)	Handle uncaught exceptions in a standard way.
static void	warning(java.lang.String info)	Defer to the set message handler to show the specified message in a modal dialog.
static void	warning(java.lang.String info, java.lang.Throwable throwable)	Show the specified message and throwable information in a modal dialog.
static boolean	yesNoCancelQuestion(java.lang.String question)	Ask the user a yes/no/cancel question, and return true if the answer is yes.
static boolean	yesNoCancelQuestion(java.lang.String question, java.lang.String trueOption, java.lang.String falseOption, java.lang.String exceptionOption)	Ask the user a question with three possible answers; return true if the answer is the first one and false if the answer is the second one; throw an exception if the user selects the third one.
static boolean	yesNoQuestion(java.lang.String question)	Ask the user a yes/no question, and return true if the answer is yes.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MessageHandler

public MessageHandler()

Create a MessageHandler.

Method Detail

error

public static void error(java.lang.String info)

Defer to the set message handler to show the specified error message.

Note that within Ptolemy, most user code should not call this method directly. Instead, throw an exception, which will be caught by the system elsewhere and include information about what object caused the error.

Parameters:

info - The message.

error

public static void error(java.lang.String info,
                         java.lang.Throwable throwable)

Defer to the set message handler to show the specified message and throwable information. If the throwable is an instance of CancelException, then it is not shown. By default, only the message of the throwable is thrown. The stack trace information is only shown if the user clicks on the "Display Stack Trace" button.

Note that within Ptolemy, most user code should not call this method directly. Instead, throw an exception, which will be caught by the system elsewhere and include information about what object caused the error.

Parameters:

info - The message.

throwable - The throwable.

See Also:

CancelException

getMessageHandler

public static MessageHandler getMessageHandler()

Return the message handler instance that is used by the static methods in this class.

Returns:

The message handler.

See Also:

setMessageHandler(MessageHandler)

isNonInteractive

public static boolean isNonInteractive()

Return true if the current process is a non-interactive session. If the nightly build is running, then return true.

This method merely checks to see if the "ptolemy.ptII.isRunningNightlyBuild" property exists and is not empty or if the "ptolemy.ptII.batchMode" property exists and is not empty and the property "ptolemyII.ptII.testingMessageHandler" is not set.

To run the test suite in the Nightly Build mode, use

  make nightly
  

Returns:

True if the nightly build is running.

message

public static void message(java.lang.String info)

Defer to the set message handler to show the specified message. An implementation may block, for example with a modal dialog.

Parameters:

info - The message.

See Also:

status(String)

setMessageHandler

public static void setMessageHandler(MessageHandler handler)

Set the message handler instance that is used by the static methods in this class. If the given handler is null, then do nothing.

Parameters:

handler - The message handler.

See Also:

getMessageHandler()

setStatusHandler

public static void setStatusHandler(StatusHandler handler)

Set the specified status handler, replacing any previously set handler.

Parameters:

handler - The handler, or null to set no handler.

See Also:

status(String)

shortDescription

public static java.lang.String shortDescription(java.lang.Throwable throwable)

Return a short description of the throwable.

Parameters:

throwable - The throwable

Returns:

If the throwable is an Exception, return "Exception", if it is an Error, return "Error", if it is a Throwable, return "Throwable".

status

public static void status(java.lang.String message)

Display a status message to the user. This method is intended for keeping users informed of what is being done. The message may be displayed for a very short time and may be cleared after some time. This method is not intended for logging or for persistent messages, nor for messages that require some acknowledgement from the user. If a StatusHandler has been registered using #addStatusHandler(StatusHandler), then delegate displaying the message to that status handler. Otherwise, display on standard out.

Parameters:

message - The message to display.

See Also:

message(String)

uncaughtException

public void uncaughtException(java.lang.Thread thread,
                              java.lang.Throwable exception)

Handle uncaught exceptions in a standard way.

Specified by:

uncaughtException in interface java.lang.Thread.UncaughtExceptionHandler

Parameters:

thread - The thread throwing the exception.

exception - The exception.

warning

public static void warning(java.lang.String info)
                    throws CancelException

Defer to the set message handler to show the specified message in a modal dialog. If the user clicks on the "Cancel" button, then throw an exception. This gives the user the option of not continuing the execution, something that is particularly useful if continuing execution will result in repeated warnings.

Note that within Ptolemy, most user code should not call this method directly. Instead, throw an exception, which will be caught by the system elsewhere and include information about what object caused the warning.

Parameters:

info - The message.

Throws:

CancelException - If the user clicks on the "Cancel" button.

warning

public static void warning(java.lang.String info,
                           java.lang.Throwable throwable)
                    throws CancelException

Show the specified message and throwable information in a modal dialog. If the user clicks on the "Cancel" button, then throw an exception. This gives the user the option of not continuing the execution, something that is particularly useful if continuing execution will result in repeated warnings. By default, only the message of the throwable is thrown. The stack trace information is only shown if the user clicks on the "Display Stack Trace" button.

Note that within Ptolemy, most user code should not call this method directly. Instead, throw an exception, which will be caught by the system elsewhere and include information about what object caused the warning.

Parameters:

info - The message.

throwable - The throwable associated with this warning.

Throws:

CancelException - If the user clicks on the "Cancel" button.

yesNoQuestion

public static boolean yesNoQuestion(java.lang.String question)

Ask the user a yes/no question, and return true if the answer is yes. This method returns true without asking the user if the property "ptolemy.ptII.isRunningNightlyBuild" is set. In the regression tests, there is no user to answer the question.

Parameters:

question - The yes/no question.

Returns:

True if the answer is yes.

yesNoCancelQuestion

public static boolean yesNoCancelQuestion(java.lang.String question)
                                   throws CancelException

Ask the user a yes/no/cancel question, and return true if the answer is yes. If the user clicks on the "Cancel" button, then throw an exception.

Parameters:

question - The yes/no/cancel question.

Returns:

True if the answer is yes.

Throws:

CancelException - If the user clicks on the "Cancel" button.

yesNoCancelQuestion

public static boolean yesNoCancelQuestion(java.lang.String question,
                                          java.lang.String trueOption,
                                          java.lang.String falseOption,
                                          java.lang.String exceptionOption)
                                   throws CancelException

Ask the user a question with three possible answers; return true if the answer is the first one and false if the answer is the second one; throw an exception if the user selects the third one.

Parameters:

question - The question.

trueOption - The option for which to return true.

falseOption - The option for which to return false.

exceptionOption - The option for which to throw an exception.

Returns:

True if the answer is the first option, false if it is the second.

Throws:

CancelException - If the user selects the third option.

_error

protected void _error(java.lang.String info)

Show the specified error message.

Parameters:

info - The message.

_error

protected void _error(java.lang.String info,
                      java.lang.Throwable throwable)

Show the specified message and throwable information. If the throwable is an instance of CancelException, then nothing is not shown. By default, only the message of the exception is thrown. The stack trace information is only shown if the user clicks on the "Display Stack Trace" button.

Parameters:

info - The message.

throwable - The throwable.

See Also:

CancelException

_message

protected void _message(java.lang.String info)

Display the warning message. In this base class, the the default handler merely prints the warning to stderr.

Parameters:

info - The message.

_warning

protected void _warning(java.lang.String info)
                 throws CancelException

Show the specified message. In this base class, the message is printed to standard error.

Derived classes might show the specified message in a modal dialog. If the user clicks on the "Cancel" button, then throw an exception. This gives the user the option of not continuing the execution, something that is particularly useful if continuing execution will result in repeated warnings.

Parameters:

info - The message.

Throws:

CancelException - If the user clicks on the "Cancel" button.

_warning

protected void _warning(java.lang.String info,
                        java.lang.Throwable throwable)
                 throws CancelException

Display the warning message and throwable information. In this base class, the the default handler merely prints the warning to stderr. If the user clicks on the "Cancel" button, then throw an exception. This gives the user the option of not continuing the execution, something that is particularly useful if continuing execution will result in repeated warnings. By default, only the message of the throwable is thrown. The stack trace information is only shown if the user clicks on the "Display Stack Trace" button.

Parameters:

info - The message.

throwable - The Throwable.

Throws:

CancelException - If the user clicks on the "Cancel" button.

_yesNoQuestion

protected boolean _yesNoQuestion(java.lang.String question)

Ask the user a yes/no question, and return true if the answer is yes. In this base class, this prints the question on standard output and looks for the reply on standard input.

Parameters:

question - The yes/no question to be asked.

Returns:

True if the answer is yes.

_yesNoCancelQuestion

protected boolean _yesNoCancelQuestion(java.lang.String question,
                                       java.lang.String trueOption,
                                       java.lang.String falseOption,
                                       java.lang.String exceptionOption)
                                throws CancelException

Ask the user a question with three possible answers; return true if the answer is the first one and false if the answer is the second one; throw an exception if the user selects the third one.

Parameters:

question - The question.

trueOption - The option for which to return true.

falseOption - The option for which to return false.

exceptionOption - The option for which to throw an exception.

Returns:

True if the answer is the first option, false if it is the second.

Throws:

CancelException - If the user selects the third option.