This is an automated email from the ASF dual-hosted git repository.

mmiller pushed a commit to branch master
in repository

The following commit(s) were added to refs/heads/master by this push:
     new aefbfd7  Checkstyle import control blog post. Fixes #149 (#206)
aefbfd7 is described below

commit aefbfd7c9289a4d1adeca49bf2b79ee272decdaa
Author: Mike Miller <>
AuthorDate: Thu Nov 7 12:46:11 2019 -0500

    Checkstyle import control blog post. Fixes #149 (#206)
 .../blog/   | 93 ++++++++++++++++++++++
 pages/                                       |  3 +
 2 files changed, 96 insertions(+)

diff --git a/_posts/blog/ 
new file mode 100644
index 0000000..46a6923
--- /dev/null
+++ b/_posts/blog/
@@ -0,0 +1,93 @@
+title: "Checking API use"
+Accumulo follows [SemVer] across versions with the declaration of a public 
API.  Code not in the public API should be
+considered unstable, at risk of changing between versions.  The public API 
packages are [listed on the website][api]
+but may not be considered when an Accumulo user writes code.  This blog post 
explains how to make Maven
+automatically detect usage of Accumulo code outside the public API.
+The techniques described in this blog post only work for Accumulo 2.0 and 
later.  Do not use with 1.X versions.
+## Checkstyle Plugin
+First add the checkstyle Maven plugin to your pom.
+    <!-- This was added to ensure project only uses Accumulo's public API -->
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-checkstyle-plugin</artifactId>
+    <version>3.1.0</version>
+    <executions>
+      <execution>
+        <id>check-style</id>
+        <goals>
+          <goal>check</goal>
+        </goals>
+        <configuration>
+          <configLocation>checkstyle.xml</configLocation>
+        </configuration>
+      </execution>
+    </executions>
+  </plugin>
+The plugin version is the latest at the time of this post.  For more 
information see the website for
+the [Apache Maven Checkstyle Plugin][plugin].  The configuration above adds 
the plugin to ```check``` execution goal
+so it will always run with your build.  
+Create the configuration file specified above: ```checkstyle.xml```
+### checkstyle.xml
+<!DOCTYPE module PUBLIC "-//Puppy Crawl//DTD Check Configuration 1.3//EN" 
+<module name="Checker">
+  <property name="charset" value="UTF-8"/>
+  <module name="TreeWalker">
+    <!--check that only Accumulo public APIs are imported-->
+    <module name="ImportControl">
+      <property name="file" value="import-control.xml"/>
+    </module>
+  </module>
+This file sets up the ImportControl module.
+## Import Control Configuration
+Create the second file specified above, ```import-control.xml``` and copy the 
configuration below.  Make sure to replace
+"insert-your-package-name" with the package name of your project.
+<!DOCTYPE import-control PUBLIC
+    "-//Checkstyle//DTD ImportControl Configuration 1.4//EN"
+    "";>
+<!-- This checkstyle rule is configured to ensure only use of Accumulo API -->
+<import-control pkg="insert-your-package-name" strategyOnMismatch="allowed">
+    <!-- API packages -->
+    <allow pkg="org.apache.accumulo.core.client"/>
+    <allow pkg=""/>
+    <allow pkg=""/>
+    <allow pkg="org.apache.accumulo.core.iterators"/>
+    <allow pkg="org.apache.accumulo.minicluster"/>
+    <allow pkg="org.apache.accumulo.hadoop.mapreduce"/>
+    <!-- disallow everything else coming from accumulo -->
+    <disallow pkg="org.apache.accumulo"/>
+This file configures the ImportControl module to only allow packages that are 
declared public API.
+## Hold the line
+Adding this to an existing project may expose usage of non public Accumulo 
API's. It may take more time than is available
+to fix those at first, but do not let this discourage adding this plugin. One 
possible way to proceed is to allow the
+currently used non-public APIs in a commented section of import-control.xml 
noting these are temporarily allowed until
+they can be removed. This strategy prevents new usages of non-public APIs 
while allowing time to work on fixing the current
+ usages of non public APIs.  Also, if you don't want your project failing to 
build because of this, you can add 
+to the maven-checkstyle-plugin configuration.
+[api]: {{ site.baseurl }}/api/
diff --git a/pages/ b/pages/
index 7a9c3ba..e33a66c 100644
--- a/pages/
+++ b/pages/
@@ -41,5 +41,8 @@ for public API were relocated, and also altered to include 
the new MapReduce mod
+See the [blog post][post] about using the checkstyle plugin for more explicit 
non-API detection.
+[post]: {{ site.baseurl }}/blog/2019/11/04/checkstyle-import-control.html

Reply via email to