tv.amwa.maj.entity
Class EssenceData

java.lang.Object
  tv.amwa.maj.entity.InterchangeObject
      tv.amwa.maj.entity.EssenceData

All Implemented Interfaces:

Serializable, Cloneable, MAJCommon, EssenceData, InterchangeObject, XMLSerializable

@AAFClass(uuid1=218169601,
          uuid2=257,
          uuid3=8960,
          uuid4={6,14,43,52,2,6,1,1},
          definedName="EssenceData",
          description="The EssenceData class contains essence.")
public class EssenceData
extends InterchangeObject
implements EssenceData, Serializable, Cloneable, MAJCommon

Implements an essence container. The methods can be used to modify essence data objects that contain the actual essence data (excluding WAVE) when it is contained within an AAF file. Normally, the client application would access the essence through the essence access interface, which handles the work of finding and (de)compressing the data. However, in rare cases direct access to the data is required, the read and write methods of this interface are provided.

This implementation tries to copy essence into memory and this is a known and significant limitation of the current version of the MAJ API. It is hoped that a mechanism for pointing to positions in external files will be introduced in a future release.

THE COMMENTS FOR THIS CLASS ARE INCOMPLETE.

Author:

Richard Cartwright

See Also:

Serialized Form

Nested Class Summary

static class

EssenceData.XMLHandler

Nested classes/interfaces inherited from class tv.amwa.maj.entity.InterchangeObject

InterchangeObject.InterchangeObjectXMLHandler

Field Summary

static String

ESSENCEDATA_TAG

Constructor Summary

EssenceData(SourceMob sourceMob, byte[] data)
Creates and initializes a new essence data object that contains essence.

Method Summary

void	appendXMLChildren(Node parent) Append child elements to the given parent node to serialize the value of an object to an XML fragment.
EssenceData	clone() Cloned essence data contains the same file mob and data, which are not themselves cloned.
boolean	equals(Object o) Two essence data objects are equal if they have the same mob id.
byte[]	getData()
SourceMob	getFileMob() Returns a reference to the file source mob that describes this essence data.
MobID	getFileMobID() Returns the mob id of the file source mob that describes this essence data.
long	getPosition() Get the absolute position within the stream of essence data.
byte[]	getSampleIndex()
long	getSampleIndexPosition() Returns the current sample index position, measured in bytes rather than samples.
long	getSampleIndexSize() Returns the total size of the sample index data, measured in bytes rather than the total number of samples.
long	getSize() Returns the total size of the stream of essence data.
int	hashCode() Returns a hash code value for this interchange object.
int	numberOfSamplesRead() Returns the number of bytes returned by the last call to EssenceData.readSampleIndex(int), which may be different from the number of bytes requested, for example near the end of the stream.
byte[]	read(int bytes) Read the given number of bytes from the pre-interleaved data of an essence stream at the current position.
byte[]	readSampleIndex(int size) Reads raw data from a sample index stream at the current sample index position.
void	setFileMob(SourceMob mob) Sets a reference to the file source mob that describes this essence data.
void	setPosition(long offset) Seek to an absolute position within the stream of essence data.
void	setPropertiesFromInterface(EssenceData castFrom)
void	setSampleIndexPosition(long offset) Seek to an absolute position within the sample index data, measured in bytes rather than samples.
void	setSampleIndexSize(long sampleIndexSize) Sets the size of the sample index, making the property present if it is currently omitted.
int	write(byte[] buffer) Write a pre-interleaved data item into the essence stream, starting at the current position.
int	writeSampleIndex(byte[] buffer) Writes the given sample index data to the sample index data at the current sample index stream position.

Methods inherited from class tv.amwa.maj.entity.InterchangeObject

castFromInterface, countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, registerImplementation, setPropertiesFromInterface, setPropertyValue, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface tv.amwa.maj.iface.InterchangeObject

countProperties, createOptionalPropertyValue, disableGenerationTracking, enableGenerationTracking, getDefinition, getGeneration, getGenerationAUID, getProperties, getPropertyValue, isGenerationTracked, isPropertyPresent, omitOpionalProperty, setPropertyValue

Methods inherited from interface tv.amwa.maj.entity.MAJCommon

toString

Field Detail

ESSENCEDATA_TAG

public static final String ESSENCEDATA_TAG

See Also:

Constant Field Values

Constructor Detail

EssenceData

public EssenceData(SourceMob sourceMob,
                   @DataBuffer
                   byte[] data)
            throws NullPointerException

Creates and initializes a new essence data object that contains essence. This method requires a weak reference to the corresponding metadata source mob of the essence data itself.

Parameters:

sourceMob - Identifies the source mob that describes the essence.

data - The essence data.

Throws:

NullPointerException - One or both of the arguments is/are null.

Method Detail

setPropertiesFromInterface

public final void setPropertiesFromInterface(EssenceData castFrom)

See Also:

InterchangeObject.setPropertiesFromInterface(tv.amwa.maj.iface.InterchangeObject)

getFileMobID

@AAFProperty(uuid1=100729094,
             uuid2=256,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="MobID",
             typeName="MobIDType",
             optional=false,
             uniqueIdentifier=true,
             pid=9985)
public MobID getFileMobID()

Description copied from interface: EssenceData

Returns the mob id of the file source mob that describes this essence data. The file source mob must exist in the same file as the essence data.

This is a required persistent property of essence data.

Specified by:

getFileMobID in interface EssenceData

Returns:

The file mob identifier associated with the essence.

getFileMob

public SourceMob getFileMob()

Description copied from interface: EssenceData

Returns a reference to the file source mob that describes this essence data. This reference will be established when the essence data is retrieved from a persistent store.

Specified by:

getFileMob in interface EssenceData

Returns:

Reference to a file mob.

setFileMob

public void setFileMob(SourceMob mob)
                throws NullPointerException

Description copied from interface: EssenceData

Sets a reference to the file source mob that describes this essence data. This reference will provide the persistent file mob id property of this essence data.

Specified by:

setFileMob in interface EssenceData

Parameters:

mob - Reference to a file source mob that describes this essence data.

Throws:

NullPointerException - The given file source mob is null.

getPosition

public long getPosition()

Description copied from interface: EssenceData

Get the absolute position within the stream of essence data.

Specified by:

getPosition in interface EssenceData

Returns:

Absolute position within the essence data.

getSampleIndexPosition

public long getSampleIndexPosition()
                            throws PropertyNotPresentException

Description copied from interface: EssenceData

Returns the current sample index position, measured in bytes rather than samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The sample index property is optional.

Specified by:

getSampleIndexPosition in interface EssenceData

Returns:

Current sample index position.

Throws:

PropertyNotPresentException - The optional sample index data is not present for this essence data.

getSampleIndexSize

public long getSampleIndexSize()
                        throws PropertyNotPresentException

Description copied from interface: EssenceData

Returns the total size of the sample index data, measured in bytes rather than the total number of samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The sample index property is optional.

Specified by:

getSampleIndexSize in interface EssenceData

Returns:

Size of the sample index data measured in bytes.

Throws:

PropertyNotPresentException - The optional sample index data is not present for this essence data.

setSampleIndexSize

public void setSampleIndexSize(@LengthType
                               long sampleIndexSize)
                        throws IllegalArgumentException

Description copied from interface: EssenceData

Sets the size of the sample index, making the property present if it is currently omitted. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. Set this value to 0 to omit this optional property.

This method will extend an existing buffer but will not truncate it. To decrease the size of the buffer, copy the data, call this method with 0 and then write the copied bytes back into the buffer.

Specified by:

setSampleIndexSize in interface EssenceData

Parameters:

sampleIndexSize - Size for the sample index data.

Throws:

IllegalArgumentException - The given sample index size is negative or smaller than the sample index already stored.

getSize

public long getSize()

Description copied from interface: EssenceData

Returns the total size of the stream of essence data.

Specified by:

getSize in interface EssenceData

Returns:

Total size of the essence data.

numberOfSamplesRead

public int numberOfSamplesRead()
                        throws PropertyNotPresentException

Description copied from interface: EssenceData

Returns the number of bytes returned by the last call to EssenceData.readSampleIndex(int), which may be different from the number of bytes requested, for example near the end of the stream.

Specified by:

numberOfSamplesRead in interface EssenceData

Returns:

Number of samples returned by the last call to EssenceData.readSampleIndex(int), or 0 if the method has not yet been called.

Throws:

PropertyNotPresentException - The optional sample index property is not present in this essence data.

read

public byte[] read(int bytes)

Description copied from interface: EssenceData

Read the given number of bytes from the pre-interleaved data of an essence stream at the current position.

Specified by:

read in interface EssenceData

Parameters:

bytes - Number of bytes to read from the data stream

Returns:

Buffer containing the requested data.

readSampleIndex

public byte[] readSampleIndex(int size)
                       throws PropertyNotPresentException

Description copied from interface: EssenceData

Reads raw data from a sample index stream at the current sample index position. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec which is why the parameter of this method is measured in bytes rather than number of samples. The sample index property is optional.

Call EssenceData.numberOfSamplesRead() directly after calling this method to find out how many samples were actually returned in the buffer.

Specified by:

readSampleIndex in interface EssenceData

Parameters:

size - Read this many bytes from the sample index stream.

Returns:

The buffer containing the required number of samples.

Throws:

PropertyNotPresentException - The optional sample index property is not present for this essence data.

setPosition

public void setPosition(long offset)

Description copied from interface: EssenceData

Seek to an absolute position within the stream of essence data.

Specified by:

setPosition in interface EssenceData

Parameters:

offset - Offset from the beginning of the essence.

setSampleIndexPosition

public void setSampleIndexPosition(@PositionType
                                   long offset)
                            throws PropertyNotPresentException

Description copied from interface: EssenceData

Seek to an absolute position within the sample index data, measured in bytes rather than samples. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. If the given offset is beyond the end of the stream, the position is set to be the end of the stream.

Specified by:

setSampleIndexPosition in interface EssenceData

Parameters:

offset - Offset from the beginning of the data measured in bytes.

Throws:

PropertyNotPresentException - The optional sample index property is not present for this essence data.

write

public int write(byte[] buffer)

Description copied from interface: EssenceData

Write a pre-interleaved data item into the essence stream, starting at the current position. The number of bytes actually written into the essence data is returned.

Specified by:

write in interface EssenceData

Parameters:

buffer - Buffer containing the data to be written.

Returns:

Buffer containing the data.

writeSampleIndex

public int writeSampleIndex(byte[] buffer)
                     throws PropertyNotPresentException

Description copied from interface: EssenceData

Writes the given sample index data to the sample index data at the current sample index stream position. The sample index stream contains an index to the samples or frames. The format of the index is determined by the associated codec. The number of samples actually written is returned and may be less than those requested at the end of the buffer.

The sample index property is optional. It is not possible to write sample index data if the property is not present. To write data, call EssenceData.setSampleIndexSize(long) first with sufficient size to write the required buffer.

Specified by:

writeSampleIndex in interface EssenceData

Parameters:

buffer - Buffer of sample data to write into the essence data.

Returns:

Number of samples actually written.

Throws:

PropertyNotPresentException - The optional sample index data is not present for this essence data.

See Also:

EssenceData.getSampleIndexPosition()

getData

@AAFProperty(uuid1=67568128,
             uuid2=0,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="Data",
             typeName="Stream",
             optional=false,
             uniqueIdentifier=false,
             pid=9986)
public byte[] getData()

getSampleIndex

@AAFProperty(uuid1=100729090,
             uuid2=256,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="SampleIndex",
             typeName="Stream",
             optional=true,
             uniqueIdentifier=false,
             pid=11009)
public byte[] getSampleIndex()

equals

public boolean equals(Object o)

Two essence data objects are equal if they have the same mob id.

Specified by:

equals in interface MAJCommon

Overrides:

equals in class Object

Parameters:

o - Object to test for equality with.

Returns:

Is the given object equals to this value?

See Also:

Object.equals(java.lang.Object)

hashCode

public int hashCode()

Description copied from interface: MAJCommon

Returns a hash code value for this interchange object.

Specified by:

hashCode in interface MAJCommon

Overrides:

hashCode in class Object

Returns:

Hash code value for this interchange object.

See Also:

Object.hashCode()

clone

public EssenceData clone()

Cloned essence data contains the same file mob and data, which are not themselves cloned.

Specified by:

clone in interface MAJCommon

Overrides:

clone in class Object

Returns:

Independent clone of this value, which is a deep copy.

See Also:

Object.clone()

appendXMLChildren

public void appendXMLChildren(Node parent)

Description copied from interface: XMLSerializable

Append child elements to the given parent node to serialize the value of an object to an XML fragment. Methods of the XMLBuilder class are provided to help with this process.

Specified by:

appendXMLChildren in interface XMLSerializable

Overrides:

appendXMLChildren in class InterchangeObject

Parameters:

parent - XML parent element to append child nodes to.