[LANG-497] Addition of ContextedException and ContextedRuntimeException

• Type: New Feature
• Status: Closed
• Priority: Major
• Resolution: Fixed
• Fix Version/s: 3.0
• Component/s: lang.exception.*
• Assignee: Unassigned
• Reporter: Derek C. Ashmore
• Created: 25/Apr/09 09:31
• Updated: 07/Sep/10 08:04
• Resolved: 09/Aug/09 18:11

Description

This is a proposal for a feature addition.

These additional exceptions (checked and unchecked versions) provide an easier and safer
way for developers to provide context when generating checked exceptions. Often,
additional information, besides what's embedded in the exception cause, is needed
for developers to debug and correct a bug. Often, this additional information can
reduce the time it takes to replicate and fix a bug.

ContextedException are easier as developers don't need to be concerned
with formatting the exception message to include additional information
with the exception. Additional information is automatically included
in the message and printed stack trace. This often thins out exception
handling code.

ContextedException is safer as the additional code needed to embed additional
information in a normal exception tends to be tested less and is more vulnerable
to errors such as null pointer exceptions.

An unchecked version of this exception is provided by ContextedRuntimeException.

To use this class write code as follows:

try

{ ... }

catch (Throwable e)

{ throw new ContextedException("Error posting account transaction", e) .addLabeledValue("accountNumber", accountNumber) .addLabeledValue("amountPosted", amountPosted) .addLabeledValue("previousBalance", previousBalance) }

}

The value of the context information is automatically included in the exception message and
when the stack trace is printed in the log.

My motivation for contributing is that I've previous versions of this running
at four clients now – I'm tiered of copying this from client to client.

I've attached the two exceptions themselves along with working test cases. Every effort has been made
to adhere to your existing style, conventions, and standards. No changes are needed for any
existing files.

I ran the site generation – These additions pass your checkstyle reports.

To streamline the committers time, I'll be happy to make any needed changes to to get this
into 3.0.

I know you're busy – thanks for taking the time to at least review this proposal.

Issue Links

• relates to: LANG-648 Require an improved Exception APIs