com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBody

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

- Direct Known Subclasses:
    ID3v23FrameBodyAttachedPicture, ID3v23FrameBodyAudioEncryption, ID3v23FrameBodyComments, ID3v23FrameBodyCommercial, ID3v23FrameBodyEncryptionMethodRegistration, ID3v23FrameBodyEqualization, ID3v23FrameBodyEventTimingCodes, ID3v23FrameBodyGeneralEncapsulatedObject, ID3v23FrameBodyGroupIdentificationRegistration, ID3v23FrameBodyInvolvedPeopleList, ID3v23FrameBodyLinkedInformation, ID3v23FrameBodyMPEGLocationLookupTable, ID3v23FrameBodyMusicCDIdentifier, ID3v23FrameBodyOwnership, ID3v23FrameBodyPlayCounter, ID3v23FrameBodyPopularimeter, ID3v23FrameBodyPositionSynchronization, ID3v23FrameBodyPrivate, ID3v23FrameBodyRecommendedBufferSize, ID3v23FrameBodyRelativeVolumeAdjustment, ID3v23FrameBodyReverb, ID3v23FrameBodySynchronizedLyricsText, ID3v23FrameBodySynchronizedTempoCodes, ID3v23FrameBodyTermsOfUse, ID3v23FrameBodyTextInformation, ID3v23FrameBodyUniqueFileIdentifier, ID3v23FrameBodyUnsynchronizedLyrics, ID3v23FrameBodyURLLink, ID3v23FrameBodyUserDefinedTextInformation, ID3v23FrameBodyUserDefinedURLLink

      public class ID3v23FrameBody
      extends ID3v23FrameBodyUtility

  This is the base class for all ID3v2.3 frame bodies. Although ID3v2.3 defines 74 different types of frames, many groups of frame bodies have the same fields, and thus are implemented by a single class. For example, there are 38 text information frames, and thus the corresponding frame bodies are implemented in one `ID3v23FrameBodyTextInformation` class. Similarly, there are 8 url link frames, but all are implemented using the `ID3v23FrameBodyURLLink` class.

  Each frame body has a raw, binary buffer, which is nothing more than a byte array. This is what is read in from the .mp3 file. This byte array holds all of the values for a given frame body. When a frame body is read in from an .mp3 file (more accurately, from the ID3v2.3 tag in the .mp3 file), this binary buffer is parsed and the values are stored in the frame body's data members. Users are then free to change the values of the frame body's data members. When the user is finished making changes, he must call the `setBuffer()` method in order to write all the frame body's data members back to the binary buffer, before calling `save(OutputStream)`. However, you should not be invoking these methods, as calling `MP3.save()` will handle all of this for you.

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

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected byte[]` | `buffer`
    `protected boolean` | `dirty` indicates whether the raw byte buffer contains the same values as the the frame body's data members.
    `protected FrameType` | `frameType` the frame type which is used by derived classes when creating error messages.

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

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23FrameBody(FrameType frameType)` This constructor is called when creating a new frame body.
    `ID3v23FrameBody(java.io.InputStream inputStream, FrameType frameType, int frameBodySize)` constructor.
    `ID3v23FrameBody(java.io.InputStream inputStream, java.lang.String invalidFrameId, int frameBodySize)` constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `FrameType` | `getFrameType()` gets the frame body's ID3v2.3 type.
    `protected int` | `getNextNullTerminator(int startingFrom, Encoding encoding)` finds the next null terminating character according to the character encoding in the raw data stream.
    `int` | `getSize()` gets the size (in bytes) of the frame body.
    `boolean` | `isDirty()` gets whether any value(s) in the frame's body have been modified.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame body's fields.
    `void` | `save(java.io.OutputStream outputStream)` save the frame body to the .mp3 file.
    `void` | `save(java.io.RandomAccessFile file)` save the frame body to the .mp3 file.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw byte buffer and store the new values there.

    - ### 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, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes`

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

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

- - ### Field Detail

    - #### buffer

          protected byte[] buffer

    - #### dirty

          protected boolean dirty

      indicates whether the raw byte buffer contains the same values as the the frame body's data members. ie, whether a user has modified the frame body's values, and if so, whether have been saved back to the raw byte buffer.

    - #### frameType

          protected FrameType frameType

      the frame type which is used by derived classes when creating error messages.

  - ### Constructor Detail

    - #### ID3v23FrameBody

          public ID3v23FrameBody(FrameType frameType)

      This constructor is called when creating a new frame body.
      Parameters:
        `frameType` - the type of ID3v2.3 frame that is to be created.

    - #### ID3v23FrameBody

          public ID3v23FrameBody(java.io.InputStream inputStream,
                         FrameType frameType,
                         int frameBodySize)
                          throws java.io.IOException

      constructor. called when reading in an existing frame body from an .mp3 file.
      Parameters:
        `inputStream` - input stream pointing to a frame body in the .mp3 file.
        `frameType` - the type of ID3v2.3 frame to create.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading in the frame body.

    - #### ID3v23FrameBody

          public ID3v23FrameBody(java.io.InputStream inputStream,
                         java.lang.String invalidFrameId,
                         int frameBodySize)
                          throws java.io.IOException

      constructor. called when reading in an existing invalid frame body from an .mp3 file. this allows invalid frames to be read in and skipped over in an attempt to read in the remaining valid frames.
      Parameters:
        `inputStream` - input stream pointing to a frame body in the .mp3 file.
        `invalidFrameId` - the id of the invalid frame.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading in the frame body.

  - ### Method Detail

    - #### getFrameType

          public FrameType getFrameType()

      gets the frame body's ID3v2.3 type.
      Returns:
        the frame body's ID3v2.3 type.

    - #### getNextNullTerminator

          protected int getNextNullTerminator(int startingFrom,
                                  Encoding encoding)

      finds the next null terminating character according to the character encoding in the raw data stream.
      Parameters:
        `startingFrom` - the index at which to start searching from in the buffer.
        `encoding` - the character set used to encode the string (and hence determine the null terminating character).
      Returns:
        the index of the next null terminator in the data.

    - #### getSize

          public int getSize()

      gets the size (in bytes) of the frame body.
      Returns:
        the size (in bytes) of the frame body.

    - #### isDirty

          public boolean isDirty()

      gets whether any value(s) in the frame's body have been modified.
      Returns:
        whether any value(s) in the frame's body have been modified.

    - #### parse

          public void parse()
                     throws java.lang.IllegalArgumentException

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

    - #### setBuffer

          public void setBuffer()

      If the frame body's values have been modified, then resize the raw byte 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.

      this method should be abstract. However, the ID3v23Frame constructor needs to be able to instanitate instances of a frame body in the case where it encounters an invalid frame. For this reason, this method was made concrete, and simply throws an exception if it is ever called in this base class. However, derived classes implement this method to correctly update the raw byte buffer.

    - #### save

          public void save(java.io.OutputStream outputStream)
                    throws java.lang.IllegalStateException,
                           java.io.IOException

      save the frame body to the .mp3 file.
      Parameters:
        `outputStream` - an output stream pointing to where the next frame body should be written.
      Throws:
        `java.lang.IllegalStateException` - If the any of the frame body's values have been modified, then the setBuffer() method must be called prior to calling save() in order to save the modifications to the frame body's raw byte buffer.
        `java.io.IOException` - if an error occurs while writing the raw byte data in the buffer to the file.

    - #### save

          public void save(java.io.RandomAccessFile file)
                    throws java.lang.IllegalStateException,
                           java.io.IOException

      save the frame body to the .mp3 file.
      Parameters:
        `file` - a random access file pointing to where the next frame body should be written.
      Throws:
        `java.lang.IllegalStateException` - If the any of the frame body's values have been modified, then the setBuffer() method must be called prior to calling save() in order to save the modifications to the frame body's raw byte buffer.
        `java.io.IOException` - if an error occurs while writing the raw byte data in the buffer to the file.