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: ServiceInstance.java,v 1.5 2008/07/11 01:46:21 arviranga Exp $
026 *
027 */
028
029/*
030 * Portions Copyrighted [2011] [ForgeRock AS]
031 */
032package com.sun.identity.sm;
033
034import java.util.Collections;
035import java.util.Map;
036import java.util.Set;
037
038import com.iplanet.sso.SSOException;
039import com.iplanet.sso.SSOToken;
040import com.iplanet.ums.IUMSConstants;
041
042/**
043 * The class <code>ServiceInstance</code> provides methods to manage service's
044 * instance variables.
045 *
046 * @supported.all.api
047 */
048public class ServiceInstance {
049    // InstanceVariables
050    private ServiceConfigManager scm;
051
052    private SSOToken token;
053
054    private ServiceInstanceImpl instance;
055
056    // Protected constructor
057    ServiceInstance(ServiceConfigManager scm, ServiceInstanceImpl i) {
058        this.scm = scm;
059        this.instance = i;
060        this.token = scm.getSSOToken();
061    }
062
063    /**
064     * Returns the instance name.
065     * 
066     * @return the instance name.
067     */
068    public String getName() {
069        return (instance.getName());
070    }
071
072    /**
073     * Returns the service name.
074     * 
075     * @return the service name.
076     */
077    public String getServiceName() {
078        return (scm.getName());
079    }
080
081    /**
082     * Returns the service version.
083     * 
084     * @return the service version.
085     */
086    public String getVersion() {
087        return (scm.getVersion());
088    }
089
090    /**
091     * Returns the group name from which the configuration parameters for the
092     * instance must be obtained.
093     * 
094     * @return the group name from which the configuration parameters for the
095     *         instance must be obtained.
096     */
097    public String getGroup() {
098        return (instance.getGroup());
099    }
100
101    /**
102     * Sets the group name for this instance.
103     * 
104     * @param groupName
105     *            name of group.
106     * @throws SSOException
107     *             if the user's single sign on token is invalid or expired
108     * @throws SMSException
109     *             if an error occurred while performing the operation
110     */
111    public void setGroup(String groupName) throws SSOException, SMSException {
112        validateServiceInstance();
113        if (!scm.containsGroup(groupName)) {
114            String[] args = { groupName };
115            throw (new SMSException(IUMSConstants.UMS_BUNDLE_NAME,
116                    "sms-invalid-group-name", args));
117        }
118        String[] groups = { groupName };
119        SMSEntry entry = instance.getSMSEntry();
120        entry.setAttribute(SMSEntry.ATTR_SERVICE_ID, groups);
121        entry.save(token);
122        instance.refresh(entry);
123    }
124
125    /**
126     * Returns the URL of the service. Will be <code>null</code> if the
127     * service does not have an URI.
128     * 
129     * @return the URL of the service. Will be <code>null</code> if the
130     *         service does not have an URI.
131     */
132    public String getURI() {
133        validate();
134        return (instance.getURI());
135    }
136
137    /**
138     * Sets the URI for the service instance.
139     * 
140     * @param uri
141     *            URI of the service instance.
142     * @throws SSOException
143     *             if the user's single sign on token is invalid or expired
144     * @throws SMSException
145     *             if an error occurred while performing the operation
146     */
147    public void setURI(String uri) throws SSOException, SMSException {
148        validateServiceInstance();
149        String[] uris = { uri };
150        SMSEntry entry = instance.getSMSEntry();
151        entry.setAttribute(SMSEntry.ATTR_LABELED_URI, uris);
152        entry.save(token);
153        instance.refresh(entry);
154    }
155
156    /**
157     * Returns the String representation of the <code>ServiceInstance</code>
158     * object.
159     * 
160     * @return the String representation of the <code>ServiceInstance</code>
161     *         object.
162     */
163    public String toString() {
164        StringBuilder sb = new StringBuilder(100);
165        sb.append("\nService Instance: ").append(getName()).append(
166                "\n\tGroup: ").append(getGroup()).append("\n\tURI: ").append(
167                getURI()).append("\n\tAttributes: ").append(getAttributes());
168        return (sb.toString());
169    }
170
171    /**
172     * Returns the attributes that are associated with the service's instances.
173     * 
174     * @return the attributes that are associated with the service's instances.
175     */
176    public Map getAttributes() {
177        validate();
178        return (instance.getAttributes());
179    }
180
181    /**
182     * Sets the attributes that are specific to the service instance. It is up
183     * to the service developer to define the set of attributes and values
184     * 
185     * @param attrs
186     *            map of attribute name to values.
187     * @throws SSOException
188     *             if the user's single sign on token is invalid or expired
189     * @throws SMSException
190     *             if an error occurred while performing the operation
191     */
192    public void setAttributes(Map attrs) throws SSOException, SMSException {
193        validateServiceInstance();
194        SMSEntry e = instance.getSMSEntry();
195        SMSUtils.setAttributeValuePairs(e, attrs, Collections.EMPTY_SET);
196        e.save(token);
197        instance.refresh(e);
198    }
199
200    /**
201     * Adds the given attribute name and values to the attribute set.
202     * 
203     * @param attrName
204     *            name of attribute.
205     * @param values
206     *            values to be added.
207     * @throws SSOException
208     *             if the user's single sign on token is invalid or expired
209     * @throws SMSException
210     *             if an error occurred while performing the operation
211     */
212    public void addAttribute(String attrName, Set values) throws SSOException,
213            SMSException {
214        validateServiceInstance();
215        SMSEntry e = instance.getSMSEntry();
216        SMSUtils.addAttribute(e, attrName, values, Collections.EMPTY_SET);
217        e.save(token);
218        instance.refresh(e);
219    }
220
221    /**
222     * Removes the specified attribute name and its values from the attribute
223     * set.
224     * 
225     * @param attrName
226     *            name of attribute.
227     * @throws SSOException
228     *             if the user's single sign on token is invalid or expired
229     * @throws SMSException
230     *             if an error occurred while performing the operation
231     */
232    public void removeAttribute(String attrName) throws SSOException,
233            SMSException {
234        validateServiceInstance();
235        SMSEntry e = instance.getSMSEntry();
236        SMSUtils.removeAttribute(e, attrName);
237        e.save(token);
238        instance.refresh(e);
239    }
240
241    /**
242     * Removes the specified attribute's values.
243     * 
244     * @param attrName
245     *            name of attribute.
246     * @param values
247     *            values to be removed.
248     * @throws SSOException
249     *             if the user's single sign on token is invalid or expired
250     * @throws SMSException
251     *             if an error occurred while performing the operation
252     */
253    public void removeAttributeValues(String attrName, Set values)
254            throws SSOException, SMSException {
255        validateServiceInstance();
256        SMSEntry e = instance.getSMSEntry();
257        SMSUtils.removeAttributeValues(e, attrName, values,
258                Collections.EMPTY_SET);
259        e.save(token);
260        instance.refresh(e);
261    }
262
263    /**
264     * Replaces the attribute's old value with the new value.
265     * 
266     * @param attrName
267     *            name of attribute.
268     * @param oldValue
269     *            old value.
270     * @param newValue
271     *            new value.
272     * @throws SSOException
273     *             if the user's single sign on token is invalid or expired
274     * @throws SMSException
275     *             if an error occurred while performing the operation
276     */
277    public void replaceAttributeValue(String attrName, String oldValue,
278            String newValue) throws SSOException, SMSException {
279        validateServiceInstance();
280        SMSEntry e = instance.getSMSEntry();
281        SMSUtils.replaceAttributeValue(e, attrName, oldValue, newValue,
282                Collections.EMPTY_SET);
283        e.save(token);
284        instance.refresh(e);
285    }
286
287    /**
288     * Replaces the attribute's old values with the new values
289     * 
290     * @param attrName
291     *            name of attribute.
292     * @param oldValues
293     *            old values.
294     * @param newValues
295     *            new values.
296     * @throws SSOException
297     *             if the user's single sign on token is invalid or expired
298     * @throws SMSException
299     *             if an error occurred while performing the operation
300     */
301    public void replaceAttributeValues(String attrName, Set oldValues,
302            Set newValues) throws SSOException, SMSException {
303        validateServiceInstance();
304        SMSEntry e = instance.getSMSEntry();
305        SMSUtils.replaceAttributeValues(e, attrName, oldValues, newValues,
306                Collections.EMPTY_SET);
307        e.save(token);
308        instance.refresh(e);
309    }
310    
311    public String toXML() {
312        return instance.toXML();
313    }
314    
315    // ----------------------------------------------------------
316    // Protected methods
317    // ----------------------------------------------------------
318    void delete() throws SMSException, SSOException {
319        validateServiceInstance();
320        SMSEntry entry = instance.getSMSEntry();
321        entry.delete();
322        instance.refresh(entry);
323    }
324    
325    // Validate PluginConfigImpl
326    protected void validate() {
327        try {
328            validateServiceInstance();
329        } catch (SMSException ex) {
330            SMSEntry.debug.error("ServiceInstance:validate exception", ex);
331        }
332    }
333    
334    protected void validateServiceInstance() throws SMSException {
335        if (!instance.isValid()) {
336            throw (new SMSException("Serviceinstance:validate " + getName() +
337                " No loger valid. Cache has been cleared. Recreate from" +
338                "ServiceConfigManager"));
339        }
340    }
341}