Add TS3Api#banClients to ban multiple clients at once

rogermb · rogermb · commit 35e1da6826ff · 2021-05-17T20:59:49.000+02:00
diff --git a/src/main/java/com/github/theholywaffle/teamspeak3/TS3Api.java b/src/main/java/com/github/theholywaffle/teamspeak3/TS3Api.java
@@ -36,6 +36,7 @@
 
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.util.Collection;
 import java.util.List;
 import java.util.Map;
 import java.util.regex.Pattern;
@@ -499,13 +500,12 @@ public void addTS3Listeners(TS3Listener... listeners) {
 	/**
 	 * Bans a client with a given client ID for a given time.
 	 * <p>
-	 * Please note that this will create 2 or 3 separate ban rules,
+	 * Please note that this will create up to three separate ban rules,
 	 * one for the targeted client's IP address, one for their unique identifier,
-	 * and potentially one more for their "myTeamSpeak" ID.
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
-	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
-	 * and the returned array will only have 1 entry.
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
 	 * </p>
 	 *
 	 * @param clientId
@@ -528,12 +528,12 @@ public int[] banClient(int clientId, long timeInSeconds) {
 	/**
 	 * Bans a client with a given client ID for a given time for the specified reason.
 	 * <p>
-	 * Please note that this will create two separate ban rules,
-	 * one for the targeted client's IP address and their unique identifier.
+	 * Please note that this will create up to three separate ban rules,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
-	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
-	 * and the returned array will only have 1 entry.
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
 	 * </p>
 	 *
 	 * @param clientId
@@ -543,7 +543,7 @@ public int[] banClient(int clientId, long timeInSeconds) {
 	 * @param reason
 	 * 		the reason for the ban, can be null
 	 *
-	 * @return an array containing the IDs of the first and the second ban entry
+	 * @return an array containing the IDs of the created ban entries
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
@@ -558,20 +558,20 @@ public int[] banClient(int clientId, long timeInSeconds, String reason) {
 	/**
 	 * Bans a client with a given client ID permanently for the specified reason.
 	 * <p>
-	 * Please note that this will create two separate ban rules,
-	 * one for the targeted client's IP address and their unique identifier.
+	 * Please note that this will create up to three separate ban rules,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
-	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
-	 * and the returned array will only have 1 entry.
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
 	 * </p>
 	 *
 	 * @param clientId
 	 * 		the ID of the client
 	 * @param reason
 	 * 		the reason for the ban, can be null
 	 *
-	 * @return an array containing the IDs of the first and the second ban entry
+	 * @return an array containing the IDs of the created ban entries
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
@@ -583,6 +583,41 @@ public int[] banClient(int clientId, String reason) {
 		return asyncApi.banClient(clientId, reason).getUninterruptibly();
 	}
 
+	/**
+	 * Bans multiple clients by their client ID for a given time for the specified reason.
+	 * <p>
+	 * Please note that this will create up to three separate ban rules for each client,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
+	 * </p><p>
+	 * <i>Exception:</i> If the banned client connects via a loopback address
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
+	 * </p><p>
+	 * <i>Exception:</i> If two or more clients are connecting from the
+	 * same IP address, only one IP ban entry for that IP will be created.
+	 * </p>
+	 *
+	 * @param clientIds
+	 * 		the IDs of the clients to be banned
+	 * @param timeInSeconds
+	 * 		the duration of the ban in seconds. 0 equals a permanent ban
+	 * @param reason
+	 * 		the reason for the ban, can be null
+	 * @param continueOnError
+	 * 		if true, continue to the next client if banning one client fails, else do not create any bans on error
+	 *
+	 * @return an array containing the IDs of the created ban entries
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see Client#getId()
+	 * @see #addBan(String, String, String, long, String)
+	 */
+	public int[] banClients(Collection<Integer> clientIds, long timeInSeconds, String reason, boolean continueOnError) {
+		return asyncApi.banClients(clientIds, timeInSeconds, reason, continueOnError).getUninterruptibly();
+	}
+
 	/**
 	 * Sends a text message to all clients on all virtual servers.
 	 * These messages will appear to clients in the tab for server messages.
diff --git a/src/main/java/com/github/theholywaffle/teamspeak3/TS3ApiAsync.java b/src/main/java/com/github/theholywaffle/teamspeak3/TS3ApiAsync.java
@@ -548,13 +548,12 @@ public void addTS3Listeners(TS3Listener... listeners) {
 	/**
 	 * Bans a client with a given client ID for a given time.
 	 * <p>
-	 * Please note that this will create 2 or 3 separate ban rules,
+	 * Please note that this will create up to three separate ban rules,
 	 * one for the targeted client's IP address, one for their unique identifier,
-	 * and potentially one more for their "myTeamSpeak" ID.
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
-	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
-	 * and the returned array will only have 1 entry.
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
 	 * </p>
 	 *
 	 * @param clientId
@@ -577,12 +576,12 @@ public CommandFuture<int[]> banClient(int clientId, long timeInSeconds) {
 	/**
 	 * Bans a client with a given client ID for a given time for the specified reason.
 	 * <p>
-	 * Please note that this will create two separate ban rules,
-	 * one for the targeted client's IP address and their unique identifier.
+	 * Please note that this will create up to three separate ban rules,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
-	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
-	 * and the returned array will only have 1 entry.
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
 	 * </p>
 	 *
 	 * @param clientId
@@ -592,7 +591,7 @@ public CommandFuture<int[]> banClient(int clientId, long timeInSeconds) {
 	 * @param reason
 	 * 		the reason for the ban, can be null
 	 *
-	 * @return an array containing the IDs of the first and the second ban entry
+	 * @return an array containing the IDs of the created ban entries
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
@@ -601,27 +600,27 @@ public CommandFuture<int[]> banClient(int clientId, long timeInSeconds) {
 	 * @see #addBan(String, String, String, long, String)
 	 */
 	public CommandFuture<int[]> banClient(int clientId, long timeInSeconds, String reason) {
-		Command cmd = BanCommands.banClient(clientId, timeInSeconds, reason);
+		Command cmd = BanCommands.banClient(Collections.singletonList(clientId), timeInSeconds, reason, false);
 		return executeAndReturnIntArray(cmd, "banid");
 	}
 
 	/**
 	 * Bans a client with a given client ID permanently for the specified reason.
 	 * <p>
-	 * Please note that this will create two separate ban rules,
-	 * one for the targeted client's IP address and their unique identifier.
+	 * Please note that this will create up to three separate ban rules,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
 	 * </p><p>
 	 * <i>Exception:</i> If the banned client connects via a loopback address
-	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created
-	 * and the returned array will only have 1 entry.
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
 	 * </p>
 	 *
 	 * @param clientId
 	 * 		the ID of the client
 	 * @param reason
 	 * 		the reason for the ban, can be null
 	 *
-	 * @return an array containing the IDs of the first and the second ban entry
+	 * @return an array containing the IDs of the created ban entries
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails
@@ -633,6 +632,42 @@ public CommandFuture<int[]> banClient(int clientId, String reason) {
 		return banClient(clientId, 0, reason);
 	}
 
+	/**
+	 * Bans multiple clients by their client ID for a given time for the specified reason.
+	 * <p>
+	 * Please note that this will create up to three separate ban rules for each client,
+	 * one for the targeted client's IP address, one for their unique identifier,
+	 * and potentially one more entry for their "myTeamSpeak" ID, if available.
+	 * </p><p>
+	 * <i>Exception:</i> If the banned client connects via a loopback address
+	 * (i.e. {@code 127.0.0.1} or {@code localhost}), no IP ban is created.
+	 * </p><p>
+	 * <i>Exception:</i> If two or more clients are connecting from the
+	 * same IP address, only one IP ban entry for that IP will be created.
+	 * </p>
+	 *
+	 * @param clientIds
+	 * 		the IDs of the clients to be banned
+	 * @param timeInSeconds
+	 * 		the duration of the ban in seconds. 0 equals a permanent ban
+	 * @param reason
+	 * 		the reason for the ban, can be null
+	 * @param continueOnError
+	 * 		if true, continue to the next client if banning one client fails, else do not create any bans on error
+	 *
+	 * @return an array containing the IDs of the created ban entries
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see Client#getId()
+	 * @see #addBan(String, String, String, long, String)
+	 */
+	public CommandFuture<int[]> banClients(Collection<Integer> clientIds, long timeInSeconds, String reason, boolean continueOnError) {
+		Command cmd = BanCommands.banClient(clientIds, timeInSeconds, reason, continueOnError);
+		return executeAndReturnIntArray(cmd, "banid");
+	}
+
 	/**
 	 * Sends a text message to all clients on all virtual servers.
 	 * These messages will appear to clients in the tab for server messages.
diff --git a/src/main/java/com/github/theholywaffle/teamspeak3/commands/BanCommands.java b/src/main/java/com/github/theholywaffle/teamspeak3/commands/BanCommands.java
@@ -26,7 +26,11 @@
  * #L%
  */
 
+import com.github.theholywaffle.teamspeak3.commands.parameter.ArrayParameter;
 import com.github.theholywaffle.teamspeak3.commands.parameter.KeyValueParam;
+import com.github.theholywaffle.teamspeak3.commands.parameter.OptionParam;
+
+import java.util.Collection;
 
 public final class BanCommands {
 
@@ -49,11 +53,19 @@ public static Command banAdd(String ip, String name, String uid, String myTSId,
 		return builder.build();
 	}
 
-	public static Command banClient(int clientId, long timeInSeconds, String reason) {
-		CommandBuilder builder = new CommandBuilder("banclient", 3);
-		builder.add(new KeyValueParam("clid", clientId));
+	public static Command banClient(Collection<Integer> clientIds, long timeInSeconds,
+	                                String reason, boolean continueOnError) {
+		CommandBuilder builder = new CommandBuilder("banclient", 4);
 		builder.addIf(timeInSeconds > 0, new KeyValueParam("time", timeInSeconds));
 		builder.addIf(reason != null, new KeyValueParam("banreason", reason));
+		builder.addIf(continueOnError, new OptionParam("continueonerror"));
+
+		ArrayParameter clients = new ArrayParameter(clientIds.size());
+		for (int clientId : clientIds) {
+			clients.add(new KeyValueParam("clid", clientId));
+		}
+		builder.add(clients);
+
 		return builder.build();
 	}
 
