java.lang.Object
- org.deepsymmetry.beatlink.Util

```
public class Util
extends Object
```
Provides utility functions.

Author:

James Elliott

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`Util.PacketType`	The known packet types used in the protocol, along with the byte values which identify them, and the names by which we describe them, and the port on which they are received.

Field Summary

Fields
Modifier and Type	Field	Description
`static Color`	`HIGH_CHORUS_1_COLOR`	The color of a chorus 1 phrase in a track with a high mood.
`static Color`	`HIGH_CHORUS_2_COLOR`	The color of a chorus 2 phrase in a track with a high mood.
`static Color`	`HIGH_DOWN_COLOR`	The color of a down phrase in a track with a high mood.
`static Color`	`HIGH_INTRO_1_COLOR`	The color of an intro 1 phrase in a track with a high mood.
`static Color`	`HIGH_INTRO_2_COLOR`	The color of an intro 2 phrase in a track with a high mood.
`static Color`	`HIGH_OUTRO_1_COLOR`	The color of an outro 1 phrase in a track with a high mood.
`static Color`	`HIGH_OUTRO_2_COLOR`	The color of an outro 2 phrase in a track with a high mood.
`static Color`	`HIGH_UP_1_COLOR`	The color of an up 1 phrase in a track with a high mood.
`static Color`	`HIGH_UP_2_COLOR`	The color of an up 2 phrase in a track with a high mood.
`static Color`	`HIGH_UP_3_COLOR`	The color of an up 3 phrase in a track with a high mood.
`static Color`	`LOW_BRIDGE_COLOR`	The color of a bridge phrase in a track with a low mood.
`static Color`	`LOW_CHORUS_COLOR`	The color of a chorus phrase in a track with a low mood.
`static Color`	`LOW_INTRO_COLOR`	The color of an intro phrase in a track with a low mood.
`static Color`	`LOW_OUTRO_COLOR`	The color of an outro phrase in a track with a low mood.
`static Color`	`LOW_VERSE_1_COLOR`	The color of a verse 1 phrase in a track with a low mood.
`static Color`	`LOW_VERSE_2_COLOR`	The color of a verse 2 phrase in a track with a low mood.
`static Color`	`MID_BRIDGE_COLOR`	The color of a bridge phrase in a track with a mid mood.
`static Color`	`MID_CHORUS_COLOR`	The color of a chorus phrase in a track with a mid mood.
`static Color`	`MID_INTRO_COLOR`	The color of an intro phrase in a track with a mid mood.
`static Color`	`MID_OUTRO_COLOR`	The color of an outro phrase in a track with a mid mood.
`static Color`	`MID_VERSE_1_COLOR`	The color of a verse 1 phrase in a track with a mid mood.
`static Color`	`MID_VERSE_2_COLOR`	The color of a verse 2 phrase in a track with a mid mood.
`static Color`	`MID_VERSE_3_COLOR`	The color of a verse 3 phrase in a track with a mid mood.
`static Color`	`MID_VERSE_4_COLOR`	The color of a verse 4 phrase in a track with a mid mood.
`static Color`	`MID_VERSE_5_COLOR`	The color of a verse 5 phrase in a track with a mid mood.
`static Color`	`MID_VERSE_6_COLOR`	The color of a verse 6 phrase in a track with a mid mood.
`static long`	`NEUTRAL_PITCH`	The value sent in beat and status packets to represent playback at normal speed.
`static Map<Integer,Map<Byte,Util.PacketType>>`	`PACKET_TYPE_MAP`	Allows a known packet type to be looked up given the port number it was received on and the packet type byte.
`static int`	`PACKET_TYPE_OFFSET`	The offset into protocol packets which identify the content of the packet.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static long`	`addressToLong(InetAddress address)`	Converts the bytes that make up an internet address into the corresponding integer value to make it easier to perform bit-masking operations on them.
`static Object`	`allocateNamedLock(String name)`	Obtain an object that can be synchronized against to provide exclusive access to a named resource, given its unique name.
`static Color`	`buildColor(Color hueColor, Color alphaColor)`	Helper method that combines the hue value of one color with the transparency of another.
`static DatagramPacket`	`buildPacket(Util.PacketType type, ByteBuffer deviceName, ByteBuffer payload)`	Build a standard-format UDP packet for sending to port 50001 or 50002 in the protocol.
`static long`	`bytesToNumber(byte[] buffer, int start, int length)`	Reconstructs a number that is represented by more than one byte in a network packet in big-endian order.
`static long`	`bytesToNumberLittleEndian(byte[] buffer, int start, int length)`	Reconstructs a number that is represented by more than one byte in a network packet in little-endian order, for the very few protocol values that are sent in this quirky way.
`static void`	`freeNamedLock(String name)`	Indicate that an object obtained from `allocateNamedLock(String)` is no longer needed by the caller, so it is eligible for garbage collection if no other threads have it allocated.
`static ByteBuffer`	`getMagicHeader()`	Get the sequence of nine bytes which begins all UDP packets sent in the protocol as a `ByteBuffer`.
`static long`	`halfFrameToTime(long halfFrame)`	Figure out the track time that corresponds to a half-frame number (75 frames per second, so 150 half-frames).
`static void`	`numberToBytes(int number, byte[] buffer, int start, int length)`	Writes a number to the specified byte array field, breaking it into its component bytes in big-endian order.
`static long`	`percentageToPitch(double percentage)`	Convert a human-oriented pitch percentage (-100% to +100%, where normal, unadjusted playback speed has the value 0%) to the raw numeric value used to represent it in beat and CDJ status packets.
`static Color`	`phraseColor(RekordboxAnlz.SongStructureEntry phrase)`	Get the color that should be used for the bar representing a phrase being painted on a waveform.
`static String`	`phraseLabel(RekordboxAnlz.SongStructureEntry phrase)`	Get the text that should be used for the label representing a phrase being painted on a waveform.
`static Color`	`phraseTextColor(RekordboxAnlz.SongStructureEntry phrase)`	Returns the color that should be used for the text of a phrase label, for legibility on the phrase background.
`static double`	`pitchToMultiplier(long pitch)`	Convert a pitch value reported by a device to the corresponding multiplier (0.0 to 2.0, where normal, unadjusted pitch has the multiplier 1.0).
`static double`	`pitchToPercentage(long pitch)`	Convert a pitch value reported by a device to the corresponding percentage (-100% to +100%, where normal, unadjusted pitch has the value 0%).
`static boolean`	`sameNetwork(int prefixLength, InetAddress address1, InetAddress address2)`	Checks whether two internet addresses are on the same subnet.
`static void`	`setPayloadByte(byte[] payload, int address, byte value)`	Helper function to create the payload for a packet being sent to port 50001 or 50002, while working with the byte addresses shown in the protocol analysis document (adjusts the address to account for the fact that the standard packet header up through the device name has not yet been prepended).
`static int`	`timeToHalfFrame(long milliseconds)`	Convert a track position (time) into the corresponding half-frame value (75 frames per second, so 150 half-frames).
`static int`	`timeToHalfFrameRounded(long milliseconds)`	Convert a track position (time) into the corresponding rounded half-frame value (75 frames per second, so 150 half-frames).
`static int`	`unsign(byte b)`	Converts a signed byte to its unsigned int equivalent in the range 0-255.
`static Util.PacketType`	`validateHeader(DatagramPacket packet, int port)`	Check to see whether a packet starts with the standard header bytes, followed by a known byte identifying it.
`static void`	`writeFully(ByteBuffer buffer, WritableByteChannel channel)`	Writes the entire remaining contents of the buffer to the channel.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - PACKET_TYPE_OFFSET
```
public static final int PACKET_TYPE_OFFSET
```
    The offset into protocol packets which identify the content of the packet.
    
    See Also:
    
    Constant Field Values
  - PACKET_TYPE_MAP
```
public static final Map<Integer,Map<Byte,Util.PacketType>> PACKET_TYPE_MAP
```
    Allows a known packet type to be looked up given the port number it was received on and the packet type byte.
  - NEUTRAL_PITCH
```
public static final long NEUTRAL_PITCH
```
    The value sent in beat and status packets to represent playback at normal speed.
    
    See Also:
    
    Constant Field Values
  - LOW_INTRO_COLOR
```
public static final Color LOW_INTRO_COLOR
```
    The color of an intro phrase in a track with a low mood.
  - LOW_VERSE_1_COLOR
```
public static final Color LOW_VERSE_1_COLOR
```
    The color of a verse 1 phrase in a track with a low mood.
  - LOW_VERSE_2_COLOR
```
public static final Color LOW_VERSE_2_COLOR
```
    The color of a verse 2 phrase in a track with a low mood.
  - LOW_BRIDGE_COLOR
```
public static final Color LOW_BRIDGE_COLOR
```
    The color of a bridge phrase in a track with a low mood.
  - LOW_CHORUS_COLOR
```
public static final Color LOW_CHORUS_COLOR
```
    The color of a chorus phrase in a track with a low mood.
  - LOW_OUTRO_COLOR
```
public static final Color LOW_OUTRO_COLOR
```
    The color of an outro phrase in a track with a low mood.
  - MID_INTRO_COLOR
```
public static final Color MID_INTRO_COLOR
```
    The color of an intro phrase in a track with a mid mood.
  - MID_VERSE_1_COLOR
```
public static final Color MID_VERSE_1_COLOR
```
    The color of a verse 1 phrase in a track with a mid mood.
  - MID_VERSE_2_COLOR
```
public static final Color MID_VERSE_2_COLOR
```
    The color of a verse 2 phrase in a track with a mid mood.
  - MID_VERSE_3_COLOR
```
public static final Color MID_VERSE_3_COLOR
```
    The color of a verse 3 phrase in a track with a mid mood.
  - MID_VERSE_4_COLOR
```
public static final Color MID_VERSE_4_COLOR
```
    The color of a verse 4 phrase in a track with a mid mood.
  - MID_VERSE_5_COLOR
```
public static final Color MID_VERSE_5_COLOR
```
    The color of a verse 5 phrase in a track with a mid mood.
  - MID_VERSE_6_COLOR
```
public static final Color MID_VERSE_6_COLOR
```
    The color of a verse 6 phrase in a track with a mid mood.
  - MID_BRIDGE_COLOR
```
public static final Color MID_BRIDGE_COLOR
```
    The color of a bridge phrase in a track with a mid mood.
  - MID_CHORUS_COLOR
```
public static final Color MID_CHORUS_COLOR
```
    The color of a chorus phrase in a track with a mid mood.
  - MID_OUTRO_COLOR
```
public static final Color MID_OUTRO_COLOR
```
    The color of an outro phrase in a track with a mid mood.
  - HIGH_INTRO_1_COLOR
```
public static final Color HIGH_INTRO_1_COLOR
```
    The color of an intro 1 phrase in a track with a high mood.
  - HIGH_INTRO_2_COLOR
```
public static final Color HIGH_INTRO_2_COLOR
```
    The color of an intro 2 phrase in a track with a high mood.
  - HIGH_UP_1_COLOR
```
public static final Color HIGH_UP_1_COLOR
```
    The color of an up 1 phrase in a track with a high mood.
  - HIGH_UP_2_COLOR
```
public static final Color HIGH_UP_2_COLOR
```
    The color of an up 2 phrase in a track with a high mood.
  - HIGH_UP_3_COLOR
```
public static final Color HIGH_UP_3_COLOR
```
    The color of an up 3 phrase in a track with a high mood.
  - HIGH_DOWN_COLOR
```
public static final Color HIGH_DOWN_COLOR
```
    The color of a down phrase in a track with a high mood.
  - HIGH_CHORUS_1_COLOR
```
public static final Color HIGH_CHORUS_1_COLOR
```
    The color of a chorus 1 phrase in a track with a high mood.
  - HIGH_CHORUS_2_COLOR
```
public static final Color HIGH_CHORUS_2_COLOR
```
    The color of a chorus 2 phrase in a track with a high mood.
  - HIGH_OUTRO_1_COLOR
```
public static final Color HIGH_OUTRO_1_COLOR
```
    The color of an outro 1 phrase in a track with a high mood.
  - HIGH_OUTRO_2_COLOR
```
public static final Color HIGH_OUTRO_2_COLOR
```
    The color of an outro 2 phrase in a track with a high mood.
- Method Detail
  - getMagicHeader
```
public static ByteBuffer getMagicHeader()
```
    Get the sequence of nine bytes which begins all UDP packets sent in the protocol as a ByteBuffer. Each call returns a new instance, so you don't need to worry about messing with buffer positions.
    
    Returns:
    
    a read-only ByteBuffer containing the header with which all protocol packets begin.
  - buildPacket
```
public static DatagramPacket buildPacket(Util.PacketType type,
                                         ByteBuffer deviceName,
                                         ByteBuffer payload)
```
    Build a standard-format UDP packet for sending to port 50001 or 50002 in the protocol.
    
    Parameters:
    
    type - the type of packet to create.
    
    deviceName - the 0x14 (twenty) bytes of the device name to send in the packet.
    
    payload - the remaining bytes which come after the device name.
    
    Returns:
    
    the packet to send.
  - setPayloadByte
```
public static void setPayloadByte(byte[] payload,
                                  int address,
                                  byte value)
```
    Helper function to create the payload for a packet being sent to port 50001 or 50002, while working with the byte addresses shown in the protocol analysis document (adjusts the address to account for the fact that the standard packet header up through the device name has not yet been prepended).
    
    Parameters:
    
    payload - the array in which the packet payload is being built
    
    address - the overall packet address (taking account the header) of the byte to be set
    
    value - the byte value to store at that packet address
  - validateHeader
```
public static Util.PacketType validateHeader(DatagramPacket packet,
                                             int port)
```
    Check to see whether a packet starts with the standard header bytes, followed by a known byte identifying it. If so, return the kind of packet that has been recognized.
    
    Parameters:
    
    packet - a packet that has just been received
    
    port - the port on which the packet has been received
    
    Returns:
    
    the type of packet that was recognized, or null if the packet was not recognized
  - unsign
```
public static int unsign(byte b)
```
    Converts a signed byte to its unsigned int equivalent in the range 0-255.
    
    Parameters:
    
    b - a byte value to be considered an unsigned integer
    
    Returns:
    
    the unsigned version of the byte
  - bytesToNumber
```
public static long bytesToNumber(byte[] buffer,
                                 int start,
                                 int length)
```
    Reconstructs a number that is represented by more than one byte in a network packet in big-endian order.
    
    Parameters:
    
    buffer - the byte array containing the packet data
    
    start - the index of the first byte containing a numeric value
    
    length - the number of bytes making up the value
    
    Returns:
    
    the reconstructed number
  - bytesToNumberLittleEndian
```
public static long bytesToNumberLittleEndian(byte[] buffer,
                                             int start,
                                             int length)
```
    Reconstructs a number that is represented by more than one byte in a network packet in little-endian order, for the very few protocol values that are sent in this quirky way.
    
    Parameters:
    
    buffer - the byte array containing the packet data
    
    start - the index of the first byte containing a numeric value
    
    length - the number of bytes making up the value
    
    Returns:
    
    the reconstructed number
  - numberToBytes
```
public static void numberToBytes(int number,
                                 byte[] buffer,
                                 int start,
                                 int length)
```
    Writes a number to the specified byte array field, breaking it into its component bytes in big-endian order. If the number is too large to fit in the specified number of bytes, only the low-order bytes are written.
    
    Parameters:
    
    number - the number to be written to the array
    
    buffer - the buffer to which the number should be written
    
    start - where the high-order byte should be written
    
    length - how many bytes of the number should be written
  - addressToLong
```
public static long addressToLong(InetAddress address)
```
    Converts the bytes that make up an internet address into the corresponding integer value to make it easier to perform bit-masking operations on them.
    
    Parameters:
    
    address - an address whose integer equivalent is desired
    
    Returns:
    
    the integer corresponding to that address
  - sameNetwork
```
public static boolean sameNetwork(int prefixLength,
                                  InetAddress address1,
                                  InetAddress address2)
```
    Checks whether two internet addresses are on the same subnet.
    
    Parameters:
    
    prefixLength - the number of bits within an address that identify the network
    
    address1 - the first address to be compared
    
    address2 - the second address to be compared
    
    Returns:
    
    true if both addresses share the same network bits
  - pitchToPercentage
```
public static double pitchToPercentage(long pitch)
```
    Convert a pitch value reported by a device to the corresponding percentage (-100% to +100%, where normal, unadjusted pitch has the value 0%).
    
    Parameters:
    
    pitch - the reported device pitch
    
    Returns:
    
    the pitch as a percentage
  - percentageToPitch
```
public static long percentageToPitch(double percentage)
```
    Convert a human-oriented pitch percentage (-100% to +100%, where normal, unadjusted playback speed has the value 0%) to the raw numeric value used to represent it in beat and CDJ status packets.
    
    Parameters:
    
    percentage - the pitch as a percentage
    
    Returns:
    
    the value that would represent that pitch in a beat or CDJ status packet
  - pitchToMultiplier
```
public static double pitchToMultiplier(long pitch)
```
    Convert a pitch value reported by a device to the corresponding multiplier (0.0 to 2.0, where normal, unadjusted pitch has the multiplier 1.0).
    
    Parameters:
    
    pitch - the reported device pitch
    
    Returns:
    
    the implied pitch multiplier
  - writeFully
```
public static void writeFully(ByteBuffer buffer,
                              WritableByteChannel channel)
                       throws IOException
```
    Writes the entire remaining contents of the buffer to the channel. May complete in one operation, but the documentation is vague, so this keeps going until we are sure.
    
    Parameters:
    
    buffer - the data to be written
    
    channel - the channel to which we want to write data
    
    Throws:
    
    IOException - if there is a problem writing to the channel
  - halfFrameToTime
```
public static long halfFrameToTime(long halfFrame)
```
    Figure out the track time that corresponds to a half-frame number (75 frames per second, so 150 half-frames).
    
    Parameters:
    
    halfFrame - the half-frame that we are interested in knowing the time for
    
    Returns:
    
    the number of milliseconds into a track that the specified half-frame begins
  - timeToHalfFrame
```
public static int timeToHalfFrame(long milliseconds)
```
    Convert a track position (time) into the corresponding half-frame value (75 frames per second, so 150 half-frames).
    
    Parameters:
    
    milliseconds - how long a track has been playing for
    
    Returns:
    
    the half-frame that contains that part of the track
  - timeToHalfFrameRounded
```
public static int timeToHalfFrameRounded(long milliseconds)
```
    Convert a track position (time) into the corresponding rounded half-frame value (75 frames per second, so 150 half-frames).
    
    Parameters:
    
    milliseconds - how long a track has been playing for
    
    Returns:
    
    the nearest half-frame that contains that part of the track
  - allocateNamedLock
```
public static Object allocateNamedLock(String name)
```
    Obtain an object that can be synchronized against to provide exclusive access to a named resource, given its unique name. Used with file canonical path names by CrateDigger to protect against race conditions where one thread creates the file and another thinks it has already been downloaded and tries to parse the partial file.
    Once the exclusive lock is no longer needed, freeNamedLock(String) should be called with the same name so the lock can be garbage collected if no other threads are now using it.
    
    Parameters:
    
    name - uniquely identifies some resource to which exclusive access is needed
    
    Returns:
    
    an object that can be used with a synchronized block to guarantee exclusive access to the resource
  - freeNamedLock
```
public static void freeNamedLock(String name)
```
    Indicate that an object obtained from allocateNamedLock(String) is no longer needed by the caller, so it is eligible for garbage collection if no other threads have it allocated.
    
    Parameters:
    
    name - uniquely identifies some resource to which exclusive access was previously needed
  - buildColor
```
public static Color buildColor(Color hueColor,
                               Color alphaColor)
```
    Helper method that combines the hue value of one color with the transparency of another.
    
    Parameters:
    
    hueColor - the color that specifies the actual hue to be drawn
    
    alphaColor - the color whose transparency will determine the transparency of the result
    
    Returns:
    
    a color with hue components from hueColor and alpha from alphaColor
  - phraseColor
```
public static Color phraseColor(RekordboxAnlz.SongStructureEntry phrase)
```
    Get the color that should be used for the bar representing a phrase being painted on a waveform.
    
    Parameters:
    
    phrase - the song structure entry representing a phrase being painted
    
    Returns:
    
    the color with which to paint the box that identifies the phrase
  - phraseTextColor
```
public static Color phraseTextColor(RekordboxAnlz.SongStructureEntry phrase)
```
    Returns the color that should be used for the text of a phrase label, for legibility on the phrase background.
    
    Parameters:
    
    phrase - the song structure entry representing a phrase being painted
    
    Returns:
    
    the color that should be used for painting the label
  - phraseLabel
```
public static String phraseLabel(RekordboxAnlz.SongStructureEntry phrase)
```
    Get the text that should be used for the label representing a phrase being painted on a waveform.
    
    Parameters:
    
    phrase - the song structure entry representing a phrase being painted
    
    Returns:
    
    the color with which to paint the box that identifies the phrase

Class Util

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PACKET_TYPE_OFFSET

PACKET_TYPE_MAP

NEUTRAL_PITCH

LOW_INTRO_COLOR

LOW_VERSE_1_COLOR

LOW_VERSE_2_COLOR

LOW_BRIDGE_COLOR

LOW_CHORUS_COLOR

LOW_OUTRO_COLOR

MID_INTRO_COLOR

MID_VERSE_1_COLOR

MID_VERSE_2_COLOR

MID_VERSE_3_COLOR

MID_VERSE_4_COLOR

MID_VERSE_5_COLOR

MID_VERSE_6_COLOR

MID_BRIDGE_COLOR

MID_CHORUS_COLOR

MID_OUTRO_COLOR

HIGH_INTRO_1_COLOR

HIGH_INTRO_2_COLOR

HIGH_UP_1_COLOR

HIGH_UP_2_COLOR

HIGH_UP_3_COLOR

HIGH_DOWN_COLOR

HIGH_CHORUS_1_COLOR

HIGH_CHORUS_2_COLOR

HIGH_OUTRO_1_COLOR

HIGH_OUTRO_2_COLOR

Method Detail

getMagicHeader

buildPacket

setPayloadByte

validateHeader

unsign

bytesToNumber

bytesToNumberLittleEndian

numberToBytes

addressToLong

sameNetwork

pitchToPercentage

percentageToPitch

pitchToMultiplier

writeFully

halfFrameToTime

timeToHalfFrame

timeToHalfFrameRounded

allocateNamedLock

freeNamedLock

buildColor

phraseColor

phraseTextColor

phraseLabel