18 Deploying Custom Code Using Dynamic Discovery

Dynamic Discovery allows you to plug your changes into the UI architecture without modifying any existing UI code. Dynamic Discovery is a framework for detecting extensible UI features. When the portal is loaded on startup, this tool automatically creates instances of objects according to an XML file. Dynamic Discovery can be configured in a few different ways. For example, it can load all instances of one specific interface from one or more libraries, or load instances of specific classes.

The main benefit of Dynamic Discovery is the ability to customize the portal without changing existing code. Using Dynamic Discovery, you can overwrite core portal classes, change the behavior of some features, customize pages, and add features to the portal simply by editing XML files and adding new libraries. Dynamic Discovery was created to make the UI as extensible as possible and to facilitate upgrading the UI after customizations have been made. If you allow your modifications to be dynamically discovered, your code will remain separate from the portal code, making upgrades easier.

Dynamic Discovery Configuration Files

Dynamic Discovery relies on three configuration files in the <PT_HOME>\settings\portal directory:

The ActivitySpaces.xml file enumerates all the JAR (or DLL) files that Oracle WebCenter Interaction uses to discover classes that implement IModel, IView, and IControl. Additionally, the portal searches these lib files for navigation schemes (INavTypes). Do not modify this file.
The CustomActivitySpaces.xml file is empty at the time a new portal ships. Functionally, this file is identical to ActivitySpaces.xml. It is a mechanism to help you keep custom code separate from platform code. (The distinction is not enforced. It is intended to help you keep custom code separate and easily identifiable.)
The *.xml files in the \dynamicloads subdirectory are also used by Dynamic Discovery. For example, all PEIs are dynamically discovered using a separate *Actions.xml file in the \PEIs subfolder. At startup, the portal loops through all of these files and calls GetInstancesFromXML on each. The returned array of objects is cached on the portal application with the key being the name or the XML file. When an event occurs, all the classes that have implemented the corresponding interface are loaded into the portal application, and each implemented function is processed in the order shown within the XML file.

Using Dynamic Discovery

The portal application uses an XML file to identify customized UI components during startup and place them in the proper location. There are two mechanisms available:

Interface-Based Dynamic Discovery supports the most commonly customized events, represented by Portal Event Interfaces (PEIs). For detailed information on PEIs, see Chapter 12, "Using PEIs".
JAR- or DLL-Based Dynamic Discovery allows you to make other extensions or changes to the UI (for example, View replacement or a new Navigation Scheme) without changing any existing source code.

A summary of each mechanism is provided below.

Interface-Based Dynamic Discovery

All PEIs are dynamically recognized through interface-based Dynamic Discovery. An XML file is provided for each PEI that contains a listing of each implementation of the specific PEI. Multiple implementations can be placed within the XML file; each implementation is processed in the order that it appears.

Find the XML file for the PEI (files for all PEIs can be found in the PT_HOME\settings\portal\dynamicloads\PEIs directory).
Open the file in a text editor and add your class name to the list. (For .NET, you must first stop the WWW Service on the portal server.) The example below is from the LoginActions.xml file.
```
<root> 
<interface name="com.plumtree.uiinfrastructure.pei.ILoginActions"/>
<interfaceassembly name="uiinfrastructure"/>
<class name="com.plumtree.portalpages.pei.PTLoginActions"/>
<class name="com.plumtree.sampleui.pei.HelloWorldLoginActions"/>
</root>
```
Note: The package referenced in the XML file must include the class that implements the corresponding PEI (as described in Using PEIs). The Dynamic Discovery process looks for a class file that matches the name listed and the PEI defined within the XML file. The name is case sensitive.
Restart your application server (Java) / the WWW Service on the portal server (.NET).
To verify that your UI modifications were loaded correctly, turn on Logging Spy and watch for Dynamic Discovery lines. There will be a separate line corresponding to each file loaded from each XML file.

For detailed instructions on PEI deployment, see Chapter 12, "Using PEIs", Step 3: Deploying a Custom PEI.

Jar or DLL-Based Dynamic Discovery

JAR- or DLL-based Dynamic Discovery allows you to make extensions or changes to the UI without changing any existing source code. By using new code instead of modifying existing code, no customizations are overwritten when the portal application is upgraded to a new release. Your code can take precedence over existing UI code, or you can create a completely new section for the UI. These UI modifications are picked up by the Dynamic Discovery package when the portal application is started.

To make an addition to the UI, create a new section using the ActivitySpace/MVC paradigm. Navigation schemes are a simplified example; for detailed instructions on deploying a new navigation scheme, see Chapter 9, "Customizing Portal Navigation", Deploying a Custom Navigation Scheme.

To modify a piece of the UI, write a new class that corresponds to the component of the UI that you want to modify. Dynamic Discovery will use the version loaded from CustomActivitySpaces.xml in place of the original version loaded from ActivitySpaces.xml. If there are multiple versions of the same component loaded in CustomActivitySpaces.xml, Dynamic Discovery gives precedence to the last version loaded. For detailed instructions on deploying a View replacement, see Chapter 13, "Using View Replacement", Deploying a Custom View.

Once the entire Activity Space has been created and compiled into a JAR/DLL file, follow the steps below to deploy the file using Dynamic Discovery.

(.NET only) Stop the WWW Service on the portal server.
Deploy the customized JAR/DLL file to the portal.
- Java: Rebuild the WAR file with the customized JAR in it, and copy the customized JAR file to PORTAL_HOME\ptportal\6.0\lib\java.
- NET: Copy the customized DLL to PORTAL_HOME\ptportal\6.0\webapp\portal\web\bin (this is in the virtual directory for the portal application).
Open the PT_HOME\settings\portal\CustomActivitySpaces.xml file in a text editor and add your customized JAR/DLL file to the list. Dynamic Discovery will use the version loaded from CustomActivitySpaces.xml in place of the original version loaded from ActivitySpaces.xml. If there are multiple versions of the same component loaded in CustomActivitySpaces.xml, Dynamic Discovery gives precedence to the last version loaded. The example below adds a View class called "sampleview".
```
<AppLibFiles>
<libfile name="sampleview"/>
</AppLibFiles>
```
Restart your application server (Java) / the WWW Service on the portal server (.NET).
When the portal application starts up, each line is processed and each JAR/DLL file that corresponds to a <libfile name=""/> attribute is loaded.