JarCasting
JarCasting JarCasting

API Plumber

A custom doclet to check that an API doesn't leak a set of "forbidden" packages.

License

License
Categories

Categories

Data
GroupId

GroupId

com.datastax.oss
ArtifactId

ArtifactId

api-plumber-doclet
Last Version

Last Version

1.0.0
Release Date

Release Date
Type

Type

jar
Description

Description

API Plumber
A custom doclet to check that an API doesn't leak a set of "forbidden" packages.
Project URL

Project URL

https://github.com/datastax/api-plumber-doclet
Source Code Management

Source Code Management

https://github.com/datastax/api-plumber-doclet

Download api-plumber-doclet

Filename Size
api-plumber-doclet-1.0.0.pom
api-plumber-doclet-1.0.0.jar 7 KB
api-plumber-doclet-1.0.0-sources.jar 5 KB
api-plumber-doclet-1.0.0-javadoc.jar 23 KB
Browse

How to add to project

<!-- https://jarcasting.com/artifacts/com.datastax.oss/api-plumber-doclet/ -->
<dependency>
    <groupId>com.datastax.oss</groupId>
    <artifactId>api-plumber-doclet</artifactId>
    <version>1.0.0</version>
</dependency>
// https://jarcasting.com/artifacts/com.datastax.oss/api-plumber-doclet/
implementation 'com.datastax.oss:api-plumber-doclet:1.0.0'
// https://jarcasting.com/artifacts/com.datastax.oss/api-plumber-doclet/
implementation ("com.datastax.oss:api-plumber-doclet:1.0.0")
'com.datastax.oss:api-plumber-doclet:jar:1.0.0'
<dependency org="com.datastax.oss" name="api-plumber-doclet" rev="1.0.0">
  <artifact name="api-plumber-doclet" type="jar" />
</dependency>
@Grapes(
@Grab(group='com.datastax.oss', module='api-plumber-doclet', version='1.0.0')
)
libraryDependencies += "com.datastax.oss" % "api-plumber-doclet" % "1.0.0"
[com.datastax.oss/api-plumber-doclet "1.0.0"]

Dependencies

test (4)

Group / Artifact Type Version
junit : junit jar 4.12
org.assertj : assertj-core jar 3.6.2
io.github.lukehutch : fast-classpath-scanner jar 2.7.4
org.apache.commons : commons-exec jar 1.3

system (1)

Group / Artifact Type Version
com.sun » tools jar 1.8

Project Modules

There are no modules declared in this project.

API Plumber doclet

A custom doclet to check that an API doesn't leak a set of "forbidden" packages.

Why

  • coding conventions: Java's visibility system lacks flexibility. One workaround is to use a naming convention with api / internal root packages. The public API should not leak any internal types.
  • shaded libraries: the API should not leak any shaded types.

Usage

Command line

javadoc -preventleak com.package1 [-preventleak com.package2] \
        -doclet com.datastax.oss.doclet.ApiPlumber ...

Maven

<plugin>
  <artifactId>maven-javadoc-plugin</artifactId>
  <executions>
    <execution>
      <id>check-api-leaks</id>
      <goals><goal>javadoc</goal></goals>
      <phase>process-classes</phase>
      <configuration>
        <doclet>com.datastax.oss.doclet.ApiPlumber</doclet>
        <docletArtifact>
          <groupId>com.datastax.oss</groupId>
          <artifactId>api-plumber-doclet</artifactId>
          <version>...</version>
        </docletArtifact>
        <additionalJOptions>
          <additionalparam>-preventleak</additionalparam>
          <additionalparam>com.package1</additionalparam>
          <additionalparam>-preventleak</additionalparam>
          <additionalparam>com.package2</additionalparam>
        </additionalJOptions>
        <useStandardDocletOptions>false</useStandardDocletOptions>
      </configuration>
    </execution>
  </executions>
</plugin>

Violations are printed on the standard error, and cause the command to return with a non-zero exit value.

You can ignore elements with a javadoc tag:

/** @leaks-private-api */
public com.example.internal.InternalType myField;
com.datastax.oss

DataStax

Versions

Version
1.0.0