001/**
002 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003 *
004 * Copyright (c) 2006 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: ConfigurationInstance.java,v 1.3 2008/06/25 05:47:25 qcheng Exp $
026 *
027 */
028
029package com.sun.identity.plugin.configuration;
030
031import java.util.Map;
032import java.util.Set;
033
034/**
035 * <code>ConfigurationInstance</code> is the interface that provides the
036 * operations on service configuration. 
037 *
038 * @supported.all.api
039 */
040public interface ConfigurationInstance {
041
042    /**
043     * Initializer.
044     * @param componentName Name of the components, e.g. SAML1, SAML2, ID-FF
045     * @param session FM Session object.
046     * @exception ConfigurationException if could not initialize the instance.
047     */
048    public void init(String componentName, Object session) 
049        throws ConfigurationException;
050
051    /**
052     * Returns Configurations.
053     * @param realm the name of organization at which the configuration resides.
054     * @param configName configuration instance name. e.g. "/sp".
055     *     The configName could be null or empty string, which means the default
056     *     configuration for this components. 
057     * @return Map of key/value pairs, key is the attribute name, value is
058     *     a Set of attribute values or null if service configuration doesn't
059     *     exist. 
060     * @exception ConfigurationException if an error occurred while getting
061     *            service configuration.
062     */
063    public Map getConfiguration(String realm, String configName)
064        throws ConfigurationException;
065
066    /**
067     * Sets Configurations.
068     * @param realm the name of organization at which the configuration resides.
069     * @param configName configuration instance name. e.g. "/sp"
070     *     The configName could be null or empty string, which means the default
071     *     configuration for this components.
072     * @param avPairs Map of key/value pairs to be set in the service
073     *     configuration, key is the attribute name, value is
074     *     a Set of attribute values. 
075     * @exception ConfigurationException if could not set service configuration
076     *     or service configuration doesn't exist.
077     * @exception UnsupportedOperationException if this operation is not
078     *     supported by the implementation.
079     */
080    public void setConfiguration(String realm,
081        String configName, Map avPairs)
082        throws ConfigurationException,UnsupportedOperationException ;
083
084    /**
085     * Creates Configurations.
086     * @param realm the name of organization at which the configuration resides.
087     * @param configName service configuration name. e.g. "/sp"
088     *     The configName could be null or empty string, which means the
089     *     default configuration for this components.
090     * @param avPairs Map of key/value pairs to be set in the service
091     *     configuration, key is the attribute name, value is
092     *     a Set of attribute values. 
093     * @exception ConfigurationException if could not create service 
094     *     configuration.
095     * @exception UnsupportedOperationException if this operation is not
096     *     supported by the implementation.   
097     */
098    public void createConfiguration(String realm,
099        String configName, Map avPairs)
100        throws ConfigurationException, UnsupportedOperationException;
101
102    /**
103     * Deletes Configuration.
104     * @param realm the name of organization at which the configuration resides.
105     * @param configName service configuration name. e.g. "/sp"
106     *     The configName could be null or empty string, which means the default
107     *     configuration for this components.
108     * @param attributes A set of attributes to be deleted from the Service
109     *     configuration. If the value is null or empty, deletes all service 
110     *     configuration.
111     * @exception ConfigurationException if could not delete service 
112     *     configuration.
113     * @exception UnsupportedOperationException if this operation is not
114     *     supported by the implementation.   
115     */
116    public void deleteConfiguration(String realm, 
117        String configName, Set attributes)
118        throws ConfigurationException, UnsupportedOperationException;
119
120    /**
121     * Returns all service configuration name for this components.
122     * @param realm the name of organization at which the configuration resides.
123     * @return Set of service configuration names. Return null if there 
124     *     is no service configuration for this component, return empty set
125     *     if there is only default configuration instance.
126     * @exception ConfigurationException if could not get all service 
127     *     configuration names.
128     * @exception UnsupportedOperationException if this operation is not
129     *     supported by the implementation.   
130     */
131    public Set getAllConfigurationNames(String realm) 
132        throws ConfigurationException, UnsupportedOperationException;
133
134    /**
135     * Registers for changes to the component's configuration. The object will
136     * be called when configuration for this component is changed.
137     * @return the registered id for this listener instance.
138     * @exception ConfigurationException if could not register the listener.
139     * @exception UnsupportedOperationException if this operation is not
140     *     supported by the implementation.   
141     */
142    public String addListener(ConfigurationListener listener)
143        throws ConfigurationException, UnsupportedOperationException;
144
145    /**
146     * Unregisters the listener from the component for the given
147     * listener ID. The ID was issued when the listener was registered.
148     * @param listenerID the returned id when the listener was registered.
149     * @exception ConfigurationException if could not register the listener.
150     * @exception UnsupportedOperationException if this operation is not
151     *     supported by the implementation.
152     */
153    public void removeListener(String listenerID)
154        throws ConfigurationException, UnsupportedOperationException;
155 }