Skip to content

Advanced API

Vincent edited this page Jun 14, 2024 · 8 revisions

Using the Advanced API

Some tricks and tips to improve the performance of your Code. All methods shown are provided the Ts3SyncAPI class (from net.devcube.vinco.teamspeakapi.api.sync). For simplicity the arguments are not shown, use the help of your IDEA or documentation in the code.

1. Getting Lists

Be aware of how much or what information you actually need in your case; otherwise, it will take more time to retrieve unused information.

For reference see: YaTQA Variables and Parameters (Client/Channel-Variables -> ~list, ~info).

A. Client List

Using getOnlineClients() or getClients() provides the information from the list of clients and contains less information about every single client compared to getClient(). But the method will send one command to the server which is faster.

Using getOnlineClientsDetailed() or getClientsDetailed() provides the information from getClient() for every client. It provides more information compared to above. But instead will send two commands to the server. The first command is used to get the client list and the other one to retrieve the information about all clients at once.

B. Channel List

Using getChannels() provides less information about every single channel than getChannel() but will send one command.

Using getChannelsDetailed() provides the information from getChannel() for every single channel. It provides more information compared to above. But instead will send much more commands to the server, because for every single channel a command is sent by getChannel() to retrieve the information.

C. DataBaseClient List

Same as above for getting Clients.

Using getDataBaseClients() provides less information about every single DataBaseClient than getDataBaseClientInfo() but will send one command.

Using getDataBaseClientsDetailed() provides the information from getDataBaseClientInfo() for every single DataBaseClient. But instead will send two commands to the server, because the first command is executed to get the database client list and one to retrieve the information about all database clients at once.

2. Getting Database Information

These Methods deal different (instead of normal Getters) with retrieved information. And also the way they store them to improve performance. Be aware that every Method answers a different Question about (mostly) the same Database information.

A. Getting Clients with a ServerGroup

Provides a List of DatabaseClient(ID)s with a specific ServerGroup.

  • getDatabaseIDsByServerGroup
  • getDatabaseClientInfosByServerGroup

B. Getting Clients with a ChannelGroup

Provides a Map which contains every DatabaseClient(ID) as a Key and the Value is a List of ChannelIDs in which the DatabaseClient(ID) has the ChannelGroup. To only get the DatabaseClient(ID)s just use keySet().

  • getDatabaseIDsByChannelGroup
  • getDatabaseClientInfosByChannelGroup

C. Getting Clients with a ChannelGroup by Channel

Provides a List of DatabaseClient(ID)s which have a specific ChannelGroup in a specific Channel.

  • getDatabaseIDsByChannelAndGroup
  • getDatabaseClientInfosByChannelAndGroup

D. Getting ChannelGroups by Channel

Provides a Map which contains every ChannelGroup(ID) as a Key and the Value is a List of DatabaseClientIDs which are in the ChannelGroup. Note that getChannelGroupInfosByChannelID caches the List of ChannelGroups to improve the performance and only returns ChannelGroups which are set to any Client. To get only the ChannelGroup(ID)s just use keySet().

  • getChannelGroupsByChannelID
  • getChannelGroupInfosByChannelID

E. Getting ChannelGroups by ClientDatabaseID

Provides a Map which contains every ChannelGroup(ID) as a Key and the Value is a List of ChannelIDs in which the Client has the ChannelGroup(ID). Note that getChannelGroupInfosByDatabaseID caches the List of ChannelGroups to improve the performance. To get only the ChannelGroup(ID)s just use keySet().

  • getChannelGroupsByDatabaseID
  • getChannelGroupInfosByDatabaseID

3. Providing Lists for Actions

These methods execute one action for more than just one Element. Instead of iterate through a List and execute the Action for every Element, these Methods execute the Action for multiple Elements at once. And send one Command to the Server which is faster. Good for interacting with multiple (maybe filtered) elements at once.

(Element means Classes from net.devcube.vinco.teamspeakapi.api.api.wrapper or Basic Datatype)

Some Methods provide optional forms of arguments. These are shown in the Name of the Method and are different type of Data. Like Permissions and PermissionIDs, Clients and ClientIDs or DBClient and ClientDBIDs.

A. Retrieve information about multiple (DataBase)Clients

  • getClientsByIDs
  • getDataBaseClientsByDBIDs

B. Add multiple Clients to a ServerGroup

  • addClientDBIDsToServerGroup
  • addDBClientsToServerGroup
  • addClientsToServerGroup

C. Remove multiple Clients from a ServerGroup

  • removeClientDBIDsFromServerGroup
  • removeDBClientsFromServerGroup
  • removeClientsFromServerGroup

D. Manage multiple Permissions from a Client in a Channel

  • addChannelClientPermissions
  • removeChannelClientPermissions

E. Manage multiple Permissions from a ChannelGroup

  • addChannelGroupPermissions
  • removeChannelGroupPermissionIDs
  • removeChannelGroupPermissions

F. Manage multiple Permissions from a Channel

  • addChannelPermissions
  • removeChannelPermissionIDs
  • removeChannelPermissions

G. Manage multiple Permissions from a Client

  • addClientPermissions
  • removeClientPermissionIDs
  • removeClientPermissions

H. Manage multiple Permissions from a ServerGroup

  • addServerGroupPermissions
  • removeServerGroupPermissionIDs
  • removeServerGroupPermissions

I. Ban multiple Clients

  • banClientIDs
  • banClients

J. Kick multiple Clients from a Channel

  • kickClientIDsFromChannel
  • kickClientsFromChannel

K. Kick multiple Clients from the Server

  • kickClientIDsFromServer
  • kickClientsFromServer

L. Move multiple Clients in a Channel

  • moveClientIDs
  • moveClients

Example:

Instead of:

public class Test {
    
    public static void test() {
        List<ClientInfo> commanderClients = syncAPI.getClients().stream().filter(client -> client.isChannelCommander()).toList();

        for (ClientInfo clients : commanderClients) {
            syncAPI.addClientToServerGroup(0, clients); //Adds every Client one by one the ServerGroup
        }
    }
}

Use:

public class Test {
    
    public static void test() {
        List<ClientInfo> commanderClients = syncAPI.getClients().stream().filter(client -> client.isChannelCommander()).toList();
        syncAPI.addClientsToServerGroup(0, commanderClients); //Adds every Client at once the ServerGroup
    }
}