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