com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBodyPopularimeter

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility
    - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody
      - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyPopularimeter

-     public class ID3v23FrameBodyPopularimeter
      extends ID3v23FrameBody

  A popularimeter frame body is associated with an ID3v2.3 `POPM` `frame` which is used to specify how much you like an .mp3 song. The popularimeter frame body contains the following fields:

  Popularimeter Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | userEmail | user's e-mail address
  2. | rating | rating of the .mp3 song from 1 - 255, where 1 is the worst and 255 is best. 0 is unknown, ie, not yet rated.
  3. | counter | number of times the .mp3 song has been played. this field is optional.

  There may be more than one popularimeter frame in each tag, but only one with the same e-mail address.

  See Also:
    `ID3v23Frame`, `ID3v23FrameBodyPlayCounter`, ID3 tag version 2.3.0 standard, wikipedia history of ID3 tags

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `BEST` highest rating possible
    `static int` | `MIDDLE` average rating
    `static int` | `UNKNOWN` the .mp3 song does not have a rating yet
    `static int` | `WORST` lowest rating possible

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23FrameBodyPopularimeter()` The default constructor is called when creating a new frame.
    `ID3v23FrameBodyPopularimeter(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.
    `ID3v23FrameBodyPopularimeter(java.lang.String userEmail, int rating, int counter)` This constructor is called when creating a new frame.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getCounter()` gets the number of times the song has been played.
    `int` | `getRating()` gets the song's rating.
    `java.lang.String` | `getUserEmail()` gets the user's e-mail address.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setCounter(int counter)` sets the number of times the song has been played.
    `void` | `setRating(int rating)` sets the rating of the song.
    `void` | `setUserEmail(java.lang.String userEmail)` sets the user's e-mail address.
    `java.lang.String` | `toString()` gets a string representation of the popularimeter frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `getFrameType, getNextNullTerminator, getSize, isDirty, save, save`

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

    - ### Methods inherited from class com.beaglebuddy.util.Utility

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, getUTF16String, getUTF8String, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes`

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### UNKNOWN

          public static final int UNKNOWN

      the .mp3 song does not have a rating yet
      See Also:
        Constant Field Values

    - #### WORST

          public static final int WORST

      lowest rating possible
      See Also:
        Constant Field Values

    - #### MIDDLE

          public static final int MIDDLE

      average rating
      See Also:
        Constant Field Values

    - #### BEST

          public static final int BEST

      highest rating possible
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ID3v23FrameBodyPopularimeter

          public ID3v23FrameBodyPopularimeter()

      The default constructor is called when creating a new frame. The default values used are:
      - empty user e-maill address
      - not yet rated
      - 0 times played

    - #### ID3v23FrameBodyPopularimeter

          public ID3v23FrameBodyPopularimeter(java.lang.String userEmail,
                                      int rating,
                                      int counter)

      This constructor is called when creating a new frame.
      Parameters:
        `userEmail` - user's e-mail.
        `rating` - [1-255] where 1 = worst and 255 = best. 0 is unknown, ie, not yet rated.
        `counter` - number of times the song has been played (optional).

    - #### ID3v23FrameBodyPopularimeter

          public ID3v23FrameBodyPopularimeter(java.io.InputStream inputStream,
                                      int frameBodySize)
                                       throws java.io.IOException

      This constructor is called when reading in an existing frame from an .mp3 file. This is then followed by a call to the parse() method.
      Parameters:
        `inputStream` - input stream pointing to a popularimeter frame body in the .mp3 file.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading the frame body.

  - ### Method Detail

    - #### parse

          public void parse()
                     throws java.lang.IllegalArgumentException

      parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
      Overrides:
        `parse` in class `ID3v23FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### getUserEmail

          public java.lang.String getUserEmail()

      gets the user's e-mail address.
      Returns:
        the user's e-mail.
      See Also:
        `setUserEmail(String)`

    - #### setUserEmail

          public void setUserEmail(java.lang.String userEmail)

      sets the user's e-mail address.
      Parameters:
        `userEmail` - the user's e-mail address.
      See Also:
        `getUserEmail()`

    - #### getRating

          public int getRating()

      gets the song's rating.
      Returns:
        the rating of the song.
      See Also:
        `setRating(int)`

    - #### setRating

          public void setRating(int rating)

      sets the rating of the song.
      Parameters:
        `rating` - [1-255] where 1 = worst and 255 = best. 0 is unknown, ie, not yet rated.
      See Also:
        `getRating()`

    - #### getCounter

          public int getCounter()

      gets the number of times the song has been played.
      Returns:
        the number of times the song has been played.
      See Also:
        `setCounter(int)`

    - #### setCounter

          public void setCounter(int counter)

      sets the number of times the song has been played.
      Parameters:
        `counter` - the number of times the song has been played.
      See Also:
        `getCounter()`

    - #### setBuffer

          public void setBuffer()

      If the frame body's values have been modified, then resize the raw binary buffer and store the new values there. When finished, the dirty flag is reset to indicate that the buffer is up to date, and the frame is now ready to be saved to the .mp3 file.
      Overrides:
        `setBuffer` in class `ID3v23FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the popularimeter frame body showing all of the frame's fields and their values.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the frame body.