tv.amwa.maj.meta
Class TypeDefinitionString

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

All Implemented Interfaces:

Serializable, DefinitionType, MetaDefinition, TypeDefinition, TypeDefinitionString, XMLSerializable, MAJCommon

@AAFClass(uuid1=218169601,
          uuid2=523,
          uuid3=0,
          uuid4={6,14,43,52,2,6,1,1},
          definedName="TypeDefinitionString",
          description="The TypeDefinitionString class defines a property type that consists of a zero-terminated array of the underlying character or integer type.")
public final class TypeDefinitionString
extends TypeDefinition
implements TypeDefinitionString, Serializable, MAJCommon

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

THE COMMENTS FOR THIS CLASS ARE INCOMPLETE.

Author:

Richard Cartwright

See Also:

Serialized Form

Nested Class Summary

static class	TypeDefinitionString.BaseStringValue Base representation for all property values representing string values.
static class	TypeDefinitionString.ByteArrayStringValue Property value for strings with an underlying element type of TypeDefinitionInteger.
static class	TypeDefinitionString.CharacterStringValue Property value for strings with an underlying element type of TypeDefinitionCharacter.
static class	TypeDefinitionString.XMLHandler

Field Summary

static TypeDefinitionString

String

Constructor Summary

TypeDefinitionString(AUID identification, String typeName, TypeDefinition typeDefinition)
Creates and initializes the string type definition with its identity and the underlying data representation.

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.
void	appendXMLChildren(Node parent) Append child elements to the given parent node to serialize the value of an object to an XML fragment.
PropertyValue	createValue(Object javaValue) Create a property value from the given Java object.
PropertyValue	createValueFromString(Buffer initData) Create a new string type property value consistent with this type definition from the given data buffer.
PropertyValue	createValueFromString(String initData) Create a new string type property value consistent with this type definition from the given Java string.
boolean	deepEquals(Object o) Check to see if this definition is equal to the given object by comparing each property.
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 TypeDefinitionString.getElementType().
String	getString(PropertyValue stringProperty) Returns the value of the given string property as a Java string.
TypeCategory	getTypeCategory() Returns the type category to which this type definition belongs, which corresponds to its sub interface.
void	setCharacterSet(String charSet) Set the character set that will be used for conversion between a Java string and this string type definition.
void	setPropertiesFromInterface(TypeDefinitionString castFrom)
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 class tv.amwa.maj.meta.TypeDefinition

setPropertiesFromInterface

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

castFromInterface, 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

String

public static final TypeDefinitionString String

Constructor Detail

TypeDefinitionString

public TypeDefinitionString(AUID identification,
                            @AAFString
                            String typeName,
                            TypeDefinition typeDefinition)
                     throws NullPointerException,
                            IllegalArgumentException

Creates and initializes the string type definition with its identity and the underlying data representation. Acceptable underlying type definitions are:

• TypeDefinitionInteger
• TypeDefinitionCharacter

It is anticipated that most Java versions of this interface will be choose TypeDefinitionCharacter and will use Java string handling in their implementation. However, by using a call to setCharacterSet(String) it is possible to define mappings between different character sets to and from Java strings.

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

typeName - Friendly name for the string data type.

typeDefinition - Type of each element to be contained in the array.

Throws:

NullPointerException - The identification and/or type definition arguments is/are null.

IllegalArgumentException - The given type is not an acceptable underlying type for a string type definition.

Method Detail

setPropertiesFromInterface

public final void setPropertiesFromInterface(TypeDefinitionString castFrom)

See Also:

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

appendElements

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

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.getElementType().

Specified by:

appendElements in interface TypeDefinitionString

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.

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

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

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:

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

appendElements

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

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.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 TypeDefinitionString.appendString(PropertyValue, Buffer).

Specified by:

appendElements in interface TypeDefinitionString

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:

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

getCount

public int getCount(PropertyValue stringProperty)
             throws NullPointerException,
                    IllegalPropertyValueException

Description copied from interface: TypeDefinitionString

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

Specified by:

getCount in interface TypeDefinitionString

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()

getElements

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

Description copied from interface: TypeDefinitionString

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

Specified by:

getElements in interface TypeDefinitionString

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:

TypeDefinitionString.setString(PropertyValue, Buffer), TypeDefinitionString.getString(PropertyValue)

getString

public String getString(PropertyValue stringProperty)
                 throws NullPointerException,
                        IllegalPropertyValueException

Description copied from interface: TypeDefinitionString

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

Specified by:

getString in interface TypeDefinitionString

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.

getPropertyValues

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

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.getElementType().

Specified by:

getPropertyValues in interface TypeDefinitionString

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:

TypeDefinitionString.appendElements(PropertyValue, PropertyValue[])

getElementType

@AAFProperty(uuid1=100729095,
             uuid2=3840,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="ElementType",
             typeName="WeakReference to TypeDefinition",
             optional=false,
             uniqueIdentifier=false,
             pid=27)
public TypeDefinition getElementType()

Description copied from interface: TypeDefinitionString

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

Specified by:

getElementType in interface TypeDefinitionString

Returns:

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

appendString

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

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.getCharacterSet(). An attempt to pass a null string will result in no change to the property value and no error.

Specified by:

appendString in interface TypeDefinitionString

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:

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

createValueFromString

public PropertyValue createValueFromString(String initData)

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.getCharacterSet(). Setting a null value will result in the return of a property value with its internal string representation set to null.

Specified by:

createValueFromString in interface TypeDefinitionString

Parameters:

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

Returns:

Newly created string property value from the given Java string.

See Also:

TypeDefinitionString.createValueFromString(Buffer)

createValueFromString

public PropertyValue createValueFromString(Buffer initData)
                                    throws IllegalArgumentException

Description copied from interface: TypeDefinitionString

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

Specified by:

createValueFromString in interface TypeDefinitionString

Parameters:

initData - 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:

TypeDefinitionString.createValueFromString(Buffer)

getCharacterSet

public String getCharacterSet()

Description copied from interface: TypeDefinitionString

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

Specified by:

getCharacterSet in interface TypeDefinitionString

Returns:

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

See Also:

Charset

setCharacterSet

public void setCharacterSet(String charSet)
                     throws NullPointerException,
                            IllegalCharsetNameException

Description copied from interface: TypeDefinitionString

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.

Specified by:

setCharacterSet in interface TypeDefinitionString

Parameters:

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

Throws:

NullPointerException - The given character set name is null.

IllegalCharsetNameException

See Also:

Charset

setString

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

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.getCharacterSet(). Setting a null value will result in the return of a property value with its internal string representation set to null.

Specified by:

setString in interface TypeDefinitionString

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:

TypeDefinitionString.getString(PropertyValue), TypeDefinitionString.setString(PropertyValue, Buffer)

setString

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

Description copied from interface: TypeDefinitionString

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

Specified by:

setString in interface TypeDefinitionString

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:

TypeDefinitionString.getElements(PropertyValue), TypeDefinitionString.setString(PropertyValue, String)

appendString

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

Description copied from interface: TypeDefinitionString

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 TypeDefinitionString.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 TypeDefinitionString.appendElements(PropertyValue, Buffer).

Specified by:

appendString in interface TypeDefinitionString

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:

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

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

deepEquals

public final boolean deepEquals(Object o)

Description copied from class: MetaDefinition

Check to see if this definition is equal to the given object by comparing each property. The MetaDefinition.equals(Object) method only checks that the identies of two definitions are equal, relying on the unqiueness ensured by identity registration. This method is provided for debugging and validation purposes.

Overrides:

deepEquals in class MetaDefinition

Parameters:

o - Object to compare to this definition.

Returns:

Is the given object a meta definiition with all of its properties equal to this meta definition?

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.

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.