Add-on System¶

This section describes the add-on system from the perspective of a developer.
The implementation of the add-on system is located in the maven module with the group Id org.openecard and the artifact Id addon.
All classes are in a sub namespace of org.openecard.addon. The module is divided into the following five packages:

org.openecard.addon
In this package are the main classes of the add-on system, for example the AddonManager or the different AddonRegistries.
org.openecard.addon.bind
This package includes all classes representing the interface between an addon and a specific binding. That is to say, here are the classes needed to convert a specific request, for example a HTTP request that arrives via the localhost binding, into a generic request, which is independent from binding and vice versa for the response.
org.openecard.addon.ifd
In here are the classes that specify the interface for an IFD protocol and the factory to instantiate such a protocol.
org.openecard.addon.manifest
This package accumulates all classes needed to convert (automatically) between the XML represantation of the add-on description and it's java object pendants.
org.openecard.addon.sal
In here are the classes that specify the interface for an SAL protocol and the factory to instantiate such a protocol.

Types of add-ons¶

In the context of Open eCard App, the terms add-on, plug-in and extension are defined as follows.

Add-on is the generic term for a component that enhances the functionality of the Open eCard App.

Extensions are independent from the context. Moreover, they are included directly into
the user interface and can be executed by the user. For instance, an add-on that provides a
PIN change functionality for smart cards is classified as an extension.

Plug-ins depend on the context in which the user uses the application. Performing
an authentication to a service using a particular smart card, for instance, requires a plug-in
which is capable of providing such functionality. Subsequently, plug-ins require a communication
with bindings to interact with external applications and services. Furthermore,
we distinguish between IFD, SAL, and application plug-ins.

Add-on development¶

This section describes the steps to take when developing an add-on.
As first step a new XML file called Addon.xml in the META-INF directory of the project should be created and the fields that describe the general part of the add-ons can already be filled.
An example file for a PIN Management addon could look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AddonBundleDescription>
    <ID>PIN-Plugin</ID>
    <Version>1.0</Version>
    <About />
    <License />
    <LocalizedName xml:lang="DE">PIN Verwaltung</LocalizedName>
    <LocalizedDescription xml:lang="DE">Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
    </LocalizedDescription>
    <LocalizedName xml:lang="EN">PIN Management</LocalizedName>
    <LocalizedDescription xml:lang="EN">Management of PIN/ PUK and possibly other secrets of the smart-card.</LocalizedDescription>
    <Logo>images/logo.png</Logo>
    <ConfigDescription />
    <BindingActions />
    <ApplicationActions />
    <IFDActions />
    <SALActions />
</AddonBundleDescription>

As can be seen, some fields can be localized. That fields are: LocalizedName, LocalizedDescription and About
The next step is to think about what actions should be offerd by the add-on and of what type these actions are.
For the PIN management example there are two actions. An action to change a PIN and a second action to unblock a PIN.
These actions are not of type ProtocolPlugin nor AppPluginAction, but of type AppExtensionAction, as they expand the function of the Open eCard App independent from a context.
This means two classes implementing the AppExtensionAction interface need to be added to the project and the two AppExtensionActionDescription that belong to them need to be added to the XML description.
Assume we are working in the org.openecard.plugins.pinplugin namespace and the two actions are called ChangePINAction and UnblockPINAction, the resulting XML would now look similar to this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<AddonBundleDescription>
    <ID>PIN-Plugin</ID>
    <Version>1.0</Version>
    <About />
    <License />
    <LocalizedName xml:lang="DE">PIN Verwaltung</LocalizedName>
    <LocalizedDescription xml:lang="DE">Verwaltung von PIN/ PUK und gegebenenfalls anderen Geheimnissen der Chipkarte.
    </LocalizedDescription>
    <LocalizedName xml:lang="EN">PIN Management</LocalizedName>
    <LocalizedDescription xml:lang="EN">Management of PIN/ PUK and possibly other secrets of the smart-card.</LocalizedDescription>
    <Logo>images/pin-management.png</Logo>
    <ConfigDescription />
    <BindingActions />
    <ApplicationActions>
        <AppExtensionActionDescription>
            <ID>ChangePINAction</ID>
            <ClassName>org.openecard.plugins.pinplugin.ChangePINAction</ClassName>
            <LocalizedName xml:lang="DE">PIN ändern</LocalizedName>
            <LocalizedDescription xml:lang="DE">Mit dieser Aktion können Sie ihre PIN ändern.</LocalizedDescription>
            <LocalizedName xml:lang="EN">Change PIN</LocalizedName>
            <LocalizedDescription xml:lang="EN">With this action you can change your PIN.</LocalizedDescription>
            <ConfigDescription />
        </AppExtensionActionDescription>
        <AppExtensionActionDescription>
            <ID>UnblockPINAction</ID>
            <ClassName>org.openecard.plugins.pinplugin.UnblockPINAction</ClassName>
            <LocalizedName xml:lang="DE">PIN entsperren</LocalizedName>
            <LocalizedDescription xml:lang="DE">Mit dieser Aktion können Sie ihre PIN entsperren.</LocalizedDescription>
            <LocalizedName xml:lang="EN">Unblock PIN</LocalizedName>
            <LocalizedDescription xml:lang="EN">With this action you can unblock your PIN.</LocalizedDescription>
            <ConfigDescription />
        </AppExtensionActionDescription>
    </ApplicationActions>
    <IFDActions />
    <SALActions />
</AddonBundleDescription>

For the actual implementation part of the add-on, the following has to be considered.
The actions need to implement the AppExtensionAction interface, which itself extends the FactoryBaseType interface.
Altogether, three functions are to be implemented:

void execute();
the actual logic of the action, in this case the PIN change, will take place here
void init(Context context) throws FactoryInitializationException;
initialization of the action; the given Context allows access to components of the Open eCard App like UserConsent or Dispatcher
void destroy();
closing resources and further cleanup.