tv.amwa.maj.meta
Class TypeDefinitionStream

java.lang.Object
  tv.amwa.maj.meta.MetaDefinition
      tv.amwa.maj.meta.TypeDefinition
          tv.amwa.maj.meta.TypeDefinitionStream

All Implemented Interfaces:

Serializable, DefinitionType, MetaDefinition, TypeDefinition, TypeDefinitionStream, XMLSerializable, MAJCommon

@AAFClass(uuid1=218169601,
          uuid2=524,
          uuid3=0,
          uuid4={6,14,43,52,2,6,1,1},
          definedName="TypeDefinitionStream",
          description="The TypeDefinitionStream class defines a property type that is stored in a stream and has a value that consists of a varying number of the bytes.")
public final class TypeDefinitionStream
extends TypeDefinition
implements TypeDefinitionStream, Serializable, XMLSerializable, MAJCommon

Implements the definition of a property type that is stored in a stream and has a value that consists of a varying number of the bytes.

THE COMMENTS FOR THIS CLASS ARE INCOMPLETE.

Author:

Richard Cartwright

See Also:

Serialized Form

Nested Class Summary

static class	TypeDefinitionStream.StreamValue
static class	TypeDefinitionStream.XMLHandler

Field Summary

static TypeDefinitionStream	DataValue
static TypeDefinitionStream	Stream

Constructor Summary

TypeDefinitionStream(AUID identification, String typeName)
Creates and initializes a new type definition for a streams, which defines a property type that is stored in a stream and has a value that consists of a varying number of the bytes.

Method Summary

void	append(PropertyValue streamProperty, byte[] data) Extend the given stream property value using the data from the given data buffer, an array of bytes.
void	appendElements(PropertyValue streamProperty, TypeDefinition elementType, PropertyValue[] data) Append the elements of the given property value array onto the end of the given stream property value.
void	appendXMLChildren(Node parent) Append child elements to the given parent node to serialize the value of an object to an XML fragment.
void	clearStoredByteOrder(PropertyValue streamProperty) Clear the stored byte order of the given stream property value.
PropertyValue	createValue(Object javaValue) Create a property value from the given Java object.
long	getPosition(PropertyValue streamProperty) Returns the current position within the given stream property value.
long	getSize(PropertyValue streamProperty) Returns the number of bytes in the given stream property value, or -1 if the stream is null.
ByteOrder	getStoredByteOrder(PropertyValue streamProperty) Returns the stored byte order of the given stream property value.
TypeCategory	getTypeCategory() Returns the type category to which this type definition belongs, which corresponds to its sub interface.
boolean	hasStoredByteOrder(PropertyValue streamProperty) Returns true if the given property value stream has a stored byte order; otherwise false.
byte[]	read(PropertyValue streamProperty, int dataSize) Copies the data from the current position in the given stream property value into a data buffer, which is of the given size.
PropertyValue[]	readElements(PropertyValue streamProperty, TypeDefinition elementType, int numElements) Reads the given number of elements from the given stream property value of the given element type and returns them as an array of property values.
void	setPosition(PropertyValue streamProperty, long newPosition) Sets the position of the given stream property value to that of the given value.
void	setPropertiesFromInterface(TypeDefinitionStream castFrom)
void	setSize(PropertyValue streamProperty, long newSize) Sets the number of bytes contained in the given stream property value to the given new size.
void	setStoredByteOrder(PropertyValue streamProperty, ByteOrder byteOrder) Sets the stored byte order of the given stream property value to the given byte order.
void	write(PropertyValue streamProperty, byte[] data) Write the given data buffer, an array of bytes, into the given stream property value and its current position.
void	writeElements(PropertyValue streamProperty, TypeDefinition elementType, PropertyValue[] data) Writes the elements of the given array of property values of the given element type into the given stream property value at its current position.

Methods inherited from class tv.amwa.maj.meta.TypeDefinition

setPropertiesFromInterface

Methods inherited from class tv.amwa.maj.meta.MetaDefinition

castFromInterface, deepEquals, equals, getAUID, getDescription, getIdentification, getName, hashCode, setDescription, setName, setPropertiesFromInterface, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

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

getAUID, getDescription, getName, setDescription, setName

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

equals, hashCode, toString

Field Detail

Stream

public static final TypeDefinitionStream Stream

DataValue

public static final TypeDefinitionStream DataValue

Constructor Detail

TypeDefinitionStream

public TypeDefinitionStream(AUID identification,
                            @AAFString
                            String typeName)
                     throws NullPointerException

Creates and initializes a new type definition for a streams, which defines a property type that is stored in a stream and has a value that consists of a varying number of the bytes. The order of the bytes is meaningful.

Creating new and unregistered type definitions is not recommended as this may cause interoperability issues with other systems. The official registry of type definitions is available from SMPTE at SMPTE Metadata Registries And Related Items. The full range of data types documented in the AAF 1.1 object specification can be accessed by name and identification using either AAFFactory.typeDefinitionForName(String) or AAFFactory.typeDefinitionForIdentification(tv.amwa.maj.record.AUID) respectively.

Parameters:

identification - AUID to be used to identify this stream type.

typeName - Friendly name for this type definition.

Throws:

NullPointerException - The identification argument is null.

Method Detail

setPropertiesFromInterface

public final void setPropertiesFromInterface(TypeDefinitionStream castFrom)

See Also:

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

append

public void append(PropertyValue streamProperty,
                   byte[] data)
            throws NullPointerException,
                   IllegalPropertyValueException,
                   DataSizeException

Description copied from interface: TypeDefinitionStream

Extend the given stream property value using the data from the given data buffer, an array of bytes. The size of the stream will increase by the size of the given data buffer.

Specified by:

append in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to extend the given data buffer.

data - Data buffer to use to extend the given stream property value.

Throws:

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

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

DataSizeException - Not enough space was available to extend the given stream property value by the given number of bytes.

appendElements

public void appendElements(PropertyValue streamProperty,
                           TypeDefinition elementType,
                           PropertyValue[] data)
                    throws NullPointerException,
                           IllegalPropertyValueException,
                           BadTypeException,
                           DataSizeException

Description copied from interface: TypeDefinitionStream

Append the elements of the given property value array onto the end of the given stream property value. All the elements of the given property value array must by of the given type.

Specified by:

appendElements in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to append elements to the end of.

elementType - Type of the elements of data to append.

data - Property values of the elements to append onto the given stream property value.

Throws:

NullPointerException - One or more of the arguments is null, or one or more of the given data values in null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

BadTypeException - One or more of the elements of the data array are not defined by the given element type.

DataSizeException - The operation failed because not enough space was available to extend the stream.

clearStoredByteOrder

public void clearStoredByteOrder(PropertyValue streamProperty)
                          throws NullPointerException,
                                 IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Clear the stored byte order of the given stream property value. The stream should be empty before calling this method to avoid a mixture of byte orders within the stream.

Specified by:

clearStoredByteOrder in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to clear the stored property value of.

Throws:

NullPointerException - The given stream property value is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

getPosition

public long getPosition(PropertyValue streamProperty)
                 throws NullPointerException,
                        IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Returns the current position within the given stream property value.

Specified by:

getPosition in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to find the current position of.

Returns:

Current position in the given stream property value.

Throws:

NullPointerException - The given stream property value is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

getSize

public long getSize(PropertyValue streamProperty)
             throws NullPointerException,
                    IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Returns the number of bytes in the given stream property value, or -1 if the stream is null.

Specified by:

getSize in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value containing the stream to determine the length of.

Returns:

Number of bytes in the stream of the given stream property value.

Throws:

NullPointerException - The given stream property value is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

getStoredByteOrder

public ByteOrder getStoredByteOrder(PropertyValue streamProperty)
                             throws NullPointerException,
                                    IllegalPropertyValueException,
                                    PropertyNotPresentException

Description copied from interface: TypeDefinitionStream

Returns the stored byte order of the given stream property value.

Specified by:

getStoredByteOrder in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to find the byte order for.

Returns:

Byte order for the given stream property value.

Throws:

NullPointerException - The given stream proeprty value is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

PropertyNotPresentException - The byte order is not stored in the given property value.

hasStoredByteOrder

public boolean hasStoredByteOrder(PropertyValue streamProperty)
                           throws NullPointerException,
                                  IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Returns true if the given property value stream has a stored byte order; otherwise false.

Specified by:

hasStoredByteOrder in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to test.

Returns:

Does the given stream property value have as stored property value?

Throws:

NullPointerException - The given stream property value is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

read

public byte[] read(PropertyValue streamProperty,
                   int dataSize)
            throws NullPointerException,
                   IllegalArgumentException,
                   EndOfDataException,
                   IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Copies the data from the current position in the given stream property value into a data buffer, which is of the given size. The data buffer is a byte array that is returned by the method.

Specified by:

read in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property array to copy data from.

dataSize - Size of the data buffer to create and return.

Returns:

Data buffer containing data copied from the given stream property at its current position and of the given size.

Throws:

NullPointerException - The given stream property value is null.

IllegalArgumentException - Cannot read a negative number of bytes from a stream property value.

EndOfDataException - Cannot read the requested amount of data as not enough bytes remain in the given stream property value at its current position.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

readElements

public PropertyValue[] readElements(PropertyValue streamProperty,
                                    TypeDefinition elementType,
                                    int numElements)
                             throws NullPointerException,
                                    IllegalPropertyValueException,
                                    BadTypeException,
                                    EndOfDataException

Description copied from interface: TypeDefinitionStream

Reads the given number of elements from the given stream property value of the given element type and returns them as an array of property values. The read takes place at the current position for the given stream property value and advances the position by the number of bytes read.

If the TypeDefinitionStream.writeElements(PropertyValue, TypeDefinition, PropertyValue[]) method has been used to write an array of property values to a stream property value at a given position, a read from the same position with this method must create an array containing the same values.

Specified by:

readElements in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to read elements from.

elementType - Type of elements to read from the given stream property value.

numElements - Number of elements to read from the given stream property value.

Returns:

Array of elements read from the given stream property value.

Throws:

NullPointerException - One or both of the stream property or element type arguments is/are null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

BadTypeException - The values in the data stream do not match the given element type.

EndOfDataException - Reading the number of requested elements will result in a read beyond the end of the given stream property value.

See Also:

TypeDefinitionStream.writeElements(PropertyValue, TypeDefinition, PropertyValue[])

setPosition

public void setPosition(PropertyValue streamProperty,
                        long newPosition)
                 throws NullPointerException,
                        IllegalArgumentException,
                        IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Sets the position of the given stream property value to that of the given value.

Specified by:

setPosition in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to have its position set.

newPosition - New position to set for the given stream property value.

Throws:

NullPointerException - The given stream property value is null.

IllegalArgumentException - The given position is outside the acceptable range for the given stream property.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

setSize

public void setSize(PropertyValue streamProperty,
                    long newSize)
             throws NullPointerException,
                    IllegalArgumentException,
                    IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Sets the number of bytes contained in the given stream property value to the given new size. If the new size is smaller than the current size, as returned by TypeDefinitionStream.getSize(PropertyValue), then the data will be truncated. If the size is larger, the beginning section of the stream value will be the same as the existing stream.

Specified by:

setSize in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value that is to have a new size.

newSize - New size, measured in bytes, for the given stream property value.

Throws:

NullPointerException - The given stream property value is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

IllegalArgumentException

setStoredByteOrder

public void setStoredByteOrder(PropertyValue streamProperty,
                               ByteOrder byteOrder)
                        throws NullPointerException,
                               IllegalPropertyValueException

Description copied from interface: TypeDefinitionStream

Sets the stored byte order of the given stream property value to the given byte order. The stream should be empty before calling this method to avoid a mixture of byte orders within the stream.

Specified by:

setStoredByteOrder in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to set the stored byte order for.

byteOrder - Byte order to set for the given stream property value.

Throws:

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

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

write

public void write(PropertyValue streamProperty,
                  byte[] data)
           throws NullPointerException,
                  IllegalPropertyValueException,
                  EndOfDataException

Description copied from interface: TypeDefinitionStream

Write the given data buffer, an array of bytes, into the given stream property value and its current position. The number of bytes written is the same as the size of the given data buffer.

Specified by:

write in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value to have data written into at its current position.

data - Data to write into the given stream property value at its current position.

Throws:

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

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

EndOfDataException - The write operation will exceed the current size of the stream.

writeElements

public void writeElements(PropertyValue streamProperty,
                          TypeDefinition elementType,
                          PropertyValue[] data)
                   throws NullPointerException,
                          IllegalPropertyValueException,
                          BadTypeException,
                          EndOfDataException

Description copied from interface: TypeDefinitionStream

Writes the elements of the given array of property values of the given element type into the given stream property value at its current position.

Specified by:

writeElements in interface TypeDefinitionStream

Parameters:

streamProperty - Stream property value into which elements are to be written.

elementType - Type of elements to be written to the given stream property value.

data - Elements to write to the given stream property value at its current position.

Throws:

NullPointerException - One or more of the arguments is null, or one or more of the data elements is null.

IllegalPropertyValueException - The given property value is not defined by this stream type definition.

BadTypeException - One or more of the elements of the data array are not defined by the given element type.

EndOfDataException - The end of the stream has been reached before all data values could be written. The stream is returned to its previous state.

See Also:

TypeDefinitionStream.readElements(PropertyValue, TypeDefinition, int)

createValue

public PropertyValue createValue(Object javaValue)
                          throws ClassCastException

Description copied from class: TypeDefinition

Create a property value from the given Java object. If the type of the object is not compatible with this type definition, a ClassCastException is thrown.

Specified by:

createValue in interface TypeDefinition

Specified by:

createValue in class TypeDefinition

Parameters:

javaValue - Java object to use to create a property value of this type.

Returns:

Property value representing the given value.

Throws:

ClassCastException - The given object cannot be cast to a property value with this type definition.

getTypeCategory

public TypeCategory getTypeCategory()

Description copied from interface: TypeDefinition

Returns the type category to which this type definition belongs, which corresponds to its sub interface. For example, TypeCategory.Int is returned for a TypeDefinitionInteger.

Specified by:

getTypeCategory in interface TypeDefinition

Specified by:

getTypeCategory in class TypeDefinition

Returns:

Type category to which the type definition belongs.

See Also:

TypeCategory

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 MetaDefinition

Parameters:

parent - XML parent element to append child nodes to.