~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you 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.    
 
  ------
  Writing a custom rule
  ------
  Brian Fox
  ------
  Mar 2007
  ------

Writing a custom rule
 
  Custom rules are easy to make with the <<<maven-enforcer-rule-api>>>. These rules can then be invoked with the 
  {{{http://maven.apache.org/plugins/maven-enforcer-plugin}maven-enforcer-plugin}}. 
  
  Note: The files shown below may be downloaded here: {{{custom-rule.zip}custom-rule.zip}}
  
  [[1]] First make a new jar project starting with the sample pom below:
  
+---+
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>your.group</groupId>
  <artifactId>custom-rule</artifactId>
  <packaging>jar</packaging>
  <version>1.0</version>
  <name>My Custom Rule</name>
  <description>This is my custom rule.</description>
  <build>	
  </build>
  <dependencies>
    <dependency>
      <groupId>org.apache.maven.shared</groupId>
      <artifactId>maven-enforcer-rule-api</artifactId>
      <version>1.0-alpha-1</version>
    </dependency>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-project</artifactId>
      <version>2.0.5</version>
    </dependency>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-core</artifactId>
      <version>2.0.5</version>
    </dependency>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-artifact</artifactId>
      <version>2.0.5</version>
    </dependency>
    <dependency>
      <groupId>org.apache.maven</groupId>
      <artifactId>maven-plugin-api</artifactId>
      <version>2.0.5</version>
    </dependency>
    <dependency>
      <groupId>org.codehaus.plexus</groupId>
      <artifactId>plexus-container-default</artifactId>
      <version>1.0-alpha-9</version>
    </dependency>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>	
  </dependencies>
</project>
+---+

  [[2]] Create your rule class. The rule must implement the {{{apidocs/index.html}EnforcerRule}} interface.
   The rule can get access to components and the log via the {{{apidocs/index.html}EnforcerRuleHelper}} interface.
   If the rule succeeds, it should just simply return. If the rule fails, it should throw an {{{apidocs/index.html}EnforcerRuleException}} with a descriptive message telling the user why the rule failed.
   
   Here's a sample class that shows how to access the helper methods and retreive components by class name from the helper:
   
+---+
package org.apache.maven.shared.rule;

import org.apache.maven.artifact.resolver.ArtifactResolver;
import org.apache.maven.execution.MavenSession;
import org.apache.maven.execution.RuntimeInformation;
import org.apache.maven.plugin.logging.Log;
import org.apache.maven.project.MavenProject;
import org.apache.maven.shared.enforcer.rule.api.EnforcerRule;
import org.apache.maven.shared.enforcer.rule.api.EnforcerRuleException;
import org.apache.maven.shared.enforcer.rule.api.EnforcerRuleHelper;
import org.codehaus.plexus.component.repository.exception.ComponentLookupException;

/**
 * @author <a href="mailto:brianf@apache.org">Brian Fox</a> 
 */
public class MyCustomRule
    implements EnforcerRule
{
    /**
     * Simple param. This rule will fail if the value is true. 
     */
    private boolean shouldIfail = false;
    
    public void execute( EnforcerRuleHelper helper )
        throws EnforcerRuleException
    {
        Log log = helper.getLog();

        try
        {
             // get the various expressions out of the helper.
            MavenProject project = (MavenProject) helper.evaluate( "${project}" );
            MavenSession session = (MavenSession) helper.evaluate( "${session}" );
            String target = (String) helper.evaluate( "${project.build.directory}" );
            String artifactId = (String) helper.evaluate( "${project.artifactId}" );

            // retreive any component out of the session directly
            ArtifactResolver resolver = (ArtifactResolver) helper.getComponent( ArtifactResolver.class );
            RuntimeInformation rti = (RuntimeInformation) helper.getComponent( RuntimeInformation.class );

            log.info( "Retrieved Target Folder: " + target );
            log.info( "Retrieved ArtifactId: " +artifactId );
            log.info( "Retrieved Project: " + project );
            log.info( "Retrieved RuntimeInfo: " + rti );
            log.info( "Retrieved Session: " + session );
            log.info( "Retrieved Resolver: " + resolver );
            
            if (this.shouldIfail)
            {
                throw new EnforcerRuleException("Failing because my param said so.");
            }
        }
        catch ( ComponentLookupException e )
        {
            throw new EnforcerRuleException("Unable to lookup a component",e);
        }
    }
}
+---+   

  [[3]] Build and Install or Deploy your custom rule.
 
  [[4]] Add your custom-rule artifact as a dependency of the <<<maven-enforcer-plugin>>> in your build:
  
+---+
<project>
  ...
   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-enforcer-plugin</artifactId>
         <dependencies>
           <dependency>
             <groupId>your.group</groupId>
             <artifactId>custom-rule</artifactId>
             <version>1.0</version>
           </dependency>
         </dependencies>
          ...
       </plugin>   
     </plugins>  
   </build>
   ...
</project>
+---+

  [[5]] Add your rule to the configuration section of the <<<maven-enforcer-plugin>>>. The name of your class will be the name of the rule, and
 you must add an <<<implementation>>> hint that contains the fully qualified class name:
 
+---+
<configuration>
  <rules>
    <myCustomRule implementation="org.apache.maven.shared.rule.myCustomRule">
      <shouldIfail>true</shouldIfail>
    </myCustomRule>
  </rules>
</configuration>
+---+

  [[6]] That's it. The full plugin config may look like this:
  
+---+
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-enforcer-plugin</artifactId>
  <dependencies>
    <dependency>
      <groupId>your.group</groupId>
      <artifactId>custom-rule</artifactId>
      <version>1.0</version>
    </dependency>
    </dependencies>
    <executions>
      <execution>
        <id>enforce</id>
          <configuration>
            <rules>
              <requireJavaVersion>
                <version>[1.3,1.6]</version>
              </requireJavaVersion>
              <requireMavenVersion>
                <version>2.0.6</version>
              </requireMavenVersion>
              <myCustomRule implementation="org.apache.maven.shared.rule.myCustomRule">
                <shouldIfail>true</shouldIfail>
              </myCustomRule>
            </rules>
          </configuration>
        <goals>
          <goal>enforce-once</goal>
        </goals>
      </execution>
   </executions>
</plugin>
+---+