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

tv.amwa.maj.io.file

## Class AAFFile

- java.lang.Object
- - tv.amwa.maj.io.file.AAFFile

- All Implemented Interfaces:
    Serializable, AAFFile

      public class AAFFile
      extends Object
      implements AAFFile, Serializable

  TODO implemenetation, head scratching, comments and tests

  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `AAFFile(FileDescriptor aafFile)` Creates and initilizes an AAF file from a Java file descriptor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static AAFFile` | `castFromInterface(AAFFile alien)` Cast a `AAFFile` value from the generic interface to this implementation of the interface.
    `void` | `close()` Dissociates this AAFFile from its storage.
    `DictionaryImpl` | `getDictionary()` Returns the dictionary that contains all types of AAF definition objects for the file.
    `PrefaceImpl` | `getPreface()` Returns the preface associated with this file.
    `FileRev` | `getRevision()` Returns the revision of the file.
    `void` | `open()` Associates this AAFFile with the storage to which it is to be associated.
    `void` | `save()` If this AAFFile is open, all unsaved changes made to the contents of this object are saved.
    `void` | `saveCopyAs(AAFFile destFile)` Copies the contents of this file to a given destination file.

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

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

- - ### Constructor Detail

    - #### AAFFile

          public AAFFile(FileDescriptor aafFile)
                  throws NullPointerException

      Creates and initilizes an AAF file from a Java file descriptor. This method makes no attempt to check the validity of the given file descriptor or whether the file it specifies exists and can be accessed.

      Parameters:
        `aafFile` - File descriptor for an AAF file.
      Throws:
        `NullPointerException` - Argument is null.

  - ### Method Detail

    - #### castFromInterface

          public static final AAFFile castFromInterface(AAFFile alien)
                                                 throws NullPointerException

      Cast a `AAFFile` value from the generic interface to this implementation of the interface. If the given value is not a native implementation, a copy will be instanciated using get and set methods.

      Parameters:
        `alien` - A potentially alien implementation of an instance of the AAFFile interface.
      Returns:
        Instance of this class that is equal to the given value and that is an instance of this concrete implementation.
      Throws:
        `NullPointerException` - Argument is null.

    - #### close

          public void close()
                     throws NotOpenException

      Description copied from interface: `AAFFile`

      Dissociates this AAFFile from its storage. Any AAF objects which were contained within this object will then no longer be available to the client.

      If the client is maintaining any references to any objects which are contained in this object, those objects will be marked as dissociated, and methods on them will fail.

      Any unsaved changes will be written to the file before the close operation is complete.

      Specified by:
        `close` in interface `AAFFile`
      Throws:
        `NotOpenException` - This object is not already open.
      See Also:
        `AAFFile.close()`

    - #### getDictionary

          public DictionaryImpl getDictionary()

      Description copied from interface: `AAFFile`

      Returns the dictionary that contains all types of AAF definition objects for the file. Note that the dictionary is automatically created when the preface is created.

      Specified by:
        `getDictionary` in interface `AAFFile`
      Returns:
        The dictionary of this file.
      See Also:
        `AAFFile.getDictionary()`

    - #### getPreface

          public PrefaceImpl getPreface()
                                 throws NotOpenException,
                                        NoPrefaceException

      Description copied from interface: `AAFFile`

      Returns the preface associated with this file. If this object has never been associated with a file, a new empty preface will be created and returned. Note that the preface is automatically created when the file object is created.

      Specified by:
        `getPreface` in interface `AAFFile`
      Returns:
        Preface of the file.
      Throws:
        `NotOpenException` - The object is not open.
        `NoPrefaceException` - The object contains no preface.
      See Also:
        `AAFFile.getPreface()`

    - #### getRevision

          public FileRev getRevision()
                              throws NotOpenException

      Description copied from interface: `AAFFile`

      Returns the revision of the file.

      Specified by:
        `getRevision` in interface `AAFFile`
      Returns:
        Revision of the file.
      Throws:
        `NotOpenException` - The object is not open.
      See Also:
        `AAFFile.getRevision()`

    - #### open

          public void open()
                    throws AlreadyOpenException

      Description copied from interface: `AAFFile`

      Associates this AAFFile with the storage to which it is to be associated. It will then be possible to access objects within this file.

      Specified by:
        `open` in interface `AAFFile`
      Throws:
        `AlreadyOpenException` - This object has already been opened.
      See Also:
        `AAFFile.open()`

    - #### save

          public void save()
                    throws NotOpenException,
                           WrongOpenModeException,
                           InsufficientSpaceException

      Description copied from interface: `AAFFile`

      If this AAFFile is open, all unsaved changes made to the contents of this object are saved.

      Specified by:
        `save` in interface `AAFFile`
      Throws:
        `NotOpenException` - The object is not open.
        `WrongOpenModeException` - This object is not open for writing or modification.
        `InsufficientSpaceException` - There is insufficient space in the storage to save the contents of this object.
      See Also:
        `AAFFile.save()`

    - #### saveCopyAs

          public void saveCopyAs(AAFFile destFile)
                          throws NotOpenException,
                                 NotWriteableException

      Description copied from interface: `AAFFile`

      Copies the contents of this file to a given destination file. Requires that the destination file be open, writable or modifiable, and not yet contain any objects.

      Specified by:
        `saveCopyAs` in interface `AAFFile`
      Parameters:
        `destFile` - File to receive a copy of the contents of this file.
      Throws:
        `NotOpenException` - The destination file is not open.
        `NotWriteableException` - The destination file cannot be written. One reason may be that it already contains objects.
      See Also:
        `AAFFile.saveCopyAs(tv.amwa.maj.model.AAFFile)`

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