use the new session manager interface
[java-idp.git] / src / edu / internet2 / middleware / shibboleth / common / NameIdentifierMapping.java
1 /*
2  * Copyright [2005] [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
17 package edu.internet2.middleware.shibboleth.common;
18
19 import java.net.URI;
20 import java.security.Principal;
21
22 import org.opensaml.SAMLNameIdentifier;
23
24 /**
25  * Defines a mechanism for converting back and forth between SAML Name Identifiers and local {@link LocalPrincipal}
26  * objects.
27  * 
28  * @author Walter Hoehn
29  */
30 public interface NameIdentifierMapping {
31
32         public static final String mappingNamespace = "urn:mace:shibboleth:namemapper:1.0";
33
34         /**
35          * @return the id of this mapping or <code>null</code> is it is not configured with one
36          */
37         public String getId();
38
39         /**
40          * Returns the Name Identifier format for this mapping.
41          * 
42          * @return the format
43          */
44         public URI getNameIdentifierFormat();
45
46         /**
47          * Maps a SAML Name Identifier to a local principal using the appropriate registered mapping. Must ensure that the
48          * SAML NameIdentifer is properly qualified.
49          * 
50          * @param nameId
51          *            the SAML Name Identifier that should be converted
52          * @param sProv
53          *            the provider initiating the request
54          * @param idProv
55          *            the provider handling the request
56          * @return the local principal
57          * @throws NameIdentifierMappingException
58          *             If the {@link NameMapper}encounters an internal error
59          * @throws InvalidNameIdentifierException
60          *             If the {@link SAMLNameIdentifier}contains invalid data
61          */
62         public Principal getPrincipal(SAMLNameIdentifier nameId, ServiceProvider sProv, IdentityProvider idProv)
63                         throws NameIdentifierMappingException, InvalidNameIdentifierException;
64
65         /**
66          * Maps a local principal to a SAML Name Identifier.
67          * 
68          * @param principal
69          *            the principal to map
70          * @param sProv
71          *            the provider initiating the request
72          * @param idProv
73          *            the provider handling the request
74          * @return the SAML name identifier
75          * @throws NameIdentifierMappingException
76          *             If the {@link NameMapper}encounters an internal error
77          */
78         public SAMLNameIdentifier getNameIdentifier(LocalPrincipal principal, ServiceProvider sProv, IdentityProvider idProv)
79                         throws NameIdentifierMappingException;
80
81         /**
82          * Cleanup resources that won't be released when this object is garbage-collected
83          */
84         public void destroy();
85
86 }