001    package org.apache.maven.plugin;
002    
003    /*
004     * Licensed to the Apache Software Foundation (ASF) under one
005     * or more contributor license agreements.  See the NOTICE file
006     * distributed with this work for additional information
007     * regarding copyright ownership.  The ASF licenses this file
008     * to you under the Apache License, Version 2.0 (the
009     * "License"); you may not use this file except in compliance
010     * with the License.  You may obtain a copy of the License at
011     *
012     *  http://www.apache.org/licenses/LICENSE-2.0
013     *
014     * Unless required by applicable law or agreed to in writing,
015     * software distributed under the License is distributed on an
016     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017     * KIND, either express or implied.  See the License for the
018     * specific language governing permissions and limitations
019     * under the License.
020     */
021    
022    import org.apache.maven.plugin.logging.Log;
023    
024    /**
025     * This interface forms the contract required for <code>Mojos</code> to interact with the <code>Maven</code>
026     * infrastructure.
027     * <br/>
028     * It features an <code>execute()</code> method, which triggers the Mojo's build-process behavior, and can throw
029     * a MojoExecutionException or MojoFailureException if error conditions occur.
030     * <br/>
031     * Also included is the <code>setLog(...)</code> method, which simply allows Maven to inject a logging mechanism which
032     * will allow the Mojo to communicate to the outside world through standard Maven channels.
033     *
034     * @author Jason van Zyl
035     */
036    public interface Mojo
037    {
038        /** The component <code>role</code> hint for Plexus container */
039        String ROLE = Mojo.class.getName();
040    
041        /**
042         * Perform whatever build-process behavior this <code>Mojo</code> implements.
043         * <br/>
044         * This is the main trigger for the <code>Mojo</code> inside the <code>Maven</code> system, and allows
045         * the <code>Mojo</code> to communicate errors.
046         *
047         * @throws MojoExecutionException if an unexpected problem occurs.
048         * Throwing this exception causes a "BUILD ERROR" message to be displayed.
049         * @throws MojoFailureException if an expected problem (such as a compilation failure) occurs.
050         * Throwing this exception causes a "BUILD FAILURE" message to be displayed.
051         */
052        void execute()
053            throws MojoExecutionException, MojoFailureException;
054    
055        /**
056         * Inject a standard <code>Maven</code> logging mechanism to allow this <code>Mojo</code> to communicate events
057         * and feedback to the user.
058         *
059         * @param log a new logger
060         */
061        // TODO: not sure about this here, and may want a getLog on here as well/instead
062        void setLog( Log log );
063    
064        /**
065         * Furnish access to the standard Maven logging mechanism which is managed in this base class.
066         *
067         * @return a log4j-like logger object which allows plugins to create messages at levels of <code>"debug"</code>,
068         * <code>"info"</code>, <code>"warn"</code>, and <code>"error"</code>. This logger is the accepted means to display
069         * information to the user.
070         */
071        Log getLog();
072    }