001package 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
022import 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 */
036public 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}