accumulo-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ktur...@apache.org
Subject [accumulo-website] branch master updated: Document public API (#109)
Date Tue, 25 Sep 2018 18:02:08 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-website.git


The following commit(s) were added to refs/heads/master by this push:
     new 16fd657  Document public API (#109)
16fd657 is described below

commit 16fd65776095f9cb4209a5858fd262e0478e5fe5
Author: Keith Turner <keith@deenlo.com>
AuthorDate: Tue Sep 25 14:02:04 2018 -0400

    Document public API (#109)
---
 README.md                            |  2 +-
 _docs-2-0/getting-started/clients.md |  4 ++++
 pages/api.md                         | 35 +++++++++++++++++++++++++++++++++++
 tour/index.md                        |  2 +-
 4 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e2cd4ce..11f139d 100644
--- a/README.md
+++ b/README.md
@@ -42,7 +42,7 @@ The source for these tags is at [_plugins/links.rb](_plugins/links.rb).
 
 | Tag   | Description            | Options                                              
                          | Examples                                             | 
 | ----- | ---------------------- | -------------------------------------------------------------------------------
| ---------------------------------------------------- |
-| jlink | Creates Javadoc link   | Link text will be class name by default. Use `-f` for
full package + class name | `{% jlink -f org.apache.accumulo.core.client.Connector %}` |
+| jlink | Creates Javadoc link   | Link text will be class name by default. Use `-f` for
full package + class name | `{% jlink -f org.apache.accumulo.core.client.Connector %}`  `{%
jlink -f org.apache.accumulo.core.client %}` |
 | jurl  | Creates Javadoc URL    | None                                                 
                          | `{% jurl org.apache.accumulo.core.client.Connector %}`     |
 | plink | Creates Property link  | Assumes server property by default. Use `-c` to link to
client properties. Accepts server property prefixes (i.e `table.*`)       | `{% plink -c instance.name
%}`                             |
 | purl  | Creates Property URL   | Default is server property. Use `-c` to link to client
properties. Accepts server property prefixes (i.e `table.*`)               | `{% purl instance.volumes
%}`                             |
diff --git a/_docs-2-0/getting-started/clients.md b/_docs-2-0/getting-started/clients.md
index 3cab9e6..0811c71 100644
--- a/_docs-2-0/getting-started/clients.md
+++ b/_docs-2-0/getting-started/clients.md
@@ -16,6 +16,10 @@ If you are using Maven to create Accumulo client code, add the following
to your
 </dependency>
 ```
 
+When writing code that uses Accumulo, only use the [Accumulo Public API](/api).
+The `accumulo-core` artifact includes implementation code that falls outside the
+Public API and should be avoided.
+
 ## Connecting
 
 Before writing Accumulo client code, you will need the following information.
diff --git a/pages/api.md b/pages/api.md
new file mode 100644
index 0000000..66a2085
--- /dev/null
+++ b/pages/api.md
@@ -0,0 +1,35 @@
+---
+title: Public API Definition
+permalink: /api/
+---
+
+Accumulo's public API is composed of all public types in the following
+packages and their sub-packages excluding those named *impl*, *thrift*, or
+*crypto*.
+
+ * {% jlink -f org.apache.accumulo.core.client %}
+ * {% jlink -f org.apache.accumulo.core.data %}
+ * {% jlink -f org.apache.accumulo.core.security %}
+ * {% jlink -f org.apache.accumulo.minicluster %}
+
+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 *not* considered public API.
+
+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 follow [semver 2.0][semver].
+Accumulo code outside of the defined API does not follow semver and may change
+in incompatible ways at any release.
+
+The following regex matches imports that are *not* Accumulo public API. This
+regex can be used with [RegexpSingleline] to automatically find suspicious
+imports in a project using Accumulo.
+
+```
+import\s+org\.apache\.accumulo\.(.*\.(impl|thrift|crypto)\..*|(?!core|minicluster).*|core\.(?!client|data|security).*)
+```
+
+[semver]: http://semver.org/spec/v2.0.0
+[RegexpSingleline]: http://checkstyle.sourceforge.net/config_regexp.html
diff --git a/tour/index.md b/tour/index.md
index 9f01ab0..eacba6a 100644
--- a/tour/index.md
+++ b/tour/index.md
@@ -9,7 +9,7 @@ skiph1fortitle: true
 {% assign first_url = tour_pages[0] | prepend: '/tour/' | append: '/' %}
 {% assign first_page = site.pages | where:'url',first_url | first %}
 
-Welcome to the Accumulo tour! The tour offers a hands on introduction to the Accumulo Java
API, broken down into
+Welcome to the Accumulo tour! The tour offers a hands on introduction to the [Accumulo Java
API](/api), broken down into
 independent steps and exercises. The exercises give you a chance to apply what you have learned
by writing code on your
 own. The answers to an exercise are typically provided in the next step.  The tour starts
with a 
 [{{ first_page.title }}]({{ first_url }}) page that will help you get set up.


Mime
View raw message