You can post comments and questions regarding the documentation provided below on the Documentation Feedback Wiki Page. The page will open in a new window.

`com.sun.identity.plugin.configuration` Package for Service Configurations

The com.sun.identity.plugin.configuration package is used to manipulate service configurations. This document contains the following sections:

com.sun.identity.plugin.configuration Interfaces
About Service Configurations
Manipulating Service Configurations with ConfigurationInstance
Event Notification with ConfigurationInstance
Sample Code

`com.sun.identity.plugin.configuration` Interfaces

Following are the interfaces in the com.sun.identity.plugin.configuration package.

`com.sun.identity.plugin.configuration.ConfigurationActionEvent`	Represents an event that has happened to the `ConfigurationInstance`
`com.sun.identity.plugin.configuration.ConfigurationException`	Thrown when there are errors related to configuration operations
`com.sun.identity.plugin.configuration.ConfigurationInstance`	Provides the methods for operations on service configurations
`com.sun.identity.plugin.configuration.ConfigurationManager`	Provides a method to retrieve configuration instances
`com.sun.identity.plugin.configuration.ConfigurationListener`	Implemented by applications in order to receive configuration data change notifications

About Service Configurations

ConfigurationInstance is the interface that provides the methods for operations on service configurations. Service configurations contain attributes; each attribute may have multiple values. Multiple sets of attributes are also supported; each set is accessed by a configuration name. Finally, service configurations are defined within realms; each realm may have more than one set of configurations. Here is an example of a service configuration:

realm 1
- config 1
- config 2
realm 2
- config 3
- config 4

Manipulating Service Configurations with `ConfigurationInstance`

ConfigurationInstance contains the following methods for manipulating service configuration attributes. Each method takes as input a realm and a configuration name.

NOTE: A null realm is considered the root realm. A null configuration name is considered the default configuration for the realm.

public Map getConfiguration(String realm, String configName)
throws ConfigurationException;
public void setConfiguration(String realm, String configName, Map avPairs)
throws ConfigurationException,UnsupportedOperationException;
public void createConfiguration(String realm, String configName, Map avPairs)
throws ConfigurationException, UnsupportedOperationException;
public void deleteConfiguration(String realm, String configName, Set attributes)
throws ConfigurationException, UnsupportedOperationException;

Attributes are represented by a Map where Key is the attribute name and value is a set of values in String.

To get a ConfigurationInstance object, call:

ConfigurationInstance ConfigurationManager.getConfigurationInstance(String componentName)

where componentName is the name of the configuration (for example, SAML1, SAML2 or ID-FF), and ConfigurationManager will read the ConfigurationInstance implementation class from the com.sun.identity.plugin.configuration.class property in FederationConfig.properties.

Event Notification with `ConfigurationInstance`

ConfigurationInstance contains the following methods for event notification:

public String addListener(ConfigurationListener listener) throws ConfigurationException, UnsupportedOperationException;
public void removeListener(String listenerID) throws ConfigurationException, UnsupportedOperationException;

These methods are used to add and remove a ConfigurationListener. ConfigurationListener has one method: public void configChanged(ConfigurationActionEvent e); This method is called when there is a change in the ConfigurationInstance. configChanged is passed a ConfigurationActionEvent as parameter. ConfigurationActionEvent reports the component name, the configuration name, the realm and the type of event action, of which there are three:

ADDED - when a configuration is created
DELETED - when a configuration is deleted
MODIFIED - when a configuration is changed

Sample Code

package com.sun.identity.plugin.configuration.unitest;

import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.Map;
import java.util.Set;
import com.sun.identity.plugin.configuration.ConfigurationActionEvent;
import com.sun.identity.plugin.configuration.ConfigurationException;
import com.sun.identity.plugin.configuration.ConfigurationInstance;
import com.sun.identity.plugin.configuration.ConfigurationManager;
import com.sun.identity.plugin.configuration.ConfigurationListener;

public class Test implements ConfigurationListener {   

    public static void main(String[] argv) {
        try {
            String componentName = "test";
            String configName = "config1";
            String realm = "/";

            // get ConfigurationInstance "test"
            ConfigurationInstance ci =
                ConfigurationManager.getConfigurationInstance(componentName);

            // add a listener to receive event notification
            ci.addListener(new Test());

            // create a configuration "config1" under realm "/" with 2
            // attributes "attr1" and "attr2"
            Set values = new HashSet();
            values.add("abcd");
            values.add("efgh");
            Map avPairs = new HashMap();
            avPairs.put("attr1", values);
            values = new HashSet();
            values.add("1234");
            values.add("5678");
            avPairs.put("attr2", values);
            ci.createConfiguration(realm, configName, avPairs);


            // get configuration we just created.
            avPairs = ci.getConfiguration(realm, configName);
            Set attrNames = avPairs.keySet();
            for(Iterator iter = attrNames.iterator(); iter.hasNext();) {
                String attrName = (String)iter.next();
                System.out.println("attribute name : " + attrName);
                values = (Set)avPairs.get(attrName);
                for(Iterator iter2 = values.iterator(); iter.hasNext();) {
                    System.out.println("attribute value : " +
                        ((String)iter.next()));
                }
            }

            // modify attribute "attr1" in configuration
            values = (Set)avPairs.get("attr1");
            values.add("ijkl");
            ci.setConfiguration(realm, configName, avPairs);

            // delete attribute "attr1" in configuration
            attrNames = new HashSet();
            attrNames.add("attr1");
            ci.deleteConfiguration(realm, configName, attrNames);

            // delete configuration
            ci.deleteConfiguration(realm, configName, null);
        } catch (ConfigurationException ex) {
            ex.printStackTrace();
        }
    }  


    /**
     * This method will be invoked when a component's 
     * configuration data has been changed. The parameters componentName,
     * realm and configName denotes the component name,
     * organization and configuration instance name that are changed 
     * respectively.
     *
     * @param e Configuration action event, like ADDED, DELETED, MODIFIED etc.
     */
    public void configChanged(ConfigurationActionEvent e) {
        System.out.println("Event component name : " + e.getComponentName());
        System.out.println("Event configuration name : " +
            e.getConfigurationName());
        System.out.println("Event realm : " + e.getRealm());
        int type = e.getType();
        if (type == ConfigurationActionEvent.ADDED) {
            System.out.println("Event type : ADDED");
        } else if (type == ConfigurationActionEvent.DELETED) {
            System.out.println("Event type : DELETED");
        } else if (type == ConfigurationActionEvent.MODIFIED) {
            System.out.println("Event type : MODIFIED");
        }
    }
}

com.sun.identity.plugin.configuration Package for Service Configurations

com.sun.identity.plugin.configuration Interfaces