Optimising Variable to reduce instantiation overhead

/*
 * Copyright (C) 1998-2000 Semiotek Inc.  All Rights Reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted under the terms of either of the following
 * Open Source licenses:
 *
 * The GNU General Public License, version 2, or any later version, as
 * published by the Free Software Foundation
 * (http://www.fsf.org/copyleft/gpl.html);
 *
 *  or
 *
 * The Semiotek Public License (http://webmacro.org/LICENSE.)
 *
 * This software is provided "as is", with NO WARRANTY, not even the
 * implied warranties of fitness to purpose, or merchantability. You
 * assume all risks and liabilities associated with its use.
 *
 * See www.webmacro.org for more information on the WebMacro project.
 */


package org.webmacro.engine;

import org.webmacro.*;
import org.webmacro.util.Named;

import java.io.IOException;

// PRIMARY CLASS: Variable

/**
 * A Variable is a reference into a Propertymap.
 * <p>
 * A variable name contains a list of names separated by dots, for
 * example "$User.Identity.email.address" is the list: User, Identity,
 * email, and address.
 * <p>
 * PLEASE NOTE: Case-sensitivity is enforced. "User" is the the same
 * name as "user".
 * <p>
 * What that means: When a template is interpreted, it is interpreted
 * in terms of data in a hashtable/map called the "context". This is
 * actually a Map of type Map. The context contains all the
 * local variables that have been set, as well as other information
 * that Macros may use to evaluate the request.
 * <p>
 * Variable depends heavily on Property introspection: It is defined
 * as a list of one or more names (separated by dots when written).
 * <p>
 * Those names are references to sub-objects within the context. The
 * Variable instance, when interpreted, will decend through the context
 * following fields, method references, or hash table look-ups based
 * on its names.
 * <p>
 * For example, the variable "$User.Identity.email.address" implies
 * that there is a "User" object under the Map--either it is
 * a field within the map, or the map has a getUser() method, or
 * the User can be obtained by calling Map.get("User").
 * <p>
 * The full expansion of $User.Identity.email.address might be:<pre>
 *
 *    Map.get("User").getIdentity().get("email").address
 *
 * </pre>. Variable (actually the Property class it uses) will figure
 * out how to decend through the object like this until it finds the
 * final reference--which is the "value" of the variable.
 * <p>
 * When searchin for subfields Variable prefers fields over getFoo()
 * methods, and getFoo() over get("Foo").
 *
 */
public abstract class Variable implements Macro, Visitable
{


    // null: because in BuildContext.getVariableType() we can just
    // return null from a HashMap for a never before heard of variable
    // to mean that it is a PROPERTY_TYPE. Only this code right here
    // and BuildContext.getVariableType() needs to know that.
    final static public Object PROPERTY_TYPE = new Object();
    final static public Object LOCAL_TYPE = new Object();

    /**
     * The name of this variable.
     */
    private String _vname;

    /**
     * The name as an array
     */
    protected Object[] _names;

    /**
     * Create a variable with the supplied name. The elements of the name
     * are either strings, or a method reference.
     */
    Variable (Object names[])
    {
        _names = names;

    }

    /**
     * Return the property names for this variable. These are stringified
     * names corresponding to the names of the variable; if one of the
     * elements of the variable name is a method call then the name of
     * the method is inserted at that point as if it were a property name.
     */
    static final String[] makePropertyNames (Object names[])
    {
        String[] sn = new String[names.length];
        for (int i = 0; i < sn.length; i++)
        {
            sn[i] = (names[i] instanceof Named) ?
                    ((Named) names[i]).getName() : (String) names[i];
        }
        return sn;
    }

    public final String[] getPropertyNames ()
    {
        return makePropertyNames(_names);
    }

    /**
     * Like getPropertyNames, but only works if isSimpleName is true
     */
    public final String getName ()
    {
        return (_names[0] instanceof Named) ?
                ((Named) _names[0]).getName()
                : (String) _names[0];
    }

    /**
     * Returns true if the Variable describes a simple name (one with only
     * one element)
     */
    public boolean isSimpleName ()
    {
        return (_names.length == 1);
    }

    /**
     * Looks in the hashTable (context) for a value keyed to this variables
     * name and returns the value string. If the resulting value is a Macro,
     * recursively call its evaluate method.
     * @return String
     */
    final public Object evaluate (Context context) throws PropertyException
    {
        try
        {
            Object val = getValue(context);
            if (val instanceof Macro)
            {
                val = ((Macro) val).evaluate(context); // recurse
            }
            return val;
        }
        catch (NullPointerException e)
        {
            // May throw
            context.getEvaluationExceptionHandler()
                    .evaluate(this, context,
                              new PropertyException.NullValueException(getVariableName()));
            return null;
        }
        catch (PropertyException e)
        {
            // May throw
            if (e instanceof PropertyException.UndefinedVariableException)
            {
                PropertyException.UndefinedVariableException uve = (PropertyException.UndefinedVariableException) e;
                if (_names.length > 1)
                    uve.setMessage(
                            "Attempted to reference a property or method of an undefined variable: $" + _names[0]);
                else
                    uve.setMessage(
                            "Attempted to evaluate an undefined variable: $" + _names[0]);
            }
            context.getEvaluationExceptionHandler()
                    .evaluate(this, context, e);
            return null;
        }
        catch (Exception e)
        {
            // May throw
            context.getEvaluationExceptionHandler()
                    .evaluate(this, context,
                            new PropertyException("Variable: exception evaluating "
                                                  + getVariableName(), e));
            return null;
        }
    }

    /**
     * Look in the hashtable (context) for a value keyed to this variables
     * name and write its value to the stream.
     * @exception PropertyException is required data is missing
     * @exception IOException if could not write to output stream
     */
    final public void write (FastWriter out, Context context)
            throws PropertyException, IOException
    {
        try
        {
            Object val = getValue(context);
            if (val instanceof Macro)
                ((Macro) val).write(out, context);
            else
            {
                if (val != null)
                {
                    String v = val.toString();
                    if (v != null)
                        out.write(v);
                    else
                    {
                        out.write(context.getEvaluationExceptionHandler()
                                .expand(this, context,
                                        new PropertyException.NullToStringException(getVariableName())));
                    }
                }
                else
                {
                    if (isSimpleName())
                    {
                        // user accessed a variable that isn't in the context
                        //     $ObjectNotInContext
                        out.write(context.getEvaluationExceptionHandler()
                                .expand(this, context,
                                        new PropertyException.NoSuchVariableException(getVariableName())));
                    }
                    else
                    {
                        // user accessed a valid property who's value is null
                        out.write(context.getEvaluationExceptionHandler()
                                .expand(this, context,
                                        new PropertyException.NullValueException(getVariableName())));
                    }
                }
            }
        }
        catch (PropertyException e)
        {
            if (e instanceof PropertyException.UndefinedVariableException)
            {
                PropertyException.UndefinedVariableException uve = (PropertyException.UndefinedVariableException) e;
                if (_names.length > 1)
                    uve.setMessage(
                            "Attempted to write a property or method value of an undefined variable: $" + _names[0]);
                else
                    uve.setMessage(
                            "Attempted to write an undefined variable: $" + _names[0]);
            }
            out.write(context.getEvaluationExceptionHandler()
                    .expand(this, context, e));
        }
        catch (Exception e)
        {
            // something we weren't expecting happened!
            // I wonder if we would ever get here?  --eric
            out.write(context.getEvaluationExceptionHandler()
                    .expand(this, context, e));
        }
    }

    /**
     * Helper method to construct a String name from a Object[] name
     */
    final static String makeName (Object[] names)
    {
        StringBuffer buf = new StringBuffer();
        for (int i = 0; i < names.length; i++)
        {
            if (i != 0)
            {
                buf.append(".");
            }
            buf.append(names[i]);
        }
        return buf.toString();
    }

    /**
     * The code to get the value represented by the variable from the
     * supplied context.
     */
    public abstract Object getValue (Context context) throws PropertyException;

    /**
     * The code to set the value represented by the variable in the
     * supplied context.
     */
    public abstract void setValue (Context c, Object v) throws PropertyException;

    /**
     * Return the String name of the variable prefixed with a string
     * representing its type. For example local:a.b.c
     */
    public abstract String toString ();

    /**
     * Return the canonical name for this variable
     */
    public synchronized String getVariableName ()
    {
      if (_vname == null) {
        _vname = makeName(_names).intern();
      }
      return _vname;
    }

    public void accept (TemplateVisitor v)
    {
        v.visitVariable(this, _names);
    }

}