apilyzer:analyze

Full name:

net.revelc.code:apilyzer-maven-plugin:1.3.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<String>`	`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> Alias is*: `allows`.
`<excludeAnnotations>`	`List<String>`	`1.1.0`	Exclude classes from public API definition using annotation. Example: <configuration> .... <excludeAnnotations> <exclude> [@]com[.]proj42[.]Alpha.* </exclude> </excludeAnnotations> ..... </configuration> See also: includeAnnotations Alias is: `excludeAnnotations`.
`<excludes>`	`List<String>`	`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> Alias is: `excludes`.
`<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`. Alias is: `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`. Alias is: `ignoreProblems`.
`<includeAnnotations>`	`List<String>`	`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(String)` is called on the output of `java.lang.annotation.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> Alias is: `includeAnnotations`.
`<includes>`	`List<String>`	`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> Alias is*: `includes`.
`<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`. Alias is: `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`. Alias is: `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<java.lang.String>
Since: 1.0.0
Required: No
Alias: allows

<excludeAnnotations>

Exclude classes from public API definition using annotation.

Example:

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

See also: includeAnnotations

Type: java.util.List<java.lang.String>
Since: 1.1.0
Required: No
Alias: excludeAnnotations

<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<java.lang.String>
Since: 1.0.0
Required: No
Alias: excludes

<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
Alias: ignoreDeprecated

<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
Alias: ignoreProblems

<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(String) is called on the output of java.lang.annotation.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<java.lang.String>
Since: 1.1.0
Required: No
Alias: includeAnnotations

<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<java.lang.String>
Since: 1.0.0
Required: No
Alias: includes

<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
Alias: outputFile

<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
Alias: skip