root/trunk/src/java/org/jcoderz/commons/package.xml

Revision 1011, 11.5 kB (checked in by amandel, 4 years ago)

Aligned svn keyword settings.
  • Property svn:mime-type set to text/xml
  • Property svn:eol-style set to native
Line 
1<body>
2
3<quote author="Douglas Adams">
4Flying is learning how to throw yourself at the ground and miss.
5</quote>
6
7<section>
8   <title>Overview</title>
9   <section>
10      <title>Requirements</title>
11      <para>The following requirements dictate the logging
12      and exception handling concept (or just "logging" for short)
13      in the jCoderZ Commons project:
14      <ul>
15         <li>Common logging concepts should be used.
16         These concepts encompass:
17            <ul>
18               <li>use of Log Levels</li>
19               <li>use of distinct logger names</li>
20            </ul>
21         </li>
22         <li>Well proven logging concepts of previous projects
23         should be used.These concepts encompass:
24            <ul>
25               <li>use of a (pseudo-)unique "tracking number" that
26               is assigned per log event</li>
27               <li>use of a unique message id per log event type
28               that links to a knowledge base describing details
29               of the log event type</li>
30               <li>use of parameters as meta data</li>
31            </ul>
32         </li>
33         <li>All available context information that could be helpful
34         to track a problem should be logged.</li>
35         <li>The logging concept must be able to handle Java Exception
36         stacktraces.</li>
37         <li>The logging concept should easily integrate into
38         CA UniCenter.</li>
39         <li>The Java Logging API (java.util.logging) should be
40         used.</li>
41         <li>The Logging concept must support a nesting concept.</li>
42         <li>Any log event or exception with the log level INFO or
43         higher must be declared in a well-defined resource file
44         (XML).</li>
45         <li>The logging classes are only allowed to have a dependency
46         to the JDK classes.</li>
47      </ul>
48      </para>
49   </section>
50   <section>
51      <title>Data Model</title>
52
53      <para>The following table shows the required data that should
54      be associated with an log event or an exception. It also shows
55      the mapping of some field to the CA Unicenter log format.
56      </para>
57
58      <table frame="topbot">
59      <title>Available field of a log event and the corresponding
60      CA Unicenter mapping.</title>
61      <tgroup cols='2' align='left' colsep='1' rowsep='1'>
62      <thead>
63      <row>
64      <entry>Log Data</entry>
65      <entry>CA UniCenter field</entry>
66      </row>
67      </thead>
68      <tbody>
69      <row><entry>Log Level</entry><entry>Level</entry></row>
70      <row><entry>Tracking Number</entry><entry>Part of the textual description</entry></row>
71      <row><entry>Message ID</entry><entry>Message ID</entry></row>
72      <row><entry>Event Time (Date &amp; Time including ms)</entry><entry>Date, Time</entry></row>
73      <row><entry>Node ID (IP Address)</entry><entry>Node ID</entry></row>
74      <row><entry>Instance ID</entry><entry>Instance ID</entry></row>
75      <row><entry>Description</entry><entry>Part of the textual description</entry></row>
76      <row><entry>Logger Name</entry><entry>-</entry></row>
77      <row><entry>Thread ID</entry><entry>-</entry></row>
78      <row><entry>Stack</entry><entry>-</entry></row>
79      <row><entry>Cause</entry><entry>-</entry></row>
80      <row><entry>Arbitrary Parameters</entry><entry>-</entry></row>
81      </tbody>
82      </tgroup>
83      </table>
84
85      <para>
86      The section below give some more detail about data fields that are
87      not self-explanatory.
88      </para>
89
90      <section>
91         <title>Log data field description</title>
92         <para>
93         <section>
94            <title>Log Level</title>
95            <para>The Java Logging API defines the following log levels
96            (in descending order): SEVERE, WARNING, INFO, CONFIG, FINE,
97            FINER, FINEST. CA UniCenter defines the following log levels
98            (in descending order): FAIL, CRITICAL, WARNING, INFO.</para>
99
100            <para>To map Java Logging levels on CA UniCenter levels, an
101            additional "critical" flag is introduced in the log data
102            structure that may only be set when the log level is "WARNING".
103            Then the following mapping applies:
104            <table frame="topbot">
105            <title>Mapping of Java Logging Levels to CA UniCenter log levels.</title>
106            <tgroup cols='2' align='left' colsep='1' rowsep='1'>
107            <thead>
108            <row>
109            <entry>Java Logging Level</entry>
110            <entry>CA UniCenter Level</entry>
111            </row>
112            </thead>
113            <tbody>
114            <row><entry>CONFIG</entry><entry>INFO</entry></row>
115            <row><entry>INFO</entry><entry>INFO</entry></row>
116            <row><entry>WARNING</entry><entry>WARNING</entry></row>
117            <row><entry>WARNING with critical flag</entry><entry>CRITICAL</entry></row>
118            <row><entry>SEVERE</entry><entry>FAIL</entry></row>
119            </tbody>
120            </tgroup>
121            </table>
122            </para>
123         </section>
124
125         <section>
126            <title>Tracking Number</title>
127            <para>String with quasi-unique number as identifier for the
128            instance of the Loggable implementation. The tracking number
129            is a kind of message digest of a concrete log event instance
130            or exception. The tracking number makes it easy to locate the
131            line in the application log where a specific log events or
132            exception occurred. Thus, the tracking number should always
133            be reported to the peer (client) in case of an error.
134            </para>
135         </section>
136
137         <section>
138            <title>Message Identifier</title>
139            <para>Unique string identifying a conrecte message type. The
140            identifier is combined from the application short name, the
141            group short name and the message name, e.g.
142            <classname>FOO_RTE_INTERNAL_ERROR</classname>. The method
143            <methodname>getSymbol</methodname> in the interface
144            <classname>LogMessageInfo</classname> returns this message
145            identifier. There is also a unique integer representation for
146            a message identifier.
147            </para>
148         </section>
149
150         <section>
151            <title>Node Identifier</title>
152            <para>String as identifier of the node running the application
153            or service. This is always the IP-address of the machine.</para>
154         </section>
155
156         <section>
157            <title>Instance Identifier</title>
158            <para>String identifier for the application or service, which
159            logs the Loggable, e.g. the name of the Bea Managed Server.</para>
160         </section>
161
162         <section>
163            <title>Thread Identifier</title>
164            <para>An long value identifying the current thread that creates
165            the log event. This is not the thread identifier of the
166            underlying operation system, since this feature is only
167            available with the 1.5 version of the JDK.</para>
168         </section>
169
170         <section>
171            <title>Parameters</title>
172            <para>Optional parameters for a log event. A parameter is a
173            key value pair that can be assigned to a concrete log event
174            instance. Some of the parameters are required and enforced
175            to render the details message description.</para>
176         </section>
177
178         <section>
179            <title>Cause</title>
180            <para>A <classname>Throwable</classname>, that was the
181            reason for the log event or exception.
182            Note: a <classname>Loggable</classname> implements a
183            <classname>Throwable</classname>, so the cause for a log event
184            or exception might be another, a nested log event or
185            exception.</para>
186         </section>
187
188         </para>
189      </section>
190   </section>
191</section>
192
193<section>
194   <title>Logic</title>
195
196   <section>
197      <title>Logging vs. Exceptions</title>
198      <para>Most of the time, when a log event occurs, it will have
199      been caused by an exception. However, there are situations where
200      such an event is detected and must be logged without an exception.
201      Thus, we distinguish between a log event and a Loggable Exception,
202      which both have the log data described above.</para>
203
204      <para>The common log data is defined in the interface
205      <classname>Loggable</classname>. This interface is implemented by
206      the three base classes:
207      <ul>
208         <li><classname>BaseException</classname>,</li>
209         <li><classname>BaseRuntimeException</classname> and</li>
210         <li><classname>LogEvent</classname></li>
211      </ul>
212      Because Java doesn't support multi-inheritance, there are
213      two implementations of a base exception, the
214      <classname>BaseException</classname> for checked exception and
215      a second one, called <classname>BaseRuntimeException</classname>,
216      that is the base class for all unchecked (runtime) exceptions.
217      </para>
218
219      <diagram type="class" name="logevent">
220         <class name="org.jcoderz.commons.LogEvent"/>
221         <class name="org.jcoderz.commons.AuditLogEvent"/>
222         <class name="org.jcoderz.commons.Loggable"/>
223         <class name="org.jcoderz.commons.BaseException"/>
224         <class name="org.jcoderz.commons.BaseRuntimeException"/>
225         <description>
226         Class diagram of the base exceptions and log events.
227         </description>
228      </diagram>
229   </section>
230
231   <section>
232      <title>Log Message Info</title>
233      <para>Some data in a log event or exception is taken from the
234      current runtime environment, like the timestamp or stack trace,
235      and is not static for a specific log event type. However, there
236      are some kind of fields for a specific log event type that will never
237      change, like the unique identifier of the message or the
238      description text. These fields are static for a specific log event
239      or exception and are defined by the interface
240      <classname>LogMessageInfo</classname>.</para>
241
242      <diagram type="class" name="logmessageinfo">
243         <class name="org.jcoderz.commons.LogMessageInfo"/>
244         <description>
245         The LogMessageInfo interface defines static fields for a specific
246         log event or exception.
247         </description>
248      </diagram>
249   </section>
250
251</section>
252
253<section>
254   <title>Implementation</title>
255
256   <para>
257   All log events and exceptions are defined in an XML file
258   called <filename>app-info.xml</filename> with an well-defined schema.
259   The following snippets is a example message out of the XML file:
260
261      <pre>
262...
263&lt;message
264   id="1"
265   name="INTERNAL_ERROR"
266   level="SEVERE"
267   base-exception="org.jcoderz.commons.RuntimeErrorException"&gt;
268   &lt;text&gt;
269      The system encountered an unexpected condition, or contains
270      a software bug. Details: {TECHNICAL_DESCRIPTION}.
271   &lt;/text&gt;
272   &lt;solution&gt;
273      Review the log file to determine the problem that led
274      to the error condition. If appropriate, contact
275      The jCoderz Project.
276   &lt;/solution&gt;
277&lt;/message&gt;
278...</pre>
279
280   </para>
281
282   <para>Another dummy paragraph.</para>
283</section>
284
285<section>
286   <title>API Documentation</title>
287   <apidoc name="base">
288      <class name="org.jcoderz.commons.BaseException"/>
289      <class name="org.jcoderz.commons.BaseRuntimeException"/>
290      <class name="org.jcoderz.commons.Loggable"/>
291      <class name="org.jcoderz.commons.LogMessageInfo"/>
292      <class name="org.jcoderz.commons.LogEvent"/>
293      <class name="org.jcoderz.commons.AuditPrincipal"/>
294      <class name="org.jcoderz.commons.AuditLogEvent"/>
295   </apidoc>
296</section>
297
298</body>
Note: See TracBrowser for help on using the browser.