Overview
This is a sample library that uses smartics-exceptions.
It shows a message bean oriented approach to separate the exception classes, with its single responsibility of 'typing' an exceptional event so that is can be caught and handled separately from the main course of actions, from the actual information describing the context in which that event has taken place.
The Scenario
This example contains a fictional service that provides resources identified by a simple resource ID. The example shows how an interface may be designed to cope with
- precondition,
- business and
- technical failures.
It also shows how the different actors that take part in the example may be separated to form different packages.
config- contains exception configuration types.exceptions- contains the basic exception types.resource- the business types.
The Service
The sample resource service is in its own package resource. There you find the resource service, the exception type, its message and logging code types.
Since this service is quite small, you might miss some actors, like the package central exception every exception of this package derives from, a code class that contains only resource related codes. The full picture of all participants would look more like this:
Codes
The CodeRange is a listing of all codes used in the project. Therefore it is part of a base package.
AnyLibCode is a tagging interface to unite all exception codes under one name. Derived from this interface is the AnyResourceCode tagging interface that has the same function as the AnyLibCode, except for the resource package only. Usually you need this interfaces only, if there a message or exception classes that share enumeration codes. Add them just in case they are really needed to reduce clutter in your packages.
The codes are defined as enumeration types. The general LibCodes provide codes for the base package. The resource package codes ResourceCode and ResourceLoggingCode define codes for exception and logging events.
Messages
Defining messages is straight forward. Add all information that is useful in given context. It enforces reuse, if you can use the same information in different contexts without making it obscure, which information is required in which scenario. If this is the case, add another message type.
Usually message types inherit from another to reduce redundancy. Mind that adding new message parameters to the base message may force changing message parameter indices in the derived classes. Please refer to Bug 712 for some details.
Exceptions
If you have message types, you usually reduce the number of exception classes. Only introduce a new exception type, if you want to enable your clients to catch and deal with exceptional events separately. If you do not have message types, you would also have to add exception types in case the context requires additional arguments to be passed to the exception event.
Using message types allows you to follow the best practice Design Exception Class Hierarchy.
Exception Package
The root exceptions, codes, messages and the code range are defined in the exceptions package.
Information on how to define smartics-exceptions can be found in the Quickstart and the user documentation.
Configuration
The library also chooses to configure the design of the error codes. You will find some information on this in the config package.
For details on configuration of smartics-exceptions, please refer to Customize Core and Customize I18N.