Plugin xref

From 0a90384a9c7d840e88d9636271e8393a514647a0 Mon Sep 17 00:00:00 2001 From: Leif Johansson Date: Tue, 28 Jul 2009 10:34:52 +0200 Subject: Import shibboleth ds 1.1.0 --- .../middleware/shibboleth/wayf/plugins/Plugin.html | 173 +++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 doc/src-xref/edu/internet2/middleware/shibboleth/wayf/plugins/Plugin.html (limited to 'doc/src-xref/edu/internet2/middleware/shibboleth/wayf/plugins/Plugin.html') diff --git a/doc/src-xref/edu/internet2/middleware/shibboleth/wayf/plugins/Plugin.html b/doc/src-xref/edu/internet2/middleware/shibboleth/wayf/plugins/Plugin.html new file mode 100644 index 0000000..0c6391a --- /dev/null +++ b/doc/src-xref/edu/internet2/middleware/shibboleth/wayf/plugins/Plugin.html @@ -0,0 +1,173 @@ + + + + +Plugin xref + + + +
View Javadoc
+
+1   /**
+2    * Copyright [2006] [University Corporation for Advanced Internet Development, Inc.]
+3    *
+4    * Licensed under the Apache License, Version 2.0 (the "License");
+5    * you may not use this file except in compliance with the License.
+6    * You may obtain a copy of the License at
+7    *
+8    * http://www.apache.org/licenses/LICENSE-2.0
+9    *
+10   * Unless required by applicable law or agreed to in writing, software
+11   * distributed under the License is distributed on an "AS IS" BASIS,
+12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+13   * See the License for the specific language governing permissions and
+14   * limitations under the License.
+15   */
+16  package edu.internet2.middleware.shibboleth.wayf.plugins;
+17  
+18  import java.util.Collection;
+19  import java.util.List;
+20  import java.util.Map;
+21  
+22  import javax.servlet.http.HttpServletRequest;
+23  import javax.servlet.http.HttpServletResponse;
+24  
+25  import org.opensaml.saml2.metadata.provider.MetadataProvider;
+26  
+27  import edu.internet2.middleware.shibboleth.wayf.IdPSite;
+28  
+29  /**
+30   * 
+31   * The Plugin interface is used to affect the 'hints' that the WAYF offers to the users.  
+32   * <p>
+33   * The WAYF can register any number of plugins.  Each plugin is called when the metadata is loaded or realoaded
+34   * (so it can do any indexing) and at the three entry points into the WAYF - Lookup (main entry), Search and Select.
+35   * Plugins are called in the order in which they are declared to the WAYF. 
+36   * <p>
+37   * Each plugin is called once when the user has made a selection.
+38   * <p>
+39   * For Search and Lookup, each plugin is called multiple times, once for each metadata provider which has 
+40   * been declared to this particular WAYF instance.  The plugin can return a context which is handed to subsequent calls.
+41   * <p>
+42   * The idea is that each plugin can affect the displayed lists of IdPs.  As a reminder the WAYF displays two lists of 
+43   * IdPs - the complete list, displayed either as a single list or a list of lists, and the hint list (which was
+44   * previously only populated from the _saml_idp cookie.  In the search case the WAYF displays a third list of
+45   * the search hits. 
+46   * <p>
+47   * When the plugin in called it is given the current set of potential IdPs as a Map from EntityID to {@link IdPSite}
+48   * and lists representing the current hint list and search results.  A Plugin can remove an entry from 
+49   * the map or the lists.  Additionally it can insert an IdPSite found in the Map into the hint or search lists.
+50   * Thus the plugin can restrict the number of sites that the WAYF instance displays in the 'complete list' and
+51   * can add or remove IdPs from the hint list.
+52   * <p>
+53   * At any stage the plugin can take control of the current request and redirect or forward it.  It signals that
+54   * it has done this to the WAYF by means of an exception.
+55   * <p> 
+56   *  The _saml_idp cookie handling code is written as a WAYF plugin.  Other plugins have been written to allow IdPs
+57   *  to be presented as hints based on the client's IP address or to redirect back to the SP once the choice of
+58   *  IdP has been made.
+59   *  <p>
+60   *  Object implementing this interface are created during WAYF discovery service initialization.  There are 
+61   *  expected to implement a constructor which takes a {@link org.w3c.dom.Element} as the only parameter and they are 
+62   *  created via this constructor, with the parameter being the appropriate section of the WAYF configuration file 
+63   *  
+64   * @version Discussion
+65   *
+66   */
+67  public interface Plugin {
+68  
+69          /**
+70           *  Whenever the WAYF discoveres that the metadata is stale, it reloads it and calls each plugin at this method.
+71           * 
+72           * @param metadata - where to get the data from.
+73           * @return the value which will be provided as input to subsequent calls to {@link #lookup Lookup} and 
+74           * {@link #search Search}
+75           */
+76          PluginMetadataParameter refreshMetadata(MetadataProvider metadata);
+77          
+78          /**
+79           * The WAYF calls each plugin at this entry point when it is first contacted.  
+80           * 
+81           * @param req - Describes the current request.  A Plugin might use it to find any appropriate cookies 
+82           * @param res - Describes the current response.  A Plugin might use it to redirect a the request. 
+83           * @param parameter Describes the metadata.
+84           * @param context Any processing context returned from a previous call.
+85           * @param validIdps The list of IdPs which is currently views as possibly matches for the pattern. 
+86           *                  The Key is the EntityId for the IdP and the value the object which describes 
+87           *                  the Idp 
+88           * @param idpList The set of Idps which are currently considered as potential hints.    
+89           * @return a context to hand to subsequent calls
+90           * @throws WayfRequestHandled if the plugin has handled the request (for instance it has
+91           * issues a redirect)
+92           *
+93           * Each plugin is called multiple times,
+94           * once for each metadata provider which is registered (Depending on the precise configuration of the WAYF
+95           * metadata providers whose metadata does not include the target may be dropped).  Initially the plugin is
+96           * called with a context parameter of <code>null</code>.  In subsequent calls, the value returned from
+97           * the previous call is passed in as the context parameter. 
+98           * 
+99           * The plugin may remove IdPSite objects from the validIdps list.
+100          * 
+101          * The plugin may add or remove them to the idpList.  IdPSite Objects which are to be added to the idpList 
+102          * should be looked up by EntityIdName in validIdps by EntityId.  Hence any metadata processing shoudl 
+103          * store the entityID. 
+104          * 
+105          */
+106         PluginContext lookup(HttpServletRequest req, 
+107                                                  HttpServletResponse res, 
+108                                                  PluginMetadataParameter parameter, 
+109                                                  Map<String, IdPSite> validIdps, 
+110                                                  PluginContext context, 
+111                                                  List<IdPSite> idpList) throws WayfRequestHandled;
+112 
+113         /**
+114          * This method is called when the user specified a search operation.  The processing is similar to 
+115          * that described for {@link #lookup lookup}.
+116          * Two additional paramaters are provided, the search parameter which was provided, and the current 
+117          * proposed list of candidate IdPs.  The plugin is at liberty to alter both the list of hints and the 
+118          * list of valid IdPs. 
+119          * 
+120          * @param req Describes the current request.  The Plugin could use it to find any appropriate cookies 
+121          * @param res Describes the result - this is needed if (for instance) a plung needs to change cookie values
+122          * @param parameter Describes the metadata
+123          * @param pattern The Search pattern provided
+124          * @param validIdps The list of IdPs which is currently views as possibly matches for the pattern.  
+125          *                  The Key is the Idp Name an the value the idp
+126          * @param context Any processing context returned from a previous call.
+127          * @param searchResult the resukt of any search
+128          * @param idpList The set of Idps which are currently considered as potential hints.  Each Idp is associated
+129          * with a numeric weight, where the lower the number is the more likely the IdP is to be a candidate.  
+130          * As descibed above the WAYF uses this to provide hint list to the GUI (or even to dispatch 
+131          * immediately to the IdP).  
+132          * @return a context to hand to subsequent calls
+133          * @throws WayfRequestHandled if the plugin has handled the request (for instance it has
+134          * issues a redirect)
+135          */
+136         PluginContext search(HttpServletRequest req, 
+137                                         HttpServletResponse res, 
+138                                         PluginMetadataParameter parameter, 
+139                                         String pattern, 
+140                                         Map<String, IdPSite> validIdps, 
+141                                         PluginContext context, 
+142                                         Collection<IdPSite> searchResult,
+143                                         List<IdPSite> idpList) throws WayfRequestHandled;
+144         
+145         /**
+146          * This method is called, for every plugin, after a user has selected an IdP.  The plugin is expected 
+147          * to use it to update any in memory state (via the {@link PluginMetadataParameter} parameter or permananent 
+148          * state (for instance by writing back a cookie.
+149          * @param req Describes the current request. 
+150          * @param res Describes the current response
+151          * @param parameter  Describes the metadata
+152          * @throws WayfRequestHandled if the plugin has handled the request (for instance it has
+153          * issues a redirect)
+154          */
+155         void selected(HttpServletRequest req, 
+156                       HttpServletResponse res, 
+157                       PluginMetadataParameter parameter, 
+158                       String idP) throws WayfRequestHandled;
+159 }
+
+ + -- cgit v1.1