Promote client to beta stability

.ci/Dockerfile

@@ -34,6 +34,7 @@ COPY LICENSE.txt NOTICE.txt ./
 # Prefetch dependencies
 COPY build.gradle.kts settings.gradle.kts ./
 COPY buildSrc ./buildSrc/
+COPY config ./config/
 COPY java-client/build.gradle.kts ./java-client/
 RUN ./gradlew resolveDependencies
 

.github/workflows/checkstyle.yml

@@ -4,14 +4,17 @@ on: [pull_request]
 jobs:
   build:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        java-version: [ 11 ]
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set up JDK 11
+      - name: Set up JDK ${{ matrix.java-version }}
         uses: actions/setup-java@v2
         with:
-          java-version: '11'
-          distribution: 'adopt'
+          java-version: ${{ matrix.java-version }}
+          distribution: 'temurin'
 
       - name: Check style and license headers
         run: |

README.md

@@ -22,77 +22,57 @@ The `docs/design` folder contains records of the major decisions in the design o
 
 ### Installing the library
 
-While it's a work in progress, snapshots of this library are published to a Maven repository hosted on [GitHub Packages](https://github.com/elastic/elasticsearch-java/packages/). To access it [you need a personal access token](https://github.com/settings/tokens) on your GitHub account that has the `read:packages` permission. This token should then be added to `~/.gradle/gradle.properties`:
-
-```properties
-ESJavaGithubPackagesUsername=YOUR_GITHUB_USERNAME
-ESJavaGithubPackagesPassword=YOUR_GITHUB_TOKEN
-```
+This library requires at least Java 8.
 
 Along with this library, you also need a JSON/object mapping library. `elasticsearch-java` has built-in support for [Jackson](https://github.com/FasterXML/jackson) and [JSON-B](http://json-b.net/) implementations such as [Eclipse Yasson](https://github.com/eclipse-ee4j/yasson).
 
-This library requires at least Java 8.
+While it's a work in progress, snapshots of this library are published to Elastic's snapshot repository. Snapshots are currently available for the upcoming version 7.15.0, built from the `7.x` branch.
 
 Gradle project (Groovy flavor) setup using Jackson:
 
 ```groovy
 repositories {
     mavenCentral()
     maven {
-        name = "ESJavaGithubPackages"
-        url = uri("https://maven.pkg.github.com/elastic/elasticsearch-java")
-        credentials(PasswordCredentials)
+        name = "Elastic-Snapshots"
+        url = uri("https://snapshots.elastic.co/maven")
     }
 }
 
 dependencies {
-    implementation 'co.elastic.clients:elasticsearch-java:8.0.0-SNAPSHOT'
+    implementation 'co.elastic.clients:elasticsearch-java:7.15.0-SNAPSHOT'
     implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.3'
 }
 ```
 
-If you are using Maven, you need to add the credentials in your `~/.m2/settings.xml`:
-
-```xml
-<settings>
-  <servers>
-    <server>
-      <id>ESJavaGithubPackages</id>
-      <username>YOUR_GITHUB_USERNAME</username>
-      <password>YOUR_GITHUB_TOKEN</password>
-    </server>
-  </servers>
-</settings>
-```
-
 In the `pom.xml` for your project add the following repository definition and dependencies:
 
 ```xml
 <project>
-    
+
   <repositories>
     <repository>
-      <id>ESJavaGithubPackages</id>
-      <url>https://maven.pkg.github.com/elastic/elasticsearch-java</url>
+      <id>Elastic-Snapshots</id>
+      <url>https://snapshots.elastic.co/maven</url>
       <snapshots>
         <enabled>true</enabled>
       </snapshots>
       </repository>
   </repositories>
-    
+
   <dependencies>
     <dependency>
       <groupId>co.elastic.clients</groupId>
       <artifactId>elasticsearch-java</artifactId>
-      <version>8.0.0-SNAPSHOT</version>
+      <version>7.15.0-SNAPSHOT</version>
     </dependency>
     <dependency>
       <groupId>com.fasterxml.jackson.core</groupId>
       <artifactId>jackson-databind</artifactId>
       <version>2.12.3</version>
     </dependency>
   </dependencies>
-    
+
 </project>
 ```
 
@@ -125,14 +105,14 @@ if (search.hits().hits().isEmpty()) {
 
 ## Compatibility
 
-The `main` branch targets the upcoming Elasticsearch 8.0. Support is still incomplete as the API code is generated from the [Elasticsearch Specification](https://github.com/elastic/elasticsearch-specification) that is also still a work in progress. 
+The `main` branch targets the next major release (8.0) and the `7.x` branch targets the next minor release. Support is still incomplete as the API code is generated from the [Elasticsearch Specification](https://github.com/elastic/elasticsearch-specification) that is also still a work in progress.
 
-As the work on the specification comes to completion, an additional `7.x` branch will provide support for the corresponding versions of Elasticsearch.
+The Elasticsearch Java client is forward compatible; meaning that the client supports communicating with greater minor versions of Elasticsearch. Elastic language clients are also backwards compatible with lesser supported minor Elasticsearch versions.
 
 ## Current status
 
 While not complete, this library is already fairly usable. What's missing falls in two main categories, related to the [Elasticsearch specification](https://github.com/elastic/elasticsearch-specification):
-* incomplete support for some data types used in specification (e.g. unions). Until they have been implemented in the code generator, they are represented as raw `JsonValue` objects. 
+* incomplete support for some data types used in specification (e.g. unions). Until they have been implemented in the code generator, they are represented as raw `JsonValue` objects.
 * incomplete APIs: as the API specification is still incomplete, so are their implementations in this library since their code is entirely generated from the spec.
 
 ## Contributing

build.gradle.kts

@@ -19,7 +19,9 @@
 
 allprojects {
     group = "co.elastic.clients"
-    version = System.getenv("VERSION") ?: "8.0.0-SNAPSHOT"
+    // Release manager provides a $VERSION. If not present, it's a local or CI snapshot build.
+    version = System.getenv("VERSION") ?:
+        (File(project.rootDir, "config/version.txt").readText().trim() + "-SNAPSHOT")
 
     repositories {
         mavenCentral()

config/checkstyle/checkstyle.xml

@@ -39,12 +39,14 @@
     <!-- Checks Java files and forbids empty Javadoc comments. -->
     <!-- Although you can use the "JavadocStyle" rule for this, it considers Javadoc -->
     <!-- that only contains a "@return" line to be empty. -->
+    <!--
     <module name="RegexpMultiline">
         <property name="id" value="EmptyJavadoc" />
         <property name="format" value="\/\*[\s\*]*\*\/" />
         <property name="fileExtensions" value="java" />
         <property name="message" value="Empty javadoc comments are forbidden" />
     </module>
+    -->
 
     <!-- Its our official line length! See checkstyle_suppressions.xml for the files that don't pass this. For now we
       suppress the check there but enforce it everywhere else. This prevents the list from getting longer even if it is

config/version.txt

@@ -0,0 +1 @@
+8.0.0

docs/connecting.asciidoc

@@ -0,0 +1,25 @@
+[[connecting]]
+== Connecting
+
+beta[]
+
+The code snippet below shows how to initialize a low level REST client and the
+Jackson object mapper to configure an ElasticsearchClient:
+
+
+["source","java"]
+--------------------------------------------------
+// Create the low-level client
+RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200)).build();
+
+// Create the transport that provides JSON and http services to API clients
+Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
+
+// And create our API client
+ElasticsearchClient client = new ElasticsearchClient(transport);
+--------------------------------------------------
+
+Authentication is managed by the
+https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/java-rest-low.html[low-level Rest Client].
+For further details on configuring authentication, refer to the
+https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/_basic_authentication.html[documentation].

docs/index.asciidoc

@@ -0,0 +1,8 @@
+= Elasticsearch Java API Client
+
+:branch: master
+include::{asciidoc-dir}/../../shared/attributes.asciidoc[]
+
+include::introduction.asciidoc[]
+include::installation.asciidoc[]
+include::connecting.asciidoc[]

docs/installation.asciidoc

@@ -0,0 +1,76 @@
+[[installation]]
+== Installation
+
+beta[]
+
+This page guides you through the installation process of the client.
+
+Requirements:
+
+* Java 8 or later. The library provides high-level type-safe classes
+  and methods for all {es} APIs. It sits on top of the
+  https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/java-rest-low.html[Low Level Rest Client]
+  that manages all http communications.
+
+* The JSON implementation used by the Java client is pluggable and you must add
+  a JSON object mapping library as a dependency to your project. It has support
+  for https://github.com/FasterXML/jackson[Jackson] or a
+  http://json-b.net/[JSON-B] library like
+  https://github.com/eclipse-ee4j/yasson[Eclipse Yasson].
+
+
+Releases are hosted on https://search.maven.org/search?q=g:co.elastic.clients[Maven Central]. If you are looking for
+a SNAPSHOT version, the Elastic Maven Snapshot repository is available at https://snapshots.elastic.co/maven/.
+
+
+[discrete]
+[[gradle]]
+=== Installation in a Gradle project by using Jackson
+
+["source","groovy",subs="attributes"]
+--------------------------------------------------
+dependencies {
+    implementation 'co.elastic.clients:elasticsearch-java:7.15.0'
+    implementation 'com.fasterxml.jackson.core:jackson-databind:2.12.3'
+}
+--------------------------------------------------
+
+[discrete]
+[[maven]]
+=== Installation in a Maven project by using Jackson
+
+In the `pom.xml` of your project, add the following repository definition and
+dependencies:
+
+["source","xml",subs="attributes"]
+--------------------------------------------------
+<project>
+
+  <dependencies>
+    <dependency>
+      <groupId>co.elastic.clients</groupId>
+      <artifactId>elasticsearch-java</artifactId>
+      <version>7.15.0-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+      <version>2.12.3</version>
+    </dependency>
+  </dependencies>
+
+</project>
+--------------------------------------------------
+
+[discrete]
+[[compatibility]]
+=== Compatibility
+
+The `main` branch targets the next major release (8.0), the `7.x` branch targets
+the next minor release. Support is still incomplete as the API code is generated
+from the {es} Specification that is also still a work in progress.
+
+The {es} Java client is forward compatible; meaning that the client supports
+communicating with greater or equal minor versions of {es}. {es} language
+clients are only backwards compatible with default distributions and without
+guarantees made.

docs/introduction.asciidoc

@@ -0,0 +1,10 @@
+[[introduction]]
+== Introduction
+
+beta[]
+
+This is the official Java API client for {es}. The client provides strongly
+typed requests and responses for all {es} APIs. It delegates protocol handling
+to an http client such as the
+https://www.elastic.co/guide/en/elasticsearch/client/java-rest/master/java-rest-low.html[{es} Low Level REST client]
+that takes care of all transport-level concerns.

java-client/build.gradle.kts

@@ -107,13 +107,15 @@ publishing {
 }
 
 dependencies {
-    val elasticsearchVersion = "7.12.0"
+    val elasticsearchVersion = "7.15.0"
     val jacksonVersion = "2.12.0"
 
     // Apache 2.0
+    // https://www.elastic.co/guide/en/elasticsearch/client/java-rest/current/java-rest-low.html
     implementation("org.elasticsearch.client", "elasticsearch-rest-client", elasticsearchVersion)
 
     // Apache 2.0
+    // https://search.maven.org/artifact/com.google.code.findbugs/jsr305
     implementation("com.google.code.findbugs:jsr305:3.0.2")
 
     // EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
@@ -131,6 +133,7 @@ dependencies {
     testImplementation("jakarta.json.bind", "jakarta.json.bind-api", "2.0.0")
 
     // Apache 2.0
+    // https://github.com/FasterXML/jackson
     compileOnly("com.fasterxml.jackson.core", "jackson-core", jacksonVersion)
     compileOnly("com.fasterxml.jackson.core", "jackson-databind", jacksonVersion)
     testImplementation("com.fasterxml.jackson.core", "jackson-core", jacksonVersion)
@@ -140,10 +143,16 @@ dependencies {
     // https://eclipse-ee4j.github.io/yasson/
     testImplementation("org.eclipse", "yasson", "2.0.2")
 
-    // Eclipse 1.0
+    // EPL-1.0
+    // https://junit.org/junit4/
     testImplementation("junit", "junit" , "4.12")
 
     // MIT
+    // https://github.com/classgraph/classgraph
+    testImplementation("io.github.classgraph:classgraph:4.8.116")
+
+    // MIT
+    // https://www.testcontainers.org/
     testImplementation("org.testcontainers", "testcontainers", "1.15.3")
     testImplementation("org.testcontainers", "elasticsearch", "1.15.3")
 }