com.tffenterprises.music.tag.id3v2
Class Flags

java.lang.Object
  extended by com.tffenterprises.music.tag.id3v2.Flags
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable
Direct Known Subclasses:
Flags_2_0, Flags_3_0

public abstract class Flags
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

Flags is a class that provides ID3v2 with an interpretation of the ID3v2 header flags. It is also the base class for all other versions of the ID3v2 flags. Flags features a factory class method that will return an object of the appropriate subclass for the version of ID3v2 being read.

A Flags subclass must override the processFlags() and postProcessFlags() methods, and provide a default constructor that is accessible to the factory static method Flags.getNewInstance(short version, byte flags).

Version:
1.0d1 $Date: 2003/03/16 18:52:29 $
Author:
Guillaume Lessard
See Also:
Serialized Form

Nested Class Summary
 class Flags.InputProcessingStream
           
 
Field Summary
private  boolean changed
          Whether this Flags object has been changed.
static java.lang.String DEFAULT
          A mnemotechnic/easy parameter to pass the ResourceBundle and obtain the Flags subclass implementing the newest spec.
static byte EXPERIMENTAL_FLAG
          Flag bit for experimental status.
private  byte flags
          A byte containing the ID3v2 flags field; 8 bits stored in a byte.
private static java.util.ResourceBundle FLAGS_CLASS_INFO
          A resource bundle listing the subclass by version
private static java.util.Hashtable FLAGS_CLASSES
          The Hashtable which contains all the initialized class objects of our subclasses, keyed by version.
static byte UNSYNCHRONIZATION_FLAG
          Flag bit for unsynchronization.
private  short version
          A short containing the represented ID3v2 specification version
 
Constructor Summary
protected Flags()
          Default constructor.
protected Flags(byte flags)
          Constructs a Flags object with zeroed flags.
 
Method Summary
 boolean check(byte flagMask)
          Check whether a combination of bits is set in the flags byte.
abstract  void checkVersion()
          Asserts that this Flags object's version is compatible with the code.
 java.lang.Object clone()
          Returns a clone of this Flags object.
 boolean equals(java.lang.Object other)
          Compares this Flags object with another one.
 java.util.zip.Checksum getChecksum()
          Returns a Checksum of all this object's data.
 byte getFlags()
          Return the current state of the flags.
private static java.lang.Class GetFlagsClass(short version)
          Obtain the Class object for the subclass of Flags corresponding to the given specification version.
private static java.lang.Class GetFlagsClass(java.lang.String versionString)
          Obtain the Class object for the subclass of Flags corresponding to the given specification version.
static Flags getNewInstance()
          Create a new Flags object; use the subclass implementing the latest version of the specification supported by this library.
static Flags getNewInstance(short version)
          Create a new Flags object of a subclass appropriate for the version parameter.
static Flags getNewInstance(short version, byte flagByte)
          Create a new Flags object of a subclass appropriate for the version parameter.
 short getVersion()
          Returns the ID3v2 specification version given to this Flags object
 int hashCode()
          Returns a hash code for this Flags object.
 boolean isChanged()
          Returns true if this Flags object has been changed.
 boolean isMarkedExperimental()
          Return true if the flags indicate experimental status.
 java.io.InputStream processInput(java.io.InputStream is)
          Process the InputStream in which the ID3v2 information is embedded.
 java.io.OutputStream processOutput(java.io.OutputStream out)
          Process the OutputStream in which the ID3v2 tag is to be embedded.
protected  java.io.OutputStream processUnsynchronization(java.io.OutputStream out)
          This sets up the unsynchronization process for ID3v2 tags (versions prior to 4.0).
 void set(byte flagMask)
          Set the bits corresponding to a mask of bits.
 void setChanged(boolean changed)
          Sets or clears the "changed" bit.
 void setFlags(byte newFlags)
          Set the flags as indicated by the newFlags parameter.
 java.lang.String toString()
          Returns a String representation of this ID3v2 Flags object.
 void unset(byte flagMask)
          Unset the bits corresponding to a mask of bits.
 void updateChecksum(java.util.zip.Checksum checksum)
          Updates a Checskum with all this object's data.
 boolean usesUnsynchronization()
          Return true if this tag used unsynchronization at the time it was read from a stream.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

UNSYNCHRONIZATION_FLAG

public static final byte UNSYNCHRONIZATION_FLAG
Flag bit for unsynchronization.

See Also:
Constant Field Values

EXPERIMENTAL_FLAG

public static final byte EXPERIMENTAL_FLAG
Flag bit for experimental status.

See Also:
Constant Field Values

DEFAULT

public static final java.lang.String DEFAULT
A mnemotechnic/easy parameter to pass the ResourceBundle and obtain the Flags subclass implementing the newest spec.

See Also:
Constant Field Values

FLAGS_CLASS_INFO

private static java.util.ResourceBundle FLAGS_CLASS_INFO
A resource bundle listing the subclass by version


FLAGS_CLASSES

private static final java.util.Hashtable FLAGS_CLASSES
The Hashtable which contains all the initialized class objects of our subclasses, keyed by version. Subclasses get added to this Hashtable as they become needed.


version

private short version
A short containing the represented ID3v2 specification version


flags

private byte flags
A byte containing the ID3v2 flags field; 8 bits stored in a byte.


changed

private transient boolean changed
Whether this Flags object has been changed.

Constructor Detail

Flags

protected Flags()
Default constructor. Constructs a Flags object with zeroed flags. This should not be called by normal users of Flags objects. Use the factory method getNewInstance() instead.


Flags

protected Flags(byte flags)
Constructs a Flags object with zeroed flags. This should not be called by normal users of Flags objects. Use the factory method getNewInstance() instead.

Parameters:
flags - a byte set to the desired flag values.
Method Detail

getNewInstance

public static Flags getNewInstance()
Create a new Flags object; use the subclass implementing the latest version of the specification supported by this library.

Returns:
a Flags instance implementing the default supported ID3v2 specification.

getNewInstance

public static Flags getNewInstance(short version)
                            throws TagDataFormatException
Create a new Flags object of a subclass appropriate for the version parameter. This getNewInstance() method's version parameter has the ID3v2 major version number in its high byte, and the minor version number in its low byte.

Parameters:
version - the version of ID3v2 for which to get a Flags object
Returns:
a Flags instance implementing the specified version of ID3v2.
Throws:
TagDataFormatException - if the specified version is unsupported.

getNewInstance

public static Flags getNewInstance(short version,
                                   byte flagByte)
                            throws TagDataFormatException
Create a new Flags object of a subclass appropriate for the version parameter. The Flags object will be instantiated with the parameter flagByte. This getNewInstance() method's version parameter has the ID3v2 major version number in its high byte, and the minor version number in its low byte.

Parameters:
version - the version of ID3v2 for which to get a Flags object
flagByte - the value of the header flags
Returns:
a Flags instance implementing the specified version of ID3v2.
Throws:
TagDataFormatException - if the specified version is unsupported.

GetFlagsClass

private static java.lang.Class GetFlagsClass(short version)
                                      throws TagDataFormatException
Obtain the Class object for the subclass of Flags corresponding to the given specification version.

Parameters:
version - the desired specification version.
Returns:
the Class object for the appropriate Flags subclass.
Throws:
TagDataFormatException - if the specified version is unsupported.

GetFlagsClass

private static java.lang.Class GetFlagsClass(java.lang.String versionString)
Obtain the Class object for the subclass of Flags corresponding to the given specification version.

Parameters:
versionString - the desired specification version.

updateChecksum

public void updateChecksum(java.util.zip.Checksum checksum)
Updates a Checskum with all this object's data. This is used by the getChecksum() method, and can be used by other objects which may have this object as a data member.

Parameters:
checksum - a Checksum to be updated.

getChecksum

public final java.util.zip.Checksum getChecksum()
Returns a Checksum of all this object's data. This is used by the hashcode() method.

Returns:
a Checksum of all this object's data.

hashCode

public final int hashCode()
Returns a hash code for this Flags object. Subclasses must override the getChecksum() method in order to return a good hash code.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code for this Flags object.

clone

public java.lang.Object clone()
Returns a clone of this Flags object. The object returned by this implementation already has the proper type. In order for this method to work, subclasses of BaseFrame must have a default constructor accessible to this class.

Overrides:
clone in class java.lang.Object
Returns:
a clone of this Flags object.

equals

public boolean equals(java.lang.Object other)
Compares this Flags object with another one.

Overrides:
equals in class java.lang.Object
Parameters:
other - The other object.
Returns:
true if the two objects are equivalent, false otherwise.

toString

public java.lang.String toString()
Returns a String representation of this ID3v2 Flags object.

Overrides:
toString in class java.lang.Object
Returns:
a String representation of this ID3v2 Flags object.

getVersion

public short getVersion()
Returns the ID3v2 specification version given to this Flags object

Returns:
the ID3v2 specification version given to this Flags object

checkVersion

public abstract void checkVersion()
                           throws TagDataFormatException
Asserts that this Flags object's version is compatible with the code.

Throws:
TagDataFormatException - if the version is not compatible.

isChanged

public boolean isChanged()
Returns true if this Flags object has been changed.

Returns:
true if this Flags object has been changed, false otherwise.

setChanged

public void setChanged(boolean changed)
Sets or clears the "changed" bit.

Parameters:
changed - true to set the changed bit, false to clear it.

getFlags

public byte getFlags()
Return the current state of the flags.

Returns:
the current state of the flags.

setFlags

public void setFlags(byte newFlags)
Set the flags as indicated by the newFlags parameter.

Parameters:
newFlags - the combination of bit values to assign to the flags.

check

public boolean check(byte flagMask)
Check whether a combination of bits is set in the flags byte.

Parameters:
flagMask - the combination of bits to check
Returns:
whether the bits from the mask are set in the flags byte.

set

public void set(byte flagMask)
Set the bits corresponding to a mask of bits.

Parameters:
flagMask - the combination of bits to set

unset

public void unset(byte flagMask)
Unset the bits corresponding to a mask of bits.

Parameters:
flagMask - the combination of bits to unset

isMarkedExperimental

public boolean isMarkedExperimental()
Return true if the flags indicate experimental status.

Returns:
whether the flags indicate experimental status.

usesUnsynchronization

public boolean usesUnsynchronization()
Return true if this tag used unsynchronization at the time it was read from a stream.

Returns:
whether the flags indicate the use of unsynchronization.

processInput

public java.io.InputStream processInput(java.io.InputStream is)
                                 throws java.io.IOException,
                                        TagDataFormatException
Process the InputStream in which the ID3v2 information is embedded. This method is called by ID3v2 when parsing the stream.

A Flags subclass should override this method act in accordance with the tag flags to correctly parse the stream. Applying a FilterInputStream subclass to the InputStream passed as is or calculating a value are typical actions.

Parameters:
is - the InputStream in which the ID3v2 information is embedded.
Returns:
the InputStream in which the ID3v2 information is embedded, filtered or not
Throws:
java.io.IOException - if an I/O error occurs.
TagDataFormatException - if the stream contains a malformed tag, or some erroneous parameters.

processOutput

public java.io.OutputStream processOutput(java.io.OutputStream out)
Process the OutputStream in which the ID3v2 tag is to be embedded. This method is called by ID3v2 when writing the tag to a file or stream.

A Flags subclass should override this method and apply whatever calculations and FilterOutputStream subclasses are necessary to output a correct stream of the tag. See the postProcessUnsynchronization for an example of a FilterOutputStream that can be applied through this method.

Parameters:
out - the OutputStream to which the ID3v2 tag will be written
Returns:
the OutputStream to which the ID3v2 tag will be written

processUnsynchronization

protected java.io.OutputStream processUnsynchronization(java.io.OutputStream out)
This sets up the unsynchronization process for ID3v2 tags (versions prior to 4.0). This is not called within Flags, but since both Flags_2_0 and Flags_3_0 need it, duplicated code is avoided here. The returned OutputStream will handle the unsynchronization process and set the Unsynchronization flag if any unsynchronization has been necessary.

Parameters:
out - an output stream to which the tag is being written.
Returns:
at output stream to which the tag is to be written.