001    /*
002     * CDDL HEADER START
003     *
004     * The contents of this file are subject to the terms of the
005     * Common Development and Distribution License, Version 1.0 only
006     * (the "License").  You may not use this file except in compliance
007     * with the License.
008     *
009     * You can obtain a copy of the license at
010     * trunk/opends/resource/legal-notices/OpenDS.LICENSE
011     * or https://OpenDS.dev.java.net/OpenDS.LICENSE.
012     * See the License for the specific language governing permissions
013     * and limitations under the License.
014     *
015     * When distributing Covered Code, include this CDDL HEADER in each
016     * file and include the License file at
017     * trunk/opends/resource/legal-notices/OpenDS.LICENSE.  If applicable,
018     * add the following below this CDDL HEADER, with the fields enclosed
019     * by brackets "[]" replaced with your own identifying information:
020     *      Portions Copyright [yyyy] [name of copyright owner]
021     *
022     * CDDL HEADER END
023     *
024     *
025     *      Copyright 2006-2008 Sun Microsystems, Inc.
026     */
027    package org.opends.server.api;
028    import org.opends.messages.Message;
029    
030    
031    
032    import java.util.List;
033    
034    import org.opends.server.admin.std.server.IdentityMapperCfg;
035    import org.opends.server.config.ConfigException;
036    import org.opends.server.types.DirectoryException;
037    import org.opends.server.types.Entry;
038    import org.opends.server.types.InitializationException;
039    
040    
041    
042    /**
043     * This class defines the set of methods and structures that must be
044     * implemented by a Directory Server identity mapper.  An identity
045     * mapper is used to identify exactly one user associated with a given
046     * identification value.  This API may be used by a number of SASL
047     * mechanisms to identify the user that is authenticating to the
048     * server.  It may also be used in other areas, like in conjunction
049     * with the proxied authorization control.
050     *
051     * @param  <T>  The type of configuration handled by this identity
052     *              mapper.
053     */
054    @org.opends.server.types.PublicAPI(
055         stability=org.opends.server.types.StabilityLevel.VOLATILE,
056         mayInstantiate=false,
057         mayExtend=true,
058         mayInvoke=true)
059    public abstract class IdentityMapper
060           <T extends IdentityMapperCfg>
061    {
062      /**
063       * Initializes this identity mapper based on the information in the
064       * provided configuration entry.
065       *
066       * @param  configuration  The configuration for the identity mapper.
067       *
068       * @throws  ConfigException  If an unrecoverable problem arises in
069       *                           the process of performing the
070       *                           initialization.
071       *
072       * @throws  InitializationException  If a problem occurs during
073       *                                   initialization that is not
074       *                                   related to the server
075       *                                   configuration.
076       */
077      public abstract void initializeIdentityMapper(T configuration)
078             throws ConfigException, InitializationException;
079    
080    
081    
082      /**
083       * Indicates whether the provided configuration is acceptable for
084       * this identity mapper.  It should be possible to call this method
085       * on an uninitialized identity mapper instance in order to
086       * determine whether the identity mapper would be able to use the
087       * provided configuration.
088       * <BR><BR>
089       * Note that implementations which use a subclass of the provided
090       * configuration class will likely need to cast the configuration
091       * to the appropriate subclass type.
092       *
093       * @param  configuration        The identity mapper configuration
094       *                              for which to make the determination.
095       * @param  unacceptableReasons  A list that may be used to hold the
096       *                              reasons that the provided
097       *                              configuration is not acceptable.
098       *
099       * @return  {@code true} if the provided configuration is acceptable
100       *          for this identity mapper, or {@code false} if not.
101       */
102      public boolean isConfigurationAcceptable(
103                          IdentityMapperCfg configuration,
104                          List<Message> unacceptableReasons)
105      {
106        // This default implementation does not perform any special
107        // validation.  It should be overridden by identity mapper
108        // implementations that wish to perform more detailed validation.
109        return true;
110      }
111    
112    
113    
114      /**
115       * Performs any finalization that may be necessary for this identity
116       * mapper.  By default, no finalization is performed.
117       */
118      public void finalizeIdentityMapper()
119      {
120        // No implementation is required by default.
121      }
122    
123    
124    
125      /**
126       * Retrieves the user entry that was mapped to the provided
127       * identification string.
128       *
129       * @param  id  The identification string that is to be mapped to a
130       *             user.
131       *
132       * @return  The user entry that was mapped to the provided
133       *          identification, or {@code null} if no users were found
134       *          that could be mapped to the provided ID.
135       *
136       * @throws  DirectoryException  If a problem occurs while attempting
137       *                              to map the given ID to a user entry,
138       *                              or if there are multiple user
139       *                              entries that could map to the
140       *                              provided ID.
141       */
142      public abstract Entry getEntryForID(String id)
143             throws DirectoryException;
144    }
145