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 <ke...@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.
