Rest HL client: Add put license action (#32214)

In the HL REST client we replace the License object with a string, because of 
complexity of this class. It is also not really needed on the client side since 
end-users are not interacting with the license besides passing it as a string 
to the server.

Relates #29827

docs/java-rest/high-level/licensing/put-license.asciidoc

@@ -0,0 +1,66 @@
+[[java-rest-high-put-license]]
+=== Update License
+
+[[java-rest-high-put-license-execution]]
+==== Execution
+
+The license can be added or updated using the `putLicense()` method:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/LicensingDocumentationIT.java[put-license-execute]
+--------------------------------------------------
+<1> Set the categories of information to retrieve. The the default is to
+return no information which is useful for checking if {xpack} is installed
+but not much else.
+<2> A JSON document containing the license information.
+
+[[java-rest-high-put-license-response]]
+==== Response
+
+The returned `PutLicenseResponse` contains the `LicensesStatus`,
+`acknowledged` flag and possible acknowledge messages. The acknowledge messages
+are present if you previously had a license with more features than one you
+are trying to update and you didn't set the `acknowledge` flag to `true`. In this case
+you need to display the messages to the end user and if they agree, resubmit the
+license with the `acknowledge` flag set to `true`. Please note that the request will
+still return a 200 return code even if requires an acknowledgement. So, it is
+necessary to check the `acknowledged` flag.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/LicensingDocumentationIT.java[put-license-response]
+--------------------------------------------------
+<1> The status of the license
+<2> Make sure that the license is valid.
+<3> Check the acknowledge flag.
+<4> It should be true if license is acknowledge.
+<5> Otherwise we can see the acknowledge messages in `acknowledgeHeader()`
+<6> and check component-specific messages in `acknowledgeMessages()`.
+
+[[java-rest-high-put-license-async]]
+==== Asynchronous Execution
+
+This request can be executed asynchronously:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/LicensingDocumentationIT.java[put-license-execute-async]
+--------------------------------------------------
+<1> The `PutLicenseRequest` to execute and the `ActionListener` to use when
+the execution completes
+
+The asynchronous method does not block and returns immediately. Once it is
+completed the `ActionListener` is called back using the `onResponse` method
+if the execution successfully completed or using the `onFailure` method if
+it failed.
+
+A typical listener for `PutLicenseResponse` looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests}/LicensingDocumentationIT.java[put-license-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed. The response is
+provided as an argument
+<2> Called in case of failure. The raised exception is provided as an argument

docs/java-rest/high-level/supported-apis.asciidoc

@@ -186,3 +186,12 @@ The Java High Level REST Client supports the following Scripts APIs:
 
 include::script/get_script.asciidoc[]
 include::script/delete_script.asciidoc[]
+
+
+== Licensing APIs
+
+The Java High Level REST Client supports the following Licensing APIs:
+
+* <<java-rest-high-put-license>>
+
+include::licensing/put-license.asciidoc[]