From commits-return-22150-archive-asf-public=cust-asf.ponee.io@accumulo.apache.org Tue Sep 25 20:02:10 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 2CB4318061A for ; Tue, 25 Sep 2018 20:02:10 +0200 (CEST) Received: (qmail 53700 invoked by uid 500); 25 Sep 2018 18:02:09 -0000 Mailing-List: contact commits-help@accumulo.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@accumulo.apache.org Delivered-To: mailing list commits@accumulo.apache.org Received: (qmail 53691 invoked by uid 99); 25 Sep 2018 18:02:09 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Sep 2018 18:02:09 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id A637F82C77; Tue, 25 Sep 2018 18:02:08 +0000 (UTC) Date: Tue, 25 Sep 2018 18:02:08 +0000 To: "commits@accumulo.apache.org" Subject: [accumulo-website] branch master updated: Document public API (#109) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Message-ID: <153789852861.29976.8023813388982800513@gitbox.apache.org> From: kturner@apache.org X-Git-Host: gitbox.apache.org X-Git-Repo: accumulo-website X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: d47fe6b5192b46d5c95954d980f2a153bf940089 X-Git-Newrev: 16fd65776095f9cb4209a5858fd262e0478e5fe5 X-Git-Rev: 16fd65776095f9cb4209a5858fd262e0478e5fe5 X-Git-NotificationType: ref_changed_plus_diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated 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 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 ``` +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.