tv.amwa.maj.iface
Interface EssenceData

All Superinterfaces:

InterchangeObject

All Known Implementing Classes:

EssenceData

public interface EssenceData
extends InterchangeObject

Specifies 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.

All methods of this interface use bytes to measure the size of buffers. Access to sample-sized sections can only be provided with reference to the associated codec, which is provided by an implementation of EssenceAccess or EssenceMultiAccess.

Author:

Richard Cartwright

See Also:

makeEssenceData(), EssenceAccess, EssenceMultiAccess, MasterMob, ContentStorage.enumEssenceData()

Method Summary

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.
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	numberOfSamplesRead() Returns the number of bytes returned by the last call to 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	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 interface tv.amwa.maj.iface.InterchangeObject

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

Method Detail

write

@UInt32
int write(@DataBuffer
                 byte[] buffer)

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.

Parameters:

buffer - Buffer containing the data to be written.

Returns:

Buffer containing the data.

read

@DataBuffer
byte[] read(@UInt32
                       int bytes)

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

Parameters:

bytes - Number of bytes to read from the data stream

Returns:

Buffer containing the requested data.

setPosition

void setPosition(@PositionType
                 long offset)

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

Parameters:

offset - Offset from the beginning of the essence.

getPosition

@PositionType
long getPosition()

Get the absolute position within the stream of essence data.

Returns:

Absolute position within the essence data.

getSize

@LengthType
long getSize()

Returns the total size of the stream of essence data.

Returns:

Total size of the essence data.

writeSampleIndex

@UInt32
int writeSampleIndex(@DataBuffer
                            byte[] buffer)
                     throws PropertyNotPresentException

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 setSampleIndexSize(long) first with sufficient size to write the required buffer.

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:

getSampleIndexPosition()

readSampleIndex

@DataBuffer
byte[] readSampleIndex(@UInt32
                                  int size)
                       throws PropertyNotPresentException

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 numberOfSamplesRead() directly after calling this method to find out how many samples were actually returned in the buffer.

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.

numberOfSamplesRead

@UInt32
int numberOfSamplesRead()
                        throws PropertyNotPresentException

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

Returns:

Number of samples returned by the last call to 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.

setSampleIndexPosition

void setSampleIndexPosition(@PositionType
                            long offset)
                            throws PropertyNotPresentException

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.

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.

getSampleIndexPosition

@PositionType
long getSampleIndexPosition()
                            throws PropertyNotPresentException

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.

Returns:

Current sample index position.

Throws:

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

getSampleIndexSize

@LengthType
long getSampleIndexSize()
                        throws PropertyNotPresentException

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.

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

void setSampleIndexSize(@LengthType
                        long sampleIndexSize)
                        throws IllegalArgumentException

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.

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.

setFileMob

void setFileMob(SourceMob mob)
                throws NullPointerException

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.

Parameters:

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

Throws:

NullPointerException - The given file source mob is null.

getFileMob

SourceMob getFileMob()

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.

Returns:

Reference to a file mob.

getFileMobID

MobID getFileMobID()

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.

Returns:

The file mob identifier associated with the essence.