Tuesday, January 8, 2008

XINS: Splitting out Logdoc?

Talking to Anthony Goubard yesterday (of JLearnIt and AntCommander fame), I realized that adding features like SMTP- and SMS-support to a Web Services framework like XINS can hardly be considered good separation of concerns. So I definitely need to revise my XINS 3.0 wishlist.

Instead, it may be a much better idea to make XINS focus more on the Web Services functionality and split some technologies out. The main candidates seem to be Logdoc and the ServiceCaller framework:
In the picture the arrows indicate dependencies. So XINS would depend on Logdoc and the ServiceCaller framework and the latter would also depend on Logdoc.

Logdoc: What is it?
In this post I will focus on Logdoc.

So what is Logdoc and why would we want to separate that out from XINS? Is it useful for other projects as well?

IMHO the answer is "yes". Logdoc is a logging system based on the infamous Apache Log4J library that offers some features over Log4J:
  • registered logging categories: there is an explicit list of all logging categories, with documentation;
  • unique log messages: each log message is in a specific category and gets a specific number; this allows system administrators to enable or disable individual messages;
  • multi-locale: it is straight-forward to add a new language for log messages;
  • separation of concerns: the code does not bother with log levels, translations and categories, instead it just deals with a single log message (identified by ID) and it's parameters.
Logdoc code example
Here is an example of a piece of Java code that uses Logdoc, from the HTTPServiceCaller class (javadoc/source):
// Unknown host
if (exception instanceof UnknownHostException) {
Log.log_1102(url, params, duration);
Notice that there is no category, no creation of objects and no language-specific stuff.

Logdoc definitions
The key to the Logdoc system is the definition of categories and entries in XML. Every entry is within a single category. Translations can be specified in separate files, one per language/locale. So for example, for the XINS/Java Server Framework, the following files define all logdoc entries and their translations:

  • src/logdoc/server/log.xml - defines all categories and contained entries; each entry has a unique number, it specified a log level and optionally some parameters;
  • src/logdoc/server/translation-bundle-en_US.xml - defines all U.S. English translations for the log messages defined in the log.xml file;
  • src/logdoc/server/translation-bundle-fr_FR.xml - defines all French (France) translations;
Adding a new set of translations is as easy as adding one line to the log.xml and one translation-bundle-xx_XX.xml file, where xx is the ISO language code and XX is the ISO country code.

Now from these specifications, both code and documentation is automatically generated, XINS-style. Here is an example of generated Logdoc documentation:
Notice that there are 2 ways to find log entries: by category and by ID (see the Logdoc entry list link at the top).

More information
For more information on Logdoc, check out the section titled "Managing logs" in the XINS User Guide.

No comments:

Post a Comment