7 Developing Plug-ins

7.1.1 About the Plug-in Framework

The plug-in framework provides Oracle Identity Manager with a number of added capabilities. For example:

• Services can define plug-in points where functionality can be extended. For example, the notification engine uses a default provider to send e-mail notifications. This provider is set up as a plug-in point so that a custom e-mail provider can be implemented.

• Services can discover all the plug-ins defined for a particular plug-in point.

• Plug-ins can be loaded from multiple sources. Feature developers do not need to be concerned about where the plug-ins are stored or with how they are loaded.

• Developers can change the plug-in code without needing to re-register the plug-in. Note: This is possible only when the plug-in is stored on the filesystem.

7.1.2 About Plug-in Stores

The plug-in framework can store plug-ins in two types of stores:

• File system

• The Oracle Identity Manager database

When looking for plug-ins, the framework first examines plug-ins registered in the database, and looks in the file system.

7.1.3 Steps for Developing Plug-ins

The basic aspects of developing and implementing plug-ins are as follows:

• Declare a plug-in instance where you may specify the type of value mapping for the plug-in point.

• Specify the properties that will comprise the plug-in metadata.

• Develop the plug-in code and distribute the plug-in.

For details, see Section 7.3, "Defining and Using Plug-ins".

7.3.1 Declaring Plug-ins

To extend the functionality provided by Oracle Identity Manager, you can declare the plug-ins for the application. The declaration can be explicit or implicit.

A plug-in has a Java class that implements the plug-in point interface. Be sure to assign unique names to all the plug-ins associated with a specific plug-in point. If the plug-in names are non-unique, an exception will be thrown during plug-in registration.

Declare the plug-ins in the plugin.xml file. For example:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins>
....
<plugins pluginpoint="oracle.iam.sample.passwdmgmt.service.PasswordElement">
        <plugin pluginclass=
        "oracle.iam.sample.passwdmgmt.custom.NumCustomPasswordElement" 
        version="1.0.1" name="num pwd element"/>
        <plugin pluginclass=
        "oracle.iam.sample.passwdmgmt.custom.DictionaryPasswordElement" 
        version="1.0.1" name="Dictionary password element" />        
</plugins>
....
</oimplugins>

The XML shows two plug-in declarations. Both the plug-ins extend from the same plug-in point.

7.3.2 Specifying Plug-in Metadata

Along with each plug-in that is defined in plugin.xml, you can specify a list of properties that comprise the plug-in metadata.

In this example, the metadata consists of a single property known as PasswordElementNum, with the value 1:

<?xml version="1.0" encoding="UTF-8"?>
<oimplugins>
    ....
  <plugins pluginpoint="oracle.iam.sample.passwdmgmt.service.PasswordElement">
    <plugin pluginclass= "oracle.iam.sample.passwdmgmt.custom.NumCustomPasswordElement"
            version="1.0.1" name="num pwd element">
      <metadata name="PasswordElementNum"><value>1</value></metadata>
    </plugin>
    <plugin pluginclass= "oracle.iam.sample.passwdmgmt.custom.DictionaryPasswordElement"
          version="1.0.1" name="Dictionary password element" >
      <metadata name="PasswordElementNum"><value>2</value></metadata>
    </plugin>
  </plugins>
    ....
</oimplugins>

7.3.3 Developing Plug-ins

An Oracle Identity Manager plug-in is distributed as a ZIP file with a specified directory structure. The directory structure is as follows:

• The plugin.xml file: The XML file contains the metadata associated with all the plug-ins such as the plug-in point it extends, the class implementing the plug-in, name, and the version number. All the fields in the XML are mandatory except the name. If the name is not given, then plugin class name is used as the name.

• The lib/ directory: The lib/ directory consists of JAR files that contains the classes implementing the plug-in logic and the dependent library JAR files. In most instances, this directory consists of a single JAR file with the implementation of all the plug-ins that are specified in plugin.xml.

• The resources/ directory: Contains resource files required by the plug-in, such as property files, resource bundles, and image files.

Multiple plug-ins implementing the same plug-in point can be part of the same ZIP file.

A plug-in has a Java class that implements the plug-in point interface. The plug-in library (JAR) can contain other classes as well, but the class implementing the plug-in is the only one that is exposed to the feature. This class must be specified in plugin.xml.

The plug-in can also use any resources files. These resources given in the resources directory of the plug-in zip can be accessed as follows:

this.getClass().getClassLoader().getResourceAsStream(<resource_name>);

7.4.1 Registering and Unregistering Plug-ins By Using APIs

You can use the following APIs for registration-related tasks:

• PlatformService.registerPlugin

• PlatformService.unRegisterPlugin

Here is an example:

ClientPlatform platform = OIMClient.getInstance();
platform.login("username", "password");
PlatformService service = platform.getService(PlatformService.class);
File zipFile = new File(fileName);
FileInputStream fis = new FileInputStream(zipFile);
int size = (int) zipFile.length();
byte[] b = new byte[size];
int bytesRead = fis.read(b, 0, size);
while (bytesRead < size) {
bytesRead += fis.read(b, bytesRead, size - bytesRead);
}
fis.close();
service.registerPlugin(b);
service.unRegisterPlugin(pluginID, version);

7.4.2 Registering and Unregistering Plug-ins By Using the Plugin Registration Utility

You can use the Plugin Registration Utility for registering and unregistering plug-ins. The utility uses the following files:

• pluginregistration.xml

• ant.properties

These files are located in the OIM_HOME/plugin_utility/ directory.

Before using the utility, perform the following:

1. Set the values for WLS_HOME and OIM_HOME in ant.properties.

   For example:

   WLS_HOME =.../middleware/wlserver_10.3
   OIM_HOME =..../middleware/Oracle_IDM1/server
   

2. Build the wlfullclient.jar in Oracle WebLogic server:

   1. Change directories to WLS_HOME/server/lib.

   2. Run the following command:

      java -jar ../../../modules/com.bea.core.jarbuilder_1.3.0.0.jar
      

      Note:

      The exact jar file version can be different based on the WLS. Use the corresponding file with the name as com.bea.core.jarbuilder at the WLS_HOME/../modules/ directory.

Registering a Plug-in

To register a plug-in:

1. Execute the ant target "register":

   ant -f  pluginregistration.xml register
   

2. This will prompt for the Oracle Identity Manager username and password along with the server information and the location of the plugin zip file. Enter the complete path of the zip file location.

Unregister a Plug-in

To unregister a plug-in:

1. Execute the ant target "unregister":

   ant -f  pluginregistration.xml unregister
   

2. This will prompt for the Oracle Identity Manager username and password along with the server information and the classname of the plug-in class. Enter the classname with the complete package.

7.5.1 Accessing Mapped Values

The plug-in framework uses the following logic to determine a simple mapped value:

• If the given attribute name has a mapping specified for the given method, then that mapping is used. Otherwise, if the given attribute name has a mapping specified for all methods, then that mapping is used. Otherwise, NoSuchMappingException is generated.

• If the attribute for the mapping is declared, then the attribute is used as the key to lookup the value in the provided HashMap.

• If the attribute for the mapping is not declared but the value of the mapping is declared, then that value is returned. For example:

  Map<String, Object> ro = new HashMap<String, Object>();
  ro.put("smvalue1", "value");
  ro.put("smattr2", "value2");
  String attr1 = PluginFramework.getMappedValue(this, ro, "attr1", "evaluate");
  String attr2 = PluginFramework.getMappedValue(this, ro, "attr2", "evaluate");