org.deepsymmetry.beatlink.dbserver

Class Client

java.lang.Object

org.deepsymmetry.beatlink.dbserver.Client

public class Client
extends Object

Manages a connection to the dbserver port on a particular player, allowing queries to be sent, and their responses to be interpreted. Direct instantiation is not available outside the package, instead ConnectionManager.invokeWithClientSession(int, ConnectionManager.ClientTask, String) must be used.

Author:

James Elliott

Field Summary

Fields

Modifier and Type	Field and Description
static long	DEFAULT_MENU_BATCH_SIZE The default maximum number of menu items we will request at a single time.
static NumberField	GREETING_FIELD The greeting message exchanged over a new connection consists of a 4-byte number field containing the value 1.
int	posingAsPlayer The player we are pretending to be.
int	targetPlayer The player number we are communicating with.

Method Summary

Modifier and Type	Method and Description
static NumberField	buildRMS1(int requestingPlayer, Message.MenuIdentifier targetMenu, CdjStatus.TrackSourceSlot slot) Build the R:M:S:1 parameter that begins many queries.
NumberField	buildRMS1(Message.MenuIdentifier targetMenu, CdjStatus.TrackSourceSlot slot) Build the R:M:S:1 parameter that begins many queries.
static long	getMenuBatchSize() Ghe maximum number of menu items we will request at a single time.
boolean	isConnected() Check whether our connection is still available for use.
Message	menuRequest(Message.KnownType requestType, Message.MenuIdentifier targetMenu, CdjStatus.TrackSourceSlot slot, Field... arguments) Send a request for a menu that we will retrieve items from in subsequent requests.
List<Message>	renderMenuItems(Message.MenuIdentifier targetMenu, CdjStatus.TrackSourceSlot slot, int offset, int count) Gather up the specified range of responses for a menu request.
List<Message>	renderMenuItems(Message.MenuIdentifier targetMenu, CdjStatus.TrackSourceSlot slot, Message availableResponse) Gather up all the responses that are available for a menu request.
static void	setMenuBatchSize(long batchSize) Set the maximum number of menu items we will request at a single time.
Message	simpleRequest(Message.KnownType requestType, Message.KnownType responseType, Field... arguments) Send a request that expects a single message as its response, then read and return that response.
String	toString()
boolean	tryLockingForMenuOperations(long timeout, TimeUnit unit) Attempt to secure exclusive access to this player for performing a menu operation, which requires multiple request/response cycles.
void	unlockForMenuOperations() Allow other threads to perform menu operations.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

targetPlayer

public final int targetPlayer

The player number we are communicating with.

posingAsPlayer

public final int posingAsPlayer

The player we are pretending to be.

GREETING_FIELD

public static final NumberField GREETING_FIELD

The greeting message exchanged over a new connection consists of a 4-byte number field containing the value 1.

DEFAULT_MENU_BATCH_SIZE

public static final long DEFAULT_MENU_BATCH_SIZE

The default maximum number of menu items we will request at a single time. We are not sure what the largest safe value to use is, but 64 seems to work well for CDJ-2000 nexus players.

See Also:

Constant Field Values

Method Detail

isConnected

public boolean isConnected()

Check whether our connection is still available for use. We will close it if there is ever a problem communicating with the dbserver.

Returns:

true if this instance can still be used to query the connected dbserver

buildRMS1

public static NumberField buildRMS1(int requestingPlayer,
                                    Message.MenuIdentifier targetMenu,
                                    CdjStatus.TrackSourceSlot slot)

Build the R:M:S:1 parameter that begins many queries.

Many request messages take, as their first argument, a 4-byte value where each byte has a special meaning. The first byte is the player number of the requesting player. The second identifies the menu into which the response is being loaded, as described by Message.MenuIdentifier. The third specifies the media slot from which information is desired, as described by CdjStatus.TrackSourceSlot, and the fourth byte always seems to be 1 (Austin's libpdjl called it sourceAnalyzed).

Parameters:

requestingPlayer - the player number that is asking the question

targetMenu - the destination for the response to this query

slot - the media library of interest for this query

Returns:

the first argument to send with the query in order to obtain the desired information

buildRMS1

public NumberField buildRMS1(Message.MenuIdentifier targetMenu,
                             CdjStatus.TrackSourceSlot slot)

Build the R:M:S:1 parameter that begins many queries.

Many request messages take, as their first argument, a 4-byte value where each byte has a special meaning. The first byte is the player number of the requesting player. The second identifies the menu into which the response is being loaded, as described by Message.MenuIdentifier. The third specifies the media slot from which information is desired, as described by CdjStatus.TrackSourceSlot, and the fourth byte always seems to be 1 (Austin's libpdjl called it sourceAnalyzed).

Parameters:

targetMenu - the destination for the response to this query

slot - the media library of interest for this query

Returns:

the first argument to send with the query in order to obtain the desired information

simpleRequest

public Message simpleRequest(Message.KnownType requestType,
                             Message.KnownType responseType,
                             Field... arguments)
                      throws IOException

Send a request that expects a single message as its response, then read and return that response.

Parameters:

requestType - identifies what kind of request to send

responseType - identifies the type of response we expect, or null if we’ll accept anything

arguments - The argument fields to send in the request

Returns:

the response from the player

Throws:

IOException - if there is a communication problem, or if the response does not have the same transaction ID as the request.

menuRequest

public Message menuRequest(Message.KnownType requestType,
                           Message.MenuIdentifier targetMenu,
                           CdjStatus.TrackSourceSlot slot,
                           Field... arguments)
                    throws IOException

Send a request for a menu that we will retrieve items from in subsequent requests.

Parameters:

requestType - identifies what kind of menu request to send

targetMenu - the destination for the response to this query

slot - the media library of interest for this query

arguments - the additional arguments needed, if any, to complete the request

Returns:

the Message.KnownType.MENU_AVAILABLE response reporting how many items are available in the menu

Throws:

IOException - if there is a problem communicating, or if the requested menu is not available

IllegalStateException - if tryLockingForMenuOperations(long, TimeUnit) was not called successfully before attempting this call

getMenuBatchSize

public static long getMenuBatchSize()

Ghe maximum number of menu items we will request at a single time. We are not sure what the largest safe value to use is, but 64 seems to work well for CDJ-2000 nexus players. Changing this will affect future calls to renderMenuItems(Message.MenuIdentifier, CdjStatus.TrackSourceSlot, Message).

Returns:

the maximum number of items renderMenuItems(Message.MenuIdentifier, CdjStatus.TrackSourceSlot, Message) will request at once

setMenuBatchSize

public static void setMenuBatchSize(long batchSize)

Set the maximum number of menu items we will request at a single time. We are not sure what the largest safe value to use is, but 64 seems to work well for CDJ-2000 nexus players. Changing this will affect future calls to renderMenuItems(Message.MenuIdentifier, CdjStatus.TrackSourceSlot, Message).

Parameters:

batchSize - the maximum number of items renderMenuItems(Message.MenuIdentifier, CdjStatus.TrackSourceSlot, Message) will request at once

tryLockingForMenuOperations

public boolean tryLockingForMenuOperations(long timeout,
                                           TimeUnit unit)
                                    throws InterruptedException

Attempt to secure exclusive access to this player for performing a menu operation, which requires multiple request/response cycles. The caller must call unlockForMenuOperations() as soon as it is done (even if it is failing because of an exception), or no future menu operations will be possible by any other thread, unless false was returned, meaning the attempt failed.

Parameters:

timeout - the time to wait for the lock

unit - the time unit of the timeout argument

Returns:

true if the lock was acquired within the specified time

Throws:

InterruptedException - if the thread is interrupted while waiting for the lock

unlockForMenuOperations

public void unlockForMenuOperations()

Allow other threads to perform menu operations. This must be called promptly, once for each time that tryLockingForMenuOperations(long, TimeUnit) was called with a true return value.

renderMenuItems

public List<Message> renderMenuItems(Message.MenuIdentifier targetMenu,
                                     CdjStatus.TrackSourceSlot slot,
                                     Message availableResponse)
                              throws IOException

Gather up all the responses that are available for a menu request. Will involve multiple requests if the number of responses available is larger than our maximum batch size (see getMenuBatchSize().

Parameters:

targetMenu - the destination for the response to this query

slot - the media library of interest for this query

availableResponse - the response to the initial menu setup request, reporting how many responses are available, as well as the target menu we are working with

Returns:

all the response items, using as many queries as necessary to gather them safely, and omitting all the header and footer items

Throws:

IOException - if there is a problem reading the menu items

IllegalStateException - if tryLockingForMenuOperations(long, TimeUnit) was not called successfully before attempting this call

renderMenuItems

public List<Message> renderMenuItems(Message.MenuIdentifier targetMenu,
                                     CdjStatus.TrackSourceSlot slot,
                                     int offset,
                                     int count)
                              throws IOException

Gather up the specified range of responses for a menu request. Will involve multiple requests if the number of responses requested is larger than our maximum batch size (see getMenuBatchSize(). It is the caller's responsibility to make sure that offset and count remain within the legal, available menu items based on the initial menu setup request. Most use cases will be best served by the simpler renderMenuItems(Message.MenuIdentifier, CdjStatus.TrackSourceSlot, Message).

Parameters:

targetMenu - the destination for the response to this query

slot - the media library of interest for this query

offset - the first response desired (the first one available has offset 0)

count - the number of responses desired

Returns:

the response items, using as many queries as necessary to gather them safely, and omitting all the header and footer items

Throws:

IOException - if there is a problem reading the menu items

IllegalStateException - if tryLockingForMenuOperations(long, TimeUnit) was not called successfully before attempting this call

toString

public String toString()

Overrides:

toString in class Object