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 {@link 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 {@link java.lang.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, {@link tv.amwa.maj.exception.BadLengthException} extends {@link java.lang.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 {@link java.lang.Exception} or {@link java.lang.RuntimeException}. All such exceptions implement the {@link tv.amwa.maj.exception.MAJException} interface. The choice for whether the exceptions are runtime exceptions or not is made as follows:

- Extends {@link java.lang.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 {@link java.lang.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 {@link tv.amwa.maj.exception.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.