* This is primarily intended as a base class or support class to * be used in implementing other logging Handlers. *
* LogRecords are published to a given java.io.OutputStream. *
* Configuration: * By default each StreamHandler is initialized using the following * LogManager configuration properties where <handler-name> * refers to the fully-qualified class name of the handler. * If properties are not defined * (or have invalid values) then the specified default values are used. *
* For example, the properties for {@code StreamHandler} would be: *
* For a custom handler, e.g. com.foo.MyHandler, the properties would be: *
* @since 1.4 */ public class StreamHandler extends Handler { private OutputStream output; private boolean doneHeader; private volatile Writer writer; /** * Create a StreamHandler, with no current output stream. */ public StreamHandler() { // configure with specific defaults for StreamHandler super(Level.INFO, new SimpleFormatter(), null); } /** * Create a StreamHandler with a given Formatter * and output stream. *
* @param out the target output stream * @param formatter Formatter to be used to format output */ public StreamHandler(OutputStream out, Formatter formatter) { // configure with default level but use specified formatter super(Level.INFO, null, Objects.requireNonNull(formatter)); setOutputStreamPrivileged(out); } /** * @see Handler#Handler(Level, Formatter, Formatter) */ StreamHandler(Level defaultLevel, Formatter defaultFormatter, Formatter specifiedFormatter) { super(defaultLevel, defaultFormatter, specifiedFormatter); } /** * Change the output stream. *
* If there is a current output stream then the Formatter's * tail string is written and the stream is flushed and closed. * Then the output stream is replaced with the new output stream. * * @param out New output stream. May not be null. * @exception SecurityException if a security manager exists and if * the caller does not have LoggingPermission("control"). */ protected synchronized void setOutputStream(OutputStream out) throws SecurityException { if (out == null) { throw new NullPointerException(); } flushAndClose(); output = out; doneHeader = false; String encoding = getEncoding(); if (encoding == null) { writer = new OutputStreamWriter(output); } else { try { writer = new OutputStreamWriter(output, encoding); } catch (UnsupportedEncodingException ex) { // This shouldn't happen. The setEncoding method // should have validated that the encoding is OK. throw new Error("Unexpected exception " + ex); } } } /** * Set (or change) the character encoding used by this Handler. *
* The encoding should be set before any LogRecords are written * to the Handler. * * @param encoding The name of a supported character encoding. * May be null, to indicate the default platform encoding. * @exception SecurityException if a security manager exists and if * the caller does not have LoggingPermission("control"). * @exception UnsupportedEncodingException if the named encoding is * not supported. */ @Override public synchronized void setEncoding(String encoding) throws SecurityException, java.io.UnsupportedEncodingException { super.setEncoding(encoding); if (output == null) { return; } // Replace the current writer with a writer for the new encoding. flush(); if (encoding == null) { writer = new OutputStreamWriter(output); } else { writer = new OutputStreamWriter(output, encoding); } } /** * Format and publish a LogRecord. *
* The StreamHandler first checks if there is an OutputStream * and if the given LogRecord has at least the required log level. * If not it silently returns. If so, it calls any associated * Filter to check if the record should be published. If so, * it calls its Formatter to format the record and then writes * the result to the current output stream. *
* If this is the first LogRecord to be written to a given * OutputStream, the Formatter's "head" string is * written to the stream before the LogRecord is written. * * @param record description of the log event. A null record is * silently ignored and is not published */ @Override public synchronized void publish(LogRecord record) { if (!isLoggable(record)) { return; } String msg; try { msg = getFormatter().format(record); } catch (Exception ex) { // We don't want to throw an exception here, but we // report the exception to any registered ErrorManager. reportError(null, ex, ErrorManager.FORMAT_FAILURE); return; } try { if (!doneHeader) { writer.write(getFormatter().getHead(this)); doneHeader = true; } writer.write(msg); } catch (Exception ex) { // We don't want to throw an exception here, but we // report the exception to any registered ErrorManager. reportError(null, ex, ErrorManager.WRITE_FAILURE); } } /** * Check if this Handler would actually log a given LogRecord. *
* This method checks if the LogRecord has an appropriate level and * whether it satisfies any Filter. It will also return false if * no output stream has been assigned yet or the LogRecord is null. *
* @param record a LogRecord * @return true if the LogRecord would be logged. * */ @Override public boolean isLoggable(LogRecord record) { if (writer == null || record == null) { return false; } return super.isLoggable(record); } /** * Flush any buffered messages. */ @Override public synchronized void flush() { if (writer != null) { try { writer.flush(); } catch (Exception ex) { // We don't want to throw an exception here, but we // report the exception to any registered ErrorManager. reportError(null, ex, ErrorManager.FLUSH_FAILURE); } } } private synchronized void flushAndClose() throws SecurityException { checkPermission(); if (writer != null) { try { if (!doneHeader) { writer.write(getFormatter().getHead(this)); doneHeader = true; } writer.write(getFormatter().getTail(this)); writer.flush(); writer.close(); } catch (Exception ex) { // We don't want to throw an exception here, but we // report the exception to any registered ErrorManager. reportError(null, ex, ErrorManager.CLOSE_FAILURE); } writer = null; output = null; } } /** * Close the current output stream. *
* The Formatter's "tail" string is written to the stream before it
* is closed. In addition, if the Formatter's "head" string has not
* yet been written to the stream, it will be written before the
* "tail" string.
*
* @exception SecurityException if a security manager exists and if
* the caller does not have LoggingPermission("control").
*/
@Override
public synchronized void close() throws SecurityException {
flushAndClose();
}
// Package-private support for setting OutputStream
// with elevated privilege.
final void setOutputStreamPrivileged(final OutputStream out) {
AccessController.doPrivileged(new PrivilegedAction