Industry for manufacturing, storing and making instances of classes and meta-classes, referenced by names and registered identifiers. This package includes the tools required to carry out the runtime linkage between the Java programming language and media-specific standards from AMWA and SMPTE. Also included are tools to generate database mappings and schema.
The package is generic and permits types other than those defined for AAF from being used to write an application. This package has been designed to ensure full support for the AAF meta model and has been tested for the AAF object model but is not tied to it.
Every virtual machine needs to have a warehouse full of all classes, types, enumerations elements etc. before useful applications can be written Most applications will need to start by registering all the AAF classes and types etc. using the convenience static method {@link tv.amwa.maj.industry.MediaEngine#initializeAAF() MediaEngine.initializeAAF()} method. User defined types are then registered.
All classes that are to be manipulated by the {@linkplain tv.amwa.maj.industry.MediaEngine media engine} and serialized to and from files must implement the {@link tv.amwa.maj.industry.MetadataObject MetadataObject} interface. This is an empty interface with no additional requirements and is used to signal to MAJ that you want to permit the object to be treated as an item of media metadata.
Any classes that are also to be treated as persistent entities should instead implement the {@link tv.amwa.maj.industry.MediaEntity MediaEntity} interface, which extends the {@link tv.amwa.maj.industry.MetadataObject MetadataObject} interface. A media interface gas a unique persistent identifier for its type for the database where it is to be stored. It also has a list index value for occasions when the entity is part of an ordered list and that list needs to be persisted in the correct order in a database.
This package defines a number of Java annotations that can be used to enhance a Java class and provide additional information that is required to use the class for representing media data. The annotations are read at runtime and used to plumb the class into the capabilities of the media engine and input/output libraries. The annotations provide missing information, such as SMPTE universal labels and AAF type names that cannot be extracted directly from the Java class itself. Specifically:
In general, the inheritance class hierarchy of the Java classes is mirrored in the media class definitions. However, sometimes the mechanics of an application require more classes in the Java class hierarchy than are represented in the media class hierarchy. The extra Java classes should be annotated as {@linkplain tv.amwa.maj.industry.HiddenClass hidden classes}.
In general, where an obvious mapping between an AAF data type and a Java data type exist, such as
between an Int32 and an int
, this is used and documented in the appropriate
package. Some special case mappings not covered elsewhere are described in this section.
All baseline type definitions of AAF are contained in the {@link tv.amwa.maj.industry.TypeDefinitions TypeDefinitions} interface. Static reference can be made to these types and the interface can be implemented to provide localised access.
All baseline classes of the AAF object model to the version currently supported by MAJ are listed in the static fields of the {@link tv.amwa.maj.industry.AAFSpecifiedClasses AAFSpecifiedClasses} interface.
Some references between objects in an AAF-based meta model are weak, allowing the target of the reference to be shared by many sources. The reference is made by using the unique identifier of the targeted item. All potential targets of weak references are required to implement the {@link tv.amwa.maj.industry.WeakReferenceTarget WeakReferenceTarget} interface, which provides a unique name and identifier by which the item can be referenced.
The source of the reference should be implemented as a field within a class as the generic class {@link tv.amwa.maj.industry.WeakReference WeakReference}. This provides mechanisms within a specific Java virtual machine for resolving and persisting weak references. However, the get and set methods for the property should use the target object itself.
When persisted to a file, a container within the file will store all the weak reference targets so that they can be resolved at runtime. For example, the {@linkplain tv.amwa.maj.model.Dictionary dictionary} stores all the {@linkplain tv.amwa.maj.model.DefinitionObject definitions} used within a file.
Sets of weak references are represented by a field of the owning class with generic type {@link tv.amwa.maj.industry.WeakReferenceSet WeakReferenceSet}. The methods of the generic type can be used to provide the property manipulating methods of the owing class.
Similarly, lists of weak references are represented by a field of the owning class with generic type {@link tv.amwa.maj.industry.WeakReferenceVector WeakReferenceVector}. The methods of the generic type can be used to provide the property manipulating methods of the owing class.
A strong reference in MAJ is represented by the interface for the target class. As the source of the reference owns the target, MAJ is very particular to clone all implementing objects on setting and getting the values to avoid side effects. Be aware, however, that Java cloning is shallow and a developer still needs to take care to avoid side effects if setting multiple strong reference type properties with the same instance of a class.
Sets of strong references are represented as a field of their owning class by a {@link java.util.Set java.util.Set}, parameterized by the type of element in the set. Static, generic methods for manipulating the set are provided in the {@link tv.amwa.maj.industry.StrongReferenceSet StrongReferenceSet} class and these can be used as a basis the methods that manipulate the value of the set property.
Similarly, lists of string references are represented as a field of their owning class by a {@link java.util.List java.util.List}, parameterized by the type of the element in the list. Static, generic methods for manipulating the list are provided in the {@link tv.amwa.maj.industry.StrongReferenceVector StrongReferenceVector} class and these can be used as a basic for the methods that manipulate the value of the list property. For lists, this has the specific advantage that list order indexes used when persisting the list to a database are maintained for you.
It is recommended that synchronized sets and lists are used in implementation to avoid runtime clashes.
A value of {@linkplain tv.amwa.maj.meta.TypeDefinitionStream stream type} is represented by an implementation of the {@link tv.amwa.maj.industry.Stream Stream} interface. This interface provides a means to seek, read and write bytes to and from an underlying stream. A {@linkplain tv.amwa.maj.industry.MemoryResidentStream memory resident stream} and a {@linkplain tv.amwa.maj.industry.FileStream basic file stream for raw essence access} are provided in this package. File-type-specific stream access is provided by implementations of this class for, for example for {@linkplain tv.amwa.maj.io.aaf.AAFStream streams in structured storage containers (AAF)} or {@linkplain tv.amwa.maj.io.aaf.MXFStream wrapped in KLV streams (MXF)}.
A mechanism is also provided to resolve a stream identifier reference to a specific stream location using the {@linkplain tv.amwa.maj.industry.StreamResolver stream resolver}. A default {@linkplain tv.amwa.maj.industry.LocalFileResolver local file resolver} provides access to local streams through the relevant methods of the {@linkplain tv.amwa.maj.industry.MediaEngine media engine}. Alternative stream resolvers can be implemented and used in place of the default one.
The table below describes the data type mappings carried out by MAJ when {@linkplain tv.amwa.maj.industry.MediaEngine#getPropertyValue(tv.amwa.maj.industry.MetadataObject, java.lang.String) getting} and {@linkplain tv.amwa.maj.industry.MediaEngine#setPropertyValue(tv.amwa.maj.industry.MetadataObject, java.lang.String, java.lang.Object) setting} properties using the generic methods of the {@linkplain tv.amwa.maj.industry.MediaEngine media engine} and creating objects using the {@linkplain tv.amwa.maj.industry.Forge forge}. For generic handling of individual property values, the {@linkplain tv.amwa.maj.industry.PropertyValue PropertyValue} interface is provided as a container for both the {@linkplain tv.amwa.maj.meta.TypeDefinition type definition} and the Java-based representation of the value.
Type classification | Accepted Java types | Returned Java type |
{@linkplain tv.amwa.maj.meta.TypeDefinitionInteger Integer} |
|
{@link java.lang.Byte}, {@link java.lang.Short}, {@link java.lang.Integer} or {@link java.lang.Long} value, depending on integer bit size. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionString String} |
|
{@link java.lang.String} |
{@linkplain tv.amwa.maj.meta.TypeDefinitionEnumeration Enumeration} |
|
Enumeration value of type {@link java.lang.Enum} or primitive boolean for Boolean enumeration |
{@linkplain tv.amwa.maj.meta.TypeDefinitionExtendibleEnumeration Extendible Enumeration} |
|
Element value, which is an {@linkplain tv.amwa.maj.record.AUID}. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionStream Stream} |
|
Implementation of the {@link tv.amwa.maj.industry.Stream Stream} interface. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionRecord Record} |
|
Value implementing the {@linkplain tv.amwa.maj.meta.TypeDefinitionRecord#getSpecification()
associated interface specification}, e.g. the interfaces in the
tv.amwa.maj.record package. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionIndirect Indirect} |
|
Unwrapped {@linkplain tv.amwa.maj.industry.PropertyValue property value} of the indirect value, which contains its actual type and value. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionIndirect Opaque} |
|
{@linkplain java.nio.ByteBuffer} representing the opaque value. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionFixedArray FixedArray} |
|
Array of elements of the array's underlying type as an Object[] . |
{@linkplain tv.amwa.maj.meta.TypeDefinitionStrongObjectReference Strong Object Reference} |
|
Referenced object of the referenced type. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionWeakObjectReference Weak Object Reference} |
|
Referenced object of the referenced type. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionSet Set} |
|
{@linkplain java.util.Set Set} of objects of the referenced type. |
{@linkplain tv.amwa.maj.meta.TypeDefinitionVariableArray Variable Array} |
|
{@linkplain java.util.List List} of objects of the referenced type. |
A Java Persistence API configuration file for a given set of classes can be generated by MAJ using the static methods of the {@link tv.amwa.maj.industry.JPAGenerator JPAGenerator} class. To be able to persist AAF, pass in the lists of {@linkplain tv.amwa.maj.industry.AAFSpecifiedClasses baseline classes}.
@see tv.amwa.maj.util.AutoGeneration