package org.litesoft.template;

// Copyright Status:
//
// All Software available from LiteSoft.org (including this file) is
// hereby released into the public domain.
//
// It is free!  As in, you may use it freely in both commercial and
// non-commercial applications, bundle it with your software
// distribution, include it on a CD-ROM, list the source code in a book,
// mirror the documentation at your own web site, or use it in any other
// way you see fit.
//
// NO Warranty!
//
// All software is provided "as is".
//
// There is ABSOLUTELY NO WARRANTY OF ANY KIND: not for the design, fitness
// (for a particular purpose), level of errors (or lack thereof), or
// applicability of this software.  The entire risk as to the quality
// and performance of this software is with you.  Should this software
// prove defective, you assume the cost of all necessary servicing, repair
// or correction.
//
// In no event unless required by applicable law or agreed to in writing
// will any party who created or may modify and/or redistribute this
// software, be liable to you for damages, including any general,
// special, incidental or consequential damages arising out of the use or
// inability to use this software (including but not limited to loss of
// data or data being rendered inaccurate or losses sustained by you or
// third parties or a failure of this software to operate with any
// other programs), even if such holder or other party has been advised
// of the possibility of such damages.
//
// NOTE: Should you discover a bug, have a recogmendation for a change, wish
// to submit modifications, or wish to add new classes/functionality,
// please email them to:
//
//        changes44@litesoft.org
//

/**
 * TemplateResolver is an interface to resolve a "substitution"
 * field to a TemplateSubstitutionFieldControl.  While the
 * normal situation is that a field is simply a field (with
 * no parameters), if there are parameters, then each Resolver
 * can choose how to demarkate the field ID from the parameters
 * and the parameters from each other.<p>
 *
 * Some examples:
 * <ul>
 *      <li>action:p1,p2,p3</li>
 *      <li>action(p1,p2,p3)</li>
 *      <li>action:name1=value1|name2=value2|name3=value3</li>
 * </ul>
 *
 * Exceptions: All problems caught when the parameter(s) are checked (as
 * indicated/implied in the @param tags) will generate an IllegalArgumentException,
 * and means the API user has a problem.  If a NullPointerException (or some
 * others, like: ClassCastException or ArrayIndexOutOfBoundsException) is thrown,
 * it means the API developer has a problem.  Any Exception that is explicitly
 * thrown in the API, but unrelated to a parameter, will be listed in the throws
 * clause (and hopefully in the tag @throws).  These may (but probably won't) be
 * checked Exceptions.
 *
 * @author  George Smith
 * @version 1.2 02/07/02 Exception Policy, Use of IllegalArgument class.
 * @version 1.1 11/12/01 JavaDoc'd
 * @version 1.0 11/07/01
 */
public interface TemplateResolver
{
    /**
     * Method to interpret a Field Reference and if appropriate to return
     * a TemplateSubstitutionFieldControl.<p>
     *
     * @param   pFieldRef   The Field Reference (to interpret).<p>
     *
     * @return the object that can generate the substitution text (or lines).
     */
    public TemplateSubstitutionFieldControl getSubstitutionFieldControl( String pFieldRef );
}