Open eCard

{{toc}}

h1. Add-on System

On this wiki page you'll find detailed information about the add-on development like the different kinds of add-ons and how they are enabled to communicate with core application.

h2. Definition of Add-on in the Open eCard context

_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.

h2. Add-on Types

h3. IFD Plug-ins

h3. SAL Plug-ins

h3. Application Plug-ins

h3. Application Extensions

h2. Architecture of an Add-on package

h3. General architecture

h3. The Add-on Manifest

h3. Types available in the configuration

h3. Configuration of an Add-on in the client

h2. Add-on Implementation

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.

h1. 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.

h1. 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:

<pre>

<?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>

</pre>

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:

<pre>

<?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>

</pre>

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.