tv.amwa.maj.iface
Interface TypeDefinitionString

All Superinterfaces:

MetaDefinition, TypeDefinition

All Known Implementing Classes:

TypeDefinitionString

public interface TypeDefinitionString
extends TypeDefinition

Specifies the definition of a property type that consists, effectively, of an array of the underlying character or integer type. In the MAJ API, all strings are represented as Java strings.

String type definitions have an underlying element type that can be found be calling getElementType(). The element type can be either a character type or an integer type. The methods of this class allow the manipulation of string property values in a way that hides the underlying value type.

For any conversion between arrays of integer values and Java strings or vice versa, the character set returned by getCharacterSet() is used. This character set can also be set using to a user-defined value with setCharacterSet(String) and the defined byte order of any buffer is respected. The default value for this property is "UTF-16", which is the same as the default character set for the Java platform.

Due to the object-oriented representation of arrays in Java including a defined length, sequences of data are not expected to be terminated with null bytes.

Property values containing null as the value for a string are acceptable.

Author:

Richard Cartwright

See Also:

makeTypeDefinitionString(), TypeCategory.String, String, TypeDefinitionCharacter

Method Summary

void	appendElements(PropertyValue stringProperty, Buffer elements) Append to the string value of the given property value using a data buffer.
void	appendElements(PropertyValue stringProperty, PropertyValue[] elements) Append to the string value of the given property value using the array of property value elements.
void	appendString(PropertyValue stringProperty, Buffer extension) Appends the given data buffer to the string of the given property value.
void	appendString(PropertyValue stringProperty, String extension) Appends the given Java String to the string of the given property value.
PropertyValue	createValueFromString(Buffer initialData) Create a new string type property value consistent with this type definition from the given data buffer.
PropertyValue	createValueFromString(String initialData) Create a new string type property value consistent with this type definition from the given Java string.
String	getCharacterSet() Returns the character set that will be used for conversion between a Java string and this string type definition.
int	getCount(PropertyValue stringProperty) Returns the length of the string contained in the given string property value, measured in the number of characters.
Buffer	getElements(PropertyValue stringProperty) Returns the value of the given string property as a data buffer consistent with the element type of this string type definition.
TypeDefinition	getElementType() Returns the underlying AAF type used to represent characters of a string of this string type definition.
PropertyValue[]	getPropertyValues(PropertyValue stringProperty) Returns the value of the given string property as an array of property values of a compatible type to the string type definition, as returned by getElementType().
String	getString(PropertyValue stringProperty) Returns the value of the given string property as a Java string.
void	setCharacterSet(String charSet) Set the character set that will be used for conversion between a Java string and this string type definition.
void	setString(PropertyValue stringProperty, Buffer data) Set the value of the string contained in the given string property value to the given data buffer.
void	setString(PropertyValue stringProperty, String data) Set the value of the string contained in the given string property value to the given Java string value.

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

getElementType

TypeDefinition getElementType()

Returns the underlying AAF type used to represent characters of a string of this string type definition.

Returns:

Underlying type used to represent characters of a string of this string type definition.

getCount

@UInt32
int getCount(PropertyValue stringProperty)
             throws NullPointerException,
                    IllegalPropertyValueException

Returns the length of the string contained in the given string property value, measured in the number of characters.

Parameters:

stringProperty - Property value containing a string to determine the length of.

Returns:

Number of characters in the given string.

Throws:

NullPointerException - The given string property value is null.

IllegalPropertyValueException - The given string property value type does not match this string type definition.

See Also:

String.length()

createValueFromString

PropertyValue createValueFromString(String initialData)

Create a new string type property value consistent with this type definition from the given Java string. Conversion to the underlying character type takes place according to the character set returned by getCharacterSet(). Setting a null value will result in the return of a property value with its internal string representation set to null.

Parameters:

initialData - Initial string data to create a new string property value.

Returns:

Newly created string property value from the given Java string.

See Also:

createValueFromString(Buffer)

createValueFromString

PropertyValue createValueFromString(Buffer initialData)
                                    throws IllegalArgumentException

Create a new string type property value consistent with this type definition from the given data buffer. Any character set conversion required takes place using the character set returned by getCharacterSet(). Setting a null value will result in the return of a property value with its internal string representation set to null.

The buffer of data must be one of the following types:

• ByteBuffer
• ShortBuffer
• IntBuffer
• LongBuffer
• CharBuffer

Any other buffer types will result in an IllegalArgumentException.

Parameters:

initialData - Initial string data to use to create a new string property value.

Returns:

Newly created string property value from the given buffer.

Throws:

IllegalArgumentException - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.

See Also:

createValueFromString(Buffer)

setString

void setString(PropertyValue stringProperty,
               String data)
               throws NullPointerException,
                      IllegalPropertyValueException

Set the value of the string contained in the given string property value to the given Java string value. Any character set conversion required takes place using the character set returned by getCharacterSet(). Setting a null value will result in the return of a property value with its internal string representation set to null.

Parameters:

stringProperty - Property value to have its string value set.

data - Value to set for the string type property value, represented as a Java String.

Throws:

NullPointerException - The given string property value is null.

IllegalPropertyValueException - The given string property type does not match this string type definition.

See Also:

getString(PropertyValue), setString(PropertyValue, Buffer)

setString

void setString(PropertyValue stringProperty,
               Buffer data)
               throws NullPointerException,
                      IllegalPropertyValueException,
                      IllegalArgumentException

Set the value of the string contained in the given string property value to the given data buffer. Any character set conversion required takes place using the character set returned by getCharacterSet(). Setting a null value will result in the return of a property value with its internal string representation set to null.

The buffer of data must be one of the following types:

• ByteBuffer
• ShortBuffer
• IntBuffer
• LongBuffer
• CharBuffer

Any other buffer types will result in an IllegalArgumentException.

Parameters:

stringProperty - Property value to have its string value set.

data - Value to set for the string type property value, represented as a data buffer.

Throws:

NullPointerException - The given string property is null.

IllegalPropertyValueException - The given string property type does not match this string type definition.

IllegalArgumentException - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.

See Also:

getElements(PropertyValue), setString(PropertyValue, String)

appendElements

void appendElements(PropertyValue stringProperty,
                    PropertyValue[] elements)
                    throws NullPointerException,
                           BadTypeException,
                           IllegalPropertyValueException,
                           BadSizeException

Append to the string value of the given property value using the array of property value elements. Each element of the given array must match the type definition returned by getElementType().

Parameters:

stringProperty - Property value containing a string to be extended.

elements - Array of property value elements to use to extend the given string.

Throws:

NullPointerException - One or both of the arguments is/are null, or one or more of the values of the given array is null.

BadTypeException - One or more of the elements of the given array of property values is of an incompatible type.

IllegalPropertyValueException - The given string property value is not of this string type definition.

BadSizeException - The number of bytes per integer of the underlying element type of this string type definition is not supported by this implementation.

See Also:

appendElements(PropertyValue, Buffer), appendString(PropertyValue, String)

appendElements

void appendElements(PropertyValue stringProperty,
                    Buffer elements)
                    throws NullPointerException,
                           IllegalArgumentException,
                           IllegalPropertyValueException

Append to the string value of the given property value using a data buffer. Any character set conversion required takes place using the character set returned by getCharacterSet(). An attempt to pass in a null buffer will result in no change to the property value and no error.

The buffer of data must be one of the following types:

• ByteBuffer
• ShortBuffer
• IntBuffer
• LongBuffer
• CharBuffer

Any other buffer types will result in an IllegalArgumentException.

This method has the same behaviour as appendString(PropertyValue, Buffer).

Parameters:

stringProperty - Property value containing a string value to append the given elements to.

elements - Buffer containing values to be appended to to the given property value.

Throws:

NullPointerException - The given string property argument is null.

IllegalArgumentException - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.

IllegalPropertyValueException - The given string property type does not match this type definition.

See Also:

appendElements(PropertyValue, PropertyValue[]), appendString(PropertyValue, String)

appendString

void appendString(PropertyValue stringProperty,
                  String extension)
                  throws NullPointerException,
                         IllegalPropertyValueException

Appends the given Java String to the string of the given property value. Any character set conversion required takes place using the character set returned by getCharacterSet(). An attempt to pass a null string will result in no change to the property value and no error.

Parameters:

stringProperty - Property value containing the string to extend.

extension - String to append to the end of the given property value.

Throws:

NullPointerException - The given string property argument is null.

IllegalPropertyValueException - The given string property value type does not match this string type definition.

See Also:

appendString(PropertyValue, Buffer), appendElements(PropertyValue, PropertyValue[])

appendString

void appendString(PropertyValue stringProperty,
                  Buffer extension)
                  throws NullPointerException,
                         IllegalArgumentException,
                         IllegalPropertyValueException

Appends the given data buffer to the string of the given property value. Any character set conversion required takes place using the character set returned by getCharacterSet(). An attempt to pass a null buffer will result in no change to the property value and no error.

The buffer of data must be one of the following types:

• ByteBuffer
• ShortBuffer
• IntBuffer
• LongBuffer
• CharBuffer

Any other buffer types will result in an IllegalArgumentException.

This method has the same behaviour as appendElements(PropertyValue, Buffer).

Parameters:

stringProperty - Property value containing the string to extend.

extension - Buffer of string data to use to extend the given property value.

Throws:

NullPointerException - The given string property value is null.

IllegalArgumentException - The given buffer must be of an appropriate type for conversion to the underlying element type for this string type definition.

IllegalPropertyValueException - The given string property value type does not match this string type definition.

See Also:

appendElements(PropertyValue, PropertyValue[]), appendString(PropertyValue, String)

getElements

Buffer getElements(PropertyValue stringProperty)
                   throws NullPointerException,
                          IllegalPropertyValueException,
                          BadSizeException

Returns the value of the given string property as a data buffer consistent with the element type of this string type definition. Any character set conversion required takes place using the character set returned by getCharacterSet(). If the internal representation of the string property value is null then this method will return null.

Note that a null character will not be inserted as the last byte of the buffer.

Parameters:

stringProperty - Property value containing the string to convert.

Returns:

Data buffer representation of the given value.

Throws:

NullPointerException - The given string property value is null.

IllegalPropertyValueException - The given string property type does not match this string property value.

BadSizeException - The number of bytes per integer of the underlying element type of this string type definition is not supported by this implementation.

See Also:

setString(PropertyValue, Buffer), getString(PropertyValue)

getPropertyValues

PropertyValue[] getPropertyValues(PropertyValue stringProperty)
                                  throws NullPointerException,
                                         IllegalPropertyValueException,
                                         BadSizeException

Returns the value of the given string property as an array of property values of a compatible type to the string type definition, as returned by getElementType().

Parameters:

stringProperty - Property value containing the string to convert.

Returns:

Java String representation of the given value.

Throws:

NullPointerException - The given string property value is null.

IllegalPropertyValueException - The type of the given string property value does not match this string type definition.

BadSizeException - The number of bytes per integer of the underlying element type of this string type definition is not supported by this implementation.

See Also:

appendElements(PropertyValue, PropertyValue[])

getString

String getString(PropertyValue stringProperty)
                 throws NullPointerException,
                        IllegalPropertyValueException

Returns the value of the given string property as a Java string.

Parameters:

stringProperty - Property value containing the string to convert.

Returns:

Java String representation of the given value, which could be a null string.

Throws:

NullPointerException - The given string property value is null.

IllegalPropertyValueException - The given string property is not of this string type definition.

getCharacterSet

String getCharacterSet()

Returns the character set that will be used for conversion between a Java string and this string type definition. If a character set has not been provided by a user then the value returned will be the default Java character set of "UTF-16".

Returns:

Character set used for conversion between this string type and Java strings.

See Also:

Charset

setCharacterSet

void setCharacterSet(String charSet)
                     throws NullPointerException,
                            UnsupportedCharsetException

Set the character set that will be used for conversion between a Java string and this string type definition. For information on valid character set names, see the relevant Java API documentation.

Parameters:

charSet - Character set used for conversion between this string type and Java strings.

Throws:

NullPointerException - The given character set name is null.

UnsupportedCharsetException - The named character set is not supported in the underlying implementation of Java.

See Also:

Charset