Fork me on GitHub

apilyzer:analyze

Full name:

net.revelc.code:apilyzer-maven-plugin:1.2.0:analyze

Description:

Analyzes declared public API.

Attributes:

  • Requires a Maven project to be executed.
  • Requires dependency resolution of artifacts in scope: compile.
  • The goal is thread-safe and supports parallel builds.
  • Binds by default to the lifecycle phase: verify.

Optional Parameters

Name Type Since Description
allows List 1.0.0 The additional classes, which are allowed to be referenced in your public API, but are not, themselves, declared as part of your API. For example, these may be objects from a standard library, which you utilize as parameters in your API methods.

These follow the same format as includes and excludes.

Example:

<configuration>
  ...
  <allows>
    <allow>com[.]google[.]common[.].*</allow>
  </allows>
  ...
</configuration>

excludeAnnotations List 1.1.0 Exclude classes from public API definition using annotation.

Example:

<configuration>
  ....
  <excludeAnnotations>
    <exclude>
      [@]com[.]proj42[.]Alpha.*
    </exclude>
  </excludeAnnotations>
  .....
</configuration>

excludes List 1.0.0 The classes to exclude from your public API definition, which may have otherwise matched your includes. The format is the same as includes.

Example:

<configuration>
  ...
  <excludes>
    <exclude>.*[.]impl[.].*</exclude>
  </excludes>
  ...
</configuration>

ignoreDeprecated boolean 1.0.0 Controls whether API items marked with the Deprecated annotation are ignored. By default, these are ignored (excluded from analysis). One useful way to make use of this plugin is to use it to help identify API methods which should be deprecated (and eventually removed) because they are using unexpected and problematic classes. Once found, they can be deprecated and excluded from future analysis.
Default value is: true.
User property is: apilyzer.ignoreDeprecated.
ignoreProblems boolean 1.0.0 Allows ignoring the problems found. If this is set to true, then the report will still be created, but the plugin will not cause the build to fail.
Default value is: false.
User property is: apilyzer.ignoreProblems.
includeAnnotations List 1.1.0 This option enables including classes in your public API definition based on class level annotations. This option takes one or more regular expression. Annotations are discovered using reflection, so annotations scoped to compile may not be seen. For each regular expression String.matches() is called on the output of Annotation.toString(). If any annotation matches any regular expression and it does not match any exclusion, then its included as an API type.

This section of the configuration is ORed with the <includes> section. So if a class matches something in either section (and its not excluded), then its included in the API definition.

This section has the same behavior with inner classes as <includes>.

Example:

<configuration>
  ....
  <includeAnnotations>
    <include>
      [@]com[.]proj42[.]Public.*
    </include>
  </includeAnnotations>
  .....
</configuration>

includes List 1.0.0 The classes to include in your public API definition. These classes will be included in the analysis. The format is java regular expressions. Any classes on the classpath whose fully-qualified class name matches any of these regular expressions, and does not match any of those in the excludes, will be included for analysis.

Matching is done with the regular expression anchored to the beginning and end of the fully-qualified class name, so there is no need to prefix with ^ or suffix with $. To match a partial class name, you will need to add .* as a prefix and/or suffix.

If an include pattern matches a class, then that class along with all of its public or protected inner classes are added to the public API definition. If you do not wish for a particular inner class to be in the public API then you can add a more specific exclusion for it. For example could include com.foo.C and exclude com.foo.C$I1 if the inner class C$I1 ends up in the API when its not wanted.

Example:

<configuration>
  ...
  <includes>
    <include>org[.]apache[.].*</include>
    <include>com[.]example[.]myproject[.].*</include>
  </includes>
  ...
</configuration>

outputFile String 1.0.0 The absolute path for the report file.
Default value is: ${project.build.directory}/apilyzer.txt.
User property is: apilyzer.outputFile.
skip boolean 1.0.0 Allows skipping execution of this plugin. This may be useful for testing, or if you find that analysis is taking too long.
Default value is: false.
User property is: apilyzer.skip.

Parameter Details

allows:

The additional classes, which are allowed to be referenced in your public API, but are not, themselves, declared as part of your API. For example, these may be objects from a standard library, which you utilize as parameters in your API methods.

These follow the same format as includes and excludes.

Example:

<configuration>
  ...
  <allows>
    <allow>com[.]google[.]common[.].*</allow>
  </allows>
  ...
</configuration>
  • Type: java.util.List
  • Since: 1.0.0
  • Required: No

excludeAnnotations:

Exclude classes from public API definition using annotation.

Example:

<configuration>
  ....
  <excludeAnnotations>
    <exclude>
      [@]com[.]proj42[.]Alpha.*
    </exclude>
  </excludeAnnotations>
  .....
</configuration>
  • Type: java.util.List
  • Since: 1.1.0
  • Required: No

excludes:

The classes to exclude from your public API definition, which may have otherwise matched your includes. The format is the same as includes.

Example:

<configuration>
  ...
  <excludes>
    <exclude>.*[.]impl[.].*</exclude>
  </excludes>
  ...
</configuration>
  • Type: java.util.List
  • Since: 1.0.0
  • Required: No

ignoreDeprecated:

Controls whether API items marked with the Deprecated annotation are ignored. By default, these are ignored (excluded from analysis). One useful way to make use of this plugin is to use it to help identify API methods which should be deprecated (and eventually removed) because they are using unexpected and problematic classes. Once found, they can be deprecated and excluded from future analysis.
  • Type: boolean
  • Since: 1.0.0
  • Required: No
  • User Property: apilyzer.ignoreDeprecated
  • Default: true

ignoreProblems:

Allows ignoring the problems found. If this is set to true, then the report will still be created, but the plugin will not cause the build to fail.
  • Type: boolean
  • Since: 1.0.0
  • Required: No
  • User Property: apilyzer.ignoreProblems
  • Default: false

includeAnnotations:

This option enables including classes in your public API definition based on class level annotations. This option takes one or more regular expression. Annotations are discovered using reflection, so annotations scoped to compile may not be seen. For each regular expression String.matches() is called on the output of Annotation.toString(). If any annotation matches any regular expression and it does not match any exclusion, then its included as an API type.

This section of the configuration is ORed with the <includes> section. So if a class matches something in either section (and its not excluded), then its included in the API definition.

This section has the same behavior with inner classes as <includes>.

Example:

<configuration>
  ....
  <includeAnnotations>
    <include>
      [@]com[.]proj42[.]Public.*
    </include>
  </includeAnnotations>
  .....
</configuration>
  • Type: java.util.List
  • Since: 1.1.0
  • Required: No

includes:

The classes to include in your public API definition. These classes will be included in the analysis. The format is java regular expressions. Any classes on the classpath whose fully-qualified class name matches any of these regular expressions, and does not match any of those in the excludes, will be included for analysis.

Matching is done with the regular expression anchored to the beginning and end of the fully-qualified class name, so there is no need to prefix with ^ or suffix with $. To match a partial class name, you will need to add .* as a prefix and/or suffix.

If an include pattern matches a class, then that class along with all of its public or protected inner classes are added to the public API definition. If you do not wish for a particular inner class to be in the public API then you can add a more specific exclusion for it. For example could include com.foo.C and exclude com.foo.C$I1 if the inner class C$I1 ends up in the API when its not wanted.

Example:

<configuration>
  ...
  <includes>
    <include>org[.]apache[.].*</include>
    <include>com[.]example[.]myproject[.].*</include>
  </includes>
  ...
</configuration>
  • Type: java.util.List
  • Since: 1.0.0
  • Required: No

outputFile:

The absolute path for the report file.
  • Type: java.lang.String
  • Since: 1.0.0
  • Required: No
  • User Property: apilyzer.outputFile
  • Default: ${project.build.directory}/apilyzer.txt

skip:

Allows skipping execution of this plugin. This may be useful for testing, or if you find that analysis is taking too long.
  • Type: boolean
  • Since: 1.0.0
  • Required: No
  • User Property: apilyzer.skip
  • Default: false