From 47e217bdd4862e6faa579cba3e8960bad4b758c4 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Tue, 31 May 2022 19:16:14 +0200 Subject: [PATCH 1/5] Add docs about MissingRequiredPropertyException --- docs/api-conventions/exceptions.asciidoc | 2 +- docs/api-conventions/index.asciidoc | 2 +- docs/index.asciidoc | 2 +- docs/troubleshooting/index.asciidoc | 17 ++++++--- .../missing-required-property.asciidoc | 36 +++++++++++++++++++ 5 files changed, 51 insertions(+), 8 deletions(-) create mode 100644 docs/troubleshooting/missing-required-property.asciidoc diff --git a/docs/api-conventions/exceptions.asciidoc b/docs/api-conventions/exceptions.asciidoc index 43d730ec9..ef1c7863c 100644 --- a/docs/api-conventions/exceptions.asciidoc +++ b/docs/api-conventions/exceptions.asciidoc @@ -1,4 +1,4 @@ -[[exceptions]] +[[exception-conventions]] === Exceptions Client methods can throw two kinds of exceptions: diff --git a/docs/api-conventions/index.asciidoc b/docs/api-conventions/index.asciidoc index 7c4373d91..d30023609 100644 --- a/docs/api-conventions/index.asciidoc +++ b/docs/api-conventions/index.asciidoc @@ -15,7 +15,7 @@ to process. The sections below explain these in details. ifdef::is_main_branch,v8_1_1_released,v7_17_2_released[] * <> endif::is_main_branch,v8_1_1_released,v7_17_2_released[] -* <> +* <> include::package-structure.asciidoc[] include::method-naming.asciidoc[] diff --git a/docs/index.asciidoc b/docs/index.asciidoc index 3860ee044..0776377e9 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -32,7 +32,7 @@ include::api-conventions/index.asciidoc[] include::usage/index.asciidoc[] -// include::troubleshooting/index.asciidoc[] +include::troubleshooting/index.asciidoc[] include::javadoc-and-source.asciidoc[] include::release-notes.asciidoc[] include::external-resources.asciidoc[] diff --git a/docs/troubleshooting/index.asciidoc b/docs/troubleshooting/index.asciidoc index 433981b6d..fbdd14942 100644 --- a/docs/troubleshooting/index.asciidoc +++ b/docs/troubleshooting/index.asciidoc @@ -1,13 +1,20 @@ +[[troubleshooting]] == Troubleshooting +* <> +// * <> +// * <> + +[[exceptions]] === Understanding exceptions -TBD +* <> -=== Debugging -TBD +// [[debugging]] +// === Debugging -=== Elasticsearch deprecation warnings +//[[deprecation-warnings]] +// === Elasticsearch deprecation warnings -TBD +include::missing-required-property.asciidoc[] diff --git a/docs/troubleshooting/missing-required-property.asciidoc b/docs/troubleshooting/missing-required-property.asciidoc new file mode 100644 index 000000000..5d480b94a --- /dev/null +++ b/docs/troubleshooting/missing-required-property.asciidoc @@ -0,0 +1,36 @@ +[[missing-required-property]] +==== I'm getting a `MissingRequiredPropertyException` in a response + +The {java-client} distinguishes optional and required properties. Optional properties are marked with the `@Nullable` annotation. + +When an API object is built and a required property hasn't been set, a `MissingRequiredPropertyException` is thrown. This applies both to request object built by your application and to response objects returned by Elasticsearch, so that you can be assured that a property that does not have the `@Nullable` annotation will never be `null`. + +However, there may be bugs in the https://github.com/elastic/elasticsearch-specification[Elasticsearch API specification] where a response object's property is incorrectly required, leading to a `MissingRequiredPropertyException` when deserializing a response. If this happens, here's how you can work around it: + +* Make sure you use the latest release of the {java-client}. The issue may already have been fixed. +* If the issue is still present on the latest version, https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that we can fix it in the next release. Please help us to improve the {java-client}. +* Temporarily disable required property checks for the offending request: + +["source","java"] +-------------------------------------------------- + ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true); + SomeRequest request = SomeRequest.of(...); + SomeResponse response = esClient.someApi(request); + ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(false); + // Do something with response +} +-------------------------------------------------- + +The `DANGEROUS_disableRequiredPropertiesCheck` method disables required property checks on the current thread, and for response deserialization in asynchronous requests. As its name implies, it is dangerous as it removes the guarantees of properties that are not `@Nullable`. This is a temporary workaround until the issue is fixed (remember to https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue]). + +The result of this method is an `AutoCloseable` object that resets required property checks to its previous setting. You can therefore use it in a try-with-resource block as follows: + +["source","java"] +-------------------------------------------------- +try (ApiTypeHelper.DisabledChecksHandle h = + ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true)) { + SomeRequest request = SomeRequest.of(...); + SomeResponse response = esClient.someApi(request); + // Do something with response +} +-------------------------------------------------- From 5acfc08a5559d4dabd6444eed0b0d5f89758b564 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Tue, 31 May 2022 20:13:31 +0200 Subject: [PATCH 2/5] Revisit section layout --- docs/troubleshooting/index.asciidoc | 4 +--- docs/troubleshooting/missing-required-property.asciidoc | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/troubleshooting/index.asciidoc b/docs/troubleshooting/index.asciidoc index fbdd14942..6be99e1b1 100644 --- a/docs/troubleshooting/index.asciidoc +++ b/docs/troubleshooting/index.asciidoc @@ -1,12 +1,10 @@ [[troubleshooting]] == Troubleshooting -* <> // * <> // * <> -[[exceptions]] -=== Understanding exceptions +.Exceptions * <> diff --git a/docs/troubleshooting/missing-required-property.asciidoc b/docs/troubleshooting/missing-required-property.asciidoc index 5d480b94a..82b7fca17 100644 --- a/docs/troubleshooting/missing-required-property.asciidoc +++ b/docs/troubleshooting/missing-required-property.asciidoc @@ -1,5 +1,5 @@ [[missing-required-property]] -==== I'm getting a `MissingRequiredPropertyException` in a response +=== `MissingRequiredPropertyException` in a response The {java-client} distinguishes optional and required properties. Optional properties are marked with the `@Nullable` annotation. From 7fa6b312145856a7980e7af9b9c6705ca05667dc Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Tue, 31 May 2022 21:14:07 +0200 Subject: [PATCH 3/5] Fix typo --- docs/usage/aggregations.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index d4ca1afd8..7d2ad887d 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -3,7 +3,7 @@ An aggregation summarizes your data as metrics, statistics, or other analytics. -NOTE: See the es-docs}/search-aggregations[{es} documentation] for a full explanation of aggregations. +NOTE: See the {es-docs}/search-aggregations[{es} documentation] for a full explanation of aggregations. [discrete] ==== A simple aggregation From 04c5b6390286ce3381f4278dc451352896969df3 Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Wed, 1 Jun 2022 10:38:33 +0200 Subject: [PATCH 4/5] Fix link, add warning --- docs/troubleshooting/missing-required-property.asciidoc | 6 ++++-- docs/usage/aggregations.asciidoc | 2 +- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/troubleshooting/missing-required-property.asciidoc b/docs/troubleshooting/missing-required-property.asciidoc index 82b7fca17..8eb7d1928 100644 --- a/docs/troubleshooting/missing-required-property.asciidoc +++ b/docs/troubleshooting/missing-required-property.asciidoc @@ -7,6 +7,8 @@ When an API object is built and a required property hasn't been set, a `MissingR However, there may be bugs in the https://github.com/elastic/elasticsearch-specification[Elasticsearch API specification] where a response object's property is incorrectly required, leading to a `MissingRequiredPropertyException` when deserializing a response. If this happens, here's how you can work around it: +WARNING: This is a workaround. Do not consider this as a permanent solution, and please https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that the problem can be fixed in a future release. + * Make sure you use the latest release of the {java-client}. The issue may already have been fixed. * If the issue is still present on the latest version, https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that we can fix it in the next release. Please help us to improve the {java-client}. * Temporarily disable required property checks for the offending request: @@ -21,9 +23,9 @@ However, there may be bugs in the https://github.com/elastic/elasticsearch-speci } -------------------------------------------------- -The `DANGEROUS_disableRequiredPropertiesCheck` method disables required property checks on the current thread, and for response deserialization in asynchronous requests. As its name implies, it is dangerous as it removes the guarantees of properties that are not `@Nullable`. This is a temporary workaround until the issue is fixed (remember to https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue]). +The `DANGEROUS_disableRequiredPropertiesCheck` method disables required property checks on the current thread, and for response deserialization in asynchronous requests. As its name implies, it is dangerous as it removes the guarantees of properties that are not `@Nullable`. This is a temporary workaround until the issue is fixed. -The result of this method is an `AutoCloseable` object that resets required property checks to its previous setting. You can therefore use it in a try-with-resource block as follows: +Note that the result of this method is an `AutoCloseable` object that resets required property checks to its previous setting. You can therefore use it in a try-with-resource block as follows: ["source","java"] -------------------------------------------------- diff --git a/docs/usage/aggregations.asciidoc b/docs/usage/aggregations.asciidoc index 7d2ad887d..51c64b341 100644 --- a/docs/usage/aggregations.asciidoc +++ b/docs/usage/aggregations.asciidoc @@ -3,7 +3,7 @@ An aggregation summarizes your data as metrics, statistics, or other analytics. -NOTE: See the {es-docs}/search-aggregations[{es} documentation] for a full explanation of aggregations. +NOTE: See the {es-docs}/search-aggregations.html[{es} documentation] for a full explanation of aggregations. [discrete] ==== A simple aggregation From 7a091cbf2f895aca0acd5a9006ed745c6816358e Mon Sep 17 00:00:00 2001 From: Sylvain Wallez Date: Wed, 1 Jun 2022 10:52:54 +0200 Subject: [PATCH 5/5] Move warning --- docs/troubleshooting/missing-required-property.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/troubleshooting/missing-required-property.asciidoc b/docs/troubleshooting/missing-required-property.asciidoc index 8eb7d1928..a338b35d1 100644 --- a/docs/troubleshooting/missing-required-property.asciidoc +++ b/docs/troubleshooting/missing-required-property.asciidoc @@ -7,12 +7,12 @@ When an API object is built and a required property hasn't been set, a `MissingR However, there may be bugs in the https://github.com/elastic/elasticsearch-specification[Elasticsearch API specification] where a response object's property is incorrectly required, leading to a `MissingRequiredPropertyException` when deserializing a response. If this happens, here's how you can work around it: -WARNING: This is a workaround. Do not consider this as a permanent solution, and please https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that the problem can be fixed in a future release. - * Make sure you use the latest release of the {java-client}. The issue may already have been fixed. * If the issue is still present on the latest version, https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that we can fix it in the next release. Please help us to improve the {java-client}. * Temporarily disable required property checks for the offending request: +WARNING: This is a workaround. Do not consider this as a permanent solution, and please https://github.com/elastic/elasticsearch-java/issues/new/choose[open an issue] so that the problem can be fixed in a future release. + ["source","java"] -------------------------------------------------- ApiTypeHelper.DANGEROUS_disableRequiredPropertiesCheck(true);