Util (beat-link 0.5.1 API)

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 and 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 and Description
`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 and 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 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 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 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`	`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.
- 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.
  - 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
  - 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
  - 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

Class Util

Nested Class Summary

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PACKET_TYPE_OFFSET

PACKET_TYPE_MAP

Method Detail

getMagicHeader

buildPacket

validateHeader

unsign

bytesToNumber

bytesToNumberLittleEndian

numberToBytes

addressToLong

sameNetwork

pitchToPercentage

pitchToMultiplier

writeFully

halfFrameToTime

timeToHalfFrame

allocateNamedLock

freeNamedLock