HLRC: add support for the clear realm cache API (#35163)

This change adds support for clearing the cache of a realm. The realms
cache may contain a stale set of credentials or incorrect role
assignment, which can be corrected by clearing the cache of the entire
realm or just that of a specific user.

Relates #29827

client/rest-high-level/src/main/java/org/elasticsearch/client/NodesResponse.java

@@ -0,0 +1,60 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch 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.
+ */
+
+package org.elasticsearch.client;
+
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+
+/**
+ * Base class for responses that are node responses. These responses always contain the cluster
+ * name and the {@link NodesResponseHeader}.
+ */
+public abstract class NodesResponse {
+
+    private final NodesResponseHeader header;
+    private final String clusterName;
+
+    protected NodesResponse(NodesResponseHeader header, String clusterName) {
+        this.header = header;
+        this.clusterName = clusterName;
+    }
+
+    /**
+     * Get the cluster name associated with all of the nodes.
+     *
+     * @return Never {@code null}.
+     */
+    public String getClusterName() {
+        return clusterName;
+    }
+
+    /**
+     * Gets information about the number of total, successful and failed nodes the request was run on.
+     * Also includes exceptions if relevant.
+     */
+    public NodesResponseHeader getHeader() {
+        return header;
+    }
+
+    public static <T extends NodesResponse> void declareCommonNodesResponseParsing(ConstructingObjectParser<T, Void> parser) {
+        parser.declareObject(ConstructingObjectParser.constructorArg(), NodesResponseHeader::fromXContent, new ParseField("_nodes"));
+        parser.declareString(ConstructingObjectParser.constructorArg(), new ParseField("cluster_name"));
+    }
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/SecurityClient.java

@@ -23,6 +23,8 @@ import org.elasticsearch.action.ActionListener;
 import org.elasticsearch.client.security.AuthenticateRequest;
 import org.elasticsearch.client.security.AuthenticateResponse;
 import org.elasticsearch.client.security.ChangePasswordRequest;
+import org.elasticsearch.client.security.ClearRealmCacheRequest;
+import org.elasticsearch.client.security.ClearRealmCacheResponse;
 import org.elasticsearch.client.security.ClearRolesCacheRequest;
 import org.elasticsearch.client.security.ClearRolesCacheResponse;
 import org.elasticsearch.client.security.CreateTokenRequest;
@@ -241,13 +243,43 @@ public final class SecurityClient {
     }
 
     /**
-     * Clears the native roles cache for a set of roles.
+     * Clears the cache in one or more realms.
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html">
+     * the docs</a> for more.
+     *
+     * @param request the request with the realm names and usernames to clear the cache for
+     * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @return the response from the clear realm cache call
+     * @throws IOException in case there is a problem sending the request or parsing back the response
+     */
+    public ClearRealmCacheResponse clearRealmCache(ClearRealmCacheRequest request, RequestOptions options) throws IOException {
+        return restHighLevelClient.performRequestAndParseEntity(request, SecurityRequestConverters::clearRealmCache, options,
+            ClearRealmCacheResponse::fromXContent, emptySet());
+    }
+
+    /**
+     * Clears the cache in one or more realms asynchronously.
+     * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-cache.html">
+     * the docs</a> for more.
+     *
+     * @param request  the request with the realm names and usernames to clear the cache for
+     * @param options  the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
+     * @param listener the listener to be notified upon request completion
+     */
+    public void clearRealmCacheAsync(ClearRealmCacheRequest request, RequestOptions options,
+                                     ActionListener<ClearRealmCacheResponse> listener) {
+        restHighLevelClient.performRequestAsyncAndParseEntity(request, SecurityRequestConverters::clearRealmCache, options,
+            ClearRealmCacheResponse::fromXContent, listener, emptySet());
+    }
+
+    /**
+     * Clears the roles cache for a set of roles.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html">
      * the docs</a> for more.
      *
      * @param request the request with the roles for which the cache should be cleared.
      * @param options the request options (e.g. headers), use {@link RequestOptions#DEFAULT} if nothing needs to be customized
-     * @return the response from the enable user call
+     * @return the response from the clear roles cache call
      * @throws IOException in case there is a problem sending the request or parsing back the response
      */
     public ClearRolesCacheResponse clearRolesCache(ClearRolesCacheRequest request, RequestOptions options) throws IOException {
@@ -256,7 +288,7 @@ public final class SecurityClient {
     }
 
     /**
-     * Clears the native roles cache for a set of roles asynchronously.
+     * Clears the roles cache for a set of roles asynchronously.
      * See <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/security-api-clear-role-cache.html">
      * the docs</a> for more.
      *

client/rest-high-level/src/main/java/org/elasticsearch/client/SecurityRequestConverters.java

@@ -23,6 +23,7 @@ import org.apache.http.client.methods.HttpGet;
 import org.apache.http.client.methods.HttpDelete;
 import org.apache.http.client.methods.HttpPost;
 import org.apache.http.client.methods.HttpPut;
+import org.elasticsearch.client.security.ClearRealmCacheRequest;
 import org.elasticsearch.client.security.ClearRolesCacheRequest;
 import org.elasticsearch.client.security.CreateTokenRequest;
 import org.elasticsearch.client.security.DeleteRoleMappingRequest;
@@ -112,6 +113,23 @@ final class SecurityRequestConverters {
         return request;
     }
 
+    static Request clearRealmCache(ClearRealmCacheRequest clearRealmCacheRequest) {
+        RequestConverters.EndpointBuilder builder = new RequestConverters.EndpointBuilder()
+            .addPathPartAsIs("_xpack/security/realm");
+        if (clearRealmCacheRequest.getRealms().isEmpty() == false) {
+            builder.addCommaSeparatedPathParts(clearRealmCacheRequest.getRealms().toArray(Strings.EMPTY_ARRAY));
+        } else {
+            builder.addPathPart("_all");
+        }
+        final String endpoint = builder.addPathPartAsIs("_clear_cache").build();
+        Request request = new Request(HttpPost.METHOD_NAME, endpoint);
+        if (clearRealmCacheRequest.getUsernames().isEmpty() == false) {
+            RequestConverters.Params params = new RequestConverters.Params(request);
+            params.putParam("usernames", Strings.collectionToCommaDelimitedString(clearRealmCacheRequest.getUsernames()));
+        }
+        return request;
+    }
+
     static Request clearRolesCache(ClearRolesCacheRequest disableCacheRequest) {
         String endpoint = new RequestConverters.EndpointBuilder()
             .addPathPartAsIs("_xpack/security/role")

client/rest-high-level/src/main/java/org/elasticsearch/client/security/ClearRealmCacheRequest.java

@@ -0,0 +1,56 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch 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.
+ */
+
+package org.elasticsearch.client.security;
+
+import org.elasticsearch.client.Validatable;
+
+import java.util.Collections;
+import java.util.List;
+import java.util.Objects;
+
+/**
+ * Request for clearing the cache of one or more realms
+ */
+public final class ClearRealmCacheRequest implements Validatable {
+
+    private final List<String> realms;
+    private final List<String> usernames;
+
+    /**
+     * Create a new request to clear cache of realms
+     * @param realms the realms to clear the cache of. Must not be {@code null}. An empty list
+     *               indicates that all realms should have their caches cleared.
+     * @param usernames the usernames to clear the cache of. Must not be {@code null}. An empty
+     *                  list indicates that every user in the listed realms should have their cache
+     *                  cleared.
+     */
+    public ClearRealmCacheRequest(List<String> realms, List<String> usernames) {
+        this.realms = Collections.unmodifiableList(Objects.requireNonNull(realms, "the realms list must not be null"));
+        this.usernames = Collections.unmodifiableList(Objects.requireNonNull(usernames, "usernames list must no be null"));
+    }
+
+    public List<String> getRealms() {
+        return realms;
+    }
+
+    public List<String> getUsernames() {
+        return usernames;
+    }
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/security/ClearRealmCacheResponse.java

@@ -0,0 +1,51 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch 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.
+ */
+
+package org.elasticsearch.client.security;
+
+import org.elasticsearch.client.NodesResponseHeader;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+import org.elasticsearch.common.xcontent.XContentParser;
+
+import java.io.IOException;
+import java.util.List;
+
+/**
+ * Response for a clear realm cache request. The response includes a header that contains the
+ * number of successful and failed nodes.
+ */
+public final class ClearRealmCacheResponse extends SecurityNodesResponse {
+
+    @SuppressWarnings("unchecked")
+    public static final ConstructingObjectParser<ClearRealmCacheResponse, Void> PARSER =
+        new ConstructingObjectParser<>("clear_realm_cache_response_parser",
+            args -> new ClearRealmCacheResponse((List<Node>) args[0], (NodesResponseHeader) args[1], (String) args[2]));
+
+    static {
+        SecurityNodesResponse.declareCommonNodesResponseParsing(PARSER);
+    }
+
+    public ClearRealmCacheResponse(List<Node> nodes, NodesResponseHeader header, String clusterName) {
+        super(nodes, header, clusterName);
+    }
+
+    public static ClearRealmCacheResponse fromXContent(XContentParser parser) throws IOException {
+        return PARSER.parse(parser, null);
+    }
+}

client/rest-high-level/src/main/java/org/elasticsearch/client/security/ClearRolesCacheResponse.java

@@ -20,18 +20,16 @@
 package org.elasticsearch.client.security;
 
 import org.elasticsearch.client.NodesResponseHeader;
-import org.elasticsearch.common.ParseField;
 import org.elasticsearch.common.xcontent.ConstructingObjectParser;
 import org.elasticsearch.common.xcontent.XContentParser;
 
 import java.io.IOException;
 import java.util.List;
-import java.util.Objects;
 
 /**
- * The response object that will be returned when clearing the cache of native roles
+ * The response object that will be returned when clearing the roles cache
  */
-public final class ClearRolesCacheResponse {
+public final class ClearRolesCacheResponse extends SecurityNodesResponse {
 
     @SuppressWarnings("unchecked")
     private static final ConstructingObjectParser<ClearRolesCacheResponse, Void> PARSER =
@@ -39,68 +37,11 @@ public final class ClearRolesCacheResponse {
             args -> new ClearRolesCacheResponse((List<Node>)args[0], (NodesResponseHeader) args[1], (String) args[2]));
 
     static {
-        PARSER.declareNamedObjects(ConstructingObjectParser.constructorArg(), (p, c, n) -> Node.PARSER.apply(p, n),
-            new ParseField("nodes"));
-        PARSER.declareObject(ConstructingObjectParser.constructorArg(), NodesResponseHeader::fromXContent, new ParseField("_nodes"));
-        PARSER.declareString(ConstructingObjectParser.constructorArg(), new ParseField("cluster_name"));
+        SecurityNodesResponse.declareCommonNodesResponseParsing(PARSER);
     }
 
-    private final List<Node> nodes;
-    private final NodesResponseHeader header;
-    private final String clusterName;
-
     public ClearRolesCacheResponse(List<Node> nodes, NodesResponseHeader header, String clusterName) {
-        this.nodes = nodes;
-        this.header = header;
-        this.clusterName = Objects.requireNonNull(clusterName, "cluster name must be provided");
-    }
-
-    /** returns a list of nodes in which the cache was cleared */
-    public List<Node> getNodes() {
-        return nodes;
-    }
-
-    /**
-     * Get the cluster name associated with all of the nodes.
-     *
-     * @return Never {@code null}.
-     */
-    public String getClusterName() {
-        return clusterName;
-    }
-
-    /**
-     * Gets information about the number of total, successful and failed nodes the request was run on.
-     * Also includes exceptions if relevant.
-     */
-    public NodesResponseHeader getHeader() {
-        return header;
-    }
-
-    public static class Node {
-
-        private static final ConstructingObjectParser<Node, String> PARSER =
-            new ConstructingObjectParser<>("clear_roles_cache_response_node", false, (args, id) -> new Node(id, (String) args[0]));
-
-        static {
-            PARSER.declareString(ConstructingObjectParser.constructorArg(), new ParseField("name"));
-        }
-
-        private final String id;
-        private final String name;
-
-        public Node(String id, String name) {
-            this.id = id;
-            this.name = name;
-        }
-
-        public String getId() {
-            return id;
-        }
-
-        public String getName() {
-            return name;
-        }
+        super(nodes, header, clusterName);
     }
 
     public static ClearRolesCacheResponse fromXContent(XContentParser parser) throws IOException {

client/rest-high-level/src/main/java/org/elasticsearch/client/security/SecurityNodesResponse.java

@@ -0,0 +1,79 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch 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.
+ */
+
+package org.elasticsearch.client.security;
+
+import org.elasticsearch.client.NodesResponse;
+import org.elasticsearch.client.NodesResponseHeader;
+import org.elasticsearch.common.ParseField;
+import org.elasticsearch.common.xcontent.ConstructingObjectParser;
+
+import java.util.List;
+
+/**
+ * Base class for security responses that are node responses. Security uses a common pattern in the
+ * response so this class is present to avoid duplication.
+ */
+public abstract class SecurityNodesResponse extends NodesResponse {
+
+    private final List<Node> nodes;
+
+    SecurityNodesResponse(List<Node> nodes, NodesResponseHeader header, String clusterName) {
+        super(header, clusterName);
+        this.nodes = nodes;
+    }
+
+    /** returns a list of nodes in which the cache was cleared */
+    public List<Node> getNodes() {
+        return nodes;
+    }
+
+    public static class Node {
+
+        private static final ConstructingObjectParser<ClearRolesCacheResponse.Node, String> PARSER =
+            new ConstructingObjectParser<>("clear_roles_cache_response_node", false,
+                (args, id) -> new ClearRolesCacheResponse.Node(id, (String) args[0]));
+
+        static {
+            PARSER.declareString(ConstructingObjectParser.constructorArg(), new ParseField("name"));
+        }
+
+        private final String id;
+        private final String name;
+
+        public Node(String id, String name) {
+            this.id = id;
+            this.name = name;
+        }
+
+        public String getId() {
+            return id;
+        }
+
+        public String getName() {
+            return name;
+        }
+    }
+
+    public static <T extends NodesResponse> void declareCommonNodesResponseParsing(ConstructingObjectParser<T, Void> parser) {
+        parser.declareNamedObjects(ConstructingObjectParser.constructorArg(), (p, c, n) -> Node.PARSER.apply(p, n),
+            new ParseField("nodes"));
+        NodesResponse.declareCommonNodesResponseParsing(parser);
+    }
+}

client/rest-high-level/src/test/java/org/elasticsearch/client/documentation/SecurityDocumentationIT.java

@@ -31,6 +31,8 @@ import org.elasticsearch.client.RequestOptions;
 import org.elasticsearch.client.RestHighLevelClient;
 import org.elasticsearch.client.security.AuthenticateResponse;
 import org.elasticsearch.client.security.ChangePasswordRequest;
+import org.elasticsearch.client.security.ClearRealmCacheRequest;
+import org.elasticsearch.client.security.ClearRealmCacheResponse;
 import org.elasticsearch.client.security.ClearRolesCacheRequest;
 import org.elasticsearch.client.security.ClearRolesCacheResponse;
 import org.elasticsearch.client.security.CreateTokenRequest;
@@ -397,7 +399,7 @@ public class SecurityDocumentationIT extends ESRestHighLevelClientTestCase {
             //end::authenticate-response
 
             assertThat(user.username(), is("test_user"));
-            assertThat(user.roles(), contains(new String[] {"superuser"}));
+            assertThat(user.roles(), contains(new String[]{"superuser"}));
             assertThat(user.fullName(), nullValue());
             assertThat(user.email(), nullValue());
             assertThat(user.metadata().isEmpty(), is(true));
@@ -422,6 +424,7 @@ public class SecurityDocumentationIT extends ESRestHighLevelClientTestCase {
             // Replace the empty listener by a blocking listener in test
             final CountDownLatch latch = new CountDownLatch(1);
             listener = new LatchedActionListener<>(listener, latch);
+
             // tag::authenticate-execute-async
             client.security().authenticateAsync(RequestOptions.DEFAULT, listener); // <1>
             // end::authenticate-execute-async
@@ -430,6 +433,51 @@ public class SecurityDocumentationIT extends ESRestHighLevelClientTestCase {
         }
     }
 
+    public void testClearRealmCache() throws Exception {
+        RestHighLevelClient client = highLevelClient();
+        {
+            //tag::clear-realm-cache-request
+            ClearRealmCacheRequest request = new ClearRealmCacheRequest(Collections.emptyList(), Collections.emptyList());
+            //end::clear-realm-cache-request
+            //tag::clear-realm-cache-execute
+            ClearRealmCacheResponse response = client.security().clearRealmCache(request, RequestOptions.DEFAULT);
+            //end::clear-realm-cache-execute
+
+            assertNotNull(response);
+            assertThat(response.getNodes(), not(empty()));
+
+            //tag::clear-realm-cache-response
+            List<ClearRealmCacheResponse.Node> nodes = response.getNodes(); // <1>
+            //end::clear-realm-cache-response
+        }
+        {
+            //tag::clear-realm-cache-execute-listener
+            ClearRealmCacheRequest request = new ClearRealmCacheRequest(Collections.emptyList(), Collections.emptyList());
+            ActionListener<ClearRealmCacheResponse> listener = new ActionListener<ClearRealmCacheResponse>() {
+                @Override
+                public void onResponse(ClearRealmCacheResponse clearRealmCacheResponse) {
+                    // <1>
+                }
+
+                @Override
+                public void onFailure(Exception e) {
+                    // <2>
+                }
+            };
+            //end::clear-realm-cache-execute-listener
+
+            // Replace the empty listener by a blocking listener in test
+            final CountDownLatch latch = new CountDownLatch(1);
+            listener = new LatchedActionListener<>(listener, latch);
+
+            // tag::clear-realm-cache-execute-async
+            client.security().clearRealmCacheAsync(request, RequestOptions.DEFAULT, listener); // <1>
+            // end::clear-realm-cache-execute-async
+
+            assertTrue(latch.await(30L, TimeUnit.SECONDS));
+        }
+    }
+
     public void testClearRolesCache() throws Exception {
         RestHighLevelClient client = highLevelClient();
         {

client/rest-high-level/src/test/java/org/elasticsearch/client/security/ClearRealmCacheResponseTests.java

@@ -0,0 +1,75 @@
+/*
+ * Licensed to Elasticsearch under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch 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.
+ */
+
+package org.elasticsearch.client.security;
+
+import org.elasticsearch.ElasticsearchException;
+import org.elasticsearch.common.Strings;
+import org.elasticsearch.common.xcontent.DeprecationHandler;
+import org.elasticsearch.common.xcontent.NamedXContentRegistry;
+import org.elasticsearch.common.xcontent.XContentParser;
+import org.elasticsearch.common.xcontent.json.JsonXContent;
+import org.elasticsearch.test.ESTestCase;
+
+import java.io.IOException;
+
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.empty;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.hasSize;
+
+public class ClearRealmCacheResponseTests extends ESTestCase {
+
+    public void testParseFromXContent() throws IOException {
+        final ElasticsearchException exception = new ElasticsearchException("test");
+        final String nodesHeader = "\"_nodes\": { \"total\": 2, \"successful\": 1, \"failed\": 1, \"failures\": [ "
+            + Strings.toString(exception) + "] },";
+        final String clusterName = "\"cluster_name\": \"cn\",";
+        try (XContentParser parser = JsonXContent.jsonXContent.createParser(NamedXContentRegistry.EMPTY,
+            DeprecationHandler.THROW_UNSUPPORTED_OPERATION, "{" + nodesHeader + clusterName +  "\"nodes\" : {} }")) {
+
+            ClearRealmCacheResponse response = ClearRealmCacheResponse.fromXContent(parser);
+            assertNotNull(response);
+            assertThat(response.getNodes(), empty());
+            assertThat(response.getClusterName(), equalTo("cn"));
+            assertThat(response.getHeader().getSuccessful(), equalTo(1));
+            assertThat(response.getHeader().getFailed(), equalTo(1));
+            assertThat(response.getHeader().getTotal(), equalTo(2));
+            assertThat(response.getHeader().getFailures(), hasSize(1));
+            assertThat(response.getHeader().getFailures().get(0).getMessage(), containsString("reason=test"));
+        }
+
+        try (XContentParser parser = JsonXContent.jsonXContent.createParser(NamedXContentRegistry.EMPTY,
+            DeprecationHandler.THROW_UNSUPPORTED_OPERATION,
+            "{" + nodesHeader + clusterName + "\"nodes\" : { " +
+                "\"id1\": { \"name\": \"a\"}, " +
+                "\"id2\": { \"name\": \"b\"}" +
+                "}}")) {
+
+            ClearRealmCacheResponse response = ClearRealmCacheResponse.fromXContent(parser);
+            assertNotNull(response);
+            assertThat(response.getNodes(), hasSize(2));
+            assertThat(response.getNodes().get(0).getId(), equalTo("id1"));
+            assertThat(response.getNodes().get(0).getName(), equalTo("a"));
+            assertThat(response.getNodes().get(1).getId(), equalTo("id2"));
+            assertThat(response.getNodes().get(1).getName(), equalTo("b"));
+        }
+    }
+
+}

docs/java-rest/high-level/security/clear-realm-cache.asciidoc

@@ -0,0 +1,33 @@
+
+--
+:api: clear-realm-cache
+:request: ClearRealmCacheRequest
+:response: ClearRealmCacheResponse
+--
+
+[id="{upid}-{api}"]
+=== Clear Realm Cache API
+
+[id="{upid}-{api}-request"]
+==== Clear Realm Cache Request
+
+A +{request}+ supports defining the name of realms and usernames that the cache should be cleared
+for.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-request]
+--------------------------------------------------
+
+include::../execution.asciidoc[]
+
+[id="{upid}-{api}-response"]
+==== Clear Roles Cache Response
+
+The returned +{response}+ allows to retrieve information about where the cache was cleared.
+
+["source","java",subs="attributes,callouts,macros"]
+--------------------------------------------------
+include-tagged::{doc-tests-file}[{api}-response]
+--------------------------------------------------
+<1> the list of nodes that the cache was cleared on

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

@@ -331,6 +331,7 @@ The Java High Level REST Client supports the following Security APIs:
 * <<java-rest-high-security-change-password>>
 * <<java-rest-high-security-delete-role>>
 * <<{upid}-clear-roles-cache>>
+* <<{upid}-clear-realm-cache>>
 * <<{upid}-authenticate>>
 * <<java-rest-high-security-get-certificates>>
 * <<java-rest-high-security-put-role-mapping>>
@@ -345,6 +346,7 @@ include::security/disable-user.asciidoc[]
 include::security/change-password.asciidoc[]
 include::security/delete-role.asciidoc[]
 include::security/clear-roles-cache.asciidoc[]
+include::security/clear-realm-cache.asciidoc[]
 include::security/authenticate.asciidoc[]
 include::security/get-certificates.asciidoc[]
 include::security/put-role-mapping.asciidoc[]