The plug-in framework enables you to define, register, and configure plug-ins, which extend the functionality provided by features. Plug-ins can be predefined or custom-developed, and they are utilized at plug-in points.

A plug-in is a logical component that extends the functionality of features provided by Oracle Identity Manager. The plug-in framework enables you to define, register, and configure plug-ins, which extend the functionality provided by features. Plug-ins can be predefined or custom-developed, and they are utilized at plug-in points. A plug-in point is a specific point in the business logic where extensibility can be provided. An interface definition called the plug-in interface accompanies such a point. You can extend the plug-in interface based on the business requirements and register them as plug-ins. To do this, you develop a Plugin Java class and compile it before archiving in a JAR file, define plug-in metadata in an XML file, and ZIP these artifacts as a plug-in package that is ready to deploy.

For example, user creation is a business operation in Oracle Identity Manager. But this operation exposes a plug-in point for user name generation. If you want to model your custom logic of user name generation, then you must identify the plug-in point specifications and develop a plug-in accordingly.

Most of the business operations in Oracle Identity Manager, such as user creation, role assignment to user, and user activation, are executed as orchestrations.

Therefore, if there is a requirement to induce any custom logic in these operations or orchestrations, then you can model that logic as event handlers at stages, such as validation, preprocess, and postprocess, in which customization is supported. However, you can analyze if any such operation also exposes a plug-in point for inducing the custom logic. If a plug-in point is available, then you can utilize the plug-in point rather than operating the underlying orchestration. For example, you can implement username generation by using the exposed plug-in without writing that as an event handler in the create user orchestration.

Figure 17-1 shows a diagrammatic representation of plug-ins and event handlers.

Figure 17-1 Plug-ins and Event Handlers

Description of "Figure 17-1 Plug-ins and Event Handlers"

The plug-in framework stores plug-ins in the plug-in stores.

This section describes plug-in stores and the types of stores. It contains the following sections:

• About Plug-in Stores

• The File Store

• The Database Store

Developing plug-ins include identifying the plug-in point and Java class, configure the plugin.xml file, identify the resource files required by the plug-in, and zipping the entire package in the file store or database store.

1. Identify the plug-in point to extend.
2. Identify the Java class that implements the plug-in point interface. Package the Java class and other dependent classes into a JAR file. Put the JAR file in the lib/ directory.
3. Create the plugin.xml file. See Declaring Plug-ins for details.
4. Identify the resource files required by the plug-in, such as property files, resource bundles, and image files.
5. Zip the entire package.

   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. These resources given in the resources directory of the plug-in zip can be accessed as follows:

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

   • The META-INF/ directory: Contains XML files showing plug-in points for event handlers. Some services, such as the notification service, read the XML files from MDS or from the META-INF/ directory of the plug-in.

   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 dependent 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.

6. Place the ZIP file in the file store (the OIM_HOME/plugins/ directory) or database store.
7. If the ZIP is placed in the database store, then register the plug-in by using the Plug-in Registration Utility, as described in Registering Plug-ins.

To extend the functionality provided by Oracle Identity Manager, you can declare the plug-ins for the application.

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.

You can use the PlatformService.registerPlugin and PlatformService.unRegisterPlugin APIs for registration-related tasks.

Here is an example:

System.out.println("Creating client....");
String ctxFactory = "weblogic.jndi.WLInitialContextFactory";
String serverURL = "t3://OIM_HOSTNAME:OIM_PORT";
System.setProperty("java.security.auth.login.config", "OIM_CLIENT_HOME/conf/authwl.conf");
String username = "USER_NAME";
char[] password = "PASSWORD".toCharArray();
Hashtable env = new Hashtable();
env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);

oimClient = new OIMClient(env);
System.out.println("Logging in");
oimClient.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);

Use the Plugin Registration Utility to register and unregister plug-ins.

This section describes how to register and unregister plug-ins by using the Plugin Registration Utility. It contains the following topics:

• The Plugin Registration Utility

• Prerequisites of Using the Plugin Registration Utility

• Registering a Plug-in

• Unregistering a Plug-in

• Re-registering and Activating an Old Plug-in Version