com.boylesoftware.cb2
Class BLErrors

java.lang.Object
  com.boylesoftware.cb2.BLErrors

All Implemented Interfaces:

java.io.Serializable

public class BLErrors

extends java.lang.Object

implements java.io.Serializable

Container for Business Level errors reported by a BLO. If a non-critical error happens in a BLO, it creates a BLErrors object in its business method, populates it with the error codes and possibly error descriptions, and then saves it in the BLO using setErrors protected method. In the business method result the BLO indicates to the caller, in a call-specific way, that there were errors. Given such a result, the caller then calls getLastErrors method on the BLO, which returns last saved BLErrors object with information about the errors and clears the internal BLO variable that stores BLErrors objects, so any consequent call to getLastErrors returns nothing until another business method sets the errors via a setErrors call.

Reporting errors using BLErrors objects, as opposed to throwing exceptions, is reserved to errors that are, in fact, normal business situations, rather then unexpected failures of the system. For example, let's assume that there is a BLO that represents some entity stored in the database and the entity has a name, which is unique. The user tries to create a new record in the database and enters a name that is already used. This is a normal business situation, quite expected, so the BLO, when requested to save the new record, does not throw any exception, but sets BLErrors instead and tells the presentation level (the caller of the business method) that it cannot save the record. The presentation level then asks the user to enter a different name and try to save the record again. However, if the record is accepted by the BLO, but during its attempt to actually insert the record into the database an unexpected underlying subsystem error happens, such as database connection is lost and the JDBC driver has thrown an SQLException, then the reaction of the BLO is to throw a BLException to indicate a critical unexpected failure.

Errors are identified by error codes and error descriptions are very optional. This is because error messages belong to the presentation level, so it is left on the presentation level implementation to interpret the error code and display correct error message to the user (or do something else to recover after the error), so the business level does not have to worry about how to formulate the error message right and in what language it should be if it is a multilingual application.

Version:

$Id: BLErrors.java,v 1.3 2004/04/16 21:43:27 levahim Exp $

Author:

Lev Himmelfarb

See Also:

Serialized Form

Field Summary

protected java.util.Map

errors The errors container.

Constructor Summary

BLErrors()
Creates an empty BLErrors object.

BLErrors(int initialCapacity)
Creates an empty BLErrors object.

Method Summary

void	addError(int error) Adds an error to the container.
void	addError(int error, java.lang.String description) Adds an error and its description to the container.
boolean	containsError(int error) Checks if there is the specified error in this BLErrors instance.
java.lang.String	getErrorDescription(int error) Gets the specified error's description.
int[]	getErrors() Gets all errors in this instance as an array or error codes.
int	size() Gets total number of errors in this instance.

Methods inherited from class java.lang.Object

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

Field Detail

errors

protected final java.util.Map errors

The errors container. Keys are error codes (objects of Integer) and values are error descriptions (objects of String). An error description can be empty string, but never null.

Constructor Detail

BLErrors

public BLErrors()

Creates an empty BLErrors object. Use BLErrors(int initialCapacity) constructor when you know in advance the number of errors you are going to put into the object - it helps to save memory and makes application more efficient.

BLErrors

public BLErrors(int initialCapacity)

Creates an empty BLErrors object. Use this constructor when you know in advance the number of errors you are going to put into the object.

Parameters:

initialCapacity - number of errors you are going to put into the object.

Method Detail

addError

public void addError(int error)

Adds an error to the container. The error description is set to an empty string by this method.

Parameters:

error - the error code.

addError

public void addError(int error,
                     java.lang.String description)

Adds an error and its description to the container.

Parameters:

error - the error code.

description - the error description, cannot be null, but can be an empty string.

containsError

public boolean containsError(int error)

Checks if there is the specified error in this BLErrors instance.

Parameters:

error - the error code.

Returns:

true if the specified error is among the errors contained within this instance.

getErrors

public int[] getErrors()

Gets all errors in this instance as an array or error codes.

Returns:

array of error codes.

getErrorDescription

public java.lang.String getErrorDescription(int error)

Gets the specified error's description.

Parameters:

error - the error code.

Returns:

the specified error's description or null if there is not such error in this instance.

size

public int size()

Gets total number of errors in this instance.

Returns:

number of errors.