Media Authoring
with Java API

tv.amwa.maj.entity
Class InterchangeObject

java.lang.Object
  extended by tv.amwa.maj.entity.InterchangeObject
All Implemented Interfaces:
Serializable, Cloneable, InterchangeObject, XMLSerializable
Direct Known Subclasses:
Component, ContentStorage, ControlPoint, DefinitionObject, DescriptiveFramework, DescriptiveObject, Dictionary, EssenceData, EssenceDescriptor, Header, Identification, KLVData, Locator, Mob, MobSlot, Parameter, RIFFChunk, SubDescriptor, TaggedValue

@AAFClass(uuid1=218169601,
          uuid2=257,
          uuid3=256,
          uuid4={6,14,43,52,2,6,1,1},
          definedName="InterchangeObject",
          description="The InterchangeObject class is a root class. All classes defined in an AAF file shall be sub-classes of InterchangeObject with the exception of the MetaDefinition classes defined by this document.")
public abstract class InterchangeObject
extends Object
implements InterchangeObject, Serializable, XMLSerializable, Cloneable

Implements the root class for all AAF persistent classes. All classes defined in an AAF file shall be sub-classes of interchange object with the exception of the meta definition classes.

THE COMMENTS FOR THIS CLASS ARE INCOMPLETE.

Author:
Richard Cartwright
See Also:
Serialized Form

Nested Class Summary
static class InterchangeObject.InterchangeObjectXMLHandler
          XML handler that is the root class for all XML handlers of interchange objects.
 
Constructor Summary
InterchangeObject()
           
 
Method Summary
 void appendXMLChildren(Node parent)
          Append child elements to the given parent node to serialize the value of an object to an XML fragment.
static InterchangeObject castFromInterface(InterchangeObject alien)
          Casts a class that implements one of the generic interfaces of the Java AAF object model to a known concrete implementation.
 int countProperties()
          Returns the number of properties currently present in this interchange object.
 PropertyValue createOptionalPropertyValue(PropertyDefinition propertyDefinition, Object intialValue)
          Creates and returns a property value according to the given property definition and sets it for this interchange object.
 void disableGenerationTracking()
          Calling this method will cause generation tracking to be disabled for the object.
 void enableGenerationTracking()
          Calling this method will cause generation tracking to be enabled for the object.
 ClassDefinition getDefinition()
          Returns the class definition that identifies the class of this interchange object.
 Identification getGeneration()
          Gets the generation of this object, which identifies when this object was created or last modified.
 AUID getGenerationAUID()
          Shortcut to get the AUID of the identification representing this object's generation.
 Iterator<Property> getProperties()
          Returns the set of properties of this interchange object, where each property contains its property definition and current value.
 PropertyValue getPropertyValue(PropertyDefinition propDef)
          Returns the requested property value of the object.
 boolean isGenerationTracked()
          Returns true if generations are being tracked by the object.
 boolean isPropertyPresent(PropertyDefinition propDef)
          Returns true if the property identified by the given property definition is legal and present; otherwise returns false.
 void omitOpionalProperty(PropertyDefinition propDef)
          Omits the given optional property from this interchange object if the property definition is legal, optional and is present.
static boolean registerImplementation(Class<?> implementor)
          Register the known implementation of an interface.
 void setPropertiesFromInterface(InterchangeObject castFrom)
          Set the properties of this instance value from those available in the given instance of an AAF interface.
 void setPropertyValue(PropertyDefinition propDef, PropertyValue propVal)
          Sets the value of the given property of this interchange object to the given value.
 String toString()
           
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

InterchangeObject

public InterchangeObject()
Method Detail

castFromInterface

public static final InterchangeObject castFromInterface(InterchangeObject alien)
                                                 throws NullPointerException,
                                                        ClassCastException

Casts a class that implements one of the generic interfaces of the Java AAF object model to a known concrete implementation. If the given class matches the known implementation, no casting takes place.

Implementing classes must first be registered using the registerImplementation(Class) method. A maximum of one concrete implementing class per interface is permitted. External classes that implement more than one interface are not supported and the behaviour of this method will not be deterministic in this case.

As an example, consider the example class castFrom or type org.external.ExternalTaggedValue that implements TaggedValue. To cast this to the known implementation of tagged value in this package, use the following code:

 TaggedValue castTo = 
     (TaggedValue) AAFObject.castFromInterface(castFrom);
 

Note that if the registration process has been unsuccessful, a runtime ClassCastException will be thrown by this code.

Parameters:
alien - Class implementing any interface that extends InterchangeObject.
Returns:
A locally-known implementation of the given interface.
Throws:
NullPointerException - Argument is null.
ClassCastException - The given class cannot be cast to a known implementations due to incompatibilities, unknown interfaces, instantiation or invocation exceptions.

registerImplementation

public static final boolean registerImplementation(Class<?> implementor)
                                            throws NullPointerException,
                                                   IllegalArgumentException

Register the known implementation of an interface. All concrete classes that extend this object must be registered, whether they are internal to this package or externally defined extensions.

All registered classes must implement a public and final method called setPropertiesFromInterface(). This method takes one parameter that is the primary interface of the Java AAF object interfaces that the concrete class supports. For example, in the TaggedValue class:

 public final void setPropertiesFromInterface(
     tv.amwa.maj.iface.TaggedValue castFrom) {
     
     super.setPropertiesFromInterface(castFrom);
     
     setName(castFrom.getName());
     setTypeDefinition(castFrom.getTypeDefinition());
     setValue(castFrom.getValue());
 }
 

It is recommended that all concrete classes register themselves as part of their static initializers. For example:

 class TaggedValue extends AAFObject {
 
     ...
     
     static {
         ...
         AAFObject.registerImplementation(TaggedValue.class);
         ...
     }
     
     ...
 }
 

If an interface is registered more than once, the previous registration is replaced. If a replacement has taken place, this method will return true.

Parameters:
implementor - A class to register as an implementation of an interface, specified by the parameter to the required method setPropertiesFromInterface().
Returns:
Is the registration causing an existing registration to be replaced?
Throws:
NullPointerException - Argument is null.
IllegalArgumentException - The given class is not concrete or it does not implement the required method setPropertiesFromInterface().

setPropertiesFromInterface

public final void setPropertiesFromInterface(InterchangeObject castFrom)
                                      throws NullPointerException

Set the properties of this instance value from those available in the given instance of an AAF interface.

Parameters:
castFrom - Value to extract properties from.
Throws:
NullPointerException - The given value to use to set this value is null.

countProperties

public int countProperties()
Description copied from interface: InterchangeObject

Returns the number of properties currently present in this interchange object.

Specified by:
countProperties in interface InterchangeObject
Returns:
Number of properties present for this interchange object.

createOptionalPropertyValue

public PropertyValue createOptionalPropertyValue(PropertyDefinition propertyDefinition,
                                                 Object intialValue)
                                          throws NullPointerException,
                                                 IllegalPropertyException,
                                                 PropertyAlreadyPresentException
Description copied from interface: InterchangeObject

Creates and returns a property value according to the given property definition and sets it for this interchange object. The property must be legal for this class and not currently present.

Important note: This is a low-level method that allows direct access to properties. If such access takes place, any semantic checking provided in named property get/set methods of the object is bypassed at the user's own risk.

Specified by:
createOptionalPropertyValue in interface InterchangeObject
Parameters:
propertyDefinition - Property definition identifying the property value to create.
intialValue - Initial value for the optional property.
Returns:
Newly created property value for this interchange object.
Throws:
NullPointerException - The given property definition and/or value is/are null.
IllegalPropertyException - The given property definition is illegal for this interchange object's class.
PropertyAlreadyPresentException - The given property is optional, but already present in this class.
See Also:
TypeDefinition.createValue(Object), InterchangeObject.setPropertyValue(PropertyDefinition, PropertyValue)

disableGenerationTracking

public void disableGenerationTracking()
Description copied from interface: InterchangeObject

Calling this method will cause generation tracking to be disabled for the object. Generation information will then not be available through the InterchangeObject.getGeneration() and InterchangeObject.getGenerationAUID() methods.

Calling the InterchangeObject.enableGenerationTracking() method will enable generation tracking for this object.

Generation tracking is disabled by default.

Specified by:
disableGenerationTracking in interface InterchangeObject

enableGenerationTracking

public void enableGenerationTracking()
Description copied from interface: InterchangeObject

Calling this method will cause generation tracking to be enabled for the object. Generation information will then be available through the InterchangeObject.getGeneration() and InterchangeObject.getGenerationAUID() methods.

Calling the InterchangeObject.disableGenerationTracking() method will disable generation tracking for this object.

Generation tracking is disabled by default.

Specified by:
enableGenerationTracking in interface InterchangeObject

getDefinition

@AAFProperty(uuid1=100729092,
             uuid2=257,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="ObjClass",
             typeName="WeakReference to ClassDefinition",
             optional=false,
             uniqueIdentifier=false,
             pid=257)
public ClassDefinition getDefinition()
Description copied from interface: InterchangeObject

Returns the class definition that identifies the class of this interchange object.

Specified by:
getDefinition in interface InterchangeObject
Returns:
Class definition that describes this object instance.

getGeneration

public Identification getGeneration()
                             throws InvalidParameterException,
                                    ObjectNotAttachedException
Description copied from interface: InterchangeObject

Gets the generation of this object, which identifies when this object was created or last modified.

This method will succeed if generation tracking is enabled for this object. Call InterchangeObject.enableGenerationTracking() and InterchangeObject.disableGenerationTracking() to control generation tracking for this object. Call InterchangeObject.isGenerationTracked() to determine if generation tracking is currently enabled for this object.

Specified by:
getGeneration in interface InterchangeObject
Returns:
Identification for when this object was last modified.
Throws:
InvalidParameterException - Generation tracking is not enabled for this object.
ObjectNotAttachedException - This object is not attached to a file from which generation information can be obtained.

getGenerationAUID

@AAFProperty(uuid1=85985025,
             uuid2=2048,
             uuid3=0,
             uuid4={6,14,43,52,1,1,1,2},
             definedName="Generation",
             typeName="AUID",
             optional=true,
             uniqueIdentifier=false,
             pid=258)
public AUID getGenerationAUID()
                       throws InvalidParameterException,
                              ObjectNotAttachedException
Description copied from interface: InterchangeObject

Shortcut to get the AUID of the identification representing this object's generation.

This method will succeed if generation tracking is enabled for this object. Call InterchangeObject.enableGenerationTracking() and InterchangeObject.disableGenerationTracking() to control generation tracking for this object. Call InterchangeObject.isGenerationTracked() to determine if generation tracking is currently enabled for this object.

Specified by:
getGenerationAUID in interface InterchangeObject
Returns:
AUID of the identification representing this object's generation.
Throws:
InvalidParameterException - Generation tracking is not enabled for this object.
ObjectNotAttachedException - This object is not attached to a file from which generation information can be obtained.
See Also:
InterchangeObject.getGeneration(), Identification.getGenerationAUID()

getProperties

public Iterator<Property> getProperties()
Description copied from interface: InterchangeObject

Returns the set of properties of this interchange object, where each property contains its property definition and current value. The set contains both optional and required properties and any extended properties if present.

Important note: This is a low-level method that allows direct access to properties. If such access takes place, any semantic checking provided in named property get/set methods of the object is bypassed at the user's own risk.

Specified by:
getProperties in interface InterchangeObject
Returns:
Iterator over the set of properties of this interchange object.

getPropertyValue

public PropertyValue getPropertyValue(PropertyDefinition propDef)
                               throws NullPointerException,
                                      IllegalPropertyException,
                                      PropertyNotPresentException
Description copied from interface: InterchangeObject

Returns the requested property value of the object. The desired property data is identified by the given property definition.

Important note: This is a low-level method that allows direct access to properties. If such access takes place, any semantic checking provided in named property get/set methods of the object is bypassed at the user's own risk.

Specified by:
getPropertyValue in interface InterchangeObject
Parameters:
propDef - Property definition identifying the requested property.
Returns:
Corresponding property value.
Throws:
NullPointerException - The given property definition is null.
IllegalPropertyException - The given property is illegal for this interchange object's class.
PropertyNotPresentException - The given property is optional, but not currently present in this instance of the class.

setPropertyValue

public void setPropertyValue(PropertyDefinition propDef,
                             PropertyValue propVal)
                      throws NullPointerException,
                             IllegalPropertyException
Description copied from interface: InterchangeObject

Sets the value of the given property of this interchange object to the given value. If the selected property is optional but not yet present, this method will make the property present before setting its value.

Important note: This is a low-level method that allows direct access to properties. If such access takes place, any semantic checking such as that which is performed in all other named property get/set methods, is at the user's own risk.

Specified by:
setPropertyValue in interface InterchangeObject
Parameters:
propDef - Property definition identifying the property to set.
propVal - Value to set for the property.
Throws:
NullPointerException - One or both of the arguments is null.
IllegalPropertyException - The given property definition defines a property that is illegal for this object's class.
See Also:
InterchangeObject.getProperties(), InterchangeObject.getPropertyValue(PropertyDefinition), PropertyDefinition.getTypeDefinition(), TypeDefinition.createValue(Object)

isGenerationTracked

public boolean isGenerationTracked()
Description copied from interface: InterchangeObject

Returns true if generations are being tracked by the object. A value of true indicates that generation information will be available through the InterchangeObject.getGeneration() and InterchangeObject.getGenerationAUID() methods.

Calling the InterchangeObject.enableGenerationTracking() method will enable generation tracking for this object; calling the InterchangeObject.disableGenerationTracking() method will disable generation tracking for this object.

Generation tracking is disabled by default.

Specified by:
isGenerationTracked in interface InterchangeObject
See Also:
InterchangeObject.enableGenerationTracking(), InterchangeObject.disableGenerationTracking()

isPropertyPresent

public boolean isPropertyPresent(PropertyDefinition propDef)
                          throws NullPointerException,
                                 IllegalPropertyException
Description copied from interface: InterchangeObject

Returns true if the property identified by the given property definition is legal and present; otherwise returns false.

Important note: This is a low-level method that allows direct access to properties. If such access takes place, any semantic checking provided in named property get/set methods of the object is bypassed at the user's own risk.

Specified by:
isPropertyPresent in interface InterchangeObject
Parameters:
propDef - Property definition identifying an optional property of this interchange object to test for.
Returns:
Is the given property present for this interchange object?
Throws:
NullPointerException - The given property definition is null.
IllegalPropertyException - The given property is illegal for this interchange object's class.
See Also:
InterchangeObject.getDefinition(), ClassDefinition.getPropertyDefinitions(), InterchangeObject.getProperties()

omitOpionalProperty

public void omitOpionalProperty(PropertyDefinition propDef)
                         throws NullPointerException,
                                IllegalPropertyException
Description copied from interface: InterchangeObject

Omits the given optional property from this interchange object if the property definition is legal, optional and is present.

Important note: This is a low-level method that allows direct access to properties. If such access takes place, any semantic checking provided in named property get/set methods of the object is bypassed at the user's own risk.

Specified by:
omitOpionalProperty in interface InterchangeObject
Parameters:
propDef - Property definition identifying the optional property to omit from this interchange object.
Throws:
NullPointerException - The given property definition is null.
IllegalPropertyException - The given property definition is illegal for the class defining this interchange object.
See Also:
InterchangeObject.getDefinition(), ClassDefinition.getPropertyDefinitions(), InterchangeObject.getProperties()

toString

public final String toString()
Overrides:
toString in class Object
See Also:
Object.toString()

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
Parameters:
parent - XML parent element to append child nodes to.

Media Authoring
with Java API

(c) 2007-2008 Richard Cartwright, all rights reserved. Subject to the terms of the AAF SDK Public Source License.