001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2005 Sun Microsystems Inc. All Rights Reserved
005 *
006 * The contents of this file are subject to the terms
007 * of the Common Development and Distribution License
008 * (the License). You may not use this file except in
009 * compliance with the License.
010 *
011 * You can obtain a copy of the License at
012 * https://opensso.dev.java.net/public/CDDLv1.0.html or
013 * opensso/legal/CDDLv1.0.txt
014 * See the License for the specific language governing
015 * permission and limitations under the License.
016 *
017 * When distributing Covered Code, include this CDDL
018 * Header Notice in each file and include the License file
019 * at opensso/legal/CDDLv1.0.txt.
020 * If applicable, add the following below the CDDL Header,
021 * with the fields enclosed by brackets [] replaced by
022 * your own identifying information:
023 * "Portions Copyrighted [year] [name of copyright owner]"
024 *
025 * $Id: AMCallBack.java,v 1.3 2008/06/25 05:41:19 qcheng Exp $
026 *
027 */
028
029package com.iplanet.am.sdk;
030
031import java.util.Map;
032import java.util.Set;
033
034import com.iplanet.sso.SSOToken;
035
036/**
037 * A Plugin Class that needs to be extended by external applications in-order to
038 * do some special pre/post-processing for creation/deletion and modification
039 * operations for User, Organization, Roles and Groups. The implementation
040 * classes/module(s) are pluggable and are configurable through the Organization
041 * attribute: <code>iplanet-am-admin-console-pre-post-processing-modules</code>
042 * of the <code>iPlanetAMAdminConsoleService</code> service.
043 * 
044 * <p>
045 * For call backs pertaining to Organizations and Organizational Units, the
046 * parent organization's configuration (
047 * <code>iPlanetAMAdminConsoleService</code>
048 * Organization configuration) will be used to obtain the plugin modules.
049 * 
050 * <p>
051 * The call backs will be made at the time of performing one of the
052 * corresponding User/Organization/Role/Group operations (create/modify/delete
053 * and attribute fetch) by the Sun Java System Access Manager SDK. Applications
054 * that need to perform special pre/post processing for one or more of the above
055 * operations, should extend the class and override the corresponding methods.
056 * 
057 * <p>
058 * The API's for pre call back provide a mechanism to inspect the attributes
059 * being modified and also modify the values appropriately if required. Care
060 * should be taken while performing such modifications, so that it will not
061 * affect other plugins which are dependent on the same attributes.
062 * 
063 * <p>
064 * <b>Note:</b>
065 * <ul>
066 * <p>
067 * <li> When more than one plugin modules are configured at a particular
068 * Organization level, the call backs for each of the plugins will occur one
069 * after the other. Also, note that the order in which plugins are called back
070 * is cannot pre-determined in any way.
071 * 
072 * <p>
073 * <li> Since the methods of this class will be invoked by the Identity Server
074 * SDK and will control the flow of SDK, extreme caution should be taken while
075 * overriding these methods to avoid performance bottle necks.
076 * 
077 * <p>
078 * <li> The exceptions thrown by the pre-processing methods of this class will
079 * be treated as a failure of external processing and the operation in progress
080 * will be halted by the SDK. The exception thrown should include a proper user
081 * specific localized error message which can be propagated back to the
082 * application using the SDK. The locale of the user should to be determined
083 * using token of the authenticated user while constructing such a localized
084 * message.
085 * </ul>
086 * 
087 * @deprecated  As of Sun Java System Access Manager 7.1.
088 * @supported.all.api
089 */
090public class AMCallBack {
091
092    protected AMCallBack() {
093    }
094
095    /**
096     * This method provides a mechanism for applications to obtain attributes
097     * external to the Access Manager data store.
098     * 
099     * This callback gets invoked when any of the {@link AMObject#getAttributes 
100     * AMObject.getAttributes()} methods are called. When multiple plugins
101     * override this method, then attributes returned from each of them will be
102     * merged and returned. When the <code>getAttribute()</code> method that
103     * request specific attributes the call backs are made only for those
104     * attributes that are not found in the Access Manager's data store. If the
105     * <code>getAttributes()</code> which do not request any specific
106     * attributes is called, the call back will take place after obtaining all
107     * the attributes for the corresponding entry from the Access Manager's data
108     * store. <br>
109     * <b>NOTE:</b>
110     * <ul>
111     * <li> This callback is not enabled by default. In order for this call back
112     * to be invoked, the organizational attribute:
113     * <code>iplanet-am-admin-console-external-attribute-fetch-enabled</code>
114     * of the <code>iPlanetAMAdminConsoleService</code> service should be set
115     * to <code>enabled</code>
116     * <li> Overriding this method would cause significant performance impact.
117     * Hence, extreme caution should be taken while overriding this method to
118     * avoid processing overhead.
119     * <li> The attributes returned by the plugins will not be cached by SDK.
120     * Hence, in order to avoid performance overheads, it is recommended that
121     * plugin's maintain a local cache of frequently attributes. Also, the cache
122     * needs to be in sync with any modifications made to those attributes.
123     * </ul>
124     * 
125     * @param token
126     *            the <code>SSOToken</code>
127     * @param entryDN
128     *            the DN of the entry being added
129     * @param attrNames
130     *            names of attributes that need to retrieved. If null, all
131     *            attributes should be returned.
132     * 
133     * @return a Map of attributes, where the key is the attribute name and the
134     *         value is a Set of values. This map of attributes will be copied
135     *         to the original map retrieved from the Access Manager data store
136     *         and will be returned to the caller.
137     */
138    public Map getAttributes(SSOToken token, String entryDN, Set attrNames) {
139        return null;
140    }
141
142    /**
143     * Method which gets invoked before a create operation is performed.
144     * 
145     * @param token
146     *            the <code>SSOToken</code>
147     * @param entryDN
148     *            the DN of the entry being added
149     * @param attributes
150     *            a map consisting of attribute names and a set of values for
151     *            each of them. This map of attributes can be inspected,
152     *            modified and sent back. Note, caution should be taken while
153     *            performing modifications to avoid changing attributes that are
154     *            used by Access Manager. If no modifications need to done,
155     *            either the original map or null value can be returned.
156     * @param objectType
157     *            represents the type of entry on which the operation is being
158     *            performed. Types could be:
159     *            <ul>
160     *            <li> {@link AMObject#USER AMObject.USER}
161     *            <li> {@link AMObject#ROLE AMObject.ROLE}
162     *            <li> {@link AMObject#FILTERED_ROLE AMObject.FILTERED_ROLE}
163     *            <li> {@link AMObject#ORGANIZATION AMObject.ORGANIZATION}
164     *            <li> {@link AMObject#ORGANIZATIONAL_UNIT 
165     *            AMObject.ORGANIZATIONAL_UNIT}
166     *            <li> {@link AMObject#GROUP AMObject.GROUP}
167     *            <li> {@link AMObject#DYNAMIC_GROUP AMObject.DYNAMIC_GROUP}
168     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
169     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
170     *            </ul>
171     * @return Map of updated values for <code>attributes<code> or null. If this
172     *         returned map is not null, then this map will be used while
173     *         performing the operation. 
174     * @throws AMPreCallBackException if an 
175     *         error that occurs during pre processing. The SDK will not proceed
176     *         with the create operation, if any one of the implementation
177     *         classes throws an exception. A user specific localized message
178     *         should be sent as part of the exception message. The specific
179     *         messages can be added to <code>amProfile.properties</code> file.
180     */
181    public Map preProcessCreate(SSOToken token, String entryDN, Map attributes,
182            int objectType) throws AMPreCallBackException {
183        return attributes;
184    }
185
186    /**
187     * Method which gets invoked before a modify operation is performed.
188     * 
189     * @param token
190     *            the <code>SSOToken</code>
191     * @param entryDN
192     *            the DN of the entry being modified
193     * @param oldAttributes
194     *            a map consisting of attribute names and a set of values for
195     *            each of them before modification
196     * @param newAttributes
197     *            a map consisting of attribute names and a set of values for
198     *            each of them after modification. This map of attributes can be
199     *            inspected, modified and sent back. Note, caution should be
200     *            taken while performing modifications to avoid changing
201     *            attributes that are used by Access Manager. If no
202     *            modifications need to done, either the original map or null
203     *            value can be returned.
204     * @param objectType
205     *            represents the type of entry on which the operation is being
206     *            performed. Types could be:
207     *            <ul>
208     *            <li> {@link AMObject#USER AMObject.USER}
209     *            <li> {@link AMObject#ROLE AMObject.ROLE}
210     *            <li> {@link AMObject#FILTERED_ROLE AMObject.FILTERED_ROLE}
211     *            <li> {@link AMObject#ORGANIZATION AMObject.ORGANIZATION}
212     *            <li> {@link AMObject#ORGANIZATIONAL_UNIT 
213     *            AMObject.ORGANIZATIONAL_UNIT}
214     *            <li> {@link AMObject#GROUP AMObject.GROUP}
215     *            <li> {@link AMObject#DYNAMIC_GROUP AMObject.DYNAMIC_GROUP}
216     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
217     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
218     *            </ul>
219     * @return Map of updated values for <code>newAttributes</code> or null.
220     *         If this returned map is not null, then this map will be used
221     *         while performing the operation.
222     * 
223     * @throws AMPreCallBackException
224     *             if an error occurs pre processing. The SDK will not proceed
225     *             with the modify operation, if any one of the implementation
226     *             classes throws an exception. A user specific localized
227     *             message should be sent as part of the exception message. The
228     *             specific messages can be added to
229     *             <code>amProfile.properties</code> file.
230     */
231    public Map preProcessModify(SSOToken token, String entryDN,
232            Map oldAttributes, Map newAttributes, int objectType)
233            throws AMPreCallBackException {
234        return newAttributes;
235    }
236
237    /**
238     * Method which gets invoked before an entry is deleted. The deletion type
239     * configured in Sun Java System Access Manager is also passed as a
240     * parameter to this method.
241     * 
242     * @param token
243     *            the <code>SSOToken</code>
244     * @param entryDN
245     *            the DN of the entry being deleted
246     * @param attributes
247     *            a map consisting of attribute names and a set of values for
248     *            each of them.
249     * @param softDeleteEnabled
250     *            if true soft delete will be performed Otherwise hard delete
251     *            will be performed.
252     * @param objectType
253     *            represents the type of entry on which the operation is being
254     *            performed. Types could be:
255     *            <ul>
256     *            <li> {@link AMObject#USER AMObject.USER}
257     *            <li> {@link AMObject#ROLE AMObject.ROLE}
258     *            <li> {@link AMObject#FILTERED_ROLE AMObject.FILTERED_ROLE}
259     *            <li> {@link AMObject#ORGANIZATION AMObject.ORGANIZATION}
260     *            <li> {@link AMObject#ORGANIZATIONAL_UNIT 
261     *            AMObject.ORGANIZATIONAL_UNIT}
262     *            <li> {@link AMObject#GROUP AMObject.GROUP}
263     *            <li> {@link AMObject#DYNAMIC_GROUP AMObject.DYNAMIC_GROUP}
264     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
265     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
266     *            </ul>
267     * @throws AMPreCallBackException
268     *             if an error occurs during entry delete pre-processing. The
269     *             SDK will not proceed with the delete operation, if any one of
270     *             the implementation classes throws an exception. A user
271     *             specific localized message should be sent as part of the
272     *             exception message. The specific messages can be added to
273     *             <code>amProfile.properties</code> file.
274     */
275    public void preProcessDelete(SSOToken token, String entryDN,
276            Map attributes, boolean softDeleteEnabled, int objectType)
277            throws AMPreCallBackException {
278    }
279
280    /**
281     * Method which gets invoked after a entry create operation is performed.
282     * 
283     * @param token
284     *            the <code>SSOToken</code>
285     * @param entryDN
286     *            the DN of the entry being added
287     * @param attributes
288     *            a map consisting of attribute names and a set of values for
289     *            each of them
290     * @param objectType
291     *            represents the type of entry on which the operation is being
292     *            performed. Types could be:
293     *            <ul>
294     *            <li> {@link AMObject#USER AMObject.USER}
295     *            <li> {@link AMObject#ROLE AMObject.ROLE}
296     *            <li> {@link AMObject#FILTERED_ROLE AMObject.FILTERED_ROLE}
297     *            <li> {@link AMObject#ORGANIZATION AMObject.ORGANIZATION}
298     *            <li> {@link AMObject#ORGANIZATIONAL_UNIT 
299     *            AMObject.ORGANIZATIONAL_UNIT}
300     *            <li> {@link AMObject#GROUP AMObject.GROUP}
301     *            <li> {@link AMObject#DYNAMIC_GROUP AMObject.DYNAMIC_GROUP}
302     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
303     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
304     *            </ul>
305     * 
306     * @throws AMPostCallBackException
307     *             if an error occurs during post processing. A user specific
308     *             localized message should be sent as part of the exception
309     *             message. The specific messages can be added to
310     *             <code>amProfile.properties</code> file.
311     */
312    public void postProcessCreate(SSOToken token, String entryDN,
313            Map attributes, int objectType) throws AMPostCallBackException {
314    }
315
316    /**
317     * Method which gets invoked after a entry is modified
318     * 
319     * @param token
320     *            the <code>SSOToken</code>
321     * @param entryDN
322     *            the DN of the entry being modified
323     * @param oldAttributes
324     *            a map consisting of attribute names and a set of values for
325     *            each of them before modification
326     * @param newAttributes
327     *            a map consisting of attribute names and a set of values for
328     *            each of them after modification
329     * @param objectType
330     *            represents the type of entry on which the operation is being
331     *            performed. Types could be:
332     *            <ul>
333     *            <li> {@link AMObject#USER AMObject.USER}
334     *            <li> {@link AMObject#ROLE AMObject.ROLE}
335     *            <li> {@link AMObject#FILTERED_ROLE AMObject.FILTERED_ROLE}
336     *            <li> {@link AMObject#ORGANIZATION AMObject.ORGANIZATION}
337     *            <li> {@link AMObject#ORGANIZATIONAL_UNIT 
338     *            AMObject.ORGANIZATIONAL_UNIT}
339     *            <li> {@link AMObject#GROUP AMObject.GROUP}
340     *            <li> {@link AMObject#DYNAMIC_GROUP AMObject.DYNAMIC_GROUP}
341     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
342     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
343     *            </ul>
344     * 
345     * @throws AMPostCallBackException
346     *             if an error occurs during post processing. A user specific
347     *             localized message should be sent as part of the exception
348     *             message. The specific messages can be added to
349     *             <code>amProfile.properties</code> file.
350     */
351    public void postProcessModify(SSOToken token, String entryDN,
352            Map oldAttributes, Map newAttributes, int objectType)
353            throws AMPostCallBackException {
354    }
355
356    /**
357     * Method which gets invoked after a entry entry is deleted. The deletion
358     * type configured in Sun Java System Access Manager is also passed as a
359     * parameter to this method.
360     * 
361     * @param token
362     *            the <code>SSOToken</code>
363     * @param entryDN
364     *            the DN of the entry being deleted
365     * @param attributes
366     *            a map consisting of attribute names and a set of values for
367     *            each of them
368     * @param softDelete
369     *            If true, this implies that the object is just being marked for
370     *            deletion, if false, then it implies that the object is being
371     *            removed from the data store.
372     * @param objectType
373     *            represents the type of entry on which the operation is being
374     *            performed. Types could be:
375     *            <ul>
376     *            <li> {@link AMObject#USER AMObject.USER}
377     *            <li> {@link AMObject#ROLE AMObject.ROLE}
378     *            <li> {@link AMObject#FILTERED_ROLE AMObject.FILTERED_ROLE}
379     *            <li> {@link AMObject#ORGANIZATION AMObject.ORGANIZATION}
380     *            <li> {@link AMObject#ORGANIZATIONAL_UNIT 
381     *            AMObject.ORGANIZATIONAL_UNIT}
382     *            <li> {@link AMObject#GROUP AMObject.GROUP}
383     *            <li> {@link AMObject#DYNAMIC_GROUP AMObject.DYNAMIC_GROUP}
384     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
385     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
386     *            </ul>
387     * @throws AMPostCallBackException
388     *             if an error occurs during post processing. A user specific
389     *             localized message should be sent as part of the exception
390     *             message. The specific messages can be added to
391     *             <code>amProfile.properties</code> file.
392     */
393    public void postProcessDelete(SSOToken token, String entryDN,
394            Map attributes, boolean softDelete, int objectType)
395            throws AMPostCallBackException {
396    }
397
398    /**
399     * Method which gets called before users are added to a role/group.
400     * 
401     * @param token
402     *            the <code>SSOToken</code>
403     * @param entryDN
404     *            the DN of the entry being added
405     * @param members
406     *            a set consisting of user DN's. This set of members can be
407     *            inspected, modified (users can be added/removed) and sent
408     *            back. If no modifications need to done, either the original
409     *            set or null value can be returned.
410     * @param objectType
411     *            represents the type of entry on which the operation is being
412     *            performed. Types could be:
413     *            <ul>
414     *            <li> {@link AMObject#ROLE AMObject.ROLE}
415     *            <li> {@link AMObject#GROUP AMObject.GROUP}
416     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
417     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
418     *            </ul>
419     * 
420     * @return Set of updated values for <code>members<code> or null. If null
421     * value or empty set is returned, no users will be added. Hence, if no
422     * modification is being performed to the original set, it needs to be 
423     * back.
424     *
425     * @throws AMPreCallBackException if an 
426     * error occurs during pre processing. The SDK will not proceed with
427     * the adding users to role/group operation, if any one of the 
428     * implementation classes throws an exception. A user specific localized 
429     * message should be sent as part of the exception message. The specific 
430     * messages can be added to
431     * <code>amProfile.properties</code> file.
432     */
433    public Set preProcessAddUser(SSOToken token, String entryDN, Set members,
434            int objectType) throws AMPreCallBackException {
435        return members;
436    }
437
438    /**
439     * Method which gets invoked after users are added to a role/group.
440     * 
441     * @param token
442     *            the <code>SSOToken</code>
443     * @param entryDN
444     *            the DN of the entry being added
445     * @param members
446     *            a Set consisting of user DN's which represent the users added
447     *            to the role/group.
448     * @param objectType
449     *            represents the type of entry on which the operation is being
450     *            performed. Types could be:
451     *            <ul>
452     *            <li> {@link AMObject#ROLE AMObject.ROLE}
453     *            <li> {@link AMObject#GROUP AMObject.GROUP}
454     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
455     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
456     *            </ul>
457     * 
458     * @throws AMPostCallBackException
459     *             if an error occurs during post processing. A user specific
460     *             localized message should be sent as part of the exception
461     *             message. The specific messages can be added to
462     *             <code>amProfile.properties</code> file.
463     */
464    public void postProcessAddUser(SSOToken token, String entryDN, Set members,
465            int objectType) throws AMPostCallBackException {
466    }
467
468    /**
469     * Method which gets called before users are removed from a role/group.
470     * 
471     * @param token
472     *            the <code>SSOToken</code>
473     * @param entryDN
474     *            the DN of the entry being added
475     * @param members
476     *            a set consisting of user DN's. This set of members can be
477     *            inspected, modified (users can be added/removed) and sent
478     *            back. If no modifications need to done, either the original
479     *            set or null value can be returned.
480     * @param objectType
481     *            represents the type of entry on which the operation is being
482     *            performed. Types could be:
483     *            <ul>
484     *            <li> {@link AMObject#ROLE AMObject.ROLE}
485     *            <li> {@link AMObject#GROUP AMObject.GROUP}
486     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
487     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
488     *            </ul>
489     * 
490     * @return Set of updated values for <code>members<code> or null. If null
491     * value or empty set is returned, no users will be removed. Hence, if no
492     * modification is being performed to the original set, it needs to be 
493     * back.
494     *
495     * @throws AMPreCallBackException if an 
496     * error that occurs during pre processing. The SDK will not proceed with
497     * the removing users from role/group operation, if any one of the 
498     * implementation classes throws an exception. A user specific localized 
499     * message should be sent as part of the exception message. The specific 
500     * messages can be added to <code>amProfile.properties</code> file.
501     */
502    public Set preProcessRemoveUser(SSOToken token, String entryDN,
503            Set members, int objectType) throws AMPreCallBackException {
504        return members;
505    }
506
507    /**
508     * Method which gets invoked after users are removed from a role/group.
509     * 
510     * @param token
511     *            the <code>SSOToken</code>
512     * @param entryDN
513     *            the DN of the entry being added
514     * @param members
515     *            a Set consisting of user DN's which represent the users added
516     *            to the role/group.
517     * @param objectType
518     *            represents the type of entry on which the operation is being
519     *            performed. Types could be:
520     *            <ul>
521     *            <li> {@link AMObject#ROLE AMObject.ROLE}
522     *            <li> {@link AMObject#GROUP AMObject.GROUP}
523     *            <li> {@link AMObject#ASSIGNABLE_DYNAMIC_GROUP 
524     *            AMObject.ASSIGNABLE_DYNAMIC_GROUP}
525     *            </ul>
526     * 
527     * @throws AMPostCallBackException
528     *             if an error occurs during post processing. A user specific
529     *             localized message should be sent as part of the exception
530     *             message. The specific messages can be added to
531     *             <code>amProfile.properties</code> file.
532     */
533    public void postProcessRemoveUser(SSOToken token, String entryDN,
534            Set members, int objectType) throws AMPostCallBackException {
535    }
536}