diff --git a/usersguide.html b/usersguide.html index a8f9969..96b3205 100644 --- a/usersguide.html +++ b/usersguide.html @@ -153,7 +153,7 @@ that logging should be performed, before incurring the overhead of the logging m Yes, the logging methods will perform the same check, but only after resolving parameters.
-+By default the message priority should be no lower than info. +That is, by default debug message should not be seen in the logs. +
+External Boundries - Expected Exceptions. +
External Boundaries - Expected Exceptions.
This classification includes exceptions such as FileNotFoundException
-that cross API/SPI boundries, and are exposed to the user of a component/toolkit.
+that cross API/SPI boundaries, and are exposed to the user of a component/toolkit.
These are listed in the 'throws' clause of a method signature.
These exceptions should be caught immediatly prior to crossing +
+Appropriate handling of these exceptions depends upon the type +of code you are developing. +API's for utility functions and tools should log these at the debug level, +if they are caught at all by internal code. +
+For higher level frameworks and middleware components, +these exceptions should be caught immediatly prior to crossing the API/SPI interface back to user code-space, logged with full stack trace at info level, and rethrown. @@ -211,13 +224,20 @@ future analysis in the event that the exception is not caught and resolved as expected by the user's code.
External Boundries - Unexpected Exceptions. +
External Boundaries - Unexpected Exceptions.
This classification includes exceptions such as NullPointerException
-that cross API/SPI boundries, and are exposed to the user of a component/toolkit.
+that cross API/SPI boundaries, and are exposed to the user of a component/toolkit.
These are runtime exceptions/error that are NOT
listed in the 'throws' clause of a method signature.
These exceptions should be caught immediatly prior to crossing +
+Appropriate handling of these exceptions depends upon the type +of code you are developing. +API's for utility functions and tools should log these at the debug level, +if they are caught at all. +
+For higher level frameworks and middleware components,
+these exceptions should be caught immediatly prior to crossing
the API/SPI interface back to user code-space,
logged with full stack trace at info level,
and rethrown/wrapped as ComponentInternalError.
@@ -225,15 +245,17 @@ The assures that the log contains a record of the root cause for
future analysis in the event that the exception is not caught and
logged/reported as expected by the user's code.
Internal Boundries. +
Internal Boundaries. Exceptions that occur internally and are resolved internally. These should be logged when caught as debug or info messages, -at your discretion. +at the programmer's discretion.
Significant Internal Boundries. -Exceptions that cross over significant internal component boundries, such as networks. +
Significant Internal Boundaries. +This typically only applies to middleware components +that span networks or runtime processes. +Exceptions that cross over significant internal component boundaries, such as networks. These should be logged when caught as info messages. -Do not assume that such a (network) boundry will deliver exceptions to the 'other side'. +Do not assume that such a (process/network) boundary will deliver exceptions to the 'other side'.