tv.amwa.maj.iface
Interface TypeDefinitionStream

All Superinterfaces:

MetaDefinition, TypeDefinition

All Known Implementing Classes:

TypeDefinitionStream

public interface TypeDefinitionStream
extends TypeDefinition

Specifies the definition of a property type that is stored in a stream and has a value that consists of a varying number of bytes. The order of the bytes is meaningful.

Note that all reads and writes advance the current position of a stream.

Author:

Richard Cartwright

See Also:

makeTypeDefinitionStream(), TypeCategory.Stream, DataBuffer, DataValue

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	clearStoredByteOrder(PropertyValue streamProperty) Clear the stored byte order of the given stream property value.
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.
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	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 interface tv.amwa.maj.iface.TypeDefinition

createValue, getTypeCategory

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

getAUID, getDescription, getName, setDescription, setName

Method Detail

getSize

@Int64
long getSize(PropertyValue streamProperty)
             throws NullPointerException,
                    IllegalPropertyValueException

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

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.

setSize

void setSize(PropertyValue streamProperty,
             @Int64
             long newSize)
             throws NullPointerException,
                    IllegalPropertyValueException

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

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.

getPosition

@Int64
long getPosition(PropertyValue streamProperty)
                 throws NullPointerException,
                        IllegalPropertyValueException

Returns the current position within the given stream property value.

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.

setPosition

void setPosition(PropertyValue streamProperty,
                 @Int64
                 long newPosition)
                 throws NullPointerException,
                        IllegalPropertyValueException

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

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.

read

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

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.

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.

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

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

write

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

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.

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.

append

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

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.

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.

hasStoredByteOrder

@Bool
boolean hasStoredByteOrder(PropertyValue streamProperty)
                           throws NullPointerException,
                                  IllegalPropertyValueException

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

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.

getStoredByteOrder

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

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

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.

setStoredByteOrder

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

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.

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.

clearStoredByteOrder

void clearStoredByteOrder(PropertyValue streamProperty)
                          throws NullPointerException,
                                 IllegalPropertyValueException

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.

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.

readElements

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

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

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:

writeElements(PropertyValue, TypeDefinition, PropertyValue[])

writeElements

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

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.

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:

readElements(PropertyValue, TypeDefinition, int)

appendElements

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

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.

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.