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

# Package tv.amwa.maj.exception

Specific exceptions thrown due to exceptional behaviour during the execution of method calls from the MAJ API.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  MAJException | Interface implemented by all exceptions that are specific to the MAJ API.
  NewForMAJ | This interfaces labels new exceptions introduced for this Java implementation of the AAF class model.

- Exception Summary
  Exception | Description
  --- | ---
  AdjacentTransitionException | Thrown when an operation on a sequence would result in two adjacent transitions within that sequence.
  AlreadyOpenException | Thrown when an attempt is made to open an AAF file that is already open.
  AlreadyUniquelyIdentifiedException | Thrown when an attempt is made to add a property to a class definition described as a unique identifier when the class already has a registered property that is a unique identifier.
  BadCloseException | Thrown when an attempt is made to open a file that has not yet been closed.
  BadLengthException | Thrown when an out of range length value is set for a component or fade in the current context.
  BadOpenException | Thrown when an attempt is made to perform an operation on a random access file that is not currently open.
  BadParameterException | Thrown when a lookup operation fails because the given parameter cannot be found in a known collection of values.
  BadPropertyException | Thrown when an optional property should be omitted in the current context.
  BadRateException | Thrown if an unacceptable edit rate is set for a source package's track.
  BadSampleOffsetException | Thrown when an offset into a segment or some file-based essence, specified by timecode or frames, is out of range.
  BadSizeException | Thrown when an array is not of the required number of elements.
  BadTypeException | Thrown when a method call on an object in the meta dictionary passes in the wrong type of property value as a parameter.
  ContainerWriteException | Thrown when writing to a data container fails.
  DataSizeException | Thrown when it has not been possible to allocate the requested or necessary amount of space for data storage.
  DuplicateEssenceKindException | Thrown when an attempt is made to add an essence kind to that supported by a codec definition that is already listed as supported by that codec.
  DuplicateException | Thrown when an attempt is made to add an element to a set that is already contained in that set.
  DuplicatePackageIDException | Thrown when an attempt is made to add essence or metadata to content storage when information with the same package id is already stored.
  DuplicateParameterException | Thrown when an attempt is made to add a parameter to an operation group that is already a parameter for that group.
  EndOfDataException | Thrown when an attempt is made to read beyond the end of a data stream.
  EssenceNotFoundException | Thrown when an attempt is made to remove some data from content storage that is not contained within that storage.
  EventSemanticsException | Thrown when an event is used in the wrong context.
  FilmDescriptorOnlyException | Thrown when an attempt is made to add an edgecode track to a source package that does not reference film essence.
  GenerationMethodNotSupportedException | Thrown when the generation of a package id is requested with a kind of generation method that is not supported.
  IllegalPropertyException | Thrown when a given property definition is illegal within the context of a metadata object.
  IllegalPropertyValueException | Thrown when a parameter to a method call of an object is outside the acceptable range or of the wrong type for that object in its current state.
  InconsistancyException | Thrown when an inconsistency occurs when searching an essence group.
  InstanceOverflowException | Thrown when the instance generator of a package id overflows.
  InsufficientSpaceException | Thrown when not enough space is available on the filing system or in a given buffer to save data.
  InsufficientTransitionMaterialException | Thrown when appending or inserting a given component to a sequence will result in insufficient material for the adjacent transition.
  InvalidDataDefinitionException | Thrown when an inappropriate data definition is used within the context of a method call.
  InvalidLinkageException | Thrown when traversal of the content in an essence group is not possible due to an invalid link.
  InvalidPackageTypeException | Thrown if the given package kind is not appropriate for a search operation.
  InvalidParameterException | Thrown whenever a method call parameter contains a value that is invalid in the current context.
  LeadingTransitionException | Thrown when the result of an operation would make the first component of a sequence a transition.
  NoMoreObjectsException | Thrown when a given parent of a tagged value definition is not known and so cannot be removed from its list of parent properties.
  NoPrefaceException | Thrown when a file does not contain a preface object.
  NotAnInterfaceException | Thrown when an interface, represented by a `Class` instance, to be implemented by a new class instance is not a Java interface.
  NotImplementedException | Thrown when a method is called that is not implemented in the MAJ API.
  NotOpenException | Thrown when an operation on a file cannot take place because the file is not in an opened state.
  NotReadableException | Thrown when a raw stream is not open and/or available for reading.
  NotSourceClipException | Thrown when adding a pulldown reference to a source package that does not contain a source clip.
  NotTapePackageException | Thrown when a request is made to find the name of a tape associated with a material package which is not describing tape-based material
  NotValidKeyException | Thrown when creating a KLV data key that does not map to a built-in type.
  NotWriteableException | Thrown when it is not possible to write to a file on the filing system.
  ObjectAlreadyAttachedException | Thrown when an attempt is made to attach an item to a collection that it already contains.
  ObjectNotAttachedException | Thrown when an interchange object is not attached to a preface object.
  ObjectNotFoundException | Thrown when a given object cannot be found in a collection, such as when a request is made to remove the item from the collection.
  OffsetSizeException | Thrown when a given offset exceeds the size of a file or the available space to extend storage for a file.
  PackageNotFoundException | Thrown when a given package identified with a package id cannot be found.
  ParameterNotFoundException | Thrown when a parameter to an operation cannot be found from its parameter id.
  PositionOutOfRangeException | Thrown when a given position, specified by frame count or timecode, is outside the the length of the referenced stream.
  PropertyAlreadyPresentException | Thrown when an attempt is made to create an optional property for an interchange object when a property with the same definition already exists for that object.
  PropertyNotPresentException | Thrown when an attempt is made to read the value of a property that is omitted from an interchange object.
  PulldownDirectionException | Thrown when an invalid pulldown direction is specified in the context of a source package.
  RationalRangeException | Thrown when a rational value is outside of the acceptable range in a given context.
  SegmentNotFoundException | Thrown when a given segment cannot be found within the segments of a selector.
  SingleChannelOpException | Thrown when an attempt is made to write samples into an essence stream that contains interleaved data.
  StreamFullException | Thrown when a stream has insufficient capacity to complete the requested write operation.
  TapeDescriptorOnlyException | Thrown if an operation relating to tape-based material is called on a source package that does not describe tape-based material.
  TimecodeNotFoundException | Thrown when a given timecode or offset is not available within a segment or package.
  TrackExistsException | Thrown when an attempt is made to add a track to a package where the given track id already exists.
  TrackNotFoundException | Thrown when a track cannot be found within a package.
  TraversalNotPossibleException | Thrown when a search operation cannot proceed.
  TypeNotFoundException | Thrown when a key cannot be resolved to a type definition.
  WrongOpenModeException | Thrown when an attempt is made to save data to a file that was not opened for writing or other modification.

## Package tv.amwa.maj.exception Description

Specific exceptions thrown due to exceptional behaviour during the execution of method calls from the MAJ API. These exceptions are loosely based on the result codes in the C-based AAF SDK.

## Design approach

This API is designed to provide AAF support using a design similar to that used by other Java APIs. The methods in the MAJ API interfaces package are designed to be similar to the methods in the C-based AAF SDK COM interfaces, as specified in file "`AAF.idl`". Rather than using in and out arguments with methods returning a result code, as defined in the COM interfaces, the MAJ API treats all method arguments as inputs:

- In cases where the C-based AAF SDK would return result code `AAFRESULT_SUCCESS`, a value is returned as the method output.
- In all other cases, a Java exception is thrown.

The following sections describe the approach taken to implementing result codes in a Java style in the MAJ API.

### Reuse of Java exceptions

Wherever possible in this API, Java's built in exceptions are used, such as those defined in the `java.lang` package. For example, instead of an `AAF_NULL_PARAM` result code being returned when an error due to a null pointer occurs within the execution of a method, the MAJ API throws a `NullPointerException` instead.

Where an AAF result code is a special kind of an existing built in Java exception, an exception is included in this package that extends the built in exception. For example, `BadLengthException` extends `IllegalArgumentException` as it represents the unexpected state where a given length value is illegal for a particular method call.

### AAF-specific exceptions

If no direct link to an Java built in exception can be identified, an AAF-specific exception is provided in this package that either directly extends `Exception` or `RuntimeException`. All such exceptions implement the `MAJException` interface. The choice for whether the exceptions are runtime exceptions or not is made as follows:

- Extends `Exception`: Exceptions that an application using this API should be expected to catch, e.g. to handle a case where searching for an item finds nothing or a file operation fails. An application or API is required by the Java compiler to provide code to catch these exceptions or throw them to a higher level API.
- Extends `RuntimeException`: Exceptions that occur during normal operation of a Java Virtual Machine at runtime, such as a call to a method with an illegal value. An application may catch these exceptions but is not required to do so by the Java compiler. Failure to catch these exceptions may result in the termination of the current thread.

Many of these exceptions can be linked to AAF SDK result codes, as listed in "`AAFResult.h`". Where this is the case, the description of the exception includes the equivalent result code.

### MAJ-specific exceptions

Certain exceptions have been introduced for behaviour specific to the MAJ API. These exceptions implement the `NewForMAJ` interface.

### Separate package for exceptions

A separate package has been used for the exceptions of this API as they are class implementations rather than interfaces. At the same time, these exceptions form a core part of the implementation-independent interfaces in the interfaces package. So that the interfaces can be distributed and managed separately from the implementations provided in this API, this separate exceptions package has been created.

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