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