libcore/logging/src/main/java/java/util/logging/Handler.java

/* 
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 * 
 *     http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */


package java.util.logging;

import java.nio.charset.Charset;
import java.security.AccessController;
import java.security.PrivilegedExceptionAction;
import java.io.UnsupportedEncodingException;

import org.apache.harmony.logging.internal.nls.Messages;

/**
 * A {@code Handler} object accepts a logging request and exports the desired
 * messages to a target, for example, a file, the console, etc. It can be
 * disabled by setting its logging level to {@code Level.OFF}.
 * 
 * @since Android 1.0
 */
public abstract class Handler {

    /*
     * -------------------------------------------------------------------
     * Constants
     * -------------------------------------------------------------------
     */
    private static final Level DEFAULT_LEVEL = Level.ALL;

    /*
     * -------------------------------------------------------------------
     * Instance variables
     * -------------------------------------------------------------------
     */

    // the error manager to report errors during logging
    private ErrorManager errorMan;

    // the character encoding used by this handler
    private String encoding;

    // the logging level
    private Level level;

    // the formatter used to export messages
    private Formatter formatter;

    // the filter used to filter undesired messages
    private Filter filter;

    // class name, used for property reading
    private String prefix;

    /*
     * -------------------------------------------------------------------
     * Constructors
     * -------------------------------------------------------------------
     */

    /**
     * Constructs a {@code Handler} object with a default error manager instance
     * {@code ErrorManager}, the default encoding, and the default logging
     * level {@code Level.ALL}. It has no filter and no formatter.
     * 
     * @since Android 1.0
     */
    protected Handler() {
        this.errorMan = new ErrorManager();
        this.level = DEFAULT_LEVEL;
        this.encoding = null;
        this.filter = null;
        this.formatter = null;
        this.prefix = this.getClass().getName();
    }

    /*
     * -------------------------------------------------------------------
     * Methods
     * -------------------------------------------------------------------
     */

    // get a instance from given class name, using Class.forName()
    private Object getDefaultInstance(String className) {
        Object result = null;
        if (null == className) {
            return result;
        }
        try {
            result = Class.forName(className).newInstance();
        } catch (Exception e) {
            //ignore
        }
        return result;
    }

    // get a instance from given class name, using context classloader
    private Object getCustomizeInstance(final String className)
            throws Exception {
        Class<?> c = AccessController.doPrivileged(new PrivilegedExceptionAction<Class<?>>() {
                    public Class<?> run() throws Exception {
                        ClassLoader loader = Thread.currentThread()
                                .getContextClassLoader();
                        if (null == loader) {
                            loader = ClassLoader.getSystemClassLoader();
                        }
                        return loader.loadClass(className);
                    }
                });
        return c.newInstance();
    }

    // print error message in some format
    void printInvalidPropMessage(String key, String value, Exception e) {
        // logging.12=Invalid property value for
        String msg = new StringBuilder().append(Messages.getString("logging.12"))  //$NON-NLS-1$
                .append(prefix).append(":").append(key).append("/").append( //$NON-NLS-1$//$NON-NLS-2$
                        value).toString();
        errorMan.error(msg, e, ErrorManager.GENERIC_FAILURE);
    }

    /*
     * init the common properties, including filter, level, formatter, and
     * encoding
     */
    @SuppressWarnings("unused")
    void initProperties(String defaultLevel, String defaultFilter,
            String defaultFormatter, String defaultEncoding) {
        LogManager manager = LogManager.getLogManager();

        //set filter
        final String filterName = manager.getProperty(prefix + ".filter"); //$NON-NLS-1$
        if (null != filterName) {
            try {
                filter = (Filter) getCustomizeInstance(filterName);
            } catch (Exception e1) {
                printInvalidPropMessage("filter", filterName, e1); //$NON-NLS-1$
                filter = (Filter) getDefaultInstance(defaultFilter);
            }
        } else {
            filter = (Filter) getDefaultInstance(defaultFilter);
        }

        //set level
        String levelName = manager.getProperty(prefix + ".level"); //$NON-NLS-1$
        if (null != levelName) {
            try {
                level = Level.parse(levelName);
            } catch (Exception e) {
                printInvalidPropMessage("level", levelName, e); //$NON-NLS-1$
                level = Level.parse(defaultLevel);
            }
        } else {
            level = Level.parse(defaultLevel);
        }

        //set formatter
        final String formatterName = manager.getProperty(prefix + ".formatter"); //$NON-NLS-1$
        if (null != formatterName) {
            try {
                formatter = (Formatter) getCustomizeInstance(formatterName);
            } catch (Exception e) {
                printInvalidPropMessage("formatter", formatterName, e); //$NON-NLS-1$
                formatter = (Formatter) getDefaultInstance(defaultFormatter);
            }
        } else {
            formatter = (Formatter) getDefaultInstance(defaultFormatter);
        }

        //set encoding
        final String encodingName = manager.getProperty(prefix + ".encoding"); //$NON-NLS-1$
        try {
            internalSetEncoding(encodingName);
        } catch (UnsupportedEncodingException e) {
            printInvalidPropMessage("encoding", encodingName, e); //$NON-NLS-1$
        }
    }

    /**
     * Closes this handler. A flush operation will be performed and all the
     * associated resources will be freed. Client applications should not use
     * this handler after closing it.
     * 
     * @throws SecurityException
     *             if a security manager determines that the caller does not
     *             have the required permission.
     *
     * @since Android 1.0             
     */
    public abstract void close();

    /**
     * Flushes any buffered output.
     * 
     * @since Android 1.0
     */
    public abstract void flush();

    /**
     * Accepts a logging request and sends it to the the target.
     * 
     * @param record
     *            the log record to be logged; {@code null} records are ignored.
     * @since Android 1.0
     */
    public abstract void publish(LogRecord record);

    /**
     * Gets the character encoding used by this handler, {@code null} for
     * default encoding.
     * 
     * @return the character encoding used by this handler.
     * @since Android 1.0
     */
    public String getEncoding() {
        return this.encoding;
    }

    /**
     * Gets the error manager used by this handler to report errors during
     * logging.
     * 
     * @return the error manager used by this handler.
     * @throws SecurityException
     *             if a security manager determines that the caller does not
     *             have the required permission.
     * @since Android 1.0            
     */
    public ErrorManager getErrorManager() {
        LogManager.getLogManager().checkAccess();
        return this.errorMan;
    }

    /**
     * Gets the filter used by this handler.
     * 
     * @return the filter used by this handler (possibly {@code null}).
     * @since Android 1.0
     */
    public Filter getFilter() {
        return this.filter;
    }

    /**
     * Gets the formatter used by this handler to format the logging messages.
     * 
     * @return the formatter used by this handler (possibly {@code null}).
     * @since Android 1.0
     */
    public Formatter getFormatter() {
        return this.formatter;
    }

    /**
     * Gets the logging level of this handler, records with levels lower than
     * this value will be dropped.
     * 
     * @return the logging level of this handler.
     * @since Android 1.0
     */
    public Level getLevel() {
        return this.level;
    }

    /**
     * Determines whether the supplied log record needs to be logged. The
     * logging levels will be checked as well as the filter.
     * 
     * @param record
     *            the log record to be checked.
     * @return {@code true} if the supplied log record needs to be logged,
     *         otherwise {@code false}.
     * @since Android 1.0
     */
    public boolean isLoggable(LogRecord record) {
        if (null == record) {
            throw new NullPointerException();
        }
        if (this.level.intValue() == Level.OFF.intValue()) {
            return false;
        } else if (record.getLevel().intValue() >= this.level.intValue()) {
            return null == this.filter || this.filter.isLoggable(record);
        }
        return false;
    }

    /**
     * Reports an error to the error manager associated with this handler,
     * {@code ErrorManager} is used for that purpose. No security checks are
     * done, therefore this is compatible with environments where the caller
     * is non-privileged.
     * 
     * @param msg
     *            the error message, may be {@code null}.
     * @param ex
     *            the associated exception, may be {@code null}.
     * @param code
     *            an {@code ErrorManager} error code.
     * @since Android 1.0
     */
    protected void reportError(String msg, Exception ex, int code) {
        this.errorMan.error(msg, ex, code);
    }

    /**
     * Sets the character encoding used by this handler. A {@code null} value
     * indicates the use of the default encoding. This internal method does
     * not check security.
     * 
     * @param newEncoding
     *            the character encoding to set.
     * @throws UnsupportedEncodingException
     *             if the specified encoding is not supported by the runtime.
     * @since Android 1.0
     */
    void internalSetEncoding(String newEncoding)
            throws UnsupportedEncodingException {
        // accepts "null" because it indicates using default encoding
        if (null == newEncoding) {
            this.encoding = null;
        } else {
            if (Charset.isSupported(newEncoding)) {
                this.encoding = newEncoding;
            } else {
                // logging.13=The encoding "{0}" is not supported.
                throw new UnsupportedEncodingException(Messages.getString(
                        "logging.13", //$NON-NLS-1$
                        newEncoding));
            }

        }
    }

    /**
     * Sets the character encoding used by this handler, {@code null} indicates
     * a default encoding.
     * 
     * @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             
     */
    public void setEncoding(String encoding) throws SecurityException,
            UnsupportedEncodingException {
        LogManager.getLogManager().checkAccess();
        internalSetEncoding(encoding);
    }

    /**
     * Sets the error manager for this handler.
     * 
     * @param em
     *            the error manager to set.
     * @throws NullPointerException
     *             if {@code em} is {@code null}.
     * @throws SecurityException
     *             if a security manager determines that the caller does not
     *             have the required permission.
     * @since Android 1.0
     */
    public void setErrorManager(ErrorManager em) {
        LogManager.getLogManager().checkAccess();
        if (null == em) {
            throw new NullPointerException();
        }
        this.errorMan = em;
    }

    /**
     * Sets the filter to be used by this handler.
     * 
     * @param newFilter
     *            the filter to set, may be {@code null}.
     * @throws SecurityException
     *             if a security manager determines that the caller does not
     *             have the required permission.
     * @since Android 1.0
     */
    public void setFilter(Filter newFilter) {
        LogManager.getLogManager().checkAccess();
        this.filter = newFilter;
    }

    /**
     * Sets the formatter to be used by this handler. This internal method does
     * not check security.
     * 
     * @param newFormatter
     *            the formatter to set.
     */
    void internalSetFormatter(Formatter newFormatter) {
        if (null == newFormatter) {
            throw new NullPointerException();
        }
        this.formatter = newFormatter;
    }

    /**
     * Sets the formatter to be used by this handler.
     * 
     * @param newFormatter
     *            the formatter to set.
     * @throws NullPointerException
     *             if {@code newFormatter} is {@code null}.
     * @throws SecurityException
     *             if a security manager determines that the caller does not
     *             have the required permission.
     * @since Android 1.0
     */
    public void setFormatter(Formatter newFormatter) {
        LogManager.getLogManager().checkAccess();
        internalSetFormatter(newFormatter);
    }

    /**
     * Sets the logging level of the messages logged by this handler, levels
     * lower than this value will be dropped.
     * 
     * @param newLevel
     *            the logging level to set.
     * @throws NullPointerException
     *             if {@code newLevel} is {@code null}.
     * @throws SecurityException
     *             if a security manager determines that the caller does not
     *             have the required permission.
     * @since Android 1.0
     */
    public void setLevel(Level newLevel) {
        if (null == newLevel) {
            throw new NullPointerException();
        }
        LogManager.getLogManager().checkAccess();
        this.level = newLevel;
    }
}