samophis.lavalink.client.entities

Class LavaClient

java.lang.Object

samophis.lavalink.client.entities.LavaClient

public abstract class LavaClient
extends java.lang.Object

Represents the LavaClient implementation of Lavalink, with default constants matching those of the Lavalink-Server, collections of nodes, players, etc.
This is the gateway into every other LavaClient action and can be constructed with a LavaClientBuilder.

Since:

0.1

Author:

SamOphis

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_BASE_INTERVAL The default reconnect "base" interval to use.
static long	DEFAULT_CACHE_EXPIRE_ACCESS The default cache expire-after-access time, in milliseconds.
static long	DEFAULT_CACHE_EXPIRE_WRITE The default cache expire-after-write time, in milliseconds.
static ReconnectIntervalFunction	DEFAULT_INTERVAL_EXPANDER The default interval expander, equivalent to raising 2 to the amount of reconnect attempts.
static java.util.concurrent.TimeUnit	DEFAULT_INTERVAL_UNIT The default TimeUnit to wait for the provided interval in.
static long	DEFAULT_MAX_INTERVAL The value the reconnect interval is capped to.
static java.lang.String	DEFAULT_PASSWORD The default password to use for the Lavalink-Server.
static int	DEFAULT_REST_PORT The default port to use for the Lavalink-Server REST API.
static int	DEFAULT_WS_PORT The default port to use for the Lavalink-Server WebSocket.

Method Summary

Modifier and Type	Method and Description
abstract void	addEntry(AudioNodeEntry entry) Adds a not-null AudioNode and opens a connection to it based on the information provided by the AudioNodeEntry.
abstract void	addNode(AudioNode node) Adds a not-null AudioNode and opens a connection to it (if it isn't already open).
abstract java.util.List<AudioNode>	getAudioNodes() Used to fetch an unmodifiable list of all the AudioNodes this client can connect to.
abstract AudioNode	getBestNode() Fetches the AudioNode with the least amount of load on it, used to balance the load of LavaPlayers on different nodes.
abstract long	getCacheExpireAfterAccessMs() Fetches the amount of time from which track data will removed from the cache after being accessed (after being written).
abstract long	getCacheExpireAfterWriteMs() Fetches the amount of time from which track data will be removed from the cache after being written without being accessed.
abstract long	getGlobalBaseReconnectInterval() Fetches the default "base" interval for reconnecting purposes, used for default values and "expansion".
abstract ReconnectIntervalFunction	getGlobalIntervalExpander() Fetches the default interval "expander", used to change the reconnect interval for the next reconnect attempt.
abstract java.util.concurrent.TimeUnit	getGlobalIntervalTimeUnit() Fetches the default TimeUnit which is used to actually wait for the intervals in a good unit, such as MILLISECONDS, HOURS, etc.
abstract long	getGlobalMaximumReconnectInterval() Fetches the default maximum interval for reconnecting purposes, used to cap the provided reconnect interval so that it never gets too high.
abstract int	getGlobalRestPort() Fetches the default REST API port for all AudioNodes the client has access to.
abstract java.lang.String	getGlobalServerPassword() Fetches the default password for all AudioNodes the client has access to.
abstract int	getGlobalWebSocketPort() Fetches the default WebSocket port for all AudioNodes the client has access to.
abstract LavaHttpManager	getHttpManager() Used to fetch the LavaHttpManager associated with this client, which is used to get track data from an identifier.
abstract com.github.benmanes.caffeine.cache.Cache<java.lang.String,TrackDataPair>	getIdentifierCache() Fetches the internal identifier cache used by LavaClient to cut down the impact of loading the same sources in quick succession.
abstract AudioNode	getNodeByIdentifier(java.lang.String address, int websocketPort) Fetches an AudioNode by address and port.
abstract LavaPlayer	getPlayerByGuildId(long guild_id) Fetches a LavaPlayer instance by Guild ID.
abstract it.unimi.dsi.fastutil.longs.Long2ObjectMap<LavaPlayer>	getPlayerMap() Fetches an unmodifiable view of the internal player map.
abstract java.util.List<LavaPlayer>	getPlayers() Used to fetch an unmodifiable list of all the LavaPlayers associated with this client.
abstract int	getShardCount() Fetches the amount of shards specified during the construction of the LavaClient instance.
abstract long	getUserId() Fetches the User ID of the Bot User specified during the construction of the LavaClient instance.
abstract LavaPlayer	newPlayer(AudioNode node, long guild_id) Fetches a not-null LavaPlayer instance associated with a positive Guild ID.
abstract LavaPlayer	newPlayer(long guild_id) Fetches a not-null LavaPlayer instance associated with a positive Guild ID.
abstract void	removeEntry(AudioNodeEntry entry) Attempts to remove the AudioNode associated with the provided, not-null AudioNodeEntry.
abstract void	removeEntry(java.lang.String serverAddress, int websocketPort) Attempts to remove the AudioNode associated with a provided server address and port.
abstract void	removeNode(AudioNode node) Attempts to remove a not-null AudioNode.
abstract LavaPlayer	removePlayer(long guild_id) Attempts to remove a LavaPlayer instance associated with a positive Guild ID.
abstract LavaPlayer	removePlayer(long guild_id, boolean shouldDestroy) Attempts to remove a LavaPlayer instance associated with a positive Guild ID.
abstract void	shutdown() Shuts down LavaClient (also resetting the state).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_REST_PORT

public static final int DEFAULT_REST_PORT

The default port to use for the Lavalink-Server REST API.

See Also:

Constant Field Values

DEFAULT_WS_PORT

public static final int DEFAULT_WS_PORT

The default port to use for the Lavalink-Server WebSocket.

See Also:

Constant Field Values

DEFAULT_PASSWORD

public static final java.lang.String DEFAULT_PASSWORD

The default password to use for the Lavalink-Server.

See Also:

Constant Field Values

DEFAULT_CACHE_EXPIRE_WRITE

public static final long DEFAULT_CACHE_EXPIRE_WRITE

The default cache expire-after-write time, in milliseconds.

See Also:

Constant Field Values

DEFAULT_CACHE_EXPIRE_ACCESS

public static final long DEFAULT_CACHE_EXPIRE_ACCESS

The default cache expire-after-access time, in milliseconds.

See Also:

Constant Field Values

DEFAULT_BASE_INTERVAL

public static final long DEFAULT_BASE_INTERVAL

The default reconnect "base" interval to use.

See Also:

Constant Field Values

DEFAULT_MAX_INTERVAL

public static final long DEFAULT_MAX_INTERVAL

The value the reconnect interval is capped to.

See Also:

Constant Field Values

DEFAULT_INTERVAL_UNIT

public static final java.util.concurrent.TimeUnit DEFAULT_INTERVAL_UNIT

The default TimeUnit to wait for the provided interval in.

DEFAULT_INTERVAL_EXPANDER

public static final ReconnectIntervalFunction DEFAULT_INTERVAL_EXPANDER

The default interval expander, equivalent to raising 2 to the amount of reconnect attempts.

Method Detail

getPlayers

@Nonnull
public abstract java.util.List<LavaPlayer> getPlayers()

Used to fetch an unmodifiable list of all the LavaPlayers associated with this client.

Returns:

An unmodifiable view of all the LavaPlayers this client contains.

getAudioNodes

@Nonnull
public abstract java.util.List<AudioNode> getAudioNodes()

Used to fetch an unmodifiable list of all the AudioNodes this client can connect to.

Returns:

An unmodifiable view of all the AudioNodes this client can connect to.

getHttpManager

@Nonnull
public abstract LavaHttpManager getHttpManager()

Used to fetch the LavaHttpManager associated with this client, which is used to get track data from an identifier.

Returns:

The LavaHttpManager used to grab track data from an identifier.

getNodeByIdentifier

@Nullable
public abstract AudioNode getNodeByIdentifier(@Nonnull
                                                        java.lang.String address,
                                                        @Nonnegative
                                                        int websocketPort)

Fetches an AudioNode by address and port. This operation is extremely fast as it only looks up the entry in a HashMap.

Parameters:

address - The not-null server address specified in the node's AudioNodeEntry.

websocketPort - The positive server WebSocket port specified in the node's AudioNodeEntry.

Returns:

A possibly-null AudioNode associated with the provided server address and WebSocket port.

Throws:

java.lang.NullPointerException - If the provided address was null.

java.lang.IllegalArgumentException - If the provided WebSocket Port was negative.

getPlayerByGuildId

@Nullable
public abstract LavaPlayer getPlayerByGuildId(@Nonnegative
                                                        long guild_id)

Fetches a LavaPlayer instance by Guild ID.

This method will return null if a player for the provided Guild ID doesn't exist, unlike previous versions of LavaClient.

Parameters:

guild_id - The positive ID of the Guild.

Returns:

A possibly-null LavaPlayer instance associated with the Guild ID.

getGlobalServerPassword

@Nonnull
public abstract java.lang.String getGlobalServerPassword()

Fetches the default password for all AudioNodes the client has access to.

This value equates to "youshallnotpass" if it's not specified during the construction of the LavaClient instance.

Returns:

The default password specified for this LavaClient instance.

getCacheExpireAfterWriteMs

@Nonnegative
public abstract long getCacheExpireAfterWriteMs()

Fetches the amount of time from which track data will be removed from the cache after being written without being accessed.

When a song loads, LavaClient caches the initial loading data temporarily so that the server nor the client have to re-load it for a certain period of time.
This value tells LavaClient how long to wait after data is written before it is removed, ignoring the access of the data.
If the data is not removed, memory usage will keep on going up which is bad for big bots or small bots on limited hardware.

This value equates to 1200000L milliseconds if it isn't manually specified during construction of the client.

Returns:

The amount of time to wait to remove cached track data after it is initially written.

See Also:

getCacheExpireAfterAccessMs()

getCacheExpireAfterAccessMs

@Nonnegative
public abstract long getCacheExpireAfterAccessMs()

Fetches the amount of time from which track data will removed from the cache after being accessed (after being written).

When a song loads, LavaClient caches the initial loading data temporarily so that the server nor the client have to re-load it for a certain period of time.
This value tells LavaClient how long to wait after data is accessed before it is removed, ignoring the writing of the data.
If the data is not removed, memory usage will slowly creep up which is bad for big bots or small bots on limited hardware.

This value equates to 900000L milliseconds if it isn't manually specified during construction of the client.

Returns:

The amount of time to wait to remove cached track data after it is accessed.

See Also:

getCacheExpireAfterWriteMs()

getGlobalWebSocketPort

@Nonnegative
public abstract int getGlobalWebSocketPort()

Fetches the default WebSocket port for all AudioNodes the client has access to.

This value equates to 80 if it's not specified during the construction of the LavaClient instance.

Returns:

The default WebSocket port for this LavaClient instance.

getGlobalBaseReconnectInterval

public abstract long getGlobalBaseReconnectInterval()

Fetches the default "base" interval for reconnecting purposes, used for default values and "expansion".

As with almost all default values, this value can be overridden on a per-node basis. This value equates to 0L if it's not specified during construction of this client.

Returns:

The default "base" interval for reconnecting purposes.

getGlobalMaximumReconnectInterval

@Nonnegative
public abstract long getGlobalMaximumReconnectInterval()

Fetches the default maximum interval for reconnecting purposes, used to cap the provided reconnect interval so that it never gets too high.

As with almost all default values, this value can be overridden on a per-node basis. This value equates to 15L if it's not specified during construction of this client.

Returns:

The not-negative maximum interval for reconnecting purposes.

getGlobalIntervalExpander

@Nonnull
public abstract ReconnectIntervalFunction getGlobalIntervalExpander()

Fetches the default interval "expander", used to change the reconnect interval for the next reconnect attempt.

As of v3.0.0, this expander returns 2 raised to the number of reconnect attempts. As with almost all default values, this value can be overridden on a per-node basis.

Returns:

The not-null ReconnectIntervalFunction used to change intervals.

getGlobalIntervalTimeUnit

@Nonnull
public abstract java.util.concurrent.TimeUnit getGlobalIntervalTimeUnit()

Fetches the default TimeUnit which is used to actually wait for the intervals in a good unit, such as MILLISECONDS, HOURS, etc.

As of v3.0.0, the returned unit is TimeUnit#SECONDS, however as with almost all default values, this value can be overridden on a per-node basis.

Returns:

The default TimeUnit to wait in.

getGlobalRestPort

@Nonnegative
public abstract int getGlobalRestPort()

Fetches the default REST API port for all AudioNodes the client has access to.

This value equates to 2333 if it's not specified during the construction of the LavaClient instance.

Returns:

The default REST API port for this LavaClient instance.

getShardCount

@Nonnegative
public abstract int getShardCount()

Fetches the amount of shards specified during the construction of the LavaClient instance.

Returns:

The amount of shards LavaClient is aware of and passes to AudioNodes when connecting.

getUserId

@Nonnegative
public abstract long getUserId()

Fetches the User ID of the Bot User specified during the construction of the LavaClient instance.

Returns:

The User ID of the Bot User which LavaClient passes to AudioNodes when connecting.

addNode

public abstract void addNode(@Nonnull
                             AudioNode node)

Adds a not-null AudioNode and opens a connection to it (if it isn't already open).

Note: This will overwrite and disconnect the client from the node if it pre-exists with the same information.

Parameters:

node - The not-null AudioNode to add.

Throws:

java.lang.NullPointerException - If the provided node was null.

removeNode

public abstract void removeNode(@Nonnull
                                AudioNode node)

Attempts to remove a not-null AudioNode.

If no node was found with the attached information, no action will be performed. Additionally, if one was found the client will disconnect from it and then remove it from the global map.

Parameters:

node - The not-null AudioNode to remove.

Throws:

java.lang.NullPointerException - If the provided AudioNode was null.

addEntry

public abstract void addEntry(@Nonnull
                              AudioNodeEntry entry)

Adds a not-null AudioNode and opens a connection to it based on the information provided by the AudioNodeEntry.

Parameters:

entry - The AudioNodeEntry containing the address, the port, etc. of the AudioNode.

Throws:

java.lang.NullPointerException - If the provided entry was null.

removeEntry

public abstract void removeEntry(@Nonnull
                                 AudioNodeEntry entry)

Attempts to remove the AudioNode associated with the provided, not-null AudioNodeEntry.

This will do nothing if no node was found, and it'll disconnect the client from the node and remove it if it was found.

Parameters:

entry - The not-null AudioNodeEntry used to identify and remove the associated AudioNode.

Throws:

java.lang.NullPointerException - If the provided AudioNodeEntry was null.

removeEntry

public abstract void removeEntry(@Nonnull
                                 java.lang.String serverAddress,
                                 @Nonnegative
                                 int websocketPort)

Attempts to remove the AudioNode associated with a provided server address and port.

This will do nothing if no node was found, and it'll disconnect the client from the node and remove it if it was found.

Parameters:

serverAddress - The not-null raw address of the server without any scheme behind it.

websocketPort - The not-negative WebSocket port of the Lavalink Server.

Throws:

java.lang.NullPointerException - If the provided server address was null.

java.lang.IllegalArgumentException - If the provided WebSocket port was negative.

getIdentifierCache

@Nonnull
public abstract com.github.benmanes.caffeine.cache.Cache<java.lang.String,TrackDataPair> getIdentifierCache()

Fetches the internal identifier cache used by LavaClient to cut down the impact of loading the same sources in quick succession.

Note: Editing this cache might cause some delay and bugs. Modifying it is your choice.

Returns:

the internal cache LavaClient uses to cut down repeated song loading impact.

getPlayerMap

@Nonnull
public abstract it.unimi.dsi.fastutil.longs.Long2ObjectMap<LavaPlayer> getPlayerMap()

Fetches an unmodifiable view of the internal player map.

Note: This returns an unmodifiable map, meaning any attempts to modify it will throw exceptions.

Returns:

An unmodifiable view of the internal player map.

newPlayer

@Nonnull
public abstract LavaPlayer newPlayer(@Nullable
                                              AudioNode node,
                                              @Nonnegative
                                              long guild_id)

Fetches a not-null LavaPlayer instance associated with a positive Guild ID.

If a player is already found, it'll simply be returned. If one doesn't exist, it'll be created but NOT connected.
In this sense, a new player doesn't submit a Voice Update to an AudioNode manually. Use an EventWaiter wherever you can instead of manually creating new players.

Parameters:

node - The possibly-null AudioNode to set. Replaced with the best available node if this is null.

guild_id - The positive ID of the Guild to connect to.

Returns:

A not-null LavaPlayer instance.

newPlayer

@Nonnull
public abstract LavaPlayer newPlayer(@Nonnegative
                                              long guild_id)

Fetches a not-null LavaPlayer instance associated with a positive Guild ID.

If a player is already found, it'll simply be returned. If one doesn't exist, it'll be created but NOT connected.
In this sense, a new player doesn't submit a Voice Update to an AudioNode manually. Use an EventWaiter wherever you can instead of manually creating new players.

Parameters:

guild_id - The positive ID of the Guild to connect to.

Returns:

A not-null LavaPlayer instance.

removePlayer

@Nullable
public abstract LavaPlayer removePlayer(@Nonnegative
                                                  long guild_id,
                                                  boolean shouldDestroy)

Attempts to remove a LavaPlayer instance associated with a positive Guild ID.

If a player is found, it'll be destroyed only if it's connected and if shouldDestroy is set to true. If it isn't found, nothing will happen and null will be returned.

Parameters:

guild_id - The positive Guild ID associated with the LavaPlayer instance.

shouldDestroy - If LavaClient should destroy the player before removing it.

Returns:

A possibly-null LavaPlayer instance.

Throws:

java.lang.IllegalArgumentException - If the provided Guild ID was negative.

removePlayer

public abstract LavaPlayer removePlayer(@Nonnegative
                                        long guild_id)

Attempts to remove a LavaPlayer instance associated with a positive Guild ID.

If a player is found, it'll simply be removed without anything else happening. If it isn't found, nothing will happen and null will be returned.

Parameters:

guild_id - The positive Guild ID associated with the LavaPlayer instance.

Returns:

A possibly-null LavaPlayer instance.

Throws:

java.lang.IllegalArgumentException - If the provided Guild ID was negative.

shutdown

public abstract void shutdown()

Shuts down LavaClient (also resetting the state).

This method removes and disconnects from all AudioNodes and LavaPlayers and additionally shuts down the attached LavaHttpManager.

Throws:

java.lang.IllegalStateException - If this client has already been shutdown.

getBestNode

@Nullable
public abstract AudioNode getBestNode()

Fetches the AudioNode with the least amount of load on it, used to balance the load of LavaPlayers on different nodes.

Returns:

The best AudioNode to connect to, returns null if no node exists.