Developing InfoSphere MDM Collaboration Server Java API based extension points

Eclipse IDE based approach

IBM® InfoSphere® Master Data Management (MDM) Collaborative Edition (CE) is the master data management solution middleware that establishes a single, integrated, consistent view of master data inside and outside of an enterprise and supports the building of master data in collaborative ways. MDM Collaborative Edition can handle master data management for diverse domains like retail, telecom, banking, energy and can address different use cases. To achieve this, MDM Collaborative Edition provides flexible data modeling, direct and workflow-based collaborative authoring of master data, import and export of master data in various formats, and various integration capabilities. MDM Collaborative Edition can deliver relevant and unique content to any person, system, partner, or customer, thereby accelerating the time-to-market and reduce costs. MDM Collaborative Edition exposes several interfaces through which the system can be customized: MDM Collaborative Edition Scripting and MEM Collaborative Edition Java APIs being the major interfaces. This article provides the details on developing applications using MDM Collaborative Edition Java APIs in the Eclipse Integrated Development Environment (IDE). Steps required to set up the environment, create the Java API-based project, run the classes, and debug using Eclipse IDE are highlighted in this article. Sample code sections and screen shots are used to illustrate the steps used in the development.

Share:

Mohana Kera (mohakera@in.ibm.com), Lead Developer, IBM

Mohana KeraMohana Kera has more than 17 years of in-depth experience in architecture, design, development, and implementation of software solutions. He has been working at IBM for more than eight years, primarily on InfoSphere MDM Collaborative Edition. He has in-depth experience with all aspects of the product and was the development lead for Java API interfaces of the system. He has published several technotes, provided customer training on Java APIs, supported customers in adopting the Java APIs, and has actively worked in developing the content for IBM Information Center around MDM Collaborative Edition Java APIs.



05 December 2013

Also available in Chinese

Introduction

MDM Collaborative Edition supports the building and managing of the master data. It provides flexible data modeling capabilities and direct and collaborative authoring of master data. It also provides several integration capabilities for integration with other third-party products. All of the functionality of the system can be accessed via out-of-the-box user interfaces or via programmatic interfaces like MDM Collaborative Edition Scripting or via MDM Collaborative Edition JavaAPIs.

Because MDM Collaborative Edition supports various use cases of data modeling and cataloging in various industries, there is always the need for customization. Customization can be done in different ways:

  • By running Java API-based extension point code, which also provides custom behavior.
  • MDM Collaborative Edition scripting API-based scripts can be run at specific points of product modification. These scripts can provide custom behavior to extend the out-of-the-box behavior.
  • By building custom user interfaces that use the Java APIs or Scripting APIs to query and modify the product data.
  • Using Java API-based web services.

For more information about the Java APIs in MDM Collaborative Edition, refer to the MDM Collaborative Edition Information Center, listed under Resources.

This article focuses on developing Java API-based extension points within the Eclipse IDE. Setting up a Java project in Eclipse IDE, adding the extension point implementation class, implementing custom code, compiling, running and debugging the extension point code are demonstrated using a simple extension point. You can use similar approaches for developing other extension points and with any Java development IDE.


Why Java APIs?

MDM Collaborative Edition Java APIs provide several advantages for MDM Collaborative Edition solution development, some of which are enumerated below:

  • Java APIs are a move toward standard technology of Java. With Java, developers of solutions on MDM Collaborative Edition have access to a full set of code libraries available in Java, which provides them with a powerful programming platform for faster solution development.
  • With Java as the language, solution developers can leverage standard Java editors, debuggers, and all of the tools that are available for Java-based programming.
  • Java APIs ease third-party integrations with MDM Collaborative Edition: many Java based integration technologies can be used for integrating other IBM or third-party systems with MDM Collaborative Edition.
  • It is easy to build code libraries using Java APIs because Java supports packaging of classes. Packaging the classes lets solution developers separate the functionality into code libraries and allows parallel development, easier source code control, and so on. Also, these packages can be easily discovered in IDEs and can show up in tool tips and context sensitive helps.
  • Java APIs facilitate standard web services implementation and deployment.

Java API usage modes

Figure 1 depicts how MDM Collaborative Edition Java APIs can be used by user applications and also how they are currently being used by MDM Collaborative Edition itself. As shown previously, Java APIs can be used through web services or via custom user interfaces, which eventually make use of the core classes provided by the system.

Figure 1. Java API Usage Modes
Figure that shows the Java API Usage Modes

Java API Class diagram

The class diagram in Figure 2 depicts the sample class structure of MDM Collaborative Edition Java APIs. As shown in Figure 2:

  • Usage of Java APIs starts with obtaining a context via the PIMContextFactory class.
  • Once the context is obtained, different manager classes can be used that support creating new MDM Collaborative Edition objects or providing access to existing objects like Catalog and hierarchies.
  • From these container objects, users can reach the objects like Item or Categories and invoke methods on them to perform operations on the system.

For more information about the Java API classes, refer to the MDM Collaborative Edition Information Center ( see Resources).

Figure 2. Sample Java API Class diagram
Figure that shows the Java API Class Diagram

What are MDM Collaborative Edition extension points?

Extension points are the points in the MDM Collaborative Edition application where custom code can be run to extend the out-of-the-box system functionality. For example, custom code can be run while saving an Item or after saving the Item. Similarly, code can be run to define the behavior of an MDM Collaborative Edition import or export job. Hence, extension point mechanism essentially provides a mechanism to extend the out-of-the-box functionality of the MDM Collaborative Edition application with custom behaviors.

Follow these steps to use the Java API-based extension points mechanism:

  1. Develop an extension point implementation class, by implementing one of the supplied interfaces, listed under Available extension points.
  2. Make the extension point class available to InfoSphere MDM Collaboration Server, as described in the section Making the implementation class available to MDM Collaborative Edition application.
  3. Provide a URL for invocation of the extension point by the InfoSphere MDM Collaboration Server, as described in the section Invoking the extension point class.

MDM Collaborative Edition Java APIs provide Java interfaces, which need to get implemented with custom code to define an extension to the system behavior. Once implemented, these implementation classes are made available to the system and an invocation URL is defined at the appropriate extension point to invoke these classes. The MDM Collaborative Edition system invokes these user-implemented classes when execution flow reaches that particular extension point.

Table 1 shows available extension points in MDM Collaborative Edition and a brief description of each extension point. Note that a specific extension point implementation class can only be invoked from the specified extension point in the application. For example, a ScriptingSandboxFunction implementation extension point can only be invoked via the Scripting Sandbox. The system throws an exception if the implementation class is invoked from a different extension point.

Table 1. Available extension points
Extension pointBrief description
CatalogExportFunctionInvoked during export of catalog contents.
CatalogPreviewFunctionInvoked during preview of catalog.
CatalogToCatalogExportFunctionInvoked during catalog to catalog exports.
CMSEntryBuildFunctionInvoked during CMS (Content Management System) entry build.
CustomToolsFunctionInvoked during rendering of the custom tools.
DataEntryFunctionInvoked during data entry.
DefaultValueRuleFunctionInvoked during value rule execution.
DistributionFunctionInvoked during distributions.
EntityReportingFunctionInvoked during entity count report runs.
EntryBuildFunctionInvoked during entry build.
EntryMacroFunctionInvoked during entry macro execution.
EntryPreviewFunctionInvoked during entry preview.
ImportFunctionInvoked during imports.
NonPersistedAttributeRuleFunctionInvoked for non persisted attribute rules.
PostSaveFunctionInvoked during post save of entries.
PrePostProcessingFunctionInvoked during pre-post processing of entries.
ReportGenerateFunctionInvoked during report execution.
RichSearchReportFunctionInvoked during rich search report execution.
RunValueRuleFunctionInvoked during value rule execution.
ScriptingSandboxFunctionInvoked during script sandbox script execution.
StringEnumerationValueRuleFunctionInvoked during string enumeration value rule execution.
TriggerFunctionInvoked during trigger script execution.
UIRefreshFunctionInvoked during UI refresh.
ValidationRuleFunctionInvoked during validation rule execution.
WorkflowStepFunctionInvoked during workflow step script execution.

Extension point argument interfaces

For each of the extension point listed in Table 1, there are associated argument interfaces. These argument interfaces provide access to system objects like Item, Category, or Input/Output objects. For example, the ScriptingSandboxFunction extension point has ScriptingSandboxFunctionArguments, which gives access to the reader and writer objects, using which inputs from the sandbox can be read or output written to.

The full list of extension point and argument interfaces are listed on the MDM Collaborative Edition InfoCenter here: Extension point and argument interfaces.


Prerequisites for developing Java API-based extension points

Several components are required before Java API-based classes can be developed. The scenarios described in this article require the following components:

  • MDM Collaborative Edition Enterprise install: untared, v6.0.0 or later.
  • Java JDK, version of which should match the version of JDK required by the MDM Collaborative Edition product version being used:
    • tools.jar from JDK is required to be present in the classpath of the Java projects.
  • A running MDM Collaborative Edition instance is required. This instance need not be running on the same machine where the IDE is running and Java API-based classes are created.
  • Client connection to the database:
    • If DB2 is being used as the database, db2jcc.jar and db2jcc_license_cu.jar are required on the classpath. These are available as part of the DB2 client install.
    • If Oracle is being used as the database, ojdbc jar is required on the classpath; the exact version of the ojdbc.jar should be compatible with the MDM Collaborative Edition version that is being used.
  • Configured etc/default folder of a MDM Collaborative Edition installation is required. Several files like common.properties, db.xml, and so on are used for running Java API-based classes.
  • A Java development IDE like Eclipse.

Developing a Java API-based extension point

The following sections provide details on how to develop Java API-based extension points using MDM Collaborative Edition Java APIs. Java API-based extension points can be invoked from within the MDM Collaborative Edition application at different points. For example, after a save of an item or when an item is checked in to a collaboration area.

The following sections show how to create a Java project in Eclipse IDE, how to configure the project, how to add an extension point implementation class, how to register the class with the application, and how they are invoked by the system. Also, debugging of such extension point classes is shown. Screen shots and sample code sections are used where relevant to illustrate the details.

Setting up Java project in Eclipse for developing Java API-based extension point

The following steps need to be used to set up a Java project, which is set up on top of the MDM Collaborative Edition enterprise install folder:

  1. Untar or unzip the enterprise install on a local drive. In this case, a folder on Microsoft® Windows® system is being used. Figure 3 shows how the directory structure looks after the tar file is unzipped:
Figure 3. MDM Collaborative Edition Install folder structure
Figure that shows the MDM Collaborative Edition Install Folder Structure
  • Once the folder is available, open Eclipse IDE.
  • Create a new workspace on the local drive, which opens an empty workspace.
  • In the new workspace, click File->New and select Java Project.
  • Clear Use default location and point the Location field to the MDM Collaborative Edition install folder.
  • Click Finish.
Figure 4. Creating a new Java API project in Eclipse
Figure that shows the Eclipse New Project

Adding the new Java API Extension point implementation class to the project

This section of the article shows how to add a new Java class that implements a specific extension point interface of MDM Collaborative Edition Java APIs.

I am using the ScriptingSandboxFunction extension point for illustration. In MDM Collaborative Edition, Scripting Sandbox is the place where scripts or Java API-based classes can be invoked to test a specific functionality. Any Java API class that needs to get invoked from the Scripting Sandbox needs to implement the interface ScriptingSandboxFunction.

  1. In Eclipse, right-click the src folder, and select the New -> Folder option.
  2. In the New Folder dialog, enter Java APIs as the Folder name. This creates a new folder called Java APIs under the src folder.
  3. Right-click on the new folder Java APIs and select New ->Class option.
  4. For Package, type in com.ibm.pim.extensionpoints.impl. This decides the package name for the new class. (Any custom package name can be provided here.)
  5. Enter the name of the class as ScriptingSandboxFunctionImpl.
  6. Click Add next to the Interfaces and type in ScriptingSandboxFunction. Select this interface and click OK.
  7. In the Java Class screen, click Finish to create the implementation class.
Figure 5. Adding a new Java class in Eclipse
Figure that shows Eclipse Project Add New Class option

Configuring the Eclipse project

The following steps are needed to configure the project, which is set up on top of the MDM Collaborative Edition Enterprise install folder:

  1. Right-click on the project name JavaAPI Extension Point Project and select Properties. Alternatively, you can select Project->Properties from the menu.
  2. Select Java Build Path. Under this area, do the following configurations.

Java Build Path Source Tab configuration

  1. Click the Source tab.
  2. Add the newly added folder using the 'Add Folder' option. Additional folders that are already present can be removed.
  3. Check Allow output folders for source folders.
  4. Modify the Default output folder value to be as shown in Figure 6. This new folder classes is created to keep the compiled Java classes
Figure 6. Eclipse project Source Tab configuration
Figure that shows the Eclipse Project Source Tab Configuration

Java Build Path Libraries Tab configuration

  1. Click the Libraries tab.
  2. By default, all of the jar files under the jars folder are selected here. Only one of the ccd_javaapi2.jar needs to be maintained, and redundant ccd_javaapi2.jar files can be removed.
  3. Add the tools.jar from your JDK area using the Add External JARs... button. This jar file is available under the lib folder of your Java JDK area.
  4. Add the database client libraries from the database client area. If you are using DB2 as the database, add db2jcc.jar and db2jcc_license_cu.jar. If you are using Oracle as the database, add the correct version of ojdbc.jar.
  5. Click OK to close the dialog.
  6. Click No if you see the "The output folder has changed. Do you want to remove all generated resources from the old location..." confirmation window.
Figure 7. Eclipse project Libraries Tab configuration
Figure that shows the Eclipse Project Libraries Tab Configuration

Newly added extension point implementation class

Figure 8 shows how the newly added extension point implementation class should show up in Eclipse:

Figure 8. Newly added Extension point implementation class in Eclipse
Figure that shows the newly added implementation class in Eclipse

Adding implementation code to the newly added class

Update the method scriptingSandbox(ScriptingSandboxFunctionArguments arg0) in the newly created class as shown in Listing 1. This is where the custom code gets plugged in to implement the custom functionality of the extension point.

  • Method scriptingSandbox reads the PrintWriter that is already available from the passed in argument.
  • Next, the code writes a test message to this writer, which will get printed on the output area of the Scripting Sandbox when the extension point is invoked.
Listing 1. Sample ScriptingSandboxFunction extension point implementation class
package com.ibm.pim.extensionpoints.impl;

import java.io.PrintWriter;

import com.ibm.pim.extensionpoints.ScriptingSandboxFunction;
import com.ibm.pim.extensionpoints.ScriptingSandboxFunctionArguments;

public class ScriptingSandboxFunctionImpl implements ScriptingSandboxFunction {

	@Override
	public void scriptingSandbox(ScriptingSandboxFunctionArguments arg0) {
		PrintWriter cpOut = arg0.getOutput();
		cpOut.write("Testing Scripting Sandbox Function extension point impl");
	}
}

Compiling the class

Once the Java class is created and saved, the project can be compiled to create the .class file. Also, it is ready to be used when there are no compilation errors in the project.

  1. Right-click on the project name on the Navigator or Package Explorer view and select Build Project. (Note that you will not see this option if Project -> Build Automatically option is checked. If it is checked, uncheck the option.)
  2. Select Project -> Clean ... option to clean the project, which will remove any pre-built classes.
  3. Now either choose the Project -> Build Project or choose the Build Project from Navigator or Project explorer view (on the right-click menu).
  4. Under the Problems view, make sure there are no compile errors reported. (If this view is not open, it can be opened using Window -> Show View ->Problems.)

Figure 9 shows how the compiled class should look in Eclipse once compilation is done and the ScriptingSandboxFunctionImpl.class file is created under the classes folder:

Figure 9. Compiled class file in Eclipse
Figure that shows the compiled class file in Eclipse

Making the implementation class available to MDM Collaborative Edition application

Once the .class file is created, the compiled class needs to be made available to the MDM Collaborative Edition application so that it can be invoked as an extension point.

Possible approaches for making the class available to the application are documented in the MDM Collaborative Edition Information Center here:
Making the extension point class available to InfoSphere MDM Collaboration Server.

For this article, I am using the approach of loading the implementation class to the document store. The following is the quick summary of the steps.

  1. Create a standalone Java API-based application, which can be used to upload the compiled classes to MDM Collaborative Edition document store. Source code for such a class is shown in Listing 2.
  2. Adjust the user name, password, and company name provided to the getContext(..) method to match your setup. Also, adjust the file paths provided to FileInputStream as needed to suit your environment.
  3. Compile the project to create the class file.
  4. Right-click the Java file and select Run As -> Run Configurations....
  5. Create a new configuration of the Java Application type.
  6. In the new run configuration entry, click the Arguments tab. Enter the following values into the VM arguments edit box (modify the folder location to match your setup):
    • -DCCD_ETC_DIR=C:\prj\MDMCS10_1\etc -DTOP=C:\prj\MDMCS10_1\etc\default -classpath $CLASSPATH
  7. Select Run to run the application. Once completed, the extension point class file will get uploaded to the document store.
Listing 2. DocstoreLoader class to upload the extension point implementation class to MDM Collaborative Edition document store
package com.ibm.pim.extensionpoints.impl;

import java.io.FileInputStream;

import com.ibm.pim.context.Context;
import com.ibm.pim.context.PIMContextFactory;
import com.ibm.pim.docstore.DocstoreManager;
import com.ibm.pim.docstore.Document;

public class DocstoreLoader
{
    public static void main(String[] args)
    {
        Context ctx = null;
        try
        {
           //get the context using user id/password
            ctx = PIMContextFactory.getContext("Admin", "xxxxx", "yyy");
            
            DocstoreManager dsMgr = ctx.getDocstoreManager();
            
            //create an empty document in the docstore, at desired location
            Document doc = dsMgr.createAndPersistDocument
                ("/uploaded_java_classes/com/ibm/pim/extensionpoints/impl/
                ScriptingSandboxFunctionImpl.class");
            
            //open a stream to the compiled class file
            FileInputStream fis = new FileInputStream
        	    ("C:\\prj\\MDMCS10_1\\classes\\com\\ibm\\pim\\extensionpoints\\impl
        	    \\ScriptingSandboxFunctionImpl.class");

            //set content of the file to the docstore document
            doc.setContent(fis);
            
            ctx.cleanUp();
        }
        catch (Exception e)
        {
            e.printStackTrace();
            System.out.println("DocstoreLoader failed!");
        }
    }
}

The uploaded extension point class will show up in the document store as shown in Figure 10:

Figure 10. Uploaded extension point class in Document store
Figure that shows the uploaded extension point class in Document store

Invoking the extension point class

The extension point class is invoked using a special invocation URL. Because the extension point is of type ScriptingSandbox, this implementation class can only be invoked via Scripting Sandbox. Enter the URL shown below in the Script sandbox and execute it using Run Script.

For this case, this is how the invocation URL looks: //script_execution_mode=java_api="japi:///uploaded_java_classes:com.ibm.pim.extensionpoints.impl.ScriptingSandboxFunctionImpl.class"

Output from invoking the extension point class

Figure 11 shows the output produced when the extension point is invoked:

Figure 11. Output from invoking the Scripting Sandbox extension point class
Figure that shows the output from invoking the Scripting Sandbox extension point class

Passing parameters to the extension point class from the script sandbox

When invoking the Scripting Sandbox extension point, parameters can be passed to the extension point. This can come in handy if you want to unit test the code segments of other extension points and pass information to simulate the actual run time environment. For example, the primary key of the item can be passed as a parameter and used inside the extension point code to load an Item object.

Listing 3 shows how to do this:

Listing 3. Reading parameters in a ScriptingSandboxFunction extension point implementation class
public void scriptingSandbox(ScriptingSandboxFunctionArguments arg0) 
{
  BufferedReader sbIn = arg0.getInput();
  try {
    String inputString1 = sbIn.readLine();
    String inputString2 = sbIn.readLine();

    PrintWriter cpOut = arg0.getOutput();
    cpOut.write("Input String 1: " + inputString1 + "\n");
    cpOut.write("Input String 2: " + inputString2 + "\n");
  }
  catch (Exception e) {
    e.printStackTrace();
  }
}

Figure 12 shows the output of such an invocation:

Figure 12. Output from invoking the Scripting Sandbox extension point class with parameters
Figure that shows the output from invoking the Scripting Sandbox extension point class with parameters

Sample PostSaveFunction extension point implementation

Listing 4 shows a post save extension point implementation. An approach similar to the previous one is used to upload the compiled class is used to the document store.

Listing 4. Sample PostSaveFunction extension point implementation class
package com.ibm.pim.extensionpoints.impl;

import com.ibm.pim.catalog.item.Item;
import com.ibm.pim.extensionpoints.PostCategorySaveFunctionArguments;
import com.ibm.pim.extensionpoints.PostCollaborationCategorySaveFunctionArguments;
import com.ibm.pim.extensionpoints.PostCollaborationItemSaveFunctionArguments;
import com.ibm.pim.extensionpoints.PostItemSaveFunctionArguments;
import com.ibm.pim.extensionpoints.PostSaveFunction;

public class PostSaveFunctionImpl implements PostSaveFunction
{
    //this method will get invoked after an item 
    //is saved in a catalog on the application. 
    public void postsave(PostItemSaveFunctionArguments inArgs)
    {
        //read the item that is being saved.
        Item itemBeingSaved = inArgs.getItem();
        //read the value of an attribute.
        Object attributeValue = 
          itemBeingSaved.getAttributeValue("some spec/some attribute");
    }

    //this method will get invoked after a category 
    //is saved in a hierarchy on the application.    
    public void postsave(PostCategorySaveFunctionArguments inArgs)
    {
    }

    //this method will get invoked after an item 
    //is saved in an item collaboration area on the application
    public void postsave(PostCollaborationItemSaveFunctionArguments inArgs)
    {
    }

    //this method will get invoked after a category 
    //is saved in a category collaboration area on the application
    public void postsave(PostCollaborationCategorySaveFunctionArguments inArgs)
    {
    }
}

Registering the PostSaveFunction extension point class

The PostSave extension point is available under the attributes of a catalog (or hierarchy). Use the following steps to register the invocation URL for an item under a catalog:

  1. Right-click on the blank area of a Catalog on the left pane and open the Catalog Attributes page (you can also use the Catalog console).
  2. In the Catalog Attributes page, click New next to the Post-save Script drop-down.
  3. In the resulting Script Editor, choose values as shown in Figure 13 and provide the invocation URL. For our example, the URL is : //script_execution_mode=java_api="japi:///uploaded_java_classes:com.ibm.pim.extensionpoints.impl.PostSaveFunctionImpl.class"
  4. Save the script.
  5. In the Catalog attributes page, select the newly added extension point invocation script, as shown in Figure 14.
  6. Now, whenever an item is saved under this catalog, the Java API extension point implementation class will get invoked, post save of the item.
Figure 13. Registering the URL for PostSaveFunction implementation class invocation
Figure that shows how to register the URL for PostSaveFunction implementation class invocation
Figure 14. Selecting the PostSaveFunction implementation class for the catalog
Figure that shows how to select the PostSaveFunction implementation class for the catalog

Sample WorkflowStepFunction Extension point implementation

Listing 5 shows how a WorkflowStepFunction extension point implementation can be implemented. An approach similar to the previous one is used to upload the compiled class to the document store.

Listing 5. Sample WorkflowStepFunction extension point implementation class
package com.ibm.pim.extensionpoints.impl;

import com.ibm.pim.collaboration.CollaborationItem;
import com.ibm.pim.collection.PIMCollection;
import com.ibm.pim.extensionpoints.WorkflowStepFunction;
import com.ibm.pim.extensionpoints.WorkflowStepFunctionArguments;

public class WorkflowStepFunctionImpl implements WorkflowStepFunction
{
    //this method is executed when item in the collaboration area enters the step
    public void in(WorkflowStepFunctionArguments inArgs)
    {
        PIMCollection <CollaborationItem> items = inArgs.getItems();
        for (CollaborationItem item : items) {
            //do some processing 
            String itemPk = item.getPrimaryKey();
        }
    }

    //this method is executed when item in the collaboration area leaves the step
    public void out(WorkflowStepFunctionArguments inArgs)
    {
    }

    //this method is executed when timeout happens on the collaboration area step
    public void timeout(WorkflowStepFunctionArguments inArgs)
    {
    }
}

The extension point invocation URL is registered for a particular workflow step. A new script can be added using the Add Script button of the workflow step definition screen. Replace the default script that gets created with the URL as shown in Figure 15:

Figure 15. Registering the URL for WorkflowStepFunction implementation class invocation
Figure that shows how to register the URL for WorkflowStepFunction implementation class invocation

Setting breakpoints and debugging

Eclipse-based debugging helps in analyzing the program flow and inspecting variable values. Once the Java API class is compiled and ready, breakpoints can be set in the code and the code can be debugged.

Most of the Java API-based extension point implementation classes are run within the AppServer service of MDM Collaborative Edition. A few of the extension points like ImportFunction and ExportFunction are run within the Scheduler service. To debug an extension point, which is invoked from the MDM Collaborative Edition user interface, the AppServer service needs to be running in the debug mode.

The following steps show you how to debug an extension point within the AppServer service. PostSaveFunction extension point is used for this example, which is run within the AppServer service.

  1. Start the AppServer in debug mode. This is done by providing the -debug flag while starting the MDM Collaborative Edition services. For example, $TOP/bin/go/start_local.sh --debug.
  2. In Eclipse, open Debug configurations and add a new configuration under Remote Java Application.
    • If AppServer is running on the same machine where Eclipse is running, use localhost for the Host field. If AppServer is running on a different box, provide the IP address of the machine.
    • Provide the Port field as application port number + 30000. (Here 30000 is the default offset; refer to the entry appsvr_debug_port in your env_settings.ini file to see the actual debug port assigned for the AppServer, if other than the default.)
  3. Click Debug and the AppServer service will be in the debug mode.
  4. Set the breakpoint on the line of code of the extension point class you want to debug.
  5. Now invoke the extension point from the UI. In the case of PostSaveFunction, the extension point gets invoked when an item is saved.
  6. Save the item after doing some changes. The breakpoint in the implementation class method will get reached.
  7. Values of the variables and system passed-in parameters can be inspected at the specific breakpoint.
  8. For any code changes done to the extension point class, the class needs to get compiled and reloaded to the document store before it can be debugged again.

Note: When the breakpoint is reached for a specific extension point, the whole appserver service pauses until resumed. If there are multiple users using the same appserver service, all of the users are paused until the execution is resumed or debugging is terminated.

Figure 16 shows the Debug Configuration for the AppServer service in the Eclipse IDE:

Figure 16. Debug configuration setup in Eclipse for debugging an extension point
Figure that shows how to setup the Debug configuration setup in Eclipse for debugging an extension point.

Figure 17 shows how the extension point debugging session looks in the Eclipse IDE:

Figure 17. Debugging the PostSaveFunction extension point in Eclipse
Figure that shows the Debugging the PostSaveFunction extension point in Eclipse

Invoking Java API extension points from MDM Collaborative Edition Scripting APIs

It is possible to invoke MDM Collaborative Edition Java API-based extension point classes from Scripting APIs. This can come in handy when there is pre-existing code that is written in MDM Collaborative Edition Scripting APIs and new custom code can be written in Java APIs and inserted into existing custom code.

Refer to the following information on the MDM Collaborative Edition InfoCenter for more information: Invoking Java API extension points from scripting.


Enabling content sensitive help using the Javadocs for Java APIs

MDM Collaborative Edition Java APIs are shipped along with the Javadocs for the APIs. The Javadocs are available within the ccd_javaapi2doc.zip file under the folder javaapi of an MDM Collaborative Edition release. The Javadocs can be plugged into Eclipse so that the Javadoc details of an API are available during development of a Java API-based class. Associating the Javadocs enables the context sensitive help for the APIs within Eclipse.

Enabling the Javadocs is done by associating the javadocs zip file to ccd_javaapi2.jar file. This is done using the following steps:

  1. Go to the Package Explorer view.
  2. Locate ccd_javaapi2.jar under the Referenced Libraries section.
  3. Right-click to open properties and select Javadoc Location on the property page.
  4. Select Javadoc in archive and select Workspace file.
  5. Use Browse, go to the javaapi folder and click the ccd_javaapi2doc.zip file.
  6. Click OK.

Figure 18 shows how the javadocs ZIP file is selected to enable context-sensitive help.

Figure 18. Enabling context sensitive help for Java APIs in Eclipse
Figure that shows enabling of context sensitive help for Java APIs in Eclipse

Figure 19 shows the context-sensitive help opened up for Java API getCurrentContext(...). The javadocs are displayed when you place the mouse cursor on the API in Eclipse.

Figure 19. Context Sensitive help displayed for Java API getContext
Figure that shows Context Sensitive help displayed for Java API getCurrentContext()

Best practices for working with Extension points

The following are some of the best practices that can be used when developing extension points using MDM CE Java APIs:

  • When developing multiple extension points in a group setting, split the functionality into different extension points across developers so that development can happen in parallel.
  • Use the package structure to componentize the extension point classes. Also, separate out the utility classes into a separate package so that they can be reused by multiple extension points.
  • Before deploying the extension point, the custom code can be unit-tested by adding a main() method to the extension point class or by putting the custom code in a ScriptingSandbox extension point and test by passing parameters.
  • Within the extension point implementation class, reuse the Java API objects to avoid reloading objects. This can give better performance.
  • MDM Collaborative Edition extension points run within the already established context (either by the AppServer service or Scheduler service). Hence, instead of establishing a new context, reuse the existing context by using the method PIMContextFactory.getCurrentContext() instead of getContext().

Conclusion

In summary, this article shows how extension points can be developed using MDM Collaborative Edition Java APIs to customize the MDM Collaborative Edition functionality. Along the lines of simple ScriptingSandBox extension point development demonstrated here, other extension points can be developed and deployed at several points in the MDM Collaborative Edition system to extend the out of the box functionality. Eclipse-based development is demonstrated in this article, which helps in faster development of the code and also facilitates easy debugging to resolve issues in the code.

MDM Collaborative Edition Java APIs provide a robust set of APIs and interfaces that provide full coverage to the functionality of the system. Simple classes used in this article can be extended further to make use of the full system capabilities and provide rich extensions to the system. In addition, because Java APIs are based on the standard Java functionality, third-party libraries can be easily used for integration with other systems or to make use of other Java code libraries.


Download

DescriptionNameSize
Java code listingsdm-1312mdmjapi.zip---

Resources

Learn

Get products and technologies

  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment.

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Information management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=956196
ArticleTitle=Developing InfoSphere MDM Collaboration Server Java API based extension points
publish-date=12052013