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 <ktur...@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+$" />
