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.
    • 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 Color phraseColor​(org.deepsymmetry.cratedigger.pdb.RekordboxAnlz.SongStructureEntry phrase)
      Get the color that should be used for the bar representing a phrase being painted on a waveform.
      static String phraseLabel​(org.deepsymmetry.cratedigger.pdb.RekordboxAnlz.SongStructureEntry phrase)
      Get the text that should be used for the label representing a phrase being painted on a waveform.
      static Color phraseTextColor​(org.deepsymmetry.cratedigger.pdb.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.
    • 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.
      • 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
      • 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​(org.deepsymmetry.cratedigger.pdb.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​(org.deepsymmetry.cratedigger.pdb.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​(org.deepsymmetry.cratedigger.pdb.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