/*
 * 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$
 */

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

/**
 * Minimal interface defining a testlet, a sort of mini-test.
 * A Testlet defines a single, simple test case that is completely
 * independent.  Commonly a Testlet will perform a single 
 * test operation and verify it, usually given a set of test 
 * data to perform the operation on.  
 *
 * <p>This makes creating data-driven tests simpler, by separating 
 * the test algorithim from the definition of the test data.  Note 
 * that logging what happened during the test is already separated 
 * out into the Logger interface.</p>
 * 
 * <p>Testlets are used with Datalets, which provide a single set 
 * of data to execute this test case with.
 * For example:</p>
 * <ul>
 *   <li>We define a Testlet that processes an XML file with a 
 *   stylesheet in a certain manner - perhaps using a specific 
 *   set of SAX calls.</li>
 *   <li>The Testlet takes as an argument a matching Datalet, that 
 *   defines any parameters that may change  - like the names 
 *   of the XML file and the stylesheet file to use.</li>
 *   <li>Test authors or users running a harness or the like can 
 *   then easily define a large set of Datalets for various 
 *   types of input files that they want to test, and simply 
 *   iterate over the set of Datalets, repeatedly calling 
 *   Testlet.execute().  Each execution of the Testlet will 
 *   be independent.</li>
 * </ul>
 * 
 * <p>Testlets may provide additional worker methods that allow them 
 * to be easily run in varying situations; for example, a 
 * testwriter may have a Test object that calls a number of Testlets 
 * for it's test cases.  If one of the Testlets finds a bug, the 
 * testwriter can simply reference the single Testlet and it's 
 * current Datalet in the bug report, without having to reference 
 * the enclosing Test file.  This makes it easier for others to 
 * reproduce the problem with a minimum of overhead.</p>
 *
 * @author Shane_Curcuru@lotus.com
 * @version $Id$
 */
public interface Testlet
{

    /**
     * Accesor method for a brief description of this Testlet.  
     * <p>Testlet implementers should provide a brief, one line 
     * description of the algorithim of their test case.</p>
     * //@todo do we need to define a setDescription() method?
     * Since Testlets are pretty self-sufficient, implementers 
     * should always just define this, and not let callers 
     * re-set them.
     *
     * @return String describing what this Testlet does.
     */
    public abstract String getDescription();


    /**
     * Accesor methods for our Logger.
     * <p>Testlets use simple Loggers that they rely on the caller 
     * to have setup.  This frees the Testlet and the Logger from 
     * having to store any other state about the Testlet.  It is 
     * the caller's responsibility to do any overall rolling-up 
     * or aggregating of results reporting, if needed.</p>
     *
     * @param l the Logger to have this test use for logging 
     * results; or null to use a default logger
     */
    public abstract void setLogger(Logger l);


    /**
     * Accesor methods for our Logger.  
     *
     * @return Logger we tell all our secrets to; may be null
     */
    public abstract Logger getLogger();


    /**
     * Get a default Logger for use with this Testlet.  
     * <p>Provided to allow subclasses to override this in different 
     * ways.  This would probably be called when setLogger(null) 
     * is called.  The most common implementation would be to 
     * return a Logger.DEFAULT_LOGGER (which simply 
     * logs things to the console).</p>
     *
     * //@todo this sort of functionality should really be provided 
     * by the Logger class itself - any caller should be able to ask 
     * Logger (or a Logger factory, if you want to get fancy) for a 
     * default Logger for use without having to supply any params.
     *
     * @return Logger suitable for passing to setLogger()
     */
    public abstract Logger getDefaultLogger();


    /**
     * Return this Testlet's default Datalet.  
     * <p>Every Testlet should have created a default Datalet that can 
     * be used with this test: i.e. the test case itself has a 
     * default, or sample set of data to execute the test with. This 
     * way a user can simply execute the Testlet on the fly without 
     * having to provide any input data.</p>
     * <p>If the Testlet can't provide a default Datalet, either 
     * the user must provide one somehow, or an error message 
     * should be printed out.  Note that the Testlet must still 
     * return a Datalet of the correct class from this method, even 
     * if the Datalet returned has no data set into it.  This would 
     * allow a harness with random test data generation capabilities 
     * to discover this Testlet, and then generate random Datalets to 
     * pass to it.</p>
     *
     * @return Datalet this Testlet can use as a default test case.
     */
    public abstract Datalet getDefaultDatalet();


    /**
     * Run this Testlet: execute it's test and return.
     * <p>The Testlet should perform it's test operation, logging 
     * information as needed to it's Logger, using the provided 
     * Datalet as a test point.</p>
     * <p>If the Datalet passed is null, the Testlet should use 
     * it's default Datalet as the test point data.</p>
     * <p>Testlets should not throw exceptions and should not 
     * return anything nor worry about checking their state or 
     * rolling up any overall results to their Logger.  Testlets 
     * should simply focus on performing their one test operation 
     * and outputting any simple pass/fail/other results to their 
     * Logger.  It is the responsibility of the caller to do any 
     * overall or rolled-up reporting that is desired.</p>
     *
     * @author Shane_Curcuru@lotus.com
     * @param Datalet to use as data points for the test; if null, 
     * will attempt to use getDefaultDatalet()
     */
    public abstract void execute(Datalet datalet);


}  // end of class Testlet