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: Organization.java,v 1.3 2008/06/25 05:41:45 qcheng Exp $
026 *
027 */
028
029package com.iplanet.ums;
030
031import java.security.Principal;
032import java.util.ArrayList;
033import java.util.Collection;
034
035import com.iplanet.services.ldap.AttrSet;
036import com.iplanet.services.util.I18n;
037
038/**
039 * Represents an organization object. An organization can have child
040 * organizations and groups, or other child objects.
041 * 
042 * <pre>
043 *  o=vortex.com  (site)
044 *       o=hp     (organization)
045 *           uid=jdoe
046 *           
047 *       o=sun    (organization)
048 *           ou=buyerclub  
049 *               uid=joe    
050 * </pre>
051 *
052 * @supported.api
053 */
054public class Organization extends PersistentObject {
055
056    private static I18n i18n = I18n.getInstance(IUMSConstants.UMS_PKG);
057
058    /**
059     * No args constructor, used to contruct the right object as entries are
060     * read from persistent storage
061     * 
062     */
063    protected Organization() throws UMSException {
064    }
065
066    /**
067     * Constructs Organization from supplied session and guid identifying the
068     * organization to be constructed.
069     * 
070     * @param session
071     *            authenticated session object maintained by Session Manager
072     * @param guid
073     *            globally unique identifier for the organization
074     */
075    Organization(Principal principal, Guid guid) throws UMSException {
076        super(principal, guid);
077        verifyClass();
078    }
079
080    /**
081     * Constructs Organization object without a session. Unlike the constructor
082     * with a session parameter , this one simply creates a Group object in
083     * memory, using the default template. Call the save() method to save the
084     * object to the persistent store.
085     * 
086     * @param attrSet
087     *            attribute/value set
088     */
089    Organization(AttrSet attrSet) throws UMSException {
090        this(TemplateManager.getTemplateManager().getCreationTemplate(_class,
091                null), attrSet);
092    }
093
094    /**
095     * Constructs Organization object without session. Unlike the constructor
096     * with session, this one simply creates Organization object in memory. Call
097     * the save() method to save the object to persistent storage.
098     * 
099     * @param template
100     *            template for the organization
101     * @param attrSet
102     *            attribute/value set
103     * @supported.api
104     */
105    public Organization(CreationTemplate template, AttrSet attrSet)
106            throws UMSException {
107        super(template, attrSet);
108    }
109
110    /**
111     * Adds a new object to the organization.
112     * 
113     * @param object
114     *            object to be added to the organization
115     * @exception AccessRightsException
116     *                if an access rights exception occurs
117     * @exception EntryAlreadyExistsException
118     *                if the entry already exists
119     * @exception UMSException
120     *                Fail to add the object
121     * @supported.api
122     */
123    public void addChild(PersistentObject object) throws AccessRightsException,
124            EntryAlreadyExistsException, UMSException {
125        Principal principal = getPrincipal();
126
127        if (principal == null) {
128            String msg = i18n.getString(IUMSConstants.BAD_PRINCIPAL_HDL);
129            throw new IllegalArgumentException(msg);
130        } else if (object == null) {
131            String msg = i18n.getString(IUMSConstants.BAD_OBJ_TO_ADD);
132            throw new IllegalArgumentException(msg);
133        }
134
135        if (object instanceof User) {
136            String pcId = getPeopleContainer((User) object);
137            if (pcId != null) {
138                PeopleContainer pc = new PeopleContainer(getPrincipal(),
139                        new Guid(pcId));
140                pc.addUser((User) object);
141            } else {
142                // no match and no default value found
143                // For now, the user will be addedd to the organization.
144                // May want to add to the default people
145                // container(ou=People) instead.
146                super.addChild(object);
147            }
148
149        } else {
150
151            super.addChild(object);
152        }
153    }
154
155    /**
156     * Removes an object from the organization.
157     * 
158     * @param object
159     *            object to be removed to the organization
160     * @exception AccessRightsException
161     *                if an access rights exception occurs
162     * @exception EntryNotFoundException
163     *                if the entry is not found
164     * @exception UMSException
165     *                Fail to remove the object
166     * @supported.api
167     */
168    public void removeChild(PersistentObject object)
169            throws AccessRightsException, EntryNotFoundException, UMSException {
170        if (object != null && getPrincipal() != null) {
171            super.removeChild(object);
172        }
173    }
174
175    /**
176     * Returns the name of the organization.
177     * 
178     * @return name of the organization
179     * @supported.api
180     */
181    public String getName() throws UMSException {
182        return getAttribute(getNamingAttribute()).getValue();
183    }
184
185    /**
186     * Get roles associated with the organization
187     * <P>
188     * TODO: Not yet implemented
189     * 
190     * @return guid identifying roles object under the organization
191     * 
192     * public String[] getRolesArray(){ //getRoles() {
193     * 
194     * return null; }
195     */
196
197    /**
198     * Get groups of which the organization is a member.
199     * <P>
200     * TODO: Not yet implemented
201     * 
202     * @return guids identifying groups that the organization is a member of
203     * 
204     * public String[] getGroups() { return null; }
205     */
206
207    /**
208     * Gets all People Containers under the organization.
209     * 
210     * @return guids identifying People Containers under the organization
211     * @exception UMSException
212     *                Failure
213     * @supported.api
214     */
215    public Collection getPeopleContainerGuids() throws UMSException {
216        Collection pcs = new ArrayList();
217        SearchTemplate template = TemplateManager.getTemplateManager()
218                .getSearchTemplate("BasicPeopleContainerSearch", getGuid());
219        SearchResults results = search(template, null);
220        while (results.hasMoreElements()) {
221            pcs.add(results.next().getGuid());
222        }
223        return pcs;
224    }
225
226    /**
227     * Gets People Container associated with the user.
228     * 
229     * @param user
230     *            user object to lookup
231     * @return guid identifying People Container associated with the user, null
232     *         if no match found
233     * @exception UMSException
234     *                Failure
235     */
236    private String getPeopleContainer(User user) throws UMSException {
237        PCMappingTable mt = PCMappingTable.getPCMappingTable(this);
238        return mt.getPeopleContainer(user);
239    }
240
241    /**
242     * Adds rule for determining which People Container the user is supposed to
243     * be in.
244     * 
245     * @param filter
246     *            filter representation of the rule. Accepts filter string with
247     *            the following format:
248     *            <P>
249     * 
250     * <PRE>
251     * 
252     * &ltfilter&gt ::= &ltand&gt | &ltitem&gt &ltand&gt ::= '(' '&'
253     *            &ltitemlist&gt ')' &ltitemlist&gt ::= &ltitem&gt | &ltitem&gt
254     *            &ltitemlist&gt &ltitem&gt ::= '(' &ltattr&gt '=' &ltvalue&gt
255     *            ')'
256     * 
257     * </PRE>
258     * 
259     * @param guid
260     *            guid of the People Container to which the rule is applied.
261     * @exception UMSException
262     *                Failure
263     * @supported.api
264     */
265    public void addPeopleContainerRule(Guid guid, String filter)
266            throws UMSException {
267        PCMappingTable mt = PCMappingTable.getPCMappingTable(this);
268        mt.addRule(guid, filter);
269    }
270
271    /**
272     * Removes the rule applying to the given People Container guid with the
273     * given filter string.
274     * 
275     * @param filter
276     *            filter string of the rule to be removed
277     * @param guid
278     *            guid of which the rule applies to
279     * @exception UMSException
280     *                Failure 
281     * @supported.api
282     */
283    public void removePeopleContainerRule(Guid guid, String filter)
284            throws UMSException {
285        PCMappingTable mt = PCMappingTable.getPCMappingTable(this);
286        mt.removeRule(guid, filter);
287    }
288
289    /**
290     * Sets the default People Container for user entries under the
291     * organization.
292     * 
293     * @param guid
294     *            guid of the default People Container
295     * @exception UMSException
296     *                Failure
297     * @supported.api
298     */
299    public void setDefaultPeopleContainer(Guid guid) throws UMSException {
300        PCMappingTable mt = PCMappingTable.getPCMappingTable(this);
301        mt.setDefault(guid);
302    }
303
304    private static final Class _class = com.iplanet.ums.Organization.class;
305}