xref: /external/apache-xml/test/java/src/org/apache/qetest/LoggingHandler.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.
 */
/*
 * $Id$
 */

/*
 *
 * LoggingHandler.java
 *
 */
package org.apache.qetest;


/**
 * Base class defining common functionality of logging handlers.
 * <p>Common functionality used for testing when implementing
 * various Handlers and Listeners.  Provides common ways to set
 * Loggers and levels, reset, and set expected errors or the
 * like.  Likely used to implement testing wrapper classes for
 * things like javax.xml.transform.ErrorListener and
 * org.xml.sax.ErrorHandler</p>
 * <p>The best description for this class can be seen in an
 * example; see trax.LoggingErrorHandler.java for one.</p>
 * @author shane_curcuru@lotus.com
 * @version $Id$
 */
public class LoggingHandler
{

    /**
     * Set a default handler for us to wrapper.
     * Often you may want to keep the default handler for some
     * operation while you're logging.  For subclasses that support
     * this call, they will log every operation, and then simply
     * call-through to this default handler.
     *
     * Subclasses should implement this and verify that the default
     * is of an appropriate type to use.
     *
     * @param default Object of the correct type to pass-through to;
     * throws IllegalArgumentException if null or incorrect type
     */
    public void setDefaultHandler(Object defaultHandler)
    {
        throw new java.lang.IllegalArgumentException("LoggingHandler.setDefaultHandler() is unimplemented!");
    }


    /**
     * Accessor method for our default handler; here returns null.
     *
     * @return default (Object) our default handler; null if unset
     */
    public Object getDefaultHandler()
    {
        return null;
    }


    /**
     * Get a list of counters of all items we've logged.
     * LoggingHandlers each will have various kinds or types of
     * things they handle (errors, warnings, messages, URIs, etc.).
     * They should keep a running tally of how many of each kind of
     * item they've 'handled'.
     *
     * @return array of int counters for each item we log;
     * subclasses should define constants for what each slot is
     */
    public int[] getCounters()
    {
        return NOTHING_HANDLED_CTR;
    }


    /**
     * Get a string representation of last item we logged.
     * For every item that we handle, subclasses should store a
     * String representation and return it here if asked.  Normally
     * this will only be a copy of the very last item we logged -
     * not necessarily what users might want, but the simplest to
     * implement everywhere.
     *
     * @return String of the last item handled
     */
    public String getLast()
    {
        return NOTHING_HANDLED;
    }


    /**
     * Reset any items or counters we've handled.
     * Resets any data about what we've handled or logged so far,
     * like getLast() and getCounters() data, as well as any
     * expected items from setExpected().  Does not change our
     * Logger or loggingLevel.
     */
    public void reset()
    {
        /* no-op */;
    }


    /**
     * Ask us to report checkPass/Fail for certain events we handle.
     * Since we may have to handle many events between when a test
     * will be able to call us, testers can set this to have us
     * automatically call checkPass when we see an item that matches,
     * or to call checkFail when we get an unexpected item.
     * Generally, we only call check* methods when:
     * <ul>
     * <li>containsString is not set, reset, or is ITEM_DONT_CARE,
     * we do nothing (i.e. never call check* for this item)</li>
     * <li>containsString is ITEM_CHECKFAIL, we will always call
     * checkFail with the contents of any item if it occours</li>
     * <li>containsString is anything else, we will grab a String
     * representation of every item of that type that comes along,
     * and if the containsString is found, case-sensitive, within
     * the handled item's string, call checkPass, otherwise
     * call checkFail</li>
     * <ul>
     * Note that most implementations will only validate the first
     * event of a specific type, and then will reset validation for
     * that event type.  This is because many events may be raised
     * in between the time that a calling Test class could tell us
     * of the 'next' expected event.
     * //@todo improve this paradigm to allow users to specify an
     * expected sequence of events.
     *
     * @param itemType which of the various types of items we might
     * handle; should be defined as a constant by subclasses
     * @param containsString a string to look for within whatever
     * item we handle - usually checked for by seeing if the actual
     * item we handle contains the containsString
     */
    public void setExpected(int itemType, String containsString)
    {
        /* no-op */;
    }


    /**
     * Accesor method for a brief description of this service.
     * Subclasses should obviously override to provide useful info.
     *
     * @return String "LoggingHandler: default implementation, does nothing"
     */
    public String getDescription()
    {
        return "LoggingHandler: default implementation, does nothing";
    }


    /**
     * Accesor methods for our Logger.
     *
     * @param l the Logger to have this test use for logging
     * results; or null to use a default logger
     */
    public void setLogger(Logger l)
	{
        // if null, set a default one
        if (null == l)
            logger = getDefaultLogger();
        else
            logger = l;
	}


    /**
     * Accesor methods for our Logger.
     *
     * @return Logger we tell all our secrets to.
     */
    public Logger getLogger()
	{
        return logger;
	}


    /**
     * Get a default Logger for use with this Handler.
     * Gets a default ConsoleLogger (only if a Logger isn't
     * currently set!).
     *
     * @return current logger; if null, then creates a
     * Logger.DEFAULT_LOGGER and returns that; if it cannot
     * create one, throws a RuntimeException
     */
    public Logger getDefaultLogger()
    {
        if (logger != null)
            return logger;

        try
        {
            Class rClass = Class.forName(Logger.DEFAULT_LOGGER);
            return (Logger)rClass.newInstance();
        }
        catch (Exception e)
        {
            // Must re-throw the exception, since returning
            //  null or the like could lead to recursion
            e.printStackTrace();
            throw new RuntimeException(e.toString());
        }
    }


    /**
     * Accesor methods for our loggingLevel.
     *
     * @param l what level we should call logger.logMsg()
     */
    public void setLoggingLevel(int l)
    {
        level = l;
    }


    /**
     * Accesor methods for our loggingLevel.
     *
     * @return what level we call logger.logMsg()
     */
    public int getLoggingLevel()
    {
        return level;
    }

    //-----------------------------------------------------------
    //---- Instance Variables and Constants
    //-----------------------------------------------------------

    /** Our Logger, who we tell all our secrets to. */
    protected Logger logger = null;

    /** What loggingLevel to use for reporter.logMsg(). */
    protected int level = Logger.DEFAULT_LOGGINGLEVEL;

    /** Default return value from getCounters() after a reset(). */
    public static final int[] NOTHING_HANDLED_CTR = { 0 };

    /** Default return value from getLast() after a reset(). */
    public static final String NOTHING_HANDLED = "NOTHING_HANDLED";

    /** Token for setExpected that we don't care (default value) about the event. */
    public static final String ITEM_DONT_CARE = "ITEM_DONT_CARE";

    /** Token for setExpected that we should call checkFail if we get the event. */
    public static final String ITEM_CHECKFAIL = "ITEM_CHECKFAIL";
}