src.org.grlea.log.package.html Maven / Gradle / Ivy
Show all versions of simple-log Show documentation
Simple Log: the simple way to log.
(See this package's description for the documentation.)
Sales Pitch
Simple Log is logging made easy.
Simple Log just works.
Er... I take that back.
You actually have to have a properties file called 'simplelog.properties' in your classpath, but it
doesn't have to contain anything.
Then Simple Log just works. : )
[Note: this is a feature: no properties file, no logging! Easy way to disable logging in deployment.]
I call Simple Log a "Logging Anti-Framework" because it is a library made in protest of the many
"logging frameworks" that exist.
Many of them are so "flexible" and "configurable" and "extendable" that you have to read an hour's
worth of documentation, learn XML and write a two-page configuration file before you can write one
message. Some of these things are so complicated they need
whole books to explain them!
Now, don't get me wrong - I'm happy to assume that these frameworks have become complex because new
features have been requested over time, and that some people use these frameworks for logging that
really is a bit different and requires something flexible that can be configured and extended and
what-not.
But most of the programs I write just don't need something like that. I need something simple that
just prints stuff to the console, works with a minimum of effort and lets me change the logging
level easily to see only the stuff I want to see.
And that's what Simple Log does. (Mmmmm... and a whole lot more, but simply.)
Design Goals
So, as you may have guessed, the whole idea of Simple Log is to be simple.
The second design goal was to make calls into the API brief, so that you don't have 3/4 of a line of
code before you get to your actual log message.
The third design goal was to have a *really* easy configuration file.
The fourth goal was to make the API as simple as possible. To me, this means you have to know about
as few classes as possible. (There's only three, and you can get by only knowing about one of them!)
The fifth goal was to make the configuration of the loggers accessible through code.
The sixth goal was... to not have any more than five goals....
Types of Logs
SO! What kind of logging can you do with this thing?
I provide for four specific types of log messages:
-
"db" = Debug (see {@link org.grlea.log.SimpleLogger#db SimpleLogger.db()})
Lets you log a simple log message, e.g. "Got to the point where you thought it wasn't getting
to."
-
"dbo" = Debug Object
(see {@link org.grlea.log.SimpleLogger#dbo(DebugLevel,String,Object) SimpleLogger.dbo()})
Debugs the name and value of an object. Specially handled variants exist for all primitives,
Object[], byte[] and char[].
-
"dbe" = Debug Exception (see {@link org.grlea.log.SimpleLogger#dbe SimpleLogger.dbe()})
Special handling of exceptions that will print a stack trace (can be turned off).
-
Tracing (see {@link org.grlea.log.SimpleLogger#entry SimpleLogger.entry()} and
{@link org.grlea.log.SimpleLogger#exit SimpleLogger.exit()})
Logs entry to and exit from a method. Can be turned on/off independent of debug level.
(I think that was the 6th design goal...)
The following convenience methods are also provided as shortcuts to the above methods:
-
For logging strings:
{@link org.grlea.log.SimpleLogger#fatal(String) fatal(String)},
{@link org.grlea.log.SimpleLogger#error(String) error(String)},
{@link org.grlea.log.SimpleLogger#warn(String) warn(String)},
{@link org.grlea.log.SimpleLogger#info(String) info(String)},
{@link org.grlea.log.SimpleLogger#debug(String) debug(String)},
{@link org.grlea.log.SimpleLogger#verbose(String) verbose(String)} and
{@link org.grlea.log.SimpleLogger#ludicrous(String) ludicrous(String)}.
-
For logging exceptions:
{@link org.grlea.log.SimpleLogger#fatalException(Throwable) fatalException(Throwable)},
{@link org.grlea.log.SimpleLogger#errorException(Throwable) errorException(Throwable)} and
{@link org.grlea.log.SimpleLogger#warnException(Throwable) warnException(Throwable)}.
-
For logging objects:
{@link org.grlea.log.SimpleLogger#infoObject(String,Object) infoObject(String,Object)},
{@link org.grlea.log.SimpleLogger#infoObject(String,boolean) infoObject(String,boolean)},
{@link org.grlea.log.SimpleLogger#infoObject(String,int) infoObject(String,int)},
{@link org.grlea.log.SimpleLogger#debugObject(String,Object) debugObject(String,Object)},
{@link org.grlea.log.SimpleLogger#debugObject(String,boolean) debugObject(String,boolean)},
{@link org.grlea.log.SimpleLogger#debugObject(String,int) debugObject(String,int)},
{@link org.grlea.log.SimpleLogger#verboseObject(String,Object) verboseObject(String,Object)},
{@link org.grlea.log.SimpleLogger#verboseObject(String,boolean) verboseObject(String,boolean)},
{@link org.grlea.log.SimpleLogger#verboseObject(String,int) verboseObject(String,int)},
{@link org.grlea.log.SimpleLogger#ludicrousObject(String,Object)
ludicrousObject(String,Object)},
{@link org.grlea.log.SimpleLogger#ludicrousObject(String,boolean)
ludicrousObject(String,boolean)},
{@link org.grlea.log.SimpleLogger#ludicrousObject(String,int)
ludicrousObject(String,int)}
Advanced Features
Simple Log is easy to use, but not simplistic.
It has quite a few slightly advanced and very useful features, all of which are available without
having to write any extra code.
Core Features
- Package-based, hierarchical inheritance of debug levels and trace flags
- Set debug levels using levels numbers or names
- Special handling of exceptions, object arrays, byte arrays and char arrays
- API support for logging primitives
- Ability to turn tracing on and off independent of the debug level
Optional Features (i.e. turned off by default):
- Send log output to a file
- Generate log file names containing the date
- Append or overwrite log file output
- Log file rolling triggered by file size or time of day
- Reloading configuration
- Customisable log format
- Customisable date format (applied to all log formats)
- Instance-based logging records (as opposed to class-based)
- Programmatic access to configuration (might have to write code here!)
Basic How-To
To use Simple Log, you basically want to just create a SimpleLogger at the top of your class, like
this:
private static final SimpleLogger log = new SimpleLogger(HelloWorld.class);
and then use that logger through your class!
Too easy!
Example (w/ Output!)
Here's an example of how you might use Simple Log:
public class
HelloWorld
{
// Create a SimpleLogger:
private static final SimpleLogger log = new SimpleLogger(HelloWorld.class);
public static void
main(String[] argv)
{
try
{
// Use it!
log.entry("main()");
log.debug("About to print 'Hello World!'");
String helloWorldString = "'Hello World!'";
log.debugObject("helloWorldString", helloWorldString);
log.db(DebugLevel.L7_LUDICROUS, "I can't believe this library has a level called 'Ludicrous'!");
System.out.println(helloWorldString);
log.debug("Printed 'Hello World!'");
log.info("Did you get that?");
log.warn("This example is very contrived.");
}
catch (Throwable t)
{
// Just in case...
log.fatal("Something really unexpected dropped by.");
log.dbe(DebugLevel.L1_FATAL, t);
}
log.exit("main()");
}
The default output (remember, the format is configurable) from running this class
(assuming the debug level is set to 7 / Ludicrous and tracing is turned on) would be:
Fri 2004/11/26 21:10:32.618|>>>|main|HelloWorld|main()
Fri 2004/11/26 21:10:32.618| |main|HelloWorld|About to print 'Hello World!'
Fri 2004/11/26 21:10:32.618|---|main|HelloWorld|helloWorldString|'Hello World!'
Fri 2004/11/26 21:10:32.618| |main|HelloWorld|I can't believe this library has a level called 'Ludicrous'!
'Hello World!'
Fri 2004/11/26 21:10:32.618| |main|HelloWorld|Printed 'Hello World!'
Fri 2004/11/26 21:10:32.618| |main|HelloWorld|Did you get that?
Fri 2004/11/26 21:10:32.618| |main|HelloWorld|This example is very contrived.
Fri 2004/11/26 21:10:32.618|<<<|main|HelloWorld|main()