The programming interfaces are preliminary and may change

The Plugin interface is used to affect the 'hints' that the Discovery Service offers to the users.

The Discovery Service can register any number of plugins. Each plugin is called when the metadata is loaded or reloaded (so it can do any indexing) and at the three entry points into the Discovery Service - Lookup (main entry), Search and Select. Plugins are called in the order in which they are declared to the Discovery Service .

Each plugin is called once when the user has made a selection.

For Search and Lookup, each plugin is called multiple times, once for each metadata provider which has been declared to this particular Discovery Service instance. The plugin can return a context which is handed to subsequent calls.

The idea is that each plugin can affect the displayed lists of IdPs. As a reminder the Discovery Service displays two lists of IdPs - the complete list, displayed either as a single list or a list of lists, and the hint list. In the search case the Discovery Service displays a third list of the search hits.

When the plugin in called it is given the current set of potential IdPs as a Map from EntityID to IdPSite and lists representing the current hint list and search results. A Plugin can remove an entry from the map or the lists. Additionally it can insert an IdPSite found in the Map into the hint or search lists. Thus the plugin can restrict the number of sites that the Discovery Service instance displays in the 'complete list' and can add or remove IdPs from the hint list.

At any stage the plugin can take control of the current request and redirect or forward it. It signals that it has done this to the Discovery Service by means of an exception.

The _saml_idp cookie handling code is written as a Discovery Service plugin. Other plugins have been written to allow IdPs to be presented as hints based on the client's IP address or to redirect back to the SP once the choice of IdP has been made.

Object implementing the plugin interface are created during Discovery Service initialization. There are expected to implement a constructor which takes a org.w3c.dom.Element as the only parameter and they are created via this constructor, with the parameter being the appropriate section of the WAYF configuration file.

Developers interested in deploying custom plugins are referred to the module in edu.internet2.middleware.shibboleth.wayf.plugins and the Cookie plugin documented in DsUserInterface#Cookie