package org.litesoft.template; import org.litesoft.util.*; import java.util.*; // 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 // /** * SimpleResolver is a simple implementation of a TemplateResolver.
* * The seperator (between the fieldID and the parameters) is a colon (':'). * As such, ".%action%." is equivalent to ".%action:%.", but NOT * equivalent to ".%action: %.". All TemplateSubstitutionFieldControls * used/returned by this resolver are treated as singletons and cached. * * 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 class SimpleResolver implements TemplateResolver { private Map zSubstituters = new HashMap(); /** * Constructor that populates a substituters (TemplateSubstitutionFieldControl) map.
* * The substituters map can be viewed as a Cashe of Field References. * The getSubstitutionFieldControl() method assumes that the Field ID is * seperated from the parameters by a colon (':'). If the Field Reference * is found in the map it is returned, if not the Field ID is checked and * if found then a new instance is requested (getInstance), which * if not null is added to the map.
* * To create the initial map, the pKeySubstituterPairs consists of an * array of paired keys (Strings) and substituters (TemplateSubstitutionFieldControl). * Obviously, if there are not an even number of entries, or they do not * alternate as (Strings), (TemplateSubstitutionFieldControl), (Strings), * (TemplateSubstitutionFieldControl),etc..., then an exception will be * thrown.
* * @param pKeySubstituterPairs Pairs of keys (Strings) and substituters (TemplateSubstitutionFieldControl) (!null). */ public SimpleResolver( Object[] pKeySubstituterPairs ) { IllegalArgument.ifNull( "KeySubstituterPairs" , pKeySubstituterPairs ); if ( (pKeySubstituterPairs.length & 1) == 1 ) IllegalArgument.exception( "KeySubstituterPairs" , "does NOT consist of 'pairs'" ); int i = 0; try { while ( i < pKeySubstituterPairs.length ) { String key = (String) pKeySubstituterPairs[ i ]; if ( key == null ) IllegalArgument.ofNull( "KeySubstituterPairs[" + i + "] (key)" ); TemplateSubstitutionFieldControl subr = (TemplateSubstitutionFieldControl) pKeySubstituterPairs[ ++i ]; if ( subr == null ) IllegalArgument.ofNull( "KeySubstituterPairs[" + i + "] (TemplateSubstitutionFieldControl)" ); zSubstituters.put( key , subr ); i++; } } catch ( ClassCastException e ) { throw IllegalArgument.exception( "KeySubstituterPairs[" + i + "]" , "was NOT a " + (((i & 1) == 0) ? "key" : "TemplateSubstitutionFieldControl") ); } } /** * Constructor that generates a very poor implementation of a NULL * Object version of a TemplateResolver.
* * The reason that it is a poor implementation, is that it never * returns a TemplateSubstitutionFieldControl object, no matter what * Field Reference is passed in. */ public SimpleResolver() { } /** * Method to interpret a Field Reference and if appropriate to return * a TemplateSubstitutionFieldControl.
* * @param pFieldRef The Field Reference (to interpret).
* * @return the object that can generate the substitution text (or lines). */ public TemplateSubstitutionFieldControl getSubstitutionFieldControl( String pFieldRef ) { if ( pFieldRef == null ) return null; TemplateSubstitutionFieldControl subr = (TemplateSubstitutionFieldControl) zSubstituters.get( pFieldRef ); if ( subr != null ) return subr; int sep = pFieldRef.indexOf( ':' ); if ( sep == -1 ) return null; subr = (TemplateSubstitutionFieldControl) zSubstituters.get( pFieldRef.substring( 0 , sep ) ); if ( subr == null ) return null; String params = pFieldRef.substring( sep + 1 ); if ( params.length() != 0 ) { subr = subr.getInstance( params ); zSubstituters.put( pFieldRef , subr ); } return subr; } }