com.redhat.ceylon.common.tool.Tool Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ceylon-complete Show documentation
There is a newer version: 1.3.3
package com.redhat.ceylon.common.tool;

import com.redhat.ceylon.common.tools.CeylonTool;

/**
 * A plug-in to the {@code ceylon} command.
 * 
 * Tool Conventions
 * As well as implementing this interface a tool must adhere to a number of 
 * conventions:
 * 
 * The class must be concrete.
 * The class must have a public no argument constructor 
 * The class's name must begin with {@code Ceylon} end with {@code Tool}. 
 *     The tool name is derived from the class name by:
 *   
 *     Removing the initial {@code Ceylon} trailing {@code Tool},
 *     Lowercasing the initial character
 *     Replacing every subsequent upper case character in the name with a 
 *     dash followed by the lowercased character
 *   
 *     So, for example the class name {@code CeylonFooBarTool} implies the 
 *     tool name {@code foo-bar}
 *  
 * 
 * In addition to those conventions, if a tool accepts command line options 
 * and/or arguments, those are represented by JavaBean setter methods one of 
 * the following annotations applied:
 * 
 * {@link Option}
 *   For {@linkplain  com.redhat.ceylon.common.tool pure options}
 * {@link OptionArgument}
 *   For {@linkplain  com.redhat.ceylon.common.tool option arguments}
 * {@link Argument}
 *   For {@linkplain  com.redhat.ceylon.common.tool arguments}
 * {@link Rest}
 *   For passing unconstrained options
 * 
 * 
 * Additional annotations provide for tool documentation:
 * 
 * {@link Summary}
 *   A one sentence summary of what the tool does.
 * {@link Description}
 *   Detailed description of a tool or its command line options 
 *   and arguments.
 * {@link RemainingSections}
 *   Additional documentation headings/sections
 * 
 * 
 * Lifecycle
 * A plug-in is a JavaBean which is instantiated (by a {@link ToolLoader}) 
 * in response to the {@code ceylon} program being executed with that 
 * tool name, or for introspection by other tools.
 * 
 * If the tool is going to be executed it is first configured by the 
 * {@link ToolFactory} according to the command line arguments given. 
 * These are configured on the tool bean 
 * according to the annotations on its JavaBean setters. Once the properties 
 * have been set the {@link #initialize()} method is invoked before the tool is
 * {@link #run()}.
 */
public interface Tool {

    /**
     * Initializes the tool. Use this for setup, special handling of attributes
     * or specialized validation of arguments etc 
     * @throws Exception If anything went wrong.
     */
    public void initialize(CeylonTool mainTool) throws Exception;
    
    /**
     * Executes the tool. 
     * @throws Exception If anything went wrong.
     */
    public void run() throws Exception;
    
}