FileDocCategorySizeDatePackage
StreamHandler.javaAPI DocAndroid 1.5 API12968Wed May 06 22:41:04 BST 2009java.util.logging

StreamHandler

public class StreamHandler extends Handler
A {@code StreamHandler} object writes log messages to an output stream, that is, objects of the class {@link java.io.OutputStream}.

A {@code StreamHandler} object reads the following properties from the log manager to initialize itself:

  • java.util.logging.StreamHandler.level specifies the logging level, defaults to {@code Level.INFO} if this property is not found or has an invalid value.
  • java.util.logging.StreamHandler.filter specifies the name of the filter class to be associated with this handler, defaults to {@code null} if this property is not found or has an invalid value.
  • java.util.logging.StreamHandler.formatter specifies the name of the formatter class to be associated with this handler, defaults to {@code java.util.logging.SimpleFormatter} if this property is not found or has an invalid value.
  • java.util.logging.StreamHandler.encoding specifies the encoding this handler will use to encode log messages, defaults to {@code null} if this property is not found or has an invalid value.

This class is not thread-safe.

since
Android 1.0

Fields Summary
private OutputStream
os
private Writer
writer
private boolean
writerNotInitialized
Constructors Summary
public StreamHandler()
Constructs a {@code StreamHandler} object. The new stream handler does not have an associated output stream.

since
Android 1.0

        initProperties("INFO", null, "java.util.logging.SimpleFormatter",  //$NON-NLS-1$//$NON-NLS-2$
                null);
        this.os = null;
        this.writer = null;
        this.writerNotInitialized = true;
StreamHandler(OutputStream os)
Constructs a {@code StreamHandler} object with the supplied output stream. Default properties are read.

param
os the output stream this handler writes to.

        this();
        this.os = os;
StreamHandler(String defaultLevel, String defaultFilter, String defaultFormatter, String defaultEncoding)
Constructs a {@code StreamHandler} object. The specified default values will be used if the corresponding properties are not found in the log manager's properties.

        initProperties(defaultLevel, defaultFilter, defaultFormatter,
                defaultEncoding);
        this.os = null;
        this.writer = null;
        this.writerNotInitialized = true;
public StreamHandler(OutputStream os, Formatter formatter)
Constructs a {@code StreamHandler} object with the supplied output stream and formatter.

param
os the output stream this handler writes to.
param
formatter the formatter this handler uses to format the output.
throws
NullPointerException if {@code os} or {@code formatter} is {@code null}.
since
Android 1.0

        this();
        if (os == null) {
            // logging.2=The OutputStream parameter is null
            throw new NullPointerException(Messages.getString("logging.2")); //$NON-NLS-1$
        }
        if (formatter == null) {
            // logging.3=The Formatter parameter is null.
            throw new NullPointerException(Messages.getString("logging.3")); //$NON-NLS-1$
        }
        this.os = os;
        internalSetFormatter(formatter);
Methods Summary
voidclose(boolean closeStream)
Closes this handler, but the underlying output stream is only closed if {@code closeStream} is {@code true}. Security is not checked.

param
closeStream whether to close the underlying output stream.

        if (null != this.os) {
            if (this.writerNotInitialized) {
                initializeWritter();
            }
            write(getFormatter().getTail(this));
            try {
                this.writer.flush();
                if (closeStream) {
                    this.writer.close();
                    this.writer = null;
                    this.os = null;
                }
            } catch (Exception e) {
                // logging.15=Exception occurred when closing the output stream.
                getErrorManager().error(Messages.getString("logging.15"), e, //$NON-NLS-1$
                        ErrorManager.CLOSE_FAILURE);
            }
        }
public voidclose()
Closes this handler. The tail string of the formatter associated with this handler is written out. A flush operation and a subsequent close operation is then performed upon the output stream. Client applications should not use a handler after closing it.

throws
SecurityException if a security manager determines that the caller does not have the required permission.
since
Android 1.0

        LogManager.getLogManager().checkAccess();
        close(true);
public voidflush()
Flushes any buffered output.

since
Android 1.0

        if (null != this.os) {
            try {
                if (null != this.writer) {
                    this.writer.flush();
                } else {
                    this.os.flush();
                }
            } catch (Exception e) {
                // logging.16=Exception occurred while flushing the output stream.
                getErrorManager().error(Messages.getString("logging.16"), //$NON-NLS-1$
                        e, ErrorManager.FLUSH_FAILURE);
            }
        }
private voidinitializeWritter()

        this.writerNotInitialized = false;
        if (null == getEncoding()) {
            this.writer = new OutputStreamWriter(this.os);
        } else {
            try {
                this.writer = new OutputStreamWriter(this.os, getEncoding());
            } catch (UnsupportedEncodingException e) {
                /*
                 * Should not happen because it's checked in
                 * super.initProperties().
                 */
            }
        }
        write(getFormatter().getHead(this));
voidinternalSetOutputStream(java.io.OutputStream newOs)
Sets the output stream this handler writes to. Note it does nothing else.

param
newOs the new output stream

        this.os = newOs;
public booleanisLoggable(java.util.logging.LogRecord record)
Determines whether the supplied log record needs to be logged. The logging levels are checked as well as the filter. The output stream of this handler is also checked. If it is {@code null}, this method returns {@code false}.

Notice : Case of no output stream will return {@code false}.

param
record the log record to be checked.
return
{@code true} if {@code record} needs to be logged, {@code false} otherwise.
since
Android 1.0

        if (null == record) {
            return false;
        }
        if (null != this.os && super.isLoggable(record)) {
            return true;
        }
        return false;
public synchronized voidpublish(java.util.logging.LogRecord record)
Accepts a logging request. The log record is formatted and written to the output stream if the following three conditions are met:
  • the supplied log record has at least the required logging level;
  • the supplied log record passes the filter associated with this handler, if any;
  • the output stream associated with this handler is not {@code null}.
If it is the first time a log record is written out, the head string of the formatter associated with this handler is written out first.

param
record the log record to be logged.
since
Android 1.0

        try {
            if (this.isLoggable(record)) {
                if (this.writerNotInitialized) {
                    initializeWritter();
                }
                String msg = null;
                try {
                    msg = getFormatter().format(record);
                } catch (Exception e) {
                    // logging.17=Exception occurred while formatting the log record.
                    getErrorManager().error(Messages.getString("logging.17"), //$NON-NLS-1$
                            e, ErrorManager.FORMAT_FAILURE);
                }
                write(msg);
            }
        } catch (Exception e) {
            // logging.18=Exception occurred while logging the record.
            getErrorManager().error(Messages.getString("logging.18"), e, //$NON-NLS-1$
                    ErrorManager.GENERIC_FAILURE);
        }
public voidsetEncoding(java.lang.String encoding)
Sets the character encoding used by this handler. A {@code null} value indicates that the default encoding should be used.

param
encoding the character encoding to set.
throws
SecurityException if a security manager determines that the caller does not have the required permission.
throws
UnsupportedEncodingException if the specified encoding is not supported by the runtime.
since
Android 1.0

        //flush first before set new encoding
        this.flush();
        super.setEncoding(encoding);
        // renew writer only if the writer exists
        if (null != this.writer) {
            if (null == getEncoding()) {
                this.writer = new OutputStreamWriter(this.os);
            } else {
                try {
                    this.writer = new OutputStreamWriter(this.os, getEncoding());
                } catch (UnsupportedEncodingException e) {
                    /*
                     * Should not happen because it's checked in
                     * super.initProperties().
                     */
                    throw new AssertionError(e);
                }
            }
        }
protected voidsetOutputStream(java.io.OutputStream os)
Sets the output stream this handler writes to. If there's an existing output stream, the tail string of the associated formatter will be written to it. Then it will be flushed, closed and replaced with {@code os}.

param
os the new output stream.
throws
SecurityException if a security manager determines that the caller does not have the required permission.
throws
NullPointerException if {@code os} is {@code null}.

        if (null == os) {
            throw new NullPointerException();
        }
        LogManager.getLogManager().checkAccess();
        close(true);
        this.writer = null;
        this.os = os;
        this.writerNotInitialized = true;
private voidwrite(java.lang.String s)

        try {
            this.writer.write(s);
        } catch (Exception e) {
            // logging.14=Exception occurred when writing to the output stream.
            getErrorManager().error(Messages.getString("logging.14"), e, //$NON-NLS-1$
                    ErrorManager.WRITE_FAILURE);
        }