Diagnostics tutorial

Introduction
Main classes
Obtaining & using Diagnostics instances
Obtaining & using Diagnosis instances
Look-through Diagnosis
Outro & todo list

<< | >>

Look-through Diagnosis

PlainTextDiagnosis
It's the easiest kind of diagnosis. It begins with document name, short comment about this library and time of generating raport.
Then it puts structure containing hierarchy and time of work for each block (as for now loop blocks are treated the same way as standard blocks).
Nested blocks will be precedet with tab sign (\t). For example:

d.openBlock("A");
...
d.openBlock("B");
...
d.closeBlock("B");
...
d.closeBlock("A");

will give

A: ... ns
B: ... ns

Expression

d.openBlock("A");
...
d.openBlock("B");
...
d.closeBlock("A");
...
d.closeBlock("B");

gives the same result.
After printing gathered data, PlainTextDiagnosis prints several information about soft- and hardware, such as JVM info, JRE version, number of processor cores, amount of memory.

HtmlDiagnosis
It puts all parts of diagnosis in the same order as PlainTextDiagnosis, but adds HTML tags, such as <head> and <body>. Formatting goes along with options contained in Map<String, String>. This implementation have 3 methods saveToFile(...) - two inherited, and one new - saveToFile(String f, Map<String, String> options). Default saveToFile(String f) is equivalent to diagnosis.saveToFile(f, diagnosis.defaultMap()). defaultMap() return default Map<String, String> object with all needed options to format HTML.

List of options:
Each font option have 3 sub-options: bold, underlined, italic. That means, if you find on this list statement "header" - font for document header (t, t, t)
it means that there are options header.bold, header.italic, header.underlined and they are set for (in order) true, true, true (font sub-options get boolean values).

Option name	Option description	Default value
document.name	Name of document, placed in <title> tags	value given with setDocumentName()
document.tab	String used as tab (for nested blocks)
background.color	Color for statement <body bgcolor="...">	White
header	Font for document header	t, t, t
header.size	Size of document header font	5
comments	Font for comments, like this about time of generating document, etc	f, f, f
comments.size	Size of comments font	3
diagnosis.name	Font for block names	t, f, f
diagnosis.time	Font for block times	f, t, f
diagnosis.size	Size for diagnosis.name & diagnosis.time fonts	4
soft.header	Font for header of "Software" part	t, f, f
soft.name	Font for names of Software elements	f, f, t
soft.value	Font for values of Software elements	f, t, f
soft.size	Size of font for all soft fonts	4
hard.header	Font for header of "Hardware" part	t, f, f
hard.name	Font for names of Hardware elements	f, f, t
hard.value	Font for values of Hardware elements	f, t, f
hard.size	Size of font for all hard fonts	4

If you have any problem with that, just obtain some defaultMap(), get it's keySet(), iterate over it, and look how does it look. Remember, that in map you should insert true and false instead of t and f, it's only to shorten the table
How is it useful?
Most of positions are probably going to stay the same, but still, you can get any look you want.
For example if you prefer to have something like that:

A: ... ns
---B: ... ns

instead of

A: ... ns
B: ... ns

you just have to change one option:

HtmlDiagnosis diag=d.getHtmlDiagnosis("My diagnosis");
Map<String, String> m=diag.defaultMap();
m.put("document.tab", "---");
diag.saveToFile("myFile.html", m);

XMLDiagnosis
Saves diagnosis in XML format. In file you have:

<?xml version="1.0" encoding="UTF-8"?>
_document
_runtime

_document is:

<document>
   <name>
   document_name
   </name>
_blocks
</document>

_blocks is set of possibly nested blocks in format:

<block>
   <name>
   block_name
   </block>
   <time units="nanoseconds">
   block_time
   </time>
   _blocks
</block>

Part in red means that unit may be changed in next releases.
_runtime is:

<runtime>
    <OS>
        <name>
        system_name
        </name>
        <version>
        system_version
        </version>
        <architecture>
        system_architecture
        </architecture>
    </OS>
    <JRE>
        <version>
        JRE_version
        </version>
        <vendor>
        JRE_vendor
        </vendor>
    </JRE>
    <VM>
        <name>
        JVM_name
        </name>
        <version>
        JVM_version
        </version>
        <vendor>
        JVM_vendor
        </vendor>
    </VM>
    <processor>
        <cores>
        number_of_processor_cores
        </cores>
    </processor>
    <memory units="bytes">
        <free>
        number_of_free_memory_bytes
        </free>
        <max>
        number_of_max_memory_bytes
        </max>
        <total>
        number_of_total_memory_bytes
        </total>
    </memory>
</runtime>

LowLevelDiagnosis
This is diagnosis which is mainly used while developing this library. It doesn't really look nice, is hard to understand, because it's almost identical in look as the data stored in memory - not really good looking for a human eye, but useful for machine.

After all it has construction alike to PlainTextDiagnosis, but instead of classic block organisation you can see entries like
block_name-BEGIN(end: ... - begin: ... = ...)
or
block_name-END(end: ... - begin: ... = ...)
Its strongly connected with part 3 of page 4