com.webmethods.portal
Class PortalException

java.lang.Object
  java.lang.Throwable
      java.lang.Exception
          com.webmethods.portal.PortalException

All Implemented Interfaces:

Serializable

public class PortalException
extends Exception

Basic class for all exceptions thrown inside the portal framework. This class supports "nested exceptions" concept, i.e. portal exceptions can wrap other thrown exceptions - this allows the system to propagate the execution stack trace, facilitating debugging.

 try {
      // Some code throws exception here
 ...
 } catch (Exception exc) {
      throw new PortalException(exc);
 }
 

You may dynmically extend the PortalException by implementing the PortalException.IPortalExceptionDelegate interface and registering your implementation with the portal.

The PortalException uses the registered delegate each time a new PortalException is constructed. It will invoke the IPortalExceptionDelegate.exceptionThrown function which gives the delegate an opprotunity to replace the original exception with a custom exception.

To register an exception delegate modify the setenv.bat/setenv.sh to have the following line: set JAVA_OPTIONS=%JAVA_OPTIONS% -DportalException.delegate=your.exception.delegate.class.name

The following is a simple example of an IPortalExceptionDelegate:

 

import java.sql.SQLException;

public class SampleExceptionDelegate implements PortalException.IPortalExceptionDelegate {

    public void initialize() {
    }

    public Throwable exceptionThrown(String message, Throwable target, PortalException portalException) {
        return new CustomException(message, target);
    }

    public class CustomException extends Exception {
        public CustomException(String message, Throwable cause) {
            super(message, cause);
        }

        public String getMessage() {
            Throwable t = getCause();
            if (t == null) {
                return super.getMessage();
            }

            if (t instanceof SQLException) {
                return "SQLException: " + super.getMessage();
            }

            return "Unknown Exception:" + super.getMessage();
        }
    }
}

 
 

See Also:

PortalException.IPortalExceptionDelegate, Serialized Form

Nested Class Summary

static interface

PortalException.IPortalExceptionDelegate The PortalException uses the registered delegate each time a new PortalException is constructed.

Field Summary

protected static String	CURRENT_ERROR_LIST
static String	EXCEPTION_DELEGATE_CLASS_NAME
protected Object	m_context
protected List	m_errorList
protected boolean	m_ignoreTargetMessage
protected boolean	m_isExpected
protected boolean	m_isLocalizable
protected Object[]	m_messageArgs
protected IMessageInfo	m_messageInfo
protected String	m_messageKey
protected Class	m_resBundleClass
protected Throwable	m_target
protected static PortalException.IPortalExceptionDelegate	s_portalExceptionDelegate

Constructor Summary

protected	PortalException() Deprecated.
	PortalException(Class resourceBundleClass, String messageKey) Constructor to create a localized exception message.
	PortalException(Class resourceBundleClass, String messageKey, Object[] messageArgs) Constructor to create a localized bundle.
	PortalException(String message) Deprecated.
	PortalException(String message, boolean isExpected) Deprecated.
	PortalException(String message, Throwable target) Deprecated.
	PortalException(String message, Throwable target, boolean isExpected) Deprecated.
	PortalException(Throwable target) Construct exception instance with nested exception only.
	PortalException(Throwable target, boolean isExpected) Constructs exception with nested exception only.
	PortalException(Throwable target, Class resourceBundleClass, String messageKey) Constructor to create a localized exception message.
	PortalException(Throwable target, Class resourceBundleClass, String messageKey, Object[] messageArgs) Constructor to create a localized bundle.

Method Summary

static void	addDetailsMesasge(IMessageInfo messageInfo) When an exception is about to be thrown, you might want to add an explanatory message to the exception.
static void	addDetailsMessage(String msg) Deprecated. (use the new local specific)
protected void	checkExpected(Throwable thrown) "inherit" expected flag from the specified exception
Throwable	getCause() Get the thrown target exception if any was assigned
Object	getContext() Get context object associated with the exception (if any).
List	getErrorList() Return error list reference if any were created.
List	getErrorList(boolean localize) Return error list reference if any were created.
protected IGlobalProvider	getGlobalProvider()
String	getLocalizedMessage() Localize the message
String	getMessage() Returns a message from the exception.
String	getMessageKey()
Throwable	getTargetException() Get the thrown target exception if any was assigned
protected void	initDetailsMessage() Initializes details message list.
boolean	isExpected() Identifies whether particular exception was expected or not.
static PortalException	notImplemented(String methodName) Allows throwing "not implemented" exception.
void	printFullStackTrace() Overridden behavior of Exception.
void	printFullStackTrace(PrintWriter s) Overridden behavior of Exception.
void	printStackTrace() Overridden behavior of Exception.
void	printStackTrace(PrintStream s) Overridden behavior of Exception.
void	printStackTrace(PrintWriter s) Overridden behavior of Exception.
static void	reset() Resets any error messages.
static PortalException	reuseOrWrapException(Throwable t)
void	setContext(Object context) Assigns context object to provide additional information about exception (if necessary).
void	setExpected(boolean value) Specify whether particular exception was expected or not.
void	setIgnoreTargetMessage(boolean value) Specify whether the exception error message should ignore the target exception.

Methods inherited from class java.lang.Throwable

fillInStackTrace, getStackTrace, initCause, setStackTrace, toString

Methods inherited from class java.lang.Object

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

Field Detail

EXCEPTION_DELEGATE_CLASS_NAME

public static final String EXCEPTION_DELEGATE_CLASS_NAME

See Also:

Constant Field Values

CURRENT_ERROR_LIST

protected static final String CURRENT_ERROR_LIST

See Also:

Constant Field Values

m_target

protected Throwable m_target

m_context

protected Object m_context

m_errorList

protected List m_errorList

m_isExpected

protected boolean m_isExpected

m_isLocalizable

protected boolean m_isLocalizable

m_resBundleClass

protected Class m_resBundleClass

m_messageKey

protected String m_messageKey

m_messageArgs

protected Object[] m_messageArgs

m_ignoreTargetMessage

protected boolean m_ignoreTargetMessage

m_messageInfo

protected transient IMessageInfo m_messageInfo

s_portalExceptionDelegate

protected static PortalException.IPortalExceptionDelegate s_portalExceptionDelegate

See Also:

PortalException.IPortalExceptionDelegate

Constructor Detail

PortalException

public PortalException(Throwable target)

Construct exception instance with nested exception only.

Parameters:

target - Nested exception

PortalException

public PortalException(Throwable target,
                       boolean isExpected)

Constructs exception with nested exception only.

Parameters:

target - Nested exception

isExpected - Expected exception flag

PortalException

public PortalException(Class resourceBundleClass,
                       String messageKey)

Constructor to create a localized exception message. The ResourceBundle will be inferred from the source paramter The messageKey will be used to obtain the correct localized message

PortalException

public PortalException(Class resourceBundleClass,
                       String messageKey,
                       Object[] messageArgs)

Constructor to create a localized bundle. The ResourceBundle will be inferred from the source paramter The messageKey will be used to obtain the correct localized message The messageArgs will be used to format the messag

PortalException

public PortalException(Throwable target,
                       Class resourceBundleClass,
                       String messageKey)

Constructor to create a localized exception message. The ResourceBundle will be inferred from the source paramter The messageKey will be used to obtain the correct localized message

PortalException

public PortalException(Throwable target,
                       Class resourceBundleClass,
                       String messageKey,
                       Object[] messageArgs)

Constructor to create a localized bundle. The ResourceBundle will be inferred from the source paramter The messageKey will be used to obtain the correct localized message The messageArgs will be used to format the messag

PortalException

protected PortalException()

Deprecated.

Default constructor without any parameters.

PortalException

public PortalException(String message,
                       Throwable target,
                       boolean isExpected)

Deprecated.

Constructs an exception instance with a target exception and detailed message.

Parameters:

message - Exception message

target - Nested exception

isExpected - Expected exception flag

PortalException

public PortalException(String message)

Deprecated.

Construct exception with message only.

Parameters:

message - Exception message

PortalException

public PortalException(String message,
                       boolean isExpected)

Deprecated.

Constructor that takes a detail message and expected flag

Parameters:

message - Exception message

isExpected - Expected exception flag

PortalException

public PortalException(String message,
                       Throwable target)

Deprecated.

Constructs exception instance with target exception and detail message. Inherits nested exception expected capability

Parameters:

message - Exception message

target - Nested exception

Method Detail

getTargetException

public Throwable getTargetException()

Get the thrown target exception if any was assigned

Returns:

Nested exception if any assigned

See Also:

PortalException.m_target

getCause

public Throwable getCause()

Get the thrown target exception if any was assigned

Overrides:

getCause in class Throwable

Returns:

Nested exception if any assigned

See Also:

PortalException.m_target

getMessage

public String getMessage()

Returns a message from the exception. If target (wrapped) exception was specified then its message is returned.

Overrides:

getMessage in class Throwable

Returns:

Exception message

getMessageKey

public String getMessageKey()

getLocalizedMessage

public String getLocalizedMessage()

Localize the message

Overrides:

getLocalizedMessage in class Throwable

printStackTrace

public void printStackTrace(PrintWriter s)

Overridden behavior of Exception. Prints stack trace to the PrintWriter. Overridden to allow Log4J to correctly print wrapped exceptions. The trick is that when we have nested exception we should print its stack trace instead of ours.

Overrides:

printStackTrace in class Throwable

Parameters:

s - PrintWriter instance

printFullStackTrace

public void printFullStackTrace(PrintWriter s)

Overridden behavior of Exception. Overridden to allow Log4J to correctly print wrapped exceptions. Uses default writer.

Parameters:

s - PrintWriter instance

printStackTrace

public void printStackTrace(PrintStream s)

Overridden behavior of Exception. Prints stack trace to the PrintStream. Overridden to allow Log4J to correctly print wrapped exceptions.

Overrides:

printStackTrace in class Throwable

Parameters:

s - PrintStream instance

printStackTrace

public void printStackTrace()

Overridden behavior of Exception. Overridden to allow Log4J to correctly print wrapped exceptions. Uses default writer.

Overrides:

printStackTrace in class Throwable

printFullStackTrace

public void printFullStackTrace()

Overridden behavior of Exception. Overridden to allow Log4J to correctly print wrapped exceptions. Uses default writer.

setIgnoreTargetMessage

public void setIgnoreTargetMessage(boolean value)

Specify whether the exception error message should ignore the target exception.

Parameters:

value - true to ignore the target exception message, false otherwise

setExpected

public void setExpected(boolean value)

Specify whether particular exception was expected or not.

Parameters:

value - whether exception is expected or not

isExpected

public boolean isExpected()

Identifies whether particular exception was expected or not.

Returns:

whether this exception instance was expected or not

checkExpected

protected void checkExpected(Throwable thrown)

"inherit" expected flag from the specified exception

Parameters:

thrown - Exception instance to inherit expected flag

getContext

public Object getContext()

Get context object associated with the exception (if any).

Returns:

context object

setContext

public void setContext(Object context)

Assigns context object to provide additional information about exception (if necessary).

Parameters:

context - Context object reference

getErrorList

public List getErrorList()

Return error list reference if any were created.

Returns:

errors list, or empty list if none created

getErrorList

public List getErrorList(boolean localize)

Return error list reference if any were created. If localize is true, then any message info's will be localized as well

Returns:

errors list, or empty list if none created

notImplemented

public static PortalException notImplemented(String methodName)

Allows throwing "not implemented" exception.

 throw PortalException.notImplemented("SomeObject.someMethod");
 

Parameters:

methodName - Signature of the method to be implemented

Returns:

Instance of the PortalException to throw further

addDetailsMesasge

public static void addDetailsMesasge(IMessageInfo messageInfo)

When an exception is about to be thrown, you might want to add an explanatory message to the exception.

Unfortunately, you might not be in the code firing the exception, but in the code that clearly understands the details of the exception.

If so, add your message to the exception (to be thrown by you or someone else) with this API.

The constructor of the PortalException will gather these up and expose them with the call: PortalException.getErrorList()

Parameters:

messageInfo - Message to add to error list

See Also:

IMessageInfo

addDetailsMessage

public static void addDetailsMessage(String msg)

Deprecated. (use the new local specific)

When an exception is about to be thrown, you might want to add an explanatory message to the exception.

Unfortunately, you might not be in the code firing the exception, but in the code that clearly understands the details of the exception.

If so, add your message to the exception (to be thrown by you or someone else) with this API.

The constructor of the PortalException will gather these up and expose them with the call: PortalException.getErrorList()

Parameters:

msg - Message to add to error list

reset

public static void reset()

Resets any error messages.

See Also:

PortalException.addDetailsMessage(java.lang.String)

initDetailsMessage

protected void initDetailsMessage()

Initializes details message list.

getGlobalProvider

protected IGlobalProvider getGlobalProvider()

reuseOrWrapException

public static PortalException reuseOrWrapException(Throwable t)