GemGenerator.java

/*
 * Copyright (c) 2007 BUSINESS OBJECTS SOFTWARE LIMITED
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 *     * Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 *  
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *  
 *     * Neither the name of Business Objects nor the names of its contributors
 *       may be used to endorse or promote products derived from this software
 *       without specific prior written permission.
 *  
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */


/*
 * GemGenerator.java
 * Creation date: Oct 9, 2003
 * By: Frank Worsley
 */
package org.openquark.gems.client.generators;

import java.util.Map;

import javax.swing.Icon;
import javax.swing.JFrame;

import org.openquark.cal.compiler.SourceModel;
import org.openquark.cal.compiler.TypeChecker;
import org.openquark.cal.services.Perspective;
import org.openquark.gems.client.ValueRunner;
import org.openquark.gems.client.valueentry.ValueEditorManager;


/**
 * The interface that must be implemented by classes that want to act as gem factories.
 * Factories are expected to block execution when their launchGenerator method is called
 * and return the source definitions they want to add. 
 * @author Frank Worsley
 */
public interface GemGenerator {

    /**
     * The source definitions generated by the generator.
     * 
     * Only one of the provided methods need return a non-empty value.
     * ie. if getModuleDefn() returns a result, getSourceElementMap() can return null or an empty map..
     * 
     * @author Edward Lam
     */
    public interface GeneratedDefinitions {
        
        /**
         * @return the generated module definition.
         */
        public SourceModel.ModuleDefn getModuleDefn();
        
        /**
         * @return the key is the source name and the value the actual source code.
         * The source definitions to create in an existing module.
         * 
         * Ordered by insertion order, so that definitions we want to create first will be created first.
         */
        public Map<String, String> getSourceElementMap();
    }
    
    /**
     * Launches the gem generator. Returns a map of source definitions the generator wants to add.
     * May return null or an empty map if no sources should be added.
     * 
     * @param parent the parent for the generator user interface
     * @param perspective the perspective to use by the generator
     * @param valueRunner a value runner to run simple CAL programs
     * @param valueEditorManager a manager for value editors used in the UI
     * @param typeChecker a type checker for fetching type information
     * @return the definitions created by the generator.
     */
    public GeneratedDefinitions launchGenerator(JFrame parent,
                                              Perspective perspective,
                                              ValueRunner valueRunner,
                                              ValueEditorManager valueEditorManager,
                                              TypeChecker typeChecker);
    
    /**
     * @return the localized, user-visible name of the generator as it should appear in the UI menu
     */
    public String getGeneratorMenuName();
    
    /**
     * @return the localized title of the generator
     */
    public String getGeneratorTitle();
    
    /**
     * @return the icon to use to represent the generator in the UI.
     */
    public Icon getGeneratorIcon();
}