AutoGeneration (Media Authoring with Java API)
Date: 2016-02-05

tv.amwa.maj.util

## Class AutoGeneration

- java.lang.Object
- - tv.amwa.maj.util.GenerationCore
  - - tv.amwa.maj.util.AutoGeneration

-     public class AutoGeneration
      extends GenerationCore

  Generate Java classes, interfaces and tests from meta dictionary extension descriptions. This command line utility generates a number of Java files from an XML meta dictionary description that can be compiled and used with the media engine and forge to create, serialize and deserialize values of the defined types.

  The typical usage is described in the following steps:

  1. Describe a meta dictionary in XML according to the registered data XML meta dictionary format. The namespace is:

     `http://www.smpte-ra.org/schemas/2001-1/2007/metadict`

     (See the file `AutoFramework.xml` in the MAJ distribution for an example, or generate some examples using the media engine's meta dictionary generator.)

  2. Run this java class as an application, providing a package name and the meta dictionary XML file:

     `java tv.amwa.maj.util.AutoGeneration` <package_name>`` <meta_dictionary_file>

  3. This generates a folder called `src` and a folder called `test` in the current working directory. These new folders contain the generated Java files according to the convention for turning a Java package name into a directory hierarchy. (Better configuration of the location will be provided in a future versions. Tests are not yet generated.)
  4. Optionally, patch the Java files. An automatic approach like this can never produce the most efficient code and may not work in all instances. It is recommended that you use an automatic patch mechanism as part of any build process.

  5. Compile the generated Java files according to your local build strategy. For example:

     - `cd src/com/portability4media/framework`
     - `javac -classpath $MAJ_JAR -d $COMPILE_TARGET *.java impl/*.java`

     Note that this code has been tested with Java 6.

  6. Initialize the compiled types and classes in your application. A factory is generated as part of the auto generation to enable you to safely initalize all the required components in the correct order. For example:

     <package_name>`.Factory.initialize();`

     Remember to initialize the AAF baseline classes first if these are required.

  7. Create instances of the classes described in the meta dictionary. Either use the generic factory methods in the media engine or the `make` method provided in the newly created factory. For example, for a class with no required properties:

     `` <class_name>`firstInstance =`
     `` <package_name>`.Factory.make("`<class_name>`");`

  Below is a brief summary of what this class does when it runs:

  - All class definitions create a Java interface and a class that implements that interface. Any inheritance described in the parent class specification is followed to create (abstract) Java classes and extension relationships.
  - All classes are cloneable and appropriate clone methods are added to the interfaces and implementations in such a way that an application does not have to perform a cast.
  - All classes can be tested for equality, can generate a hash code and write themselves out as a string. The string representation is according to the SMPTE 2001-1 registered data XML format.
  - All implementations have media class and media property annotations, amongst others, added so that the MAJ media engine can be used to manage instances of the extension class. At runtime, definitions of the classes can be accessed through the warehouse.
  - All property definitions for a class are added to the interface for that class. This is normally achieved by a pair of get and set methods. Properties of set and variable array type have append, add, remove, contains etc. methods generated to manage their elements.

  - All type definitions result in a static instance to represent them in an interface called `TypeDefinitions`. The following additional files are generated from these definitions:

    - All enumeration types result in the generation of a Java `enum`. This allows an application developer to manipulate enumeration values in the standard Java way.
    - All extendible extendible enumeration types result in a Java interface containing static constants representing each extendible enumeration element. This can be used by an application developer to use names to set enumeration values. These interface files can be used to seed values into the warehouse.

    - All record types result in the generation of an interface and a class that is an implementation of that interface. The interface has get and set methods for each member and the implementation provides basic equals, hash code, clone and to string methods.

      The string representation provides an XML representation of the value. A static parse method to read a value represented that way and turn it back into a value of the record type is also provided.

    - Although no additional file is generated, classes that have the potential to be weak reference targets have suitable code injected so that they can be referenced and dereferenced at runtime.

    At runtime, definitions of the types can be accessed through the warehouse.

  - A file of common constants is created, including the symbol space for the extension meta dictionary.

  - A factory class is generated with convenience methods for initializing and creating instances of the defined classes and types. The process of initialization includes:

    - Registering all the extension classes with the warehouse.
    - Registering all of the extendible enumeration values with the warehouse.
    - Registering the implementing classes for all record type values.
    - Registering all the extension type definitions with the warehouse.

    The factory also contains methods to create and parse values of the extension record types.

- - ### Field Summary

    - ### Fields inherited from class tv.amwa.maj.util.GenerationCore

      `LINE_WIDTH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AutoGeneration()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `main(String[] args)`

    - ### Methods inherited from class tv.amwa.maj.util.GenerationCore

      `makeDirectories`

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### AutoGeneration

          public AutoGeneration()

  - ### Method Detail

    - #### main

          public static final void main(String[] args)

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