Programming the V4 Installer

The Installer is written in Java.  It presented to the end user via an ant script with three "targets":

• install – This is used to install and update (calls install-nocopy).

• install-nocopy – Used primarily on Windows but available on all platforms. It does an install or upgrade on a "populated" build environment (calls build-war)

• build-war – Rebuilds the war file for an existing install.

The ant script combines these appropriately 

These targets prompt for user input, with it being possible to use properties to provide values - ultimately allowing for an unattended install.

However it is quite possible to write Java code  control the installation operation.

Extending the Installer Programmatically

The main point of extension is the InstallerProperties interface and the concrete (and extendable) InstallerPropertiesImpl class. This encapsulates everything about the install and the shipped implementation consults properties or the user in the same way that the current ant based build does. It is extremely likely that InstallerProperties will be extended during the life of V4 with suitable default methods. For instance slip-streaming in a case such as https://shibboleth.atlassian.net/browse/IDP-553 would be done this way.

Installation classes

The classes which do the work of the install are

• CopyDistribution

• V4Install

• BuildWar

The install-nocopy target implemented by calling V4Install  and then BuildWar. The install target is implemented by calling all three.

These are also API classes, but they are "locked down" and not suitable for extension:

• They are final

• The export one public constructor

• They normally export one public method execute()

The idea is that these functions may be called, but not extended. This gives us room to make more changes to their implementation during the life of V4.

Support Classes

The support classes are not intended for extension without the Shibboleth project and are all marked final. Where made possible by the rest of our code base their methods are marked protected. The classes are:

• CurrentInstallState - encapsulates the state of the install when the installation started

• InstallerSupport - some widely used helper functions

• PropertiesWithComments - allows manipulation of property files during install (and occasionally during upgrade). The main feature is comment-respecting property replacement and property rename.

Metadata Generation

The V4Install class also has a method setMetadataGenerator(MetadataGenerator) where MetadataGenerator is a public interface with three methods

1. setOutput(@Nonnull File where) which sets where the file is to be generated.

2. setParameters(@Nonnull final MetadataGeneratorParameters what) which sets the parameters from which the metadata may be generated

3. generate() to write the metadata file

The setMetadataGenerator method is defaulted suitably.

You can implement your own metadata generation by implementing a MetadataGenerator and installing it appropriately.

Property-Driven Install

PropertyDrivenInstallation is an easier way to affect much if the installation behavior.