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: AMObject.java,v 1.4 2008/06/25 05:41:20 qcheng Exp $
026 *
027 */
028
029package com.iplanet.am.sdk;
030
031import java.util.Map;
032import java.util.Set;
033
034import com.iplanet.sso.SSOException;
035
036
037/**
038 * The <code>AMObject</code> interface provides methods to manage various Sun
039 * Java System Access Manager objects and their attributes.
040 *
041 * @deprecated As of Sun Java System Access Manager 7.1.
042 * @supported.all.api
043 */
044public interface AMObject extends AMConstants {
045
046    // Object Types
047    /**
048     * Represents a User object type
049     */
050    public static final int USER = 1;
051
052    /**
053     * Represents an Organization object type
054     */
055    public static final int ORGANIZATION = 2;
056
057    /**
058     * Represents a Organizational Unit object type
059     */
060    public static final int ORGANIZATIONAL_UNIT = 3;
061
062    /**
063     * Represents a group container object type
064     */
065    public static final int GROUP_CONTAINER = 4;
066
067    /**
068     * Represents a People Container object type
069     */
070    public static final int PEOPLE_CONTAINER = 5;
071
072    /**
073     * Represents a Role object type
074     */
075    public static final int ROLE = 6;
076
077    /**
078     * Represents a Managed Role object type
079     */
080    public static final int MANAGED_ROLE = 7;
081
082    /**
083     * Represents a Filtered Role object type
084     */
085    public static final int FILTERED_ROLE = 8;
086
087    /**
088     * Represents a Group object type
089     */
090    public static final int GROUP = 9;
091
092    /**
093     * Represents a Static Group object type
094     */
095    public static final int STATIC_GROUP = 10;
096
097    /**
098     * Represents a Dynamic Group object type
099     */
100    public static final int DYNAMIC_GROUP = 11;
101
102    /**
103     * Represents a Dynamic Group object type
104     */
105    public static final int ASSIGNABLE_DYNAMIC_GROUP = 12;
106
107    /**
108     * Represents a Template object type
109     */
110    public static final int TEMPLATE = 13;
111
112    /**
113     * Represents Policy Information
114     */
115    public static final int POLICY = 14;
116
117    /**
118     * Represents Service Information
119     */
120    public static final int SERVICE = 15;
121
122    /**
123     * Represents role profile Information
124     */
125    public static final int ROLE_PROFILE = 16;
126
127    /**
128     * Represents group profile Information
129     */
130    public static final int GROUP_PROFILE = 17;
131
132    /**
133     * Represents resource object type
134     */
135    public static final int RESOURCE = 21;
136
137    /**
138     * Represents the status of an object as active
139     */
140    public static final int ACTIVE = 18;
141
142    /**
143     * String representation of the "active" state
144     */
145    public static final String ACTIVE_VALUE = "active";
146
147    /**
148     * Represents the status of an object as inactive
149     */
150    public static final int INACTIVE = 19;
151
152    /**
153     * String representation of the "inactive" state
154     */
155    public static final String INACTIVE_VALUE = "inactive";
156
157    /**
158     * Represents the status of an object as "deleted"
159     */
160    public static final int DELETED = 20;
161
162    /**
163     * String representation of the "deleted" state
164     */
165    public static final String DELETED_VALUE = "deleted";
166
167    /**
168     * Represents an object type that cannot be identified
169     */
170    public static final int UNKNOWN_OBJECT_TYPE = -1;
171
172    /**
173     * Used to indicate the object type has not yet determined. Mainly used in
174     * caching. Local to this package
175     */
176    static final int UNDETERMINED_OBJECT_TYPE = -9999;
177
178    /**
179     * Returns the DN of the entry.
180     * 
181     * @return String DN
182     */
183    public String getDN();
184
185    /**
186     * Returns the parent DN of the entry.
187     * 
188     * @return String DN
189     */
190    public String getParentDN();
191
192    /**
193     * Stores the change to directory server. This method should be called after
194     * doing <code>setAttributes</code> so that the changes that are made can
195     * be permanently committed to the LDAP data store.
196     * 
197     * @throws AMException
198     *             if an error is encountered when trying to access/retrieve
199     *             data from the data store.
200     * @throws SSOException
201     *             if the single sign on token is no longer valid.
202     */
203    public void store() throws AMException, SSOException;
204
205    /**
206     * Stores the change to directory server. This method should be called after
207     * doing <code>setAttributes</code> or any other <code>set methods </code>
208     * provided. so that the changes that are made can be permanently committed
209     * to the LDAP data store.
210     * 
211     * @param addValues
212     *            If <code>addValues</code> is true, then the attribute values
213     *            as set in the <code>setAttributes</code> method are added to
214     *            any existing values for the same attribute in the directory.
215     *            Otherwise, the attribute values replace existing values in the
216     *            data store.
217     * @throws AMException
218     *             if an error is encountered when trying to access/retrieve
219     *             data from the data store.
220     * @throws SSOException
221     *             if the single sign on token is no longer valid.
222     */
223    public void store(boolean addValues) throws AMException, SSOException;
224
225    /**
226     * Checks if the entry exists in the directory or not. First a syntax check
227     * is done on the DN string corresponding to the entry. If the DN syntax is
228     * valid, a directory call will be made to check for the existence of the
229     * entry.
230     * <p>
231     * 
232     * <B>NOTE:</B> This method internally invokes a call to the directory to
233     * verify the existence of the entry. There could be a performance overhead.
234     * Hence, please use your discretion while using this method.
235     * 
236     * @return false if the entry does not have a valid DN syntax or if the
237     *         entry does not exists in the Directory. False otherwise.
238     * @throws SSOException
239     *             if the single sign on token is no longer valid.
240     */
241    public boolean isExists() throws SSOException;
242
243    /**
244     * Returns Map of all attributes. Map key is the attribute name and value is
245     * the attribute value.
246     * 
247     * @return Map of all attributes.
248     * @throws AMException
249     *             if an error is encountered when trying to access/retrieve
250     *             data from the data store.
251     * @throws SSOException
252     *             if the single sign on token is no longer valid.
253     */
254    public Map getAttributes() throws AMException, SSOException;
255
256    /**
257     * Returns Map of all attributes directly from data store. Map key is the
258     * attribute name and value is the attribute value.
259     * 
260     * @return Map of all attributes.
261     * @throws AMException
262     *             if an error is encountered when trying to access/retrieve
263     *             data from the data store
264     * @throws SSOException
265     *             if the single sign on token is no longer valid.
266     */
267    public Map getAttributesFromDataStore() throws AMException, SSOException;
268
269    /**
270     * Returns Map of all attributes. Map key is the attribute name and value is
271     * the attribute value in byte[][] format.
272     * 
273     * @return Map of all attributes.
274     * @throws AMException
275     *             if an error is encountered when trying to access/retrieve
276     *             data from the data store
277     * @throws SSOException
278     *             if the single sign on token is no longer valid.
279     */
280    public Map getAttributesByteArray() throws AMException, SSOException;
281
282    /**
283     * Returns Map of specified attributes. Map key is the attribute name and
284     * value is the attribute value.
285     * 
286     * @param attributeNames
287     *            The Set of attribute names.
288     * @return Map of specified attributes.
289     * @throws AMException
290     *             if an error is encountered when trying to access/retrieve
291     *             data from the data store
292     * @throws SSOException
293     *             if the single sign on token is no longer valid.
294     */
295    public Map getAttributes(Set attributeNames) throws AMException,
296            SSOException;
297
298    /**
299     * Returns Map of specified attributes directly from data store. Map key is
300     * the attribute name and value is the attribute value.
301     * 
302     * @param attributeNames
303     *            The Set of attribute names.
304     * @return Map of specified attributes.
305     * @throws AMException
306     *             if an error is encountered when trying to access/retrieve
307     *             data from the data store
308     * @throws SSOException
309     *             if the single sign on token is no longer valid.
310     */
311    public Map getAttributesFromDataStore(Set attributeNames)
312            throws AMException, SSOException;
313
314    /**
315     * Returns Map of specified attributes. Map key is the attribute name and
316     * value is the attribute value in byte[][] format.
317     * 
318     * @param attributeNames
319     *            The Set of attribute names.
320     * @return Map of specified attributes. The key of the map is the attribute
321     *         name and the values in byte[][] format.
322     * @throws AMException
323     *             if an error is encountered when trying to access/retrieve
324     *             data from the data store
325     * @throws SSOException
326     *             if the single sign on token is no longer valid.
327     */
328    public Map getAttributesByteArray(Set attributeNames) throws AMException,
329            SSOException;
330
331    /**
332     * Returns attribute value.
333     * 
334     * @param attributeName
335     *            Attribute name
336     * @return Set of attribute values.
337     * @throws AMException
338     *             if an error is encountered when trying to access/retrieve
339     *             data from the data store
340     * @throws SSOException
341     *             if the single sign on token is no longer valid.
342     */
343    public Set getAttribute(String attributeName) throws AMException,
344            SSOException;
345
346    /**
347     * Returns attribute value.
348     * 
349     * @param attributeName
350     *            Attribute name
351     * @return attribute values in byte[][] format or null if the attribute does
352     *         not exist.
353     * @throws AMException
354     *             if an error is encountered when trying to access/retrieve
355     *             data from the data store
356     * @throws SSOException
357     *             if the single sign on token is no longer valid.
358     */
359    public byte[][] getAttributeByteArray(String attributeName)
360            throws AMException, SSOException;
361
362    /**
363     * Returns string type attribute value.
364     * 
365     * @param attributeName
366     *            Attribute name
367     * @return String value of attribute
368     * @throws AMException
369     *             if an error is encountered when trying to access/retrieve
370     *             data from the data store
371     * @throws SSOException
372     *             if the single sign on token is no longer valid.
373     */
374    public String getStringAttribute(String attributeName) throws AMException,
375            SSOException;
376
377    /**
378     * Returns Map of all attributes of specified service. Map key is the
379     * attribute name and value is the attribute value.
380     * 
381     * @param serviceName
382     *            Service name
383     * @return Map of all attributes of specified service, an empty Map will be
384     *         returned if no service attribute is defined in the specified
385     *         service.
386     * @throws AMException
387     *             if an error is encountered when trying to access/retrieve
388     *             data from the data store
389     * @throws SSOException
390     *             if the single sign on token is no longer valid.
391     * @deprecated This method has been deprecated. Please use service template
392     *             objects to obtain service attributes.
393     * @see AMOrganization#getTemplate
394     */
395    public Map getServiceAttributes(String serviceName) throws AMException,
396            SSOException;
397
398    /**
399     * Creates a Template with no priority for the given service associated with
400     * this <code>AMObject</code>.
401     * 
402     * @param templateType
403     *           the template type. Can be one of the following:
404     *           <ul>
405     *           <li>
406     *           {@link AMTemplate#DYNAMIC_TEMPLATE AMTemplate.DYNAMIC_TEMPLATE}
407     *           <li> {@link AMTemplate#ORGANIZATION_TEMPLATE  
408     *           AMTemplate.ORGANIZATION_TEMPLATE}
409     *           </ul>
410     * 
411     * @param serviceName
412     *            service name
413     * @param attributes
414     *            Map of attributes name-value pairs. if it is null default
415     *            values will be used.
416     * @return <code>AMTemplate</code> the service template for this
417     *         <code>AMObject</code>.
418     * @throws AMException
419     *             if an error is encountered when trying to access/retrieve
420     *             data from the data store.
421     * @throws SSOException
422     *             if the single sign on token is no longer valid.
423     * @throws UnsupportedOperationException
424     *             if the class implementing this interface does not support
425     *             this method.
426     */
427    public AMTemplate createTemplate(int templateType, String serviceName,
428            Map attributes) throws UnsupportedOperationException, AMException,
429            SSOException;
430
431    /**
432     * Creates a Template with a priority for the given service associated with
433     * this <code>AMObject</code>.
434     * 
435     * @param templateType
436     *           the template type. Can be one of the following:
437     *           <ul>
438     *           <li>
439     *           {@link AMTemplate#DYNAMIC_TEMPLATE AMTemplate.DYNAMIC_TEMPLATE}
440     *           <li> {@link AMTemplate#ORGANIZATION_TEMPLATE  
441     *           AMTemplate.ORGANIZATION_TEMPLATE}
442     *           </ul>
443     * @param serviceName
444     *            service name.
445     * @param attributes
446     *            Map of attributes name-value pairs
447     * @param priority
448     *            template priority (0 is the highest priority)
449     * @return <code>AMTemplate</code> the service template for this
450     *         <code>AMObject</code>.
451     * 
452     * @throws AMException
453     *             if an error is encountered when trying to access/retrieve
454     *             data from the data store
455     * @throws SSOException
456     *             if the single sign on token is no longer valid.
457     * @throws UnsupportedOperationException
458     *             if the class implementing this interface does not support
459     *             this method
460     */
461    public AMTemplate createTemplate(int templateType, String serviceName,
462            Map attributes, int priority) throws UnsupportedOperationException,
463            AMException, SSOException;
464
465    /**
466     * Returns the Template for the given service associated with this
467     * <code>AMObject</code>.
468     * 
469     * @param serviceName
470     *            service name.
471     * @param templateType
472     *           the template type. Can be one of the following:
473     *           <ul>
474     *           <li>
475     *           {@link AMTemplate#DYNAMIC_TEMPLATE AMTemplate.DYNAMIC_TEMPLATE}
476     *           <li> {@link AMTemplate#ORGANIZATION_TEMPLATE  
477     *           AMTemplate.ORGANIZATION_TEMPLATE}
478     *           </ul>
479     * @return <code>AMTemplate</code> the service template for this
480     *         <code>AMObject</code>.
481     * 
482     * @throws AMException
483     *             if an error is encountered when trying to access/retrieve
484     *             data from the data store
485     * @throws SSOException
486     *             if the single sign on token is no longer valid.
487     * @throws UnsupportedOperationException
488     *             if the class implementing this interface does not support
489     *             this method
490     */
491    public AMTemplate getTemplate(String serviceName, int templateType)
492            throws UnsupportedOperationException, AMException, SSOException;
493
494    /**
495     * Assigns the given policies to this object.
496     * 
497     * @param serviceName
498     *            service name.
499     * @param policyDNs
500     *            Set of policy DN string
501     * 
502     * @throws AMException
503     *             if an error is encountered when trying to access/retrieve
504     *             data from the data store
505     * @throws SSOException
506     *             if the single sign on token is no longer valid.
507     * @deprecated This method has been deprecated. Please use:
508     *             <code>com.sun.identity.policy</code> package for creating
509     *             and managing policies.
510     */
511    public void assignPolicies(String serviceName, Set policyDNs)
512            throws AMException, SSOException;
513
514    /**
515     * Unassigns the given policies from this object.
516     * 
517     * @param serviceName
518     *            service name.
519     * @param policyDNs
520     *            Set of policy DN string
521     * 
522     * @throws AMException
523     *             if an error is encountered when trying to access/retrieve
524     *             data from the data store
525     * @throws SSOException
526     *             if the single sign on token is no longer valid.
527     * @deprecated This method has been deprecated. Please use:
528     *             <code>com.sun.identity.policy</code> package for creating
529     *             and managing policies.
530     */
531    public void unassignPolicies(String serviceName, Set policyDNs)
532            throws AMException, SSOException;
533
534    /**
535     * Sets byte attribute values in this <code>AMObject</code>. Note that
536     * this method sets or replaces the attribute value with the new value
537     * supplied. Also, the attributes changed by this method are not committed
538     * to the LDAP data store unless the method {@link AMObject#store store()}
539     * is called explicitly.
540     * 
541     * @param attrName
542     *            the attribute name
543     * @param byteValues
544     *            attribute values in byte[][] format
545     * 
546     * @throws AMException
547     *             if an error is encountered when trying to access/retrieve
548     *             data from the data store
549     * @throws SSOException
550     *             if the single sign on token is no longer valid.
551     */
552    public void setAttributeByteArray(String attrName, byte[][] byteValues)
553            throws AMException, SSOException;
554
555    /**
556     * Sets byte attribute values in this <code>AMObject</code>. Note that
557     * this method sets or replaces the attribute value with the new value
558     * supplied. Also, the attributes changed by this method are not committed
559     * to the LDAP data store unless the method {@link AMObject#store store()}
560     * is called explicitly.
561     * 
562     * @param attributes
563     *            Map where key is the attribute name and values are in byte[][]
564     *            format.
565     * 
566     * @throws AMException
567     *             if an error is encountered when trying to access/retrieve
568     *             data from the data store
569     * @throws SSOException
570     *             if the single sign on token is no longer valid.
571     */
572
573    public void setAttributesByteArray(Map attributes) throws AMException,
574            SSOException;
575
576    /**
577     * Sets attribute values in this <code>AMObject</code>. Note that this
578     * method sets or replaces the attribute value with the new value supplied.
579     * Also, the attributes changed by this method are not committed to the LDAP
580     * data store unless the method {@link AMObject#store store()} is called
581     * explicitly.
582     * 
583     * @param attributes
584     *            Map where key is the attribute name and value is a Set of
585     *            attribute values. Each of the attribute value must be a string
586     *            value.
587     * 
588     * @throws AMException
589     *             if an error is encountered when trying to access/retrieve
590     *             data from the data store
591     * @throws SSOException
592     *             if the single sign on token is no longer valid.
593     */
594    public void setAttributes(Map attributes) throws AMException, SSOException;
595
596    /**
597     * Removes attributes in this <code>AMObject</code>. The attributes are
598     * removed from the LDAP data store
599     * 
600     * @param attributes
601     *            The Set of attribute names
602     * @throws AMException
603     *             if an error is encountered when trying to access/retrieve
604     *             data from the data store
605     * @throws SSOException
606     *             if the single sign on token is no longer valid.
607     */
608    public void removeAttributes(Set attributes) throws AMException,
609            SSOException;
610
611    /**
612     * Sets string type attribute value.
613     * 
614     * @param attributeName
615     *            attribute name
616     * @param value
617     *            value to be set for the attribute names.
618     * @throws AMException
619     *             if an error is encountered when trying to access/retrieve
620     *             data from the data store.
621     * @throws SSOException
622     *             if the single sign on token is no longer valid.
623     */
624    public void setStringAttribute(String attributeName, String value)
625            throws AMException, SSOException;
626
627    /**
628     * Deletes the object.
629     * 
630     * @see #delete(boolean)
631     * @see #purge(boolean, int)
632     * @throws AMException
633     *             if an error is encountered when trying to access/retrieve
634     *             data from the data store
635     * @throws SSOException
636     *             if the single sign on token is no longer valid.
637     */
638    public void delete() throws AMException, SSOException;
639
640    /**
641     * Deletes object(s). This method takes a boolean parameter, if its value is
642     * true, will remove the object and any objects under it, otherwise, will
643     * try to remove the object only. Two notes on recursive delete. First, be
644     * aware of the PERFORMANCE hit when large amount of child objects present.
645     * In the soft-delete mode, this method will mark the following objects for
646     * deletion: <code> Organization, Group, User </code>
647     * <code>purge()</code>
648     * should be used to physically delete this object.
649     * 
650     * @see #purge(boolean, int)
651     * 
652     * @param recursive
653     *            if true delete the object and any objects under it, otherwise,
654     *            delete the object only.
655     * @throws AMException
656     *             if an error is encountered when trying to access/retrieve
657     *             data from the data store
658     * @throws SSOException
659     *             if the single sign on token is no longer valid.
660     */
661    public void delete(boolean recursive) throws AMException, SSOException;
662
663    /**
664     * Search objects based on specified level and filter.
665     * 
666     * @param level
667     *            The search level starting from the object
668     * @param filter
669     *            The search filter
670     * @return Set of object DN's matching the search
671     * @throws AMException
672     *             if an error is encountered when trying to access/retrieve
673     *             data from the data store
674     * @throws SSOException
675     *             if the single sign on token is no longer valid.
676     */
677    public Set search(int level, String filter) throws AMException,
678            SSOException;
679
680    /**
681     * Registers a event listener that needs to be invoked when a relevant event
682     * occurs. If the listener was already registered, then it is registered
683     * only once; no duplicate registration is allowed.
684     * <p>
685     * {@link Object#equals Object.equals()} method on the listener object is
686     * used to determine duplicates.
687     * 
688     * @param listener
689     *            listener object that will be called upon when an event occurs.
690     * @throws SSOException
691     *             if errors were encountered in adding a new
692     *             <code>SSOTokenListener</code> instance
693     */
694    public void addEventListener(AMEventListener listener) throws SSOException;
695
696    /**
697     * Unregisters a previously registered event listener. If the
698     * <code>listener</code> was not registered previously, the method simply
699     * returns without doing anything.
700     * 
701     * @param listener
702     *            listener object that will be removed or unregistered.
703     */
704    public void removeEventListener(AMEventListener listener);
705
706    /**
707     * Creates a Policy Template with no priority for the given service
708     * associated with this <code>AMObject</code>. This is a convenience
709     * method and is equivalent to <code>createTemplate(
710     * AMTemplate.POLICY_TEMPLATE, serviceName, attributes)</code>.
711     * 
712     * @param serviceName
713     *            service name.
714     * @param attributes
715     *            Map of attributes name-value pairs.
716     * @return <code>AMTemplate</code> the service template for this
717     *         <code>AMObject</code>.
718     * @throws AMException
719     *             if an error is encountered when trying to access/retrieve
720     *             data from the data store.
721     * @throws SSOException
722     *             if the single sign on token is no longer valid.
723     * @throws UnsupportedOperationException
724     *             if the class implementing this interface does not support
725     *             this method.
726     * @deprecated use <code>com.sun.identity.policy</code> package for
727     *             creating and managing policies.
728     */
729    public AMTemplate createPolicyTemplate(String serviceName, Map attributes)
730            throws UnsupportedOperationException, AMException, SSOException;
731
732    /**
733     * Creates a Policy Template with a priority for the given service
734     * associated with this <code>AMObject</code>. This is a convenience
735     * method and is equivalent to
736     * <code>createTemplate(AMTemplate.POLICY_TEMPLATE, serviceName,
737     * attributes, priority)</code>.
738     * 
739     * @param serviceName
740     *            service name.
741     * @param attributes
742     *            Map of attributes name-value pairs.
743     * @param priority
744     *            template priority (0 is the highest priority).
745     * @return <code>AMTemplate</code> the service template for this
746     *         <code>AMObject</code>.
747     * 
748     * @throws AMException
749     *             if an error is encountered when trying to access/retrieve
750     *             data from the data store
751     * @throws SSOException
752     *             if the single sign on token is no longer valid.
753     * @throws UnsupportedOperationException
754     *             if the class implementing this interface does not support
755     *             this method.
756     * @deprecated use <code>com.sun.identity.policy</code> package for
757     *             creating and managing policies.
758     */
759    public AMTemplate createPolicyTemplate(String serviceName, Map attributes,
760            int priority) throws UnsupportedOperationException, AMException,
761            SSOException;
762
763    /**
764     * Returns the policy template for a service defined for this object
765     * ignoring any inheritance. This is a convenience method and is equivalent
766     * to <code>getTemplate(serviceName, AMTemplate.POLICY_TEMPLATE)</code>.
767     * <code>AMUser</code> object will throw
768     * <code>UnsupportedOperationException</code> because this method is not
769     * relevant for <code>AMUser</code>.
770     * 
771     * @param serviceName
772     *            service name.
773     * @return <code>AMTemplate</code> the policy template of the service for
774     *         this object.
775     * @throws UnsupportedOperationException
776     *             if the class implementing this interface does not support
777     *             this method.
778     * @throws AMException
779     *             if an error is encountered when trying to access/retrieve
780     *             data from the data store.
781     * @throws SSOException
782     *             if the single sign on token is no longer valid
783     * @deprecated This method has been deprecated. Please use:
784     *             <code>com.sun.identity.policy</code> package for creating
785     *             and managing policies.
786     */
787    public AMTemplate getPolicyTemplate(String serviceName)
788            throws UnsupportedOperationException, AMException, SSOException;
789
790    /**
791     * Returns the effective service policy defined at this object after
792     * considering any inheritance from any policy templates.
793     * 
794     * @param serviceName
795     *            service name.
796     * @return Map the effective service policy for the object after
797     *         inheritance; key is the attribute name and value is attribute
798     *         value. An empty Map will be returned if no policy attribute is
799     *         defined in the specified service.
800     * 
801     * @throws UnsupportedOperationException
802     *             if the class implementing this interface does not support
803     *             this method
804     * @throws AMException
805     *             if an error is encountered when trying to access/retrieve
806     *             data from the data store
807     * @throws SSOException
808     *             if the single sign on token is no longer valid
809     * @deprecated This method has been deprecated. Please use:
810     *             <code>com.sun.identity.policy</code> package for creating
811     *             and managing policies.
812     */
813    public Map getPolicy(String serviceName)
814            throws UnsupportedOperationException, AMException, SSOException;
815
816    /**
817     * Returns the object's organization. NOTE: Obtaining an organization DN
818     * involves considerable overhead. Hence after obtaining the organization
819     * DN, each object saves this information. Consecutives method calls on this
820     * object fetch the value stored in the object. Creating a new
821     * <code>AMObject</code> instance every time to obtain the organization DN
822     * is not recommended.
823     * 
824     * @return The object's organization DN.
825     * 
826     * @throws AMException
827     *             if an error is encountered when trying to access/retrieve
828     *             data from the data store or the object does not have
829     *             organization DN.
830     * @throws SSOException
831     *             if the single sign on token is no longer valid.
832     */
833    public String getOrganizationDN() throws AMException, SSOException;
834
835    /**
836     * Assign services to the entity (user/group/organization/organization
837     * unit). Also sets the attributes as provided in the map
838     * <code>serviceNameAndAttrs</code>. <code>serviceNameAndAttrs</code>
839     * is a map of keys which are service names and values which are
840     * attribute-value maps. Attribute values are validated against the
841     * respective service schemas before being set. Any required attributes (as
842     * defined in the service schema) not provided in the attribute Map, will be
843     * included and set to default values (picked up from the service schema).
844     * Only services which have been registered with the parent organization of
845     * the entity (the organization itself, in case the entity is an
846     * organization) will be assigned to the entity. So before assigning a
847     * service to an entity, <code>registerService()</code> should be used on
848     * the parent organization.
849     * 
850     * @see AMOrganization#registerService
851     * @param serviceNameAndAttrs
852     *            Map of Service name with Map of Attribute-Value pairs
853     * @throws AMException
854     *             if an error is encounters when trying to access/retrieve data
855     *             from the data store
856     * @throws SSOException
857     *             if the token is no longer valid
858     */
859    public void assignServices(Map serviceNameAndAttrs) throws AMException,
860            SSOException;
861
862    /**
863     * Assign services to the entity (user/group/organization/organization
864     * unit). Also sets the attributes as provided in the map
865     * <code>serviceNameAndAttrs</code>. <code>serviceNameAndAttrs</code>
866     * is a map of keys which are service names and values which are
867     * attribute-value maps. Attribute values are validated against the
868     * respective service schemas before being set. Any required attributes (as
869     * defined in the service schema) not provided in the attribute Map, will be
870     * included and set to default values (picked up from the service schema).
871     * Only services which have been registered with the parent organization of
872     * the entity (the organization itself, in case the entity is an
873     * organization) will be assigned to the entity. So before assigning a
874     * service to an entity, <code>registerService()</code> should be used on
875     * the parent organization.
876     * 
877     * @see AMOrganization#registerService
878     * @param serviceNameAndAttrs
879     *            Map of Service name with Map of Attribute-Value pairs
880     * @param store
881     *            If true, then the service attributes are saved in the
882     *            directory entry, otherwise, they are saved in the object and
883     *            the store method has to be called, to save these attributes
884     *            persistently in the data store.
885     * @throws AMException
886     *             if an error is encounters when trying to access/retrieve data
887     *             from the data store
888     * @throws SSOException
889     *             if the token is no longer valid
890     */
891    /*
892     * public void assignServices(Map serviceNameAndAttrs, boolean store) throws
893     * AMException, SSOException;
894     */
895
896    /**
897     * Modify the service attributes of a service assigned to a entity
898     * (user/group/organization/organizational unit). It replaces existing
899     * service attribute values with the ones provided. If new attribute values
900     * are provided, those are set too. Values of the attribute are validated
901     * against the service schema. Before the values are replaced in the entry,
902     * the <code>ServiceCallback</code> classes, if any, are instantiated and
903     * the <code>validateAttribute()</code> method is called.
904     * 
905     * @param serviceName
906     *            Name of the service which has to be modified
907     * @param attrMap
908     *            Map of attribute names and set of attribute values.
909     * @throws AMException
910     *             if an error occurs during validation or storing
911     * @throws SSOException
912     *             if the single sign on token is no longer valid.
913     */
914    public void modifyService(String serviceName, Map attrMap)
915            throws AMException, SSOException;
916
917    /**
918     * Set the status of the service for this entity (User/Organization
919     * /Group/Organizational Unit). The valid values for the status attribute
920     * are defined in the SMS DTD. Before the status attribute is set, it is
921     * verified to see if the service is first assigned to the user or not, and
922     * that the value for the status is valid per the DTD.
923     * 
924     * @param serviceName
925     *            Name of service whose status attribute has to be changed
926     * @param status
927     *            One of the status values as defined in the service schema
928     * @throws AMException
929     *             if a data store exception is encountered.
930     * @throws SSOException
931     *             if the single sign on token is no longer valid.
932     */
933    public void setServiceStatus(String serviceName, String status)
934            throws AMException, SSOException;
935
936    /**
937     * Get the status of the service for this entity (user/group/organization/
938     * organizational unit). Returns null, if service is not assigned to the
939     * entity.
940     * 
941     * @return status Value of the status attribute
942     * @param serviceName
943     *            Name of service
944     * @throws AMException
945     *             if a data store exception is encountered
946     * @throws SSOException
947     *             if single sign on token is no longer valid.
948     */
949    public String getServiceStatus(String serviceName) throws AMException,
950            SSOException;
951
952    /**
953     * Unassigns services from the user/group/organization/ organizational unit.
954     * 
955     * @param serviceNames
956     *            Set of service names
957     * @throws AMException
958     *             if there is an internal error in the access management data
959     *             store.
960     * @throws SSOException
961     *             if the single sign on token is no longer valid
962     */
963    public void unassignServices(Set serviceNames) throws AMException,
964            SSOException;
965
966    /**
967     * Returns all service names that are assigned to the
968     * user/group/organization/organizational unit.
969     * 
970     * @return The Set of service names that are assigned to the user.
971     * 
972     * @throws AMException
973     *             if there is an internal error in the access management data
974     *             store.
975     * @throws SSOException
976     *             if the single sign on token is no longer valid
977     */
978    public Set getAssignedServices() throws AMException, SSOException;
979
980    /**
981     * This method will physically delete the entry from the data store. This
982     * method will override the soft-delete option, which the method
983     * <code> delete()</code> will not. There is a big PERFORMANCE hit if this
984     * method is used to delete a large Organization in the recursive mode.
985     * 
986     * @see #delete()
987     * @param recursive
988     *            If true, then recursively delete the whole subtree.
989     * @param graceperiod
990     *            If set to an integer greater than -1, it will verify if the
991     *            object was last modified at least that many days ago before
992     *            physically deleting it. Pre/Post <code>Callback</code>
993     *            plugins as registered in the Administration Service, will be
994     *            called upon object deletion. If any of the
995     *            <code>pre-callback</code> classes throw an exception, then
996     *            the operation is aborted.
997     * @throws AMException
998     *             if there is an internal error in the access management data
999     *             store.
1000     * @throws SSOException
1001     *             if the single sign on token is no longer valid
1002     */
1003    public void purge(boolean recursive, int graceperiod) throws AMException,
1004            SSOException;
1005}




























































Copyright © 2010-2017, ForgeRock All Rights Reserved.