Add selectVirtualServer overloads that also set the query's nickname

... which is a new feature added in TS3 server v3.4.0

Author: rogermb

src/main/java/com/github/theholywaffle/teamspeak3/TS3Api.java

@@ -3699,13 +3699,38 @@ public List<CustomPropertyAssignment> searchCustomClientProperty(String key, Str
 	 * 		if the execution of a command fails
 	 * @querycommands 1
 	 * @see VirtualServer#getId()
+	 * @see #selectVirtualServerById(int, String)
 	 * @see #selectVirtualServerByPort(int)
 	 * @see #selectVirtualServer(VirtualServer)
 	 */
 	public void selectVirtualServerById(int id) {
 		asyncApi.selectVirtualServerById(id).getUninterruptibly();
 	}
 
+	/**
+	 * Moves the server query into the virtual server with the specified ID
+	 * and sets the server query's nickname.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
+	 *
+	 * @param id
+	 * 		the ID of the virtual server
+	 * @param nickname
+	 * 		the nickname, or {@code null} if the nickname should not be set
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see VirtualServer#getId()
+	 * @see #selectVirtualServerById(int)
+	 * @see #selectVirtualServerByPort(int, String)
+	 * @see #selectVirtualServer(VirtualServer, String)
+	 */
+	public void selectVirtualServerById(int id, String nickname) {
+		asyncApi.selectVirtualServerById(id, nickname).getUninterruptibly();
+	}
+
 	/**
 	 * Moves the server query into the virtual server with the specified voice port.
 	 *
@@ -3717,12 +3742,37 @@ public void selectVirtualServerById(int id) {
 	 * @querycommands 1
 	 * @see VirtualServer#getPort()
 	 * @see #selectVirtualServerById(int)
+	 * @see #selectVirtualServerByPort(int, String)
 	 * @see #selectVirtualServer(VirtualServer)
 	 */
 	public void selectVirtualServerByPort(int port) {
 		asyncApi.selectVirtualServerByPort(port).getUninterruptibly();
 	}
 
+	/**
+	 * Moves the server query into the virtual server with the specified voice port
+	 * and sets the server query's nickname.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
+	 *
+	 * @param port
+	 * 		the voice port of the virtual server
+	 * @param nickname
+	 * 		the nickname, or {@code null} if the nickname should not be set
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see VirtualServer#getPort()
+	 * @see #selectVirtualServerById(int, String)
+	 * @see #selectVirtualServerByPort(int)
+	 * @see #selectVirtualServer(VirtualServer, String)
+	 */
+	public void selectVirtualServerByPort(int port, String nickname) {
+		asyncApi.selectVirtualServerByPort(port, nickname).getUninterruptibly();
+	}
+
 	/**
 	 * Moves the server query into the specified virtual server.
 	 *
@@ -3734,11 +3784,35 @@ public void selectVirtualServerByPort(int port) {
 	 * @querycommands 1
 	 * @see #selectVirtualServerById(int)
 	 * @see #selectVirtualServerByPort(int)
+	 * @see #selectVirtualServer(VirtualServer, String)
 	 */
 	public void selectVirtualServer(VirtualServer server) {
 		asyncApi.selectVirtualServer(server).getUninterruptibly();
 	}
 
+	/**
+	 * Moves the server query into the specified virtual server
+	 * and sets the server query's nickname.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
+	 *
+	 * @param server
+	 * 		the virtual server to move into
+	 * @param nickname
+	 * 		the nickname, or {@code null} if the nickname should not be set
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #selectVirtualServerById(int, String)
+	 * @see #selectVirtualServerByPort(int, String)
+	 * @see #selectVirtualServer(VirtualServer)
+	 */
+	public void selectVirtualServer(VirtualServer server, String nickname) {
+		asyncApi.selectVirtualServer(server, nickname).getUninterruptibly();
+	}
+
 	/**
 	 * Sends an offline message to the client with the given unique identifier.
 	 * <p>
@@ -4026,10 +4100,12 @@ public void setMessageReadFlag(Message message, boolean read) {
 
 	/**
 	 * Sets the nickname of the server query client.
-	 * The nickname must be between 3 and 30 UTF-8 bytes long and BB codes will be ignored.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
 	 *
 	 * @param nickname
-	 * 		the new nickname, may not contain any BB codes and may not be {@code null}
+	 * 		the new nickname, may not be {@code null}
 	 *
 	 * @throws TS3CommandFailedException
 	 * 		if the execution of a command fails

src/main/java/com/github/theholywaffle/teamspeak3/TS3ApiAsync.java

@@ -4265,11 +4265,38 @@ public CommandFuture<List<CustomPropertyAssignment>> searchCustomClientProperty(
 	 * 		if the execution of a command fails
 	 * @querycommands 1
 	 * @see VirtualServer#getId()
+	 * @see #selectVirtualServerById(int, String)
 	 * @see #selectVirtualServerByPort(int)
 	 * @see #selectVirtualServer(VirtualServer)
 	 */
 	public CommandFuture<Void> selectVirtualServerById(int id) {
-		Command cmd = QueryCommands.useId(id);
+		return selectVirtualServerById(id, null);
+	}
+
+	/**
+	 * Moves the server query into the virtual server with the specified ID
+	 * and sets the server query's nickname.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
+	 *
+	 * @param id
+	 * 		the ID of the virtual server
+	 * @param nickname
+	 * 		the nickname, or {@code null} if the nickname should not be set
+	 *
+	 * @return a future to track the progress of this command
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see VirtualServer#getId()
+	 * @see #selectVirtualServerById(int)
+	 * @see #selectVirtualServerByPort(int, String)
+	 * @see #selectVirtualServer(VirtualServer, String)
+	 */
+	public CommandFuture<Void> selectVirtualServerById(int id, String nickname) {
+		Command cmd = QueryCommands.useId(id, nickname);
 		return executeAndReturnError(cmd);
 	}
 
@@ -4286,10 +4313,37 @@ public CommandFuture<Void> selectVirtualServerById(int id) {
 	 * @querycommands 1
 	 * @see VirtualServer#getPort()
 	 * @see #selectVirtualServerById(int)
+	 * @see #selectVirtualServerByPort(int, String)
 	 * @see #selectVirtualServer(VirtualServer)
 	 */
 	public CommandFuture<Void> selectVirtualServerByPort(int port) {
-		Command cmd = QueryCommands.usePort(port);
+		return selectVirtualServerByPort(port, null);
+	}
+
+	/**
+	 * Moves the server query into the virtual server with the specified voice port
+	 * and sets the server query's nickname.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
+	 *
+	 * @param port
+	 * 		the voice port of the virtual server
+	 * @param nickname
+	 * 		the nickname, or {@code null} if the nickname should not be set
+	 *
+	 * @return a future to track the progress of this command
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see VirtualServer#getPort()
+	 * @see #selectVirtualServerById(int, String)
+	 * @see #selectVirtualServerByPort(int)
+	 * @see #selectVirtualServer(VirtualServer, String)
+	 */
+	public CommandFuture<Void> selectVirtualServerByPort(int port, String nickname) {
+		Command cmd = QueryCommands.usePort(port, nickname);
 		return executeAndReturnError(cmd);
 	}
 
@@ -4306,11 +4360,37 @@ public CommandFuture<Void> selectVirtualServerByPort(int port) {
 	 * @querycommands 1
 	 * @see #selectVirtualServerById(int)
 	 * @see #selectVirtualServerByPort(int)
+	 * @see #selectVirtualServer(VirtualServer, String)
 	 */
 	public CommandFuture<Void> selectVirtualServer(VirtualServer server) {
 		return selectVirtualServerById(server.getId());
 	}
 
+	/**
+	 * Moves the server query into the specified virtual server
+	 * and sets the server query's nickname.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
+	 *
+	 * @param server
+	 * 		the virtual server to move into
+	 * @param nickname
+	 * 		the nickname, or {@code null} if the nickname should not be set
+	 *
+	 * @return a future to track the progress of this command
+	 *
+	 * @throws TS3CommandFailedException
+	 * 		if the execution of a command fails
+	 * @querycommands 1
+	 * @see #selectVirtualServerById(int, String)
+	 * @see #selectVirtualServerByPort(int, String)
+	 * @see #selectVirtualServer(VirtualServer)
+	 */
+	public CommandFuture<Void> selectVirtualServer(VirtualServer server, String nickname) {
+		return selectVirtualServerById(server.getId(), nickname);
+	}
+
 	/**
 	 * Sends an offline message to the client with the given unique identifier.
 	 * <p>
@@ -4647,10 +4727,12 @@ public CommandFuture<Void> setMessageReadFlag(Message message, boolean read) {
 
 	/**
 	 * Sets the nickname of the server query client.
-	 * The nickname must be between 3 and 30 UTF-8 bytes long and BB codes will be ignored.
+	 * <p>
+	 * The nickname must be between 3 and 30 UTF-8 bytes long. BB codes will be ignored.
+	 * </p>
 	 *
 	 * @param nickname
-	 * 		the new nickname, may not contain any BB codes and may not be {@code null}
+	 * 		the new nickname, may not be {@code null}
 	 *
 	 * @return a future to track the progress of this command
 	 *

src/main/java/com/github/theholywaffle/teamspeak3/commands/QueryCommands.java

@@ -28,6 +28,7 @@
 
 import com.github.theholywaffle.teamspeak3.api.event.TS3EventType;
 import com.github.theholywaffle.teamspeak3.commands.parameter.KeyValueParam;
+import com.github.theholywaffle.teamspeak3.commands.parameter.OptionParam;
 import com.github.theholywaffle.teamspeak3.commands.parameter.ValueParam;
 
 public final class QueryCommands {
@@ -70,12 +71,20 @@ public static Command serverNotifyUnregister() {
 		return new CommandBuilder("servernotifyunregister").build();
 	}
 
-	public static Command useId(int id) {
-		return new CommandBuilder("use", 1).add(new KeyValueParam("sid", id)).build();
+	public static Command useId(int id, String nickname) {
+		CommandBuilder builder = new CommandBuilder("use", 3);
+		builder.add(new KeyValueParam("sid", id));
+		builder.add(new OptionParam("virtual"));
+		builder.addIf(nickname != null, new KeyValueParam("client_nickname", nickname));
+		return builder.build();
 	}
 
-	public static Command usePort(int port) {
-		return new CommandBuilder("use", 1).add(new KeyValueParam("port", port)).build();
+	public static Command usePort(int port, String nickname) {
+		CommandBuilder builder = new CommandBuilder("use", 3);
+		builder.add(new KeyValueParam("port", port));
+		builder.add(new OptionParam("virtual"));
+		builder.addIf(nickname != null, new KeyValueParam("client_nickname", nickname));
+		return builder.build();
 	}
 
 	public static Command whoAmI() {