KEYCLOAK-9865 Update documentation in testsuite

testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/updaters/ClientAttributeUpdater.java

@@ -15,13 +15,20 @@ import static org.hamcrest.Matchers.hasSize;
 import static org.junit.Assert.assertThat;
 
 /**
- *
+ * Updater for client attributes. See {@link ServerResourceUpdater} for further details.
  * @author hmlnarik
  */
 public class ClientAttributeUpdater extends ServerResourceUpdater<ClientAttributeUpdater, ClientResource, ClientRepresentation> {
 
     private final RealmResource realmResource;
 
+    /**
+     * Creates a {@ClientAttributeUpdater} for the given client. The client must exist.
+     * @param adminClient
+     * @param realm
+     * @param clientId
+     * @return
+     */
     public static ClientAttributeUpdater forClient(Keycloak adminClient, String realm, String clientId) {
         RealmResource realmRes = adminClient.realm(realm);
         ClientsResource clients = realmRes.clients();

testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/updaters/RealmAttributeUpdater.java

@@ -6,7 +6,7 @@ import java.util.HashMap;
 import java.util.List;
 
 /**
- *
+ * Updater for realm attributes. See {@link ServerResourceUpdater} for further details.
  * @author hmlnarik
  */
 public class RealmAttributeUpdater extends ServerResourceUpdater<ServerResourceUpdater, RealmResource, RealmRepresentation> {

testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/updaters/RoleScopeUpdater.java

@@ -23,7 +23,7 @@ import java.util.Set;
 import java.util.stream.Collectors;
 
 /**
- *
+ * Updater for role scope attributes. See {@link ServerResourceUpdater} for further details.
  * @author hmlnarik
  */
 public class RoleScopeUpdater extends ServerResourceUpdater<RoleScopeUpdater, RoleScopeResource, List<RoleRepresentation>> {

testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/updaters/ServerResourceUpdater.java

@@ -28,7 +28,30 @@ import java.util.function.Supplier;
 import java.util.stream.Collectors;
 
 /**
+ * Class for updating a server resource. This class supports reverting changes via try-with-resources block.
  *
+ * It works as follows:
+ * <ol>
+ *   <li>In the constructor, current representation of the resource is obtained and stored internally into two object:
+ *       one that is used to capture modifications local, and another one which is immutable and used for restoration at the end</li>
+ *   <li>The first object can be modified locally via instance methods.</li>
+ *   <li>Once modifications are finalized, {@link #update()} method updates the object on the server.
+ *       Note that this method can be called more than once inside the {@code try} block.</li>
+ *   <li>After finishing the try-with-resources block, the changes are reverted back by updating the resource on the server
+ *       to the state in the first step</li>
+ * </ol>
+ *
+ * It is generally used according to the following pattern:
+ * <pre>
+ * try (ServerResourceUpdater sru = new ServerResourceUpdater().setProperty(x).update()) {
+ *     // ... do the job
+ *     // Potentially use sru to modify the object again and run sru.update()
+ * }
+ * </pre>
+ *
+ * @param <T> Type of the subclass (to support Builder pattern)
+ * @param <Rep> Object representation type
+ * @param <Res> Server resource
  * @author hmlnarik
  */
 public abstract class ServerResourceUpdater<T extends ServerResourceUpdater, Res, Rep> implements Closeable {
@@ -48,10 +71,18 @@ public abstract class ServerResourceUpdater<T extends ServerResourceUpdater, Res
         this.rep = representationGenerator.get();
     }
 
+    /**
+     * Returns server resource accessing the object.
+     * @return
+     */
     public Res getResource() {
         return resource;
     }
 
+    /**
+     * Updates the object on the server according to the current internal representation.
+     * @return
+     */
     public T update() {
         performUpdate(origRep, rep);
         this.updated = true;
@@ -62,11 +93,20 @@ public abstract class ServerResourceUpdater<T extends ServerResourceUpdater, Res
         updater.accept(to);
     }
 
+    /**
+     * Updates the internal representation by a custom function.
+     * @param representationUpdater
+     * @return
+     */
     public T updateWith(Consumer<Rep> representationUpdater) {
         representationUpdater.accept(this.rep);
         return (T) this;
     }
 
+    /**
+     * Reverts the object state on the server to the state that was there upon creation of this updater.
+     * @throws IOException
+     */
     @Override
     public void close() throws IOException {
         if (this.updated) {

testsuite/integration-arquillian/tests/base/src/main/java/org/keycloak/testsuite/updaters/UserAttributeUpdater.java

@@ -1,12 +1,9 @@
 package org.keycloak.testsuite.updaters;
 
 import org.keycloak.admin.client.Keycloak;
-import org.keycloak.admin.client.resource.ClientResource;
-import org.keycloak.admin.client.resource.ClientsResource;
 import org.keycloak.admin.client.resource.UserResource;
 import org.keycloak.admin.client.resource.UsersResource;
 import org.keycloak.models.UserModel;
-import org.keycloak.representations.idm.ClientRepresentation;
 import org.keycloak.representations.idm.UserRepresentation;
 import java.util.Arrays;
 import java.util.HashMap;
@@ -16,11 +13,18 @@ import static org.hamcrest.Matchers.hasSize;
 import static org.junit.Assert.assertThat;
 
 /**
- *
+ * Updater for user attributes. See {@link ServerResourceUpdater} for further details.
  * @author hmlnarik
  */
 public class UserAttributeUpdater extends ServerResourceUpdater<UserAttributeUpdater, UserResource, UserRepresentation> {
 
+    /**
+     * Creates a {@UserAttributeUpdater} for the given user. The user must exist.
+     * @param adminClient
+     * @param realm
+     * @param clientId
+     * @return
+     */
     public static UserAttributeUpdater forUserByUsername(Keycloak adminClient, String realm, String userName) {
         UsersResource users = adminClient.realm(realm).users();
         List<UserRepresentation> foundUsers = users.search(userName);