accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ktur...@apache.org
Subject [accumulo] 02/03: Move public API docs to Accumulo.java (#656)
Date Fri, 21 Sep 2018 22:17:26 GMT
This is an automated email from the ASF dual-hosted git repository.

kturner pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/accumulo.git

commit c1ecab247db862aba6437b768609a352f753bd49
Author: Keith Turner <kturner@apache.org>
AuthorDate: Thu Sep 20 18:51:46 2018 -0400

    Move public API docs to Accumulo.java (#656)
---
 README.md                                          | 28 +--------
 .../org/apache/accumulo/core/client/Accumulo.java  | 73 ++++++++++++++++++++--
 .../accumulo/core/client/AccumuloClient.java       |  6 +-
 pom.xml                                            |  1 +
 4 files changed, 75 insertions(+), 33 deletions(-)

diff --git a/README.md b/README.md
index 4d96516..2a59659 100644
--- a/README.md
+++ b/README.md
@@ -46,30 +46,7 @@ This command produces `assemble/target/accumulo-<version>-bin.tar.gz`
 
 ## Accumulo API
 
-The public Accumulo API is composed of all public types in the following packages
-and their subpackages excluding those named *impl*, *thrift*, or *crypto*.
-
-   * org.apache.accumulo.core.client
-   * org.apache.accumulo.core.data
-   * org.apache.accumulo.core.security
-   * org.apache.accumulo.minicluster
-
-A type is a class, interface, or enum.  Anything with public or protected
-acccess in an API type is in the API.  This includes, but is not limited to:
-methods, members classes, interfaces, and enums.  Package-private types in
-the above packages are *not* considered public API.
-
-The following regex matches imports that are *not* Accumulo public API. This
-regex can be used with [RegexpSingleline][regex] to automatically find
-suspicious imports in a project using Accumulo.
-
-```
-import\s+org\.apache\.accumulo\.(.*\.(impl|thrift|crypto)\..*|(?!core|minicluster).*|core\.(?!client|data|security).*)
-```
-
-The Accumulo project maintains binary compatibility across this API within a
-major release, as defined in the Java Language Specification 3rd ed. Starting
-with Accumulo 1.6.2 and 1.7.0 all API changes will follow [semver 2.0][semver]
+The javadoc in [Accumulo.java] defines Accumulo's public API.
 
 ## Export Control
 
@@ -99,6 +76,7 @@ the bouncycastle library for some crypographic technology as well. See
 [the BouncyCastle FAQ][bouncy-faq] for
 more details on bouncycastle's cryptography features.
 
+[Accumulo.java]: core/src/main/java/org/apache/accumulo/core/client/Accumulo.java
 [accumulo]: https://accumulo.apache.org
 [logo]: contrib/accumulo-logo.png
 [install]: INSTALL.md
@@ -109,8 +87,6 @@ more details on bouncycastle's cryptography features.
 [docs]: https://accumulo.apache.org/latest/accumulo_user_manual
 [examples]: https://github.com/apache/accumulo-examples
 [javadocs]: https://accumulo.apache.org/latest/apidocs
-[semver]: http://semver.org/spec/v2.0.0
-[regex]: http://checkstyle.sourceforge.net/config_regexp.html
 [li]: https://img.shields.io/badge/license-ASL-blue.svg
 [ll]: https://www.apache.org/licenses/LICENSE-2.0
 [mi]: https://maven-badges.herokuapp.com/maven-central/org.apache.accumulo/accumulo-core/badge.svg
diff --git a/core/src/main/java/org/apache/accumulo/core/client/Accumulo.java b/core/src/main/java/org/apache/accumulo/core/client/Accumulo.java
index 67b4a0e..cfaa7ac 100644
--- a/core/src/main/java/org/apache/accumulo/core/client/Accumulo.java
+++ b/core/src/main/java/org/apache/accumulo/core/client/Accumulo.java
@@ -17,26 +17,89 @@
 package org.apache.accumulo.core.client;
 
 import org.apache.accumulo.core.client.impl.AccumuloClientImpl;
+import org.apache.accumulo.core.client.lexicoder.Lexicoder;
+import org.apache.accumulo.core.client.rfile.RFile;
 
+//CHECKSTYLE:OFF
 /**
- * The main entry point for Accumulo public API.
+ * Entry point for majority of Accumulo's public API. Other Accumulo API entry points are
linked
+ * below.
  *
+ * <H2>API Definition</H2>
+ *
+ * Accumulo's public API is composed of all public types in the following packages and their
+ * sub-packages excluding those named <i>impl</i>, <i>thrift</i>,
or <i>crypto</i>.
+ *
+ * <UL>
+ * <LI>org.apache.accumulo.core.client
+ * <LI>org.apache.accumulo.core.data
+ * <LI>org.apache.accumulo.core.security
+ * <LI>org.apache.accumulo.minicluster
+ * </UL>
+ *
+ * <p>
+ * A type is a class, interface, or enum. Anything with public or protected access in an
API type is
+ * in the API. This includes, but is not limited to: methods, members classes, interfaces,
and
+ * enums. Package-private types in the above packages are <i>not</i> considered
public API.
+ *
+ * <p>
+ * API changes are made according to semver 2.0. Accumulo did not always follow semver, it
was
+ * adopted for Accumulo 1.6.2 and 1.7.0. The Accumulo project maintains binary compatibility
across
+ * this API within a major release, as defined in the Java Language Specification 3rd ed.
Accumulo
+ * code outside of the API does not follow semver and may change in incompatible ways at
any
+ * release.
+ *
+ * <p>
+ * The following regex matches imports that are <i>not</i> Accumulo public API.
This regex can be
+ * used with <a href="http://checkstyle.sourceforge.net/config_regexp.html">RegexpSingleline</a>
to
+ * automatically find suspicious imports in a project using Accumulo.
+ *
+ * <p>
+ * {@code import\s+org\.apache\.accumulo\.(.*\.(impl|thrift|crypto)\..*|(?!core|minicluster).*|core\.(?!client|data|security).*)}
+ *
+ * <H2>API Entry Points</H2>
+ *
+ * <p>
+ * This class contains all API entry points created in 2.0.0 or later. The majority of the
API is
+ * accessible indirectly via methods in this class. Below are a list of APIs entry points
that were
+ * created before Accumulo 2.0 and not accessible from here.
+ *
+ * <UL>
+ * <LI>Hadoop input, output formats and partitioners in
+ * {@code org.apache.accumulo.core.client.mapred} and
+ * {@code org.apache.accumulo.core.client.mapreduce} packages (excluding {@code impl} sub-packages).
+ * <LI>{@code org.apache.accumulo.minicluster.MiniAccumuloCluster} Not linkable by
javadoc, because
+ * in a separate module.
+ * <LI>{@link Lexicoder} and all of its implementations in the same package (excluding
the
+ * {@code impl} sub-package).
+ * <LI>{@link RFile}
+ * </UL>
+ *
+ * @see <a href="http://accumulo.apache.org/">Accumulo Website</a>
+ * @see <a href="http://semver.org/spec/v2.0.0">Semver 2.0</a>
  * @since 2.0.0
  */
+// CHECKSTYLE:ON
 public final class Accumulo {
 
   private Accumulo() {}
 
   /**
-   * Create an Accumulo client builder, used to construct a client. For example:
+   * Fluent entry point for creating an {@link AccumuloClient}. For example:
    *
-   * {@code Accumulo.newClient().forInstance(instanceName, zookeepers)
-   *         .usingPassword(user, password).withZkTimeout(1234).build();}
+   * <pre>
+   * <code>
+   *    AccumuloClient client = Accumulo.newClient()
+   *      .forInstance(instanceName, zookeepers)
+   *      .usingPassword(user, password)
+   *      .withZkTimeout(1234)
+   *      .build();
+   * </code>
+   * </pre>
    *
    * @return a builder object for Accumulo clients
    */
   public static AccumuloClient.ClientInfoOptions newClient() {
     return new AccumuloClientImpl.AccumuloClientBuilderImpl();
   }
-
 }
diff --git a/core/src/main/java/org/apache/accumulo/core/client/AccumuloClient.java b/core/src/main/java/org/apache/accumulo/core/client/AccumuloClient.java
index 02c2575..31b37f3 100644
--- a/core/src/main/java/org/apache/accumulo/core/client/AccumuloClient.java
+++ b/core/src/main/java/org/apache/accumulo/core/client/AccumuloClient.java
@@ -31,8 +31,8 @@ import org.apache.accumulo.core.security.Authorizations;
  * writer for the instance as well as various objects that permit administrative operations.
  * Enforces security on the client side with by requiring user credentials.
  *
- * Supports fluent API. Various options can be provided to {@link Accumulo#newClient()} and
when
- * finished a call to build() will return the AccumuloClient object. For example:
+ * Supports fluent API for creation. Various options can be provided to {@link Accumulo#newClient()}
+ * and when finished a call to build() will return the AccumuloClient object. For example:
  *
  * {@code Accumulo.newClient().forInstance(instanceName, zookeepers)
  *         .usingPassword(user, password).withZkTimeout(1234).build();}
@@ -187,6 +187,8 @@ public interface AccumuloClient {
    * @return Scanner object for configuring and querying data with
    * @throws TableNotFoundException
    *           when the specified table doesn't exist
+   *
+   * @see IsolatedScanner
    */
   public Scanner createScanner(String tableName, Authorizations authorizations)
       throws TableNotFoundException;
diff --git a/pom.xml b/pom.xml
index a23707e..6d3112b 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1158,6 +1158,7 @@
                 <property name="eachLine" value="true" />
               </module>
               <module name="TreeWalker">
+                <module name="SuppressionCommentFilter" />
                 <module name="OneTopLevelClass" />
                 <module name="RegexpSinglelineJava">
                   <property name="format" value="\s+$" />


Mime
View raw message