Interface Compatibility Layer

Over time, a number of different HLA interface specifications have been released. Backwards compatibility between these specifications has not been good, and as such, a number of API differences exist between them. Portico has to support many of these interfaces, and as such, have to contend with the incompatibilities that exist between them.

The Problem
To make use of the types from a specific API would mean those types would need to be present even when they are not being used by federate code. For example, if Portico were to internally make use of an exception type that only existed in the IEEE 1516 specification, that type would need to be shipped with the Portico client jar file containing the 1.3 interfaces. This is clearly inelegant.

The Solution
Portico prefers to treat the HLA interface specifications as a kind of "skin" on the outside of the RTI. In this outermost layer, all specification-specific types are translated into a corresponding type from the "compatibility package". From there on in, the Portico-specific compatibility types are used, with the use of any interface-specific types within RTI code is strictly prohibited.

As callbacks or responses are returned to the outermost layer, they are translated back into a type specific to the interface, thus completing the illusion.

The Compatibility Layer
Interface incompatibilities often come in two forms:


 * Differing Collection Types (handle sets etc...)
 * Differing Exception Types

Some differences introduce new or differing APIs, while others are just naming changes. The compatibility layer is also broken up into two separate sections. The first deals with collections, while the second with exceptions.

Collections
Internally, Portico uses native Java collections such as Lists and Maps as containers. Thus, all HLA-specific set types have to be translated to-and-from standard Java collections before being used within Portico. For an example of how this is done, see the code for the  class.

As all HLA collection types are interfaces that have to be implemented, there is a separate package for each specification. All these packages are held in the  package:


 * : Contains implementation code for both HLA 1.3 and Annex A (rti-ng compatible) interfaces
 * : Contains implementation code IEEE 1516 interface

These packages also include things like FOM parsers,  implementations and so forth.

Exceptions and Other Types
There are many changes to exception types between the various specifications (especially from 1.3 to 1516). For the most part, the incompatibilities stem from the standard committee renaming exceptions even though they perform exactly the same purpose (don't ask me why).

To solve this problem, a set of Portico-specific exception types was created. It is the role of the interface-specific layer (mentioned above) to perform the necessary mapping between the interface exception and the internal Portico exception.

All the Portico specific exception types are stored in the package. *ALL* internal Portico types should only ever use the exceptions from that package and NEVER exceptions from an interface specific package. In the event that an unrecognised exception is received in the interface layer and no mapping can occur, an  is thrown instead (embedding the original exception as the cause).