Initial import

andrross · May 7, 2021 · 8d6ab5b · 8d6ab5b
1 parent e7415b3
commit 8d6ab5b
Show file tree

Hide file tree

Showing 59 changed files with 6,022 additions and 19 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,23 +1,19 @@
-# Compiled class file
-*.class
+.gradle
+build/
+/gradle/
 
-# Log file
-*.log
+# Ignore Gradle GUI config
+gradle-app.setting
 
-# BlueJ files
-*.ctxt
+# Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
+!gradle-wrapper.jar
 
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
+# Cache of project
+.gradletasknamecache
 
-# Package Files #
-*.jar
-*.war
-*.nar
-*.ear
-*.zip
-*.tar.gz
-*.rar
+# # Work around https://youtrack.jetbrains.com/issue/IDEA-116898
+# gradle/wrapper/gradle-wrapper.properties
 
-# virtual machine crash logs, see http://www.java.com/en/download/help/error_hotspot.xml
-hs_err_pid*
+# IntelliJ Idea
+.idea
+*.iml
diff --git a/README.md b/README.md
@@ -1,2 +1,61 @@
 # elasticsearch-java
-Next-gen Official Elasticsearch Java Client 
+
+Next Generation [Elasticsearch](https://github.com/elastic/elasticsearch) High Level Java client
+
+_**This project is still a work in progress**_
+
+This high-level client provides strongly typed requests and responses for all Elasticsearch APIs.
+It uses the Java low-level client for all transport-level concerns (http connection establishment and pooling, retries, etc).
+
+The `docs/design` folder contains records of the major decisions in the design of the API. Most notably:
+
+- Object construction is based on the [fluent builder pattern](https://www.informit.com/articles/article.aspx?p=1216151).
+- Nested objects can be constructed with builder lambdas, allowing for clean and expressive DSL-like code.
+- Optional values are represented as `null` with `@Nullable` annotations instead of the newer  `Optional`, the Java ecosystem being still very null-based.
+
+## Getting started
+
+### Installing the library
+
+While still a work in progress, this library is published on a private Maven repository hosted on [GitHub Packages](https://docs.github.com/en/packages).
+
+It can be added to a Gradle project (Groovy flavor) as follows:
+
+```groovy
+repositories {
+    mavenCentral()
+    maven {
+        name = "GitHubPackages"
+        url = uri("https://maven.pkg.github.com/elastic/elasticsearch-java")
+        credentials {
+            username = project.findProperty("gpr.user") ?: System.getenv("GITHUB_USERNAME")
+            password = project.findProperty("gpr.key") ?: System.getenv("GITHUB_TOKEN")
+        }
+    }
+}
+
+dependencies {
+    implementation 'co.elastic.clients:java-client:1.0.0-SNAPSHOT'
+}
+```
+
+### Your first request
+
+```java
+// Create the low-level client
+RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200)).build();
+
+// Build the high-level client
+ElasticsearchClient client = new ElasticsearchClient(restClient);
+
+// Search all items in an index
+SearchResponse search = client.search(s -> s
+    .index("test-index")
+);
+
+if (search.hits().hits().isEmpty()) {
+    System.out.println("No match");
+} else {
+    //...
+}
+```
diff --git a/build.gradle.kts b/build.gradle.kts
@@ -0,0 +1,32 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+group = "co.elastic.clients"
+version = "1.0-SNAPSHOT"
+
+
+subprojects {
+    apply(plugin = "checkstyle")
+}
+
+/*
+TODO:
+- checkstyle + reformat
+- license check
+ */
diff --git a/config/checkstyle/checkstyle.xml b/config/checkstyle/checkstyle.xml
@@ -0,0 +1,141 @@
+<?xml version="1.0"?>
+<!--
+  ~ Licensed to Elasticsearch B.V. under one or more contributor
+  ~ license agreements. See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright
+  ~ ownership. Elasticsearch B.V. licenses this file to you under
+  ~ the Apache License, Version 2.0 (the "License"); you may
+  ~ not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+
+<!DOCTYPE module PUBLIC
+        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
+        "https://checkstyle.org/dtds/configuration_1_3.dtd">
+
+<module name="Checker">
+    <property name="charset" value="UTF-8" />
+
+    <module name="SuppressionFilter">
+        <property name="file" value="${config_loc}/checkstyle_suppressions.xml" />
+    </module>
+
+    <module name="Header">
+        <property name="headerFile" value="${config_loc}/header.java.txt"/>
+        <property name="fileExtensions" value="java,kt,kts"/>
+    </module>
+
+    <module name="SuppressWarningsFilter" />
+
+    <!-- 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
+      unfair. -->
+    <module name="LineLength">
+        <property name="max" value="140" />
+        <property name="ignorePattern" value="^ *\* *https?://[^ ]+$" />
+    </module>
+
+    <module name="TreeWalker">
+        <!-- Make the @SuppressWarnings annotations available to Checkstyle -->
+        <module name="SuppressWarningsHolder" />
+
+        <module name="AvoidStarImport" />
+
+        <!-- Unused imports are forbidden -->
+        <module name="UnusedImports" />
+
+        <!-- Non-inner classes must be in files that match their names. -->
+        <module name="OuterTypeFilename" />
+
+        <!-- No line wraps inside of import and package statements. -->
+        <module name="NoLineWrap" />
+
+        <!-- only one statement per line should be allowed -->
+        <module name="OneStatementPerLine" />
+
+        <!-- Each java file has only one outer class -->
+        <module name="OneTopLevelClass" />
+
+        <!-- The suffix L is preferred, because the letter l (ell) is often
+          hard to distinguish from the digit 1 (one). -->
+        <module name="UpperEll" />
+
+        <module name="EqualsHashCode" />
+
+        <!-- Checks that the order of modifiers conforms to the suggestions in the
+        Java Language specification, sections 8.1.1, 8.3.1 and 8.4.3. It is not that
+        the standard is perfect, but having a consistent order makes the code more
+        readable and no other order is compellingly better than the standard.
+        The correct order is:
+                public
+                protected
+                private
+                abstract
+                static
+                final
+                transient
+                volatile
+                synchronized
+                native
+                strictfp
+        -->
+        <module name="ModifierOrder" />
+
+        <!-- Checks that we don't include modifier where they are implied. For
+          example, this does not allow interface methods to be declared public
+          because they are *always* public. -->
+        <module name="RedundantModifier" />
+
+        <!-- Checks that all java files have a package declaration and that it
+          lines up with the directory structure. -->
+        <module name="PackageDeclaration" />
+
+        <!-- We don't use Java's builtin serialization and we suppress all warning
+          about it. The flip side of that coin is that we shouldn't _try_ to use
+          it. We can't outright ban it with ForbiddenApis because it complain about
+          every we reference a class that implements Serializable like String or
+          Exception.
+          -->
+        <module name="RegexpSinglelineJava">
+            <property name="format" value="serialVersionUID" />
+            <property name="message" value="Do not declare serialVersionUID." />
+            <property name="ignoreComments" value="true" />
+        </module>
+        <module name="RegexpSinglelineJava">
+            <property name="format" value="java\.io\.Serializable;" />
+            <property name="message" value="References java.io.Serializable." />
+            <property name="ignoreComments" value="true" />
+        </module>
+        <!-- end Orwellian suppression of Serializable -->
+
+        <!-- Forbid equality comparisons with `true` -->
+        <module name="DescendantToken">
+            <property name="id" value="EqualityWithTrue" />
+            <property name="tokens" value="EQUAL" />
+            <property name="limitedTokens" value="LITERAL_TRUE" />
+            <property name="maximumNumber" value="0" />
+            <property name="maximumDepth" value="1" />
+            <message key="descendant.token.max" value="Do not check for equality with 'true', since it is implied" />
+        </module>
+
+    </module>
+</module>
diff --git a/config/checkstyle/checkstyle_suppressions.xml b/config/checkstyle/checkstyle_suppressions.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<!--
+  ~ Licensed to Elasticsearch B.V. under one or more contributor
+  ~ license agreements. See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright
+  ~ ownership. Elasticsearch B.V. licenses this file to you under
+  ~ the Apache License, Version 2.0 (the "License"); you may
+  ~ not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing,
+  ~ software distributed under the License is distributed on an
+  ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  ~ KIND, either express or implied.  See the License for the
+  ~ specific language governing permissions and limitations
+  ~ under the License.
+  -->
+
+<!DOCTYPE suppressions PUBLIC
+        "-//Checkstyle//DTD SuppressionFilter Configuration 1.1//EN"
+        "https://checkstyle.org/dtds/suppressions_1_1.dtd">
+
+<suppressions>
+    <!-- Do not enforce line length on generated code -->
+    <suppress files="client[/\\]src[/\\]main[/\\]java[/\\]co[/\\]elastic[/\\]clients[/\\]elasticsearch[/\\]api[^.]*\.java" checks="LineLength" />
+    <suppress files="client[/\\]src[/\\]main[/\\]java[/\\]co[/\\]elastic[/\\]clients[/\\]elasticsearch[/\\]api[^.]*\.java" checks="UnusedImports" />
+    <suppress files="client[/\\]src[/\\]main[/\\]java[/\\]co[/\\]elastic[/\\]clients[/\\]elasticsearch[/\\]Elasticsearch[^.]*\.java" checks="LineLength" />
+    <suppress files="client[/\\]src[/\\]main[/\\]java[/\\]co[/\\]elastic[/\\]clients[/\\]elasticsearch[/\\]Elasticsearch[^.]*\.java" checks="UnusedImports" />
+</suppressions>
diff --git a/config/checkstyle/header.java.txt b/config/checkstyle/header.java.txt
@@ -0,0 +1,18 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */