tv.amwa.maj.industry (Media Authoring with Java API)
Date: 2016-02-05

# Package tv.amwa.maj.industry

Industry for manufacturing, storing and making instances of classes and meta-classes, referenced by names and registered identifiers.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  AAFSpecifiedClasses | Lists of classes implementing thoses specified for the Advanced Authoring Format (AAF).
  MediaEntity | Specifies a media class with metadata that can be persisted using the Java Persistence API.
  MediaEnumerationValue | Implemented by enumeration specifications that includes an integer value representing an AAF enumeration data type.
  MetadataObject | Specifies any object holding metadata that could be defined by the SMPTE registration authority and serialised to an AAF file, MXF file etc..
  PropertyValue | Specifies the type and current value of a property.
  Stream | Read and write access to stream type data.
  StreamResolver | Specifies a means for an application to resolve a URI reference to a stream to a means to read and write the data in that stream.
  TypeDefinitions | All AAF-specified type definitions as static constants in an interface.
  WeakReferenceTarget | Specifies that a metadata object can be the target of a weak reference.

- Class Summary
  Class | Description
  --- | ---
  FileStream | Provides access to stream data represented as a locally accessible file.
  Forge | Stamps out values of the model, record and union types, acting as a factory for these values and objects.
  JPAGenerator |
  LocalFileResolver | Default implementation of a stream resolver that resolves URIs for streams to stream access to local files.
  MediaEngine | An engine to allow the manipulation of metadata objects.
  MemoryResidentStream | Implementation of a stream as memory-resident byte buffer.
  StrongReferenceSet | Utilities for manipulating media entities stored in a strong reference set.
  StrongReferenceVector | Utilities for manipulating media entities stored in a strong reference variable array (vector).
  Warehouse | Warehouse with a dynamic inventory of classes, types, definitions and extendible enumeration items.
  WeakReference<T extends WeakReferenceTarget> | Represents and provides a means to resolve a weak references that are stored as a field of an implementing class.
  WeakReferenceSet<T extends WeakReferenceTarget> | Represents a set of weak references and provides a means to resolve them at runtime.
  WeakReferenceVector<T extends WeakReferenceTarget> | Represents a variable array (vector) of weak references and provides a means to resolve them at runtime.

- Enum Summary
  Enum | Description
  --- | ---
  EmitXMLClassIDAs | Specifies how the class identifier for the type of an object should be included with that object when it is serialized to XML.

- Annotation Types Summary
  Annotation Type | Description
  --- | ---
  ExtendibleEnumerationItem | Labels an AUID that represents an element of an extendible enumeration.
  HiddenClass | Labels a class introduced into a Java class hierarchy for convenience, between media classes, but not part of a registered hierarchy.
  MediaClass | Labels a Java class as one suitable for use as an AAF specified class, extension class or class from another namespace compatible with SMPTE registration.
  MediaListAppend | Labels a method as one used to append an element to an AAF-type variable length array of the given property name.
  MediaListGetAt | Labels a method as one used to get an element at an index into an AAF-type variable length array of the given property name.
  MediaListInsertAt | Labels a method as one used to insert an element at an index into an AAF-type variable length array of the given property name.
  MediaListPrepend | Labels a method as one used to prepend an element to an AAF-type variable length array of the given property name.
  MediaListRemoveAt | Labels a method as one used to remove an element at an index from an AAF-type variable length array for the property of the given name.
  MediaProperty | Labels a get method of a Java class to indicate that it provides access to the property value of an AAF class.
  MediaPropertyClear | Labels a method as one used to clear an AAF-type set or variable size array for the property of the given name.
  MediaPropertyContains | Labels a method as one used to test if an element is contained in an AAF-type set for the property of the given name.
  MediaPropertyCount | Labels a method as one used to count the number of elements in AAF-type variable length arrays or sets of the given property name.
  MediaPropertyRemove | Labels a method as one used to remove an element from an AAF-type set for the property of the given name.
  MediaPropertySetter | Labels a method as one used to set the value of a property of the given name.
  MediaSetAdd | Labels a method as one used to add an element to an AAF-type set for the property of the given name.

## Package tv.amwa.maj.industry Description

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.

# Core industrial units

Developer's of applications the create and manipulate media data using MAJ need to use the three main classes of static methods in the MAJ industry package. The heavy lifting of the MAJ API is carried out by the following three classes:

- New instances of objects and values can be made using the forge.
- Existing objects can be manipulated using the media engine.
- An registration and search capability for shared definitions, including all classes and types known to the running virtual machine, are stored in the runtime-dynamic warehouse.

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 `MediaEngine.initializeAAF()` method. User defined types are then registered.

# Link to Java

## Implemented interfaces

All classes that are to be manipulated by the media engine and serialized to and from files must implement the `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 `MediaEntity` interface, which extends the `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.

## Annotations

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:

- A Java class can become the specification of an AAF class definition by annotating it as a media class.
- The set and get methods of a class can become properties of a class by annotating methods with media property getter and media property setter annotations.
- For methods relating to properties of a collection, additional annotations are defined, including:
  - collection contains;
  - count the number of elements;
  - clear the collection to empty;
  - remove an element.
- To label a method used to add elements to a set, the specific add to set annotation is provided;
- For methods relating to elements of a list, the following annotations should be used:
  - append an element to the list;
  - prepend an element to the list;
  - get an element at a specific index;
  - insert an element at a specific index;
  - remove an element at a specific index.

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

## Data types

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.

### Baseline definitions

All baseline type definitions of AAF are contained in the `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 `AAFSpecifiedClasses` interface.

### Weak references

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 `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 `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 dictionary stores all the definitions used within a file.

### Weak reference collections

Sets of weak references are represented by a field of the owning class with generic type `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 `WeakReferenceVector`. The methods of the generic type can be used to provide the property manipulating methods of the owing class.

### Strong references

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.

### Strong reference collections

Sets of strong references are represented as a field of their owning class by a `java.util.Set`, parameterized by the type of element in the set. Static, generic methods for manipulating the set are provided in the `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 `java.util.List`, parameterized by the type of the element in the list. Static, generic methods for manipulating the list are provided in the `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.

### Streams

A value of stream type is represented by an implementation of the `Stream` interface. This interface provides a means to seek, read and write bytes to and from an underlying stream. A memory resident stream and a 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 streams in structured storage containers (AAF) or wrapped in KLV streams (MXF).

A mechanism is also provided to resolve a stream identifier reference to a specific stream location using the stream resolver. A default local file resolver provides access to local streams through the relevant methods of the media engine. Alternative stream resolvers can be implemented and used in place of the default one.

## Property type mapping table

The table below describes the data type mappings carried out by MAJ when getting and setting properties using the generic methods of the media engine and creating objects using the forge. For generic handling of individual property values, the PropertyValue interface is provided as a container for both the type definition and the Java-based representation of the value.

Type classification | Accepted Java types | Returned Java type
Integer | primitive `int`, `short`, `int` or `long` value. `Byte`, `Short`, `Integer` or `Long` value. A `String` representation of the number. `byte[]` or ByteBuffer value with enough bytes to represent the type of value. | `Byte`, `Short`, `Integer` or `Long` value, depending on integer bit size.
String | `String` `byte[]` or ByteBuffer UTF-16 encoding of the string. | `String`
Enumeration | Enumeration value of type `Enum`. Element name for the enumeration value. Symbol for the enumeration value. Numerical code for the enumeration value. `byte[]` or ByteBuffer encoding of the value. `boolean` or `Boolean` for the Boolean enumeration only. | Enumeration value of type `Enum` or primitive `boolean` for Boolean enumeration
Extendible Enumeration | Element value, which is an AUID. Element value encoded as a string, e.g. starting "`urn:smpte:ul:...`". Element name for the enumeration value. `byte[]` or ByteBuffer 16-byte encoding of the AUID value. | Element value, which is an AUID.
Stream | `byte[]` or ByteBuffer representation of the stream. To be improved with external file reference ... | Implementation of the `Stream` interface.
Record | Value implementing the associated interface specification, e.g. the interfaces in the `tv.amwa.maj.record` package. String representation of the value, e.g. "`3/4`" for a rational value. An array of property values in the property order of the record. `byte[]` or ByteBuffer representation of the record value. | Value implementing the associated interface specification, e.g. the interfaces in the `tv.amwa.maj.record` package.
Indirect | Unwrapped property value of the indirect value, which contains its actual type and value. | Unwrapped property value of the indirect value, which contains its actual type and value.
Opaque | `byte[]` or ByteBuffer representing the opaque value. | ByteBuffer representing the opaque value.
FixedArray | Array of elements of the array's underlying type. Array of property values. Collection of elements of the array's underlying type or property values. `byte[]` or ByteBuffer representing a sequence of elements of the array's underlying type. | Array of elements of the array's underlying type as an `Object[]`.
Strong Object Reference | Referenced object of the referenced type. property value containing the referenced value. | Referenced object of the referenced type.
Weak Object Reference | Referenced object of the referenced type. property value containing the referenced value. Name of target of the reference to be looked up and resolved in the warehouse. | Referenced object of the referenced type.
Set | Collection of objects of the referenced type or a collection of property values containing the referenced values. Array of objects of the referenced type or an array of property values containing the referenced values. A single value of the referenced type or a single property value to make a set of size one from. | Set of objects of the referenced type.
Variable Array | Collection of objects of the referenced type or a collection of property values containing the referenced values. Array of objects of the referenced type or an array of property values containing the referenced values. A single value of the referenced type or a single property value to make a set of size one from. | List of objects of the referenced type.

## Database mapping

A Java Persistence API configuration file for a given set of classes can be generated by MAJ using the static methods of the `JPAGenerator` class. To be able to persist AAF, pass in the lists of baseline classes.

See Also:
  `AutoGeneration`

(c)2007-2016 Richard Cartwright, all rights reserved. Licensed under Apache 2 license and subject to the AMWA IPR policy.