<?xml version="1.0"?>
<!-- 
/*
 * Copyright 2001-2004 The Apache Software Foundation.
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 -->

<document>

  <properties>
    <title>Maven Caller plugin</title>
    <author email="vmassol@apache.org">Vincent Massol</author>
  </properties>

  <body>
    <section name="Maven Caller Plug-in">
      <p>
        The Caller plugin is an interface abstraction for goals. It defines
        several Well-Known Goal Interfaces (WKGI). This allows a plugin
        to call another plugin through this Caller plugin. The benefit is
        that it is then possible to rewire the implementation of a WKGI.
      </p>
      <p>
        Here's a typical scenario. Imagine you wish to implement an aspectj
        plugin. This plugin will compile the Java sources using the Aspectj
        compiler. However, the project you wish to use the aspectj plugin on
        is a webapp and thus you will need call the <code>war:war</code>.
        Alas, the <code>war:war</code> goal has a hard-wired call to 
        <code>java:compile</code>. What you would like is redirect this call
        to your <code>aspectj:compile</code> goal. The solution: the Caller
        plugin.
      </p>
      <p>
        Here's what you would write. In the war plugin's 
        <code>plugin.jelly</code>, you would replace the call to
      </p>
<source><![CDATA[
<attainGoal name="java:compile"/>
]]></source>
      <p>
        by
      </p>
<source><![CDATA[
<caller:call goalInterface="compile-java"/>
]]></source>
      <p>
        Then, in your Aspectj plugin, you would call
      </p>
<source><![CDATA[
<caller:set goalInterface="compile-java" goal="aspectj:compile"/>
]]></source>
      <p>
        Thus, when, as a user you will call the <code>war:war</code>
        goal, your <code>aspectj:compile</code> goal will be called.
      </p>
      <p> 
        For more information on the functionality provided by this plugin,
        please see the <a href="goals.html">Goals</a> document.
      </p>
      <p>
        For more information on how to customise the functionality provided
        by this plugin, please see the <a href="properties.html">properties</a>
        document.
      </p>
    </section>
 </body>
</document>
