HLRC: Implement get-user-privileges API (#36292)

This adds the _security/user/_privileges API to the High
Level Rest Client.

This also makes some changes to the Java model for the Role APIs
in order to better accommodate the GetPrivileges API

docs/java-rest/high-level/execution-no-req.asciidoc

@@ -0,0 +1,55 @@
+////
+This file is included by high level rest client API documentation pages
+where the client method does not use a request object.
+For methods with requests, see execution.asciidoc
+////
+
+[id="{upid}-{api}-sync"]
+==== Synchronous Execution
+
+When executing the +{api}+ API in the following manner, the client waits
+for the +{response}+ to be returned before continuing with code execution:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute]
+--------------------------------------------------
+
+Synchronous calls may throw an `IOException` in case of either failing to
+parse the REST response in the high-level REST client, the request times out
+or similar cases where there is no response coming back from the server.
+
+In cases where the server returns a `4xx` or `5xx` error code, the high-level
+client tries to parse the response body error details instead and then throws
+a generic `ElasticsearchException` and adds the original `ResponseException` as a
+suppressed exception to it.
+
+[id="{upid}-{api}-async"]
+==== Asynchronous Execution
+
+The +{api}+ API can also be called in an asynchronous fashion so that
+the client can return directly. Users need to specify how the response or
+potential failures will be handled by passing a listener to the
+asynchronous {api} method:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute-async]
+--------------------------------------------------
+<1> The `RequestOptions` and `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. Failure scenarios and expected exceptions are the same as in the
+synchronous execution case.
+
+A typical listener for +{api}+ looks like:
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-execute-listener]
+--------------------------------------------------
+<1> Called when the execution is successfully completed.
+<2> Called when the +{api}+ call fails.

docs/java-rest/high-level/security/get-user-privileges.asciidoc

@@ -0,0 +1,46 @@
+--
+:api: get-user-privileges
+:request: GetUserPrivilegesRequest
+:response: GetUserPrivilegesResponse
+--
+
+[id="{upid}-{api}"]
+=== Get User Privileges API
+
+include::../execution-no-req.asciidoc[]
+
+[id="{upid}-{api}-response"]
+==== Get User Privileges Response
+
+The returned +{response}+ contains the following properties
+
+`clusterPrivileges`::
+A `Set` of all _cluster_ privileges that are held by the user.
+This will be the union of all the _cluster_ privileges from the user's roles.
+
+`globalPrivileges`::
+A `Set` of all _global_ privileges that are held by the user.
+This will be the union of all the _global_ privileges from the user's roles.
+Because this a union of multiple roles, it may contain multiple privileges for
+the same `category` and `operation` (which is why is is represented as a `Set`
+rather than a single object).
+
+`indicesPrivileges`::
+A `Set` of all _index_ privileges that are held by the user.
+This will be the union of all the _index_ privileges from the user's roles.
+Because this a union of multiple roles, it may contain multiple privileges for
+the same `index`, and those privileges may have independent field level security
+access grants and/or multiple document level security queries.
+
+`applicationPrivileges`::
+A `Set` of all _application_ privileges that are held by the user.
+This will be the union of all the _application_ privileges from the user's roles.
+
+`runAsPrivilege`::
+A `Set` representation of the _run-as_ privilege that is held by the user.
+This will be the union of the _run-as_ privilege from each of the user's roles.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------

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

@@ -398,6 +398,7 @@ The Java High Level REST Client supports the following Security APIs:
 * <<{upid}-clear-realm-cache>>
 * <<{upid}-authenticate>>
 * <<{upid}-has-privileges>>
+* <<{upid}-get-user-privileges>>
 * <<java-rest-high-security-get-certificates>>
 * <<java-rest-high-security-put-role-mapping>>
 * <<java-rest-high-security-get-role-mappings>>
@@ -422,6 +423,7 @@ include::security/clear-roles-cache.asciidoc[]
 include::security/clear-realm-cache.asciidoc[]
 include::security/authenticate.asciidoc[]
 include::security/has-privileges.asciidoc[]
+include::security/get-user-privileges.asciidoc[]
 include::security/get-certificates.asciidoc[]
 include::security/put-role-mapping.asciidoc[]
 include::security/get-role-mappings.asciidoc[]