001package org.andromda.core.templateengine;
002
003import java.io.Writer;
004import java.util.List;
005import java.util.Map;
006
007/**
008 * The interface that all templates engines used within AndroMDA must implement.
009 * It allows us to plug-in the template engine to use for processing of
010 * templates used by the system.
011 *
012 * @author Chad Brandon
013 * @author Bob Fields
014 */
015public interface TemplateEngine
016{
017    /**
018     * Initializes the TempateEngine.
019     *
020     * @param namespace The name of a namespace this can be used for whatever the
021     *        template engine implementation likes. For example, it can help
022     *        determine the name of the log file to which output is logged.
023     * @throws Exception
024     */
025    public void initialize(String namespace)
026        throws Exception;
027
028    /**
029     * Processes a template.
030     *
031     * @param templateFile the path to the template file that will be processed.
032     * @param templateObjects any additional objects we wish to make available
033     *        to the translation template that is processed
034     * @param output the Writer to which to write the output of the processing.
035     * @throws Exception any exception that may occur
036     */
037    public void processTemplate(
038        String templateFile,
039        Map<String, Object> templateObjects,
040        Writer output)
041        throws Exception;
042
043    /**
044     * Shuts down the template engine. The meaning of this is defined by the
045     * template engine itself. At least, it should close any logfiles.
046     */
047    public void shutdown();
048
049    /**
050     * Returns the list of macro libraries used within this template engine.
051     *
052     * @return List the list of macros
053     */
054    public List<String> getMacroLibraries();
055
056    /**
057     * Adds a a macro library for use within this template engine.
058     *
059     * @param macroLibrary
060     */
061    public void addMacroLibrary(String macroLibrary);
062
063    /**
064     * Sets the location of <code>merge</code> templates. These are templates
065     * that will be merged into cartridges during processing from an external
066     * location. This allows the ability to define templates external to plugins
067     * so that these templates can override plugin templates in order to provide
068     * customization.
069     *
070     * @param mergeLocation the location of the merge files.
071     */
072    public void setMergeLocation(String mergeLocation);
073
074    /**
075     * Evaluates the <code>expression</code> contained within the template
076     * being processed and returns the result.
077     *
078     * @param expression the expression to evaluate.
079     * @param templateObjects any additional objects we wish to make available
080     *        to the template engine when the expression is evaluated.  It this is null
081     *        there will be nothing to be evaluated and therefore this operation will return
082     *        null.
083     * @return the result of the evaluated expression as a String.
084     */
085    public String getEvaluatedExpression(String expression, Map<String, Object> templateObjects);
086}