 ~~ The MIT License
 ~~
 ~~ Copyright (c) 2009 codehaus.org.
 ~~
 ~~ Permission is hereby granted, free of charge, to any person obtaining a copy
 ~~ of this software and associated documentation files (the "Software"), to deal
 ~~ in the Software without restriction, including without limitation the rights
 ~~ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 ~~ copies of the Software, and to permit persons to whom the Software is
 ~~ furnished to do so, subject to the following conditions:
 ~~
 ~~ The above copyright notice and this permission notice shall be included in
 ~~ all copies or substantial portions of the Software.
 ~~
 ~~ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 ~~ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 ~~ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 ~~ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 ~~ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 ~~ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 ~~ THE SOFTWARE.
 ~~

 -----
 Usage
 -----
 Stephen Connolly
 ------
 2009-11-04
 ------

Usage

  The enforcer rule offers a rule for checking projects against the signatures of an API.

* Basic Usage

** Checking a project against an API signature

  In order to check your project against an API signature, you must add the enforcer rule as a dependency to
  the maven-enforcer-plugin and then configure the maven-enforcer-plugin to run the rule:

---
<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <artifactId>maven-enforcer-plugin</artifactId>
        <version>1.0-beta-1</version>
        ...
        <dependencies>
            ...
            <dependency>
                <groupId>${project.groupId}</groupId>
                <artifactId>${project.artifactId}</artifactId>
                <version>${project.version}</version>
            </dependency>
            ...
        </dependencies>
        ...
        <executions>
           ....
          <execution>
            <id>check-signatures</id>
            <phase>process-test-classes</phase>
            <goals>
              <goal>enforce</goal>
            </goals>
            <configuration>
              <rules>
                <checkSignatureRule implementation="org.codehaus.mojo.animal_sniffer.enforcer.CheckSignatureRule">
                  ...
                  <signature>
                    <groupId>org.codehaus.mojo.signature</groupId>
                    <artifactId>java15</artifactId>
                    <version>1.0</version>
                  </signature>
                  ...
                </checkSignatureRule>
              </rules>
            </configuration>
          </execution>
          ...
        </executions>
        ...
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>
---

  The example above configures the signature for JRE 1.5. For a list of other ready-made signatures, please visit the
  {{{http://mojo.codehaus.org/signatures/}Animal Scents subproject}}.

  Once you have configured your project with details of the signature to check, maven-enforcer will be able to
  throw a build error if your any of your classes reference a class, a method, or a field which is not in either
  the signature or your project's dependencies. 

  <Note:> if you want to check against
  multiple separate APIs (e.g. check against the Tomcat, JBoss, and Jetty servlet containers,
  or check against multiple java versions) then you will probably want to keep the signature
  configuration inside each of your multiple executions otherwise your project will be 
  checked against the union of all the signatures specified, which is probably not what you 
  wanted.

  {{{./examples/checking-signatures.html} Some more detailed examples of the <<<checkSignatureRule>>> rule}}.
