Package org.deepsymmetry.beatlink

Class 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 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 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 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.

    • 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

      • 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