Added javadoc for NameMapper classes.
authorwassa <wassa@ab3bd59b-922f-494d-bb5f-6f0a3c29deca>
Wed, 21 Jan 2004 04:49:20 +0000 (04:49 +0000)
committerwassa <wassa@ab3bd59b-922f-494d-bb5f-6f0a3c29deca>
Wed, 21 Jan 2004 04:49:20 +0000 (04:49 +0000)
git-svn-id: https://subversion.switch.ch/svn/shibboleth/java-idp/trunk@829 ab3bd59b-922f-494d-bb5f-6f0a3c29deca

src/edu/internet2/middleware/shibboleth/common/NameIdentifierMapping.java
src/edu/internet2/middleware/shibboleth/common/NameMapper.java
src/edu/internet2/middleware/shibboleth/common/PrincipalNameIdentifier.java
src/edu/internet2/middleware/shibboleth/hs/HSNameIdentifierMapping.java
src/edu/internet2/middleware/shibboleth/hs/HSNameMapper.java
src/edu/internet2/middleware/shibboleth/hs/provider/AQHNameIdentifierMapping.java
src/edu/internet2/middleware/shibboleth/hs/provider/CryptoShibHandle.java
src/edu/internet2/middleware/shibboleth/hs/provider/SharedMemoryShibHandle.java

index a104097..1d8484e 100644 (file)
@@ -52,14 +52,40 @@ import java.net.URI;
 import org.opensaml.SAMLNameIdentifier;
 
 /**
+ * Defines a mechanism for converting SAML Name Identifiers to local <code>AuthNPrincipal</code>
+ * objects.
+ * 
  * @author Walter Hoehn
  */
 public interface NameIdentifierMapping {
-       
+
        public static final String mappingNamespace = "urn:mace:shibboleth:origin.config:1.0";
 
+       /**
+        * Returns the Name Identifier format for this mapping.
+        * 
+        * @return the format
+        */
        public URI getNameIdentifierFormat();
 
+       /**
+        * Maps a SAML Name Identifier to a local principal using the appropriate
+        * registered mapping.
+        * 
+        * @param nameId
+        *            the SAML Name Identifier that should be converted
+        * @param sProv
+        *            the provider initiating the request
+        * @param idProv
+        *            the provider handling the request
+        * @return the local principal
+        * @throws NameIdentifierMappingException
+        *             If the <code>NameMapper</code> encounters an internal
+        *             error
+        * @throws InvalidNameIdentifierException
+        *             If the <code>SAMLNameIdentifier</code> contains invalid
+        *             data
+        */
        public AuthNPrincipal getPrincipal(SAMLNameIdentifier nameId, ServiceProvider sProv, IdentityProvider idProv)
                throws NameIdentifierMappingException, InvalidNameIdentifierException;
 
index 9ebb65f..9e6dca2 100644 (file)
@@ -64,16 +64,23 @@ import org.xml.sax.InputSource;
 import edu.internet2.middleware.shibboleth.hs.provider.SharedMemoryShibHandle;
 
 /**
+ * Facility for managing mappings from SAML Name Identifiers to local <code>AuthNPrincipal</code>
+ * objects. Mappings are registered by Name Identifier format.
+ * 
  * @author Walter Hoehn
+ * @see NameIdentifierMapping
  */
 public class NameMapper {
 
        private static Logger log = Logger.getLogger(NameMapper.class.getName());
        protected Map byFormat = new HashMap();
        private static Map registeredMappingTypes = Collections.synchronizedMap(new HashMap());
+       /** Indicated of whether mappings have been added */
        protected boolean initialized = false;
+       /** Mapping to use if no other mappings have been added */
        protected SharedMemoryShibHandle defaultMapping;
 
+       //Preload aliases for bundled mappings
        static {
                try {
                        registeredMappingTypes.put(
@@ -95,6 +102,7 @@ public class NameMapper {
 
        public NameMapper() {
                try {
+                       //Load the default mapping
                        String rawConfig =
                                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
                                        + "<NameMapping format=\"urn:mace:shibboleth:1.0:nameIdentifier\""
@@ -114,6 +122,19 @@ public class NameMapper {
                defaultMapping = null;
        }
 
+       /**
+        * 
+        * Constructs a <code>NameIdentifierMapping</code> based on XML
+        * configuration data and adds it to this <code>NameMapper</code>,
+        * registering it according to its format.
+        * 
+        * @param e
+        *            An XML representation of a <code>NameIdentifierMapping</code>
+        * 
+        * @throws NameIdentifierMappingException
+        *             If the mapping could not be constructed according to the
+        *             supplied configuration
+        */
        public void addNameMapping(Element e) throws NameIdentifierMappingException {
 
                if (!e.getTagName().equals("NameMapping")) {
@@ -160,6 +181,13 @@ public class NameMapper {
 
        }
 
+       /**
+        * Adds a <code>NameIdentifierMapping</code> to this <code>NameMapper</code>,
+        * registering it according to its format.
+        * 
+        * @param mapping
+        *            the mapping to add
+        */
        public void addNameMapping(NameIdentifierMapping mapping) {
 
                initialize();
@@ -172,6 +200,15 @@ public class NameMapper {
 
        }
 
+       /**
+        * Returns the <code>NameIdentifierMapping</code> registered for a given
+        * format
+        * 
+        * @param format
+        *            the registered format
+        * @return the mapping or <tt>null</tt> if no mapping is registered for
+        *         the given format
+        */
        public NameIdentifierMapping getNameIdentifierMapping(URI format) {
                if (!initialized) {
                        return defaultMapping;
@@ -204,6 +241,24 @@ public class NameMapper {
 
        }
 
+       /**
+        * Maps a SAML Name Identifier to a local principal using the appropriate
+        * registered mapping.
+        * 
+        * @param nameId
+        *            the SAML Name Identifier that should be converted
+        * @param sProv
+        *            the provider initiating the request
+        * @param idProv
+        *            the provider handling the request
+        * @return the local principal
+        * @throws NameIdentifierMappingException
+        *             If the <code>NameMapper</code> encounters an internal
+        *             error
+        * @throws InvalidNameIdentifierException
+        *             If the <code>SAMLNameIdentifier</code> contains invalid
+        *             data
+        */
        public AuthNPrincipal getPrincipal(SAMLNameIdentifier nameId, ServiceProvider sProv, IdentityProvider idProv)
                throws NameIdentifierMappingException, InvalidNameIdentifierException {
 
index b338abe..2df4d8b 100644 (file)
@@ -51,6 +51,9 @@ import org.opensaml.SAMLNameIdentifier;
 import org.w3c.dom.Element;
 
 /**
+ * <code>NameMapping</code> implementation that creates a principal from a
+ * shared principal name.
+ * 
  * @author Walter Hoehn
  */
 public class PrincipalNameIdentifier extends BaseNameIdentifierMapping {
index cc8ca74..6c6f93f 100644 (file)
@@ -1,38 +1,48 @@
 /*
- * The Shibboleth License, Version 1. Copyright (c) 2002 University Corporation for Advanced Internet Development, Inc.
- * All rights reserved
+ * The Shibboleth License, Version 1. Copyright (c) 2002 University Corporation
+ * for Advanced Internet Development, Inc. All rights reserved
  * 
  * 
- * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
- * following conditions are met:
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
  * 
- * Redistributions of source code must retain the above copyright notice, this list of conditions and the following
- * disclaimer.
+ * Redistributions of source code must retain the above copyright notice, this
+ * list of conditions and the following disclaimer.
  * 
- * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
- * disclaimer in the documentation and/or other materials provided with the distribution, if any, must include the
- * following acknowledgment: "This product includes software developed by the University Corporation for Advanced
- * Internet Development <http://www.ucaid.edu> Internet2 Project. Alternately, this acknowledegement may appear in the
- * software itself, if and wherever such third-party acknowledgments normally appear.
+ * Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution, if any, must include
+ * the following acknowledgment: "This product includes software developed by
+ * the University Corporation for Advanced Internet Development
+ * <http://www.ucaid.edu> Internet2 Project. Alternately, this acknowledegement
+ * may appear in the software itself, if and wherever such third-party
+ * acknowledgments normally appear.
  * 
- * Neither the name of Shibboleth nor the names of its contributors, nor Internet2, nor the University Corporation for
- * Advanced Internet Development, Inc., nor UCAID may be used to endorse or promote products derived from this software
- * without specific prior written permission. For written permission, please contact shibboleth@shibboleth.org
+ * Neither the name of Shibboleth nor the names of its contributors, nor
+ * Internet2, nor the University Corporation for Advanced Internet Development,
+ * Inc., nor UCAID may be used to endorse or promote products derived from this
+ * software without specific prior written permission. For written permission,
+ * please contact shibboleth@shibboleth.org
  * 
- * Products derived from this software may not be called Shibboleth, Internet2, UCAID, or the University Corporation
- * for Advanced Internet Development, nor may Shibboleth appear in their name, without prior written permission of the
+ * Products derived from this software may not be called Shibboleth, Internet2,
+ * UCAID, or the University Corporation for Advanced Internet Development, nor
+ * may Shibboleth appear in their name, without prior written permission of the
  * University Corporation for Advanced Internet Development.
  * 
  * 
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND WITH ALL FAULTS. ANY EXPRESS OR
- * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
- * PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED AND THE ENTIRE RISK OF SATISFACTORY QUALITY, PERFORMANCE,
- * ACCURACY, AND EFFORT IS WITH LICENSEE. IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS OR THE UNIVERSITY
- * CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
- * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
- * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
- * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND WITH ALL FAULTS. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+ * PARTICULAR PURPOSE, AND NON-INFRINGEMENT ARE DISCLAIMED AND THE ENTIRE RISK
+ * OF SATISFACTORY QUALITY, PERFORMANCE, ACCURACY, AND EFFORT IS WITH LICENSEE.
+ * IN NO EVENT SHALL THE COPYRIGHT OWNER, CONTRIBUTORS OR THE UNIVERSITY
+ * CORPORATION FOR ADVANCED INTERNET DEVELOPMENT, INC. BE LIABLE FOR ANY
+ * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+ * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+ * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
 package edu.internet2.middleware.shibboleth.hs;
@@ -46,12 +56,40 @@ import edu.internet2.middleware.shibboleth.common.NameIdentifierMappingException
 import edu.internet2.middleware.shibboleth.common.ServiceProvider;
 
 /**
+ * Defines a mechanism for generating SAML Name Identifiers from <code>AuthNPrincipal</code>
+ * objects.
+ * 
  * @author Walter Hoehn
  */
 public interface HSNameIdentifierMapping extends NameIdentifierMapping {
-       
+
+       /**
+        * @return the id of this mapping or <tt>null</tt> is it is not
+        *         configured with one
+        */
        public String getId();
-       
-       public SAMLNameIdentifier getNameIdentifierName(AuthNPrincipal principal, ServiceProvider sProv, IdentityProvider idProv) throws NameIdentifierMappingException;
+
+       /**
+        * 
+        * Maps a local principal to a SAML Name Identifier.
+        * 
+        * @param id
+        *            the id under which the effective <code>HSNameIdentifierMapping</code>
+        *            is registered
+        * @param principal
+        *            the principal to map
+        * @param sProv
+        *            the provider initiating the request
+        * @param idProv
+        *            the provider handling the request
+        * @return @throws
+        *         NameIdentifierMappingException If the <code>NameMapper</code>
+        *         encounters an internal error
+        */
+       public SAMLNameIdentifier getNameIdentifierName(
+               AuthNPrincipal principal,
+               ServiceProvider sProv,
+               IdentityProvider idProv)
+               throws NameIdentifierMappingException;
 
 }
index aa13549..9b95ac3 100644 (file)
@@ -61,12 +61,26 @@ import edu.internet2.middleware.shibboleth.common.NameMapper;
 import edu.internet2.middleware.shibboleth.common.ServiceProvider;
 
 /**
+ * <code>NameMapper</code> that additionally maps local <code>AuthNPrincipal</code>
+ * to SAML Name Identifiers. Mappings can be associated with a <code>String</code>
+ * id and recovered based on the same.
+ * 
  * @author Walter Hoehn
+ * @see NameMapper
+ * @see HSNameIdentifierMapping
  */
 public class HSNameMapper extends NameMapper {
 
        private Map byId = new HashMap();
 
+       /**
+        * Adds a <code>NameIdentifierMapping</code> to this <code>HSNameMapper</code>,
+        * registering it according to its format and, if applicable, according to
+        * its id.
+        * 
+        * @param mapping
+        *            the mapping to add
+        */
        public void addNameMapping(NameIdentifierMapping mapping) {
                super.addNameMapping(mapping);
                if (mapping instanceof HSNameIdentifierMapping) {
@@ -77,6 +91,15 @@ public class HSNameMapper extends NameMapper {
                }
        }
 
+       /**
+        * Returns the <code>HSNameIdentifierMapping</code> registered for a
+        * given id
+        * 
+        * @param id
+        *            the registered id
+        * @return the mapping or <tt>null</tt> if no mapping is registered for
+        *         the given id
+        */
        public HSNameIdentifierMapping getNameIdentifierMappingById(String id) {
 
                if (id == null || id.equals("")) {
@@ -96,6 +119,23 @@ public class HSNameMapper extends NameMapper {
                return (HSNameIdentifierMapping) byId.get(id);
        }
 
+       /**
+        * 
+        * Maps a local principal to a SAML Name Identifier using the mapping registered under a given id.
+        * 
+        * @param id
+        *            the id under which the effective <code>HSNameIdentifierMapping</code>
+        *            is registered
+        * @param principal
+        *            the principal to map
+        * @param sProv
+        *            the provider initiating the request
+        * @param idProv
+        *            the provider handling the request
+        * @return @throws
+        *         NameIdentifierMappingException If the <code>NameMapper</code>
+        *         encounters an internal error
+        */
        public SAMLNameIdentifier getNameIdentifierName(
                String id,
                AuthNPrincipal principal,
index 91bbee4..58dff56 100644 (file)
@@ -56,6 +56,9 @@ import edu.internet2.middleware.shibboleth.common.BaseNameIdentifierMapping;
 import edu.internet2.middleware.shibboleth.common.NameIdentifierMappingException;
 
 /**
+ * Base class for <code>NameIdentifierMapping</code> implementations that
+ * support Shibboleth Attribute Query Handles.
+ * 
  * @author Walter Hoehn
  */
 public abstract class AQHNameIdentifierMapping extends BaseNameIdentifierMapping {
index d7342c1..5a85375 100644 (file)
@@ -92,6 +92,10 @@ import edu.internet2.middleware.shibboleth.common.ShibResource;
 import edu.internet2.middleware.shibboleth.hs.HSNameIdentifierMapping;
 
 /**
+ * <code>HSNameIdentifierMapping</code> implementation that uses symmetric
+ * encryption to securely transport principal data inside Shibboleth Attribute
+ * Query Handles.
+ * 
  * @author Walter Hoehn
  */
 public class CryptoShibHandle extends AQHNameIdentifierMapping implements HSNameIdentifierMapping {
index 40ccbd6..d69caa4 100644 (file)
@@ -67,6 +67,9 @@ import edu.internet2.middleware.shibboleth.common.ServiceProvider;
 import edu.internet2.middleware.shibboleth.hs.HSNameIdentifierMapping;
 
 /**
+ * <code>HSNameIdentifierMapping</code> implementation that uses an in-memory
+ * cache to store mappings between principal names and Shibboleth Attribute Query Handles.
+ * 
  * @author Walter Hoehn
  */
 public class SharedMemoryShibHandle extends AQHNameIdentifierMapping implements HSNameIdentifierMapping {
@@ -109,7 +112,7 @@ public class SharedMemoryShibHandle extends AQHNameIdentifierMapping implements
                synchronized (cache.handleEntries) {
                        if (!cache.handleEntries.containsKey(nameId.getName())) {
                                log.debug("The Name Mapping Cache does not contain an entry for this Attribute Query Handle.");
-                               throw new InvalidNameIdentifierException("The Name Mapping Cache does not contain an entry for this Attribute Query Handle.");
+                               throw new NameIdentifierMappingException("The Name Mapping Cache does not contain an entry for this Attribute Query Handle.");
                        }
                }