org.x4juli.handlers
Class WriterHandler

java.lang.Object
  java.util.logging.Handler
      org.x4juli.global.components.AbstractHandler
          org.x4juli.handlers.WriterHandler

All Implemented Interfaces:

Component, ExtendedHandler, Handler, OptionHandler

Direct Known Subclasses:

ConsoleHandler, FileHandler

public class WriterHandler

extends AbstractHandler

WriterHandler appends log events to a Writer.

Attribute	Description	Required
.autoflush	Flush the writer after every record publishing or not. Should correspond to buffered IO. Allowed values "true" or "false".	No. Default is true.
.encoding	Specifies the encoding of the logfile. Allowed are all supported encodings of the platform. Supported Encodings	No. Default is value of system property "file.encoding".
.writer	Writer to publish logrecords to. Value is the full qualified classname of the writer. Do not specifiy any writer if you are using a subclass (FileHandler, RollingFileHandler).	YES. Default is null, which will lead to errors.

WriterHandler can be configured programattically or using configuration by file. Do not use the default constructor in programattically use.

Logging API as a whole was originally done for Apache log4j. Juli is a port of main parts of that to complete the Java Logging APIs. All credits for initial idea, design, implementation, documentation belong to the log4j crew. This file was originally published by Ceki Gülcü. Please use exclusively the appropriate mailing lists for questions, remarks and contribution.

Since:

0.5

Author:

Boris Unckel

Field Summary

protected boolean	immediateFlush Immediate flush means that the underlying writer or output stream will be flushed at the end of each append operation.
protected java.io.Writer	writer This is the Writer where we will write to.

Fields inherited from class org.x4juli.global.components.AbstractHandler

active, closed, extFormatter, headFilter, manager, name, repository, tailFilter

Fields inherited from class java.util.logging.Handler

Constructor Summary

WriterHandler()
Default Constructor instantiation used for configuration by file.

WriterHandler(java.lang.String handlerName)
Utility Constructor - sets the formatter to null.

Method Summary

void	activateOptions() Activate the options that were previously set with calls to option setters. This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set. Subclasses have not set active to true, but call super as last statement!
protected void	appendLogRecord(ExtendedLogRecord record) Subclasses of AbstractHandler should implement this method to perform actual logging. See also AbstractHandler.publish(ExtendedLogRecord) method.
protected boolean	checkEntryConditions() This method determines if there is a sense in attempting to append.
void	close()
protected void	closeWriter() Close the underlying Writer.
void	configure() Configure all properties of the object. Subclasses should call super.configure() to ensure proper configuration.
protected java.io.OutputStreamWriter	createWriter(java.io.OutputStream os) Returns an OutputStreamWriter when passed an OutputStream.
void	flush()
java.lang.String	getFullQualifiedClassName() Determine performant the FullQualifiedClassName. Subclasses should overwrite this method. Dynamic determination is not recommended.
boolean	getImmediateFlush() Returns value of the ImmediateFlush option.
void	setImmediateFlush(boolean value) If the ImmediateFlush option is set to true, the appender will flush at the end of each write.
void	setWriter(java.io.Writer writer) Sets the Writer where the log output will go.
protected void	subAppend(ExtendedLogRecord record) Actual writing occurs here.
protected void	writeFooter() Write a footer as produced by the embedded formatter's Formatter.getTail(java.util.logging.Handler) method.
protected void	writeHeader() Write a header as produced by the embedded formatter's Formatter.getHead(java.util.logging.Handler) method.

Methods inherited from class org.x4juli.global.components.AbstractHandler

addFilter, clearFilters, finalize, getFilter, getFormatter, getLogger, getLoggerRepository, getMessageProperties, getName, getNonFloodingLogger, getProperty, getProperty, getProperty, isActive, isClosed, isLoggable, isLoggable, publish, publish, resetErrorCount, setFilter, setFormatter, setName, setObjectStore, toString

Methods inherited from class java.util.logging.Handler

getEncoding, getErrorManager, getLevel, reportError, setEncoding, setErrorManager, setLevel

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.x4juli.global.spi.ExtendedHandler

getEncoding, getErrorManager, getLevel, setEncoding, setErrorManager, setLevel

Field Detail

immediateFlush

protected boolean immediateFlush

Immediate flush means that the underlying writer or output stream will be flushed at the end of each append operation. Immediate flush is slower but ensures that each append request is actually written. If immediateFlush is set to false, then there is a good chance that the last few logs events are not actually written to persistent media if and when the application crashes.

The immediateFlush variable is set to true by default.

writer

protected java.io.Writer writer

This is the Writer where we will write to.

Constructor Detail

WriterHandler

public WriterHandler()

Default Constructor instantiation used for configuration by file. This automaticaly activatesOptions(). Avoid in programmatically use.

Calls @link{AbstractHandler#AbstractHandler()}.

Since:

0.5

WriterHandler

public WriterHandler(java.lang.String handlerName)

Utility Constructor - sets the formatter to null. Does not call activateOptions().

Parameters:

handlerName - of the current instance.

Since:

0.5

Method Detail

close

public void close()
           throws java.lang.SecurityException

Throws:

java.lang.SecurityException

closeWriter

protected void closeWriter()

Close the underlying Writer.

flush

public void flush()

setWriter

public void setWriter(java.io.Writer writer)

Sets the Writer where the log output will go. The specified Writer must be opened by the user and be writable.

The java.io.Writer will be closed when the appender instance is closed.

WARNING: Logging to an unopened Writer will fail.

Parameters:

writer - An already opened Writer.

Since:

0.5

createWriter

protected java.io.OutputStreamWriter createWriter(java.io.OutputStream os)

Returns an OutputStreamWriter when passed an OutputStream. The encoding used will depend on the value of the encoding property. If the encoding value is specified incorrectly the writer will be opened using the default system encoding (an error message will be printed to the loglog.

setImmediateFlush

public void setImmediateFlush(boolean value)

If the ImmediateFlush option is set to true, the appender will flush at the end of each write. This is the default behavior. If the option is set to false, then the underlying stream can defer writing to physical medium to a later time.

Avoiding the flush operation at the end of each append results in a performance gain of 10 to 20 percent. However, there is safety tradeoff involved in skipping flushing. Indeed, when flushing is skipped, then it is likely that the last few log events will not be recorded on disk when the application exits. This is a high price to pay even for a 20% performance gain.

getImmediateFlush

public boolean getImmediateFlush()

Returns value of the ImmediateFlush option.

activateOptions

public void activateOptions()

Activate the options that were previously set with calls to option setters.

This allows to defer activiation of the options until all options have been set. This is required for components which have related options that remain ambigous until all are set.
Subclasses have not set active to true, but call super as last statement!

Specified by:

activateOptions in interface OptionHandler

Overrides:

activateOptions in class AbstractHandler

configure

public void configure()

Configure all properties of the object. Subclasses should call super.configure() to ensure proper configuration.

Overrides:

configure in class AbstractHandler

getFullQualifiedClassName

public java.lang.String getFullQualifiedClassName()

Determine performant the FullQualifiedClassName. Subclasses should overwrite this method. Dynamic determination is not recommended.

Specified by:

getFullQualifiedClassName in interface ExtendedHandler

Overrides:

getFullQualifiedClassName in class AbstractHandler

Since:

0.5

appendLogRecord

protected void appendLogRecord(ExtendedLogRecord record)

Subclasses of AbstractHandler should implement this method to perform actual logging. See also AbstractHandler.publish(ExtendedLogRecord) method.

Specified by:

appendLogRecord in class AbstractHandler

Parameters:

record - to write to the log

subAppend

protected void subAppend(ExtendedLogRecord record)

Actual writing occurs here.

Most subclasses of WriterAppender will need to override this method.

Since:

0.5

checkEntryConditions

protected boolean checkEntryConditions()

This method determines if there is a sense in attempting to append.

It checks whether there is a set output target and also if there is a set layout. If these checks fail, then the boolean value false is returned.

writeFooter

protected void writeFooter()

Write a footer as produced by the embedded formatter's Formatter.getTail(java.util.logging.Handler) method.

writeHeader

protected void writeHeader()

Write a header as produced by the embedded formatter's Formatter.getHead(java.util.logging.Handler) method.