Using InfoSphere MDM Collaboration Server Java APIs

Eclipse IDE-based approach

IBM® InfoSphere® MDM Collaboration Server exposes several interfaces through which the system can be customized - InfoSphere MDM Collaboration Server scripting, and InfoSphere MDM Collaboration Server Java APIs being the major interfaces. This article provides the details of developing applications using InfoSphere MDM Server Collaboration Server 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 is provided to illustrate the steps used in the development.

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

Author photoMohana Kera has more than 15 years of in-depth experience in architecture, design, development and implementation of software solutions. He has been working at IBM for more than 7 years, primarily on InfoSphere MDM Collaboration Server. 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, and has actively worked in developing the content for IBM Information Center around MDM Collaboration Server Java APIs.



13 December 2012

Introduction

IBM InfoSphere Master Data Management Collaboration Server is a powerful master data management (MDM) solution that includes flexible data modeling, collaborative authoring, and workflow capabilities to handle all domains and use cases across all industries. It is the 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. InfoSphere Master Data Management Collaboration Server can deliver relevant and unique content to any person, system, partner, or customer, thereby accelerating the time to market and reducing costs.

Since MDM Collaboration Server supports various use cases of data modeling and cataloging in various industries, there is always the need for customization. Customization can be done in the following ways.

  • By running Java API-based extension point code, which also provides custom behavior.
  • MDM Collaboration Server 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 which 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 Collaboration Server, please refer to the MDM Collaboration Server Information Center, listed in the Resources section.

This article focuses on the use of Java API interfaces and shows how Java API-based code can be developed within the IDE (Integrated Development Environment) like Eclipse. Setting up a Java project in Eclipse IDE is demonstrated for developing a simple Java API-based application. Additional steps for compiling, running, and debugging this simple application are also demonstrated. The same approach can be used when working with any Java development IDE.


Why Java APIs?

MDM Collaboration Server Java APIs provide several advantages for MDM Collaboration Server solution development, some of which are described as follows.

  • Java APIs are a move toward the standard technology of Java. With Java, developers of solutions on MDM Collaboration Server have access to a full set of code libraries available in Java, which provide them with a powerful programming platform for faster solution development.
  • With Java as the language, solution developers can leverage standard Java editors, debugging tools, and all of the tools that are available for Java-based programming.
  • Java APIs ease third party integrations with MDM Collaboration Server - many Java-based integration technologies can be used for integrating other IBM or third party systems with MDM Collaboration Server.
  • It is easy to build code libraries using Java APIs since 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 shows how MDM Collaboration Server Java APIs can be used by user applications, and also how they are currently being used by MDM Collaboration Server itself. Java APIs can be used through WebServices 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 shown in Figure 2 depicts the sample class structure of MDM Collaboration Server Java APIs.

Figure 2. Sample Java API class diagram
Figure that shows the Java API class diagram

The 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 Collaboration Server objects, or provide access to existing objects like catalog and hierarchies. From these container objects, you 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, please refer to the MDM Collaboration Server Information Center, listed in the Resources section.


MDM Collaboration Server data model used

As shown in Figure 3, for the sample example and scenarios in this document, a simple MDM Collaboration Server data model is used. A basic primary spec by name JavaAPI Demo Spec with three attributes - sku, name, and display name is used. In-addition to the spec, a catalog by name JavaAPI Demo Catalog is also created.

Figure 3. MDM Collaboration Server Data model used for the samples in this article.
Figure that shows the Java API Data model setup used for samples in this article.

Prerequisites

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

  • MDM Collaboration Server Enterprise install - untared, v6.0.0 or later.
  • Java JDK, a version that should match the version of JDK required by the MDM Collaboration Server product being used.
  • The tools.jar from JDK is required to be present in the classpath of the Java projects.
  • A running MDM Collaboration Server instance is required. This instance need not be running on the same machine where IDE is running, and the Java API-based classes are created.
  • Client connection to the database.
    • If DB2 is being used as the database, then 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, then ojdbc jar is required on the classpath. The exact version of the ojdbc.jar should be compatible with the MDM Collaboration Server version that is being used.
  • Configured default folder of a MDM Collaboration Server 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 standalone Java API-based application

This section provides details on how to develop standalone Java API-based applications using MDM Collaboration Server Java APIs. These are Java classes with the main() method, and can be run from the command line or directly within the IDE.

This section also shows how to create a Java project in Eclipse IDE, how to configure the project, how to compile and run these applications, and how to debug such applications. Screen shots and sample code sections are used where relevant to illustrate the details.

Important note: MDM Collaboration Server doesn't support standalone Java API-based applications for production use. However, they can be used to test functionality, or for doing unit testing before Java API-based code is used in extension points.


Setting up a Java project in Eclipse for developing Java API-based class

The following steps need to be used to set up a Java project, which is set up on top of the MDM Collaboration Server 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 4 shows how the directory structure looks after the tar file is unzipped.
    Figure 4. MDM Collaboration Server Install folder structure
    Figure that shows the MDM Collaboration Server Install Folder Structure
  2. Once the folder is available, open Eclipse IDE.
  3. Provide a new workspace on the local drive, which will open an empty workspace.
  4. Click File, click New, and then select Java Project.
  5. Make sure to clear the Use default location check box, and then enter the path to your MDM Collaboration Server install folder in the Location field.
  6. Click Finish, as shown in Figure 5.
    Figure 5. Eclipse new Java API project
    Figure that shows the Eclipse New Project

Configure the Eclipse project

Perform the following steps to set up a Java project, which is setup on top of the MDM Collaboration Server enterprise install folder.

  1. Right click the project name and select Properties.
  2. Select Java Build Path. Under this area, perform the following configurations.

Java Build Path Source tab configuration

To configure the Java Build Source Path, perform the following steps, also shown in Figure 6.

  1. Click the Source tab.
  2. Make sure to select the Allow output folders for source folders check box.
  3. By default, the value of Default output folder would be mdmpim_9102_16_combined_unix/bin. Modify this to mdmpim_9102_16_combined_unix/classes.
    Figure 6. Eclipse project Source Tab configuration
    Figure that shows the Eclipse Project Source Tab Configuration

Java Build Path Libraries tab configuration

To configure the Java Build Libraries Path, perform the following steps, as shown in Figure 7.

  1. Click the Libraries tab.
  2. By default, all of the jar files under the jars folder are selected here. The following .jar entries can be removed from this set.
    • ccd_javaapi.jar.
    • One of the ccd_javaapi2.jar (you should see two entries for this jar file).
  3. Click the Add External JARs button to add the tools.jar from your JDK area. This jar file is available under the lib folder of your JDK area.
  4. Add the database client libraries from the database client area. For DB2, add db2jcc.jar and db2jcc_license_cu.jar. For Oracle, add the correct version of ojdbc.jar.
  5. Click OK to close the dialog box. You might get this confirmation message in a new window: The output folder has changed. Do you want to remove all generated resources from the old location. Click No.
    Figure 7. Eclipse project Libraries Tab configuration
    Figure that shows the Eclipse Project Libraries Tab Configuration

Adding the new Java class to the project

In this section of the article, perform the following steps to add a new Java class in Eclipse that makes use of the MDM Collaboration Server Java APIs.

  1. In Eclipse, right click the src folder, and then click New Folder.
  2. In the New Folder dialog box, type Java APIs as the folder name. This will create a new folder called Java APIs under the src folder.
  3. Right click the Java APIs folder and select New File option.
  4. In the New File screen, provide the File name as JAPISampleApp.java as shown in Figure 8.
    Figure 8. Adding a new Java class in Eclipse
    Figure that shows Eclipse Project Add New Class option
  5. Click Finish.

The Java class JAPISampleApp shown in Listing 1 is used as the sample class for this exercise. Use the following steps to add the new class to the Java project.

  1. Copy and paste the sample Java code to the newly created file JAPISampleApp.java.
  2. Modify the line of code that obtains the context using the getContext method, and provide the right user name, password, and company name.
  3. Provide the existing spec name to the getSpec() method, and an existing catalog name to getCatalog() method.
Listing 1. Sample Java API application
import com.ibm.pim.catalog.Catalog;
import com.ibm.pim.catalog.CatalogManager;
import com.ibm.pim.context.Context;
import com.ibm.pim.context.PIMContextFactory;
import com.ibm.pim.spec.Spec;
import com.ibm.pim.spec.SpecManager;
                
public class JAPISampleApp
{
    public static void main(String[] args)
    {
        Context ctx = null; 
        try
        {
            //Obtain a new context by providing a user name, password and a company.
            ctx = PIMContextFactory.getContext("Admin", "password", "trigo");
            System.out.println("Context: " + ctx.toString());
                
            //Get the SpecManager object to access a pre-existing spec by 
            //the name 'JavaAPI Demo Spec'
            SpecManager specMgr = ctx.getSpecManager();
            Spec spec = specMgr.getSpec("JavaAPI Demo Spec");
            System.out.println("Spec name: " + spec.getName());
                
            //Get the CatalogManager object to access a pre-existing catalog 
            //by the name 'JavaAPI Demo Catalog'            
            CatalogManager ctgManager = ctx.getCatalogManager();
            Catalog catalog = ctgManager.getCatalog("JavaAPI Demo Catalog");
            System.out.println("Catalog name: " + catalog.getName());
        }
        catch (Exception e)
        {
            //If code runs into any exception, simply print the failure message.
            e.printStackTrace();
            System.out.println("JAPISampleApp failed");
        }
    }
}

Compile 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 run if there are no compilation errors in the project.

  1. Right click the project name on the Navigator or Package Explorer view, and select Build Project.
  2. Note that you will not see this option if the Project > Build Automatically check box is selected. If it is selected, then clear the check box.
  3. Click Project and select Clean to remove any pre-built classes.
  4. Now select Build Project from the Navigator or Project Explorer view (on the right-click menu).
  5. Under the Problems view, make sure there are no compile errors reported. If this view is not open, you can click Window, Show View, Problems.

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

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

Running the class

Once the .class file is created, the class is ready to be run. Use the following steps to configure the runtime environment and run the application.

  1. Right click the JAPISampleApp.java file, click Run As, and then select Run Configurations.
  2. From the Create, manage, and run configurations screen, click the Java Application option, and then click New launch configuration. This will create a new runtime configuration with the name JAPISampleApp.
  3. Click the Arguments tab, and type the following values into the VM arguments edit box (modify the folder location to match your setup), as shown in Figure 10.
    • -DCCD_ETC_DIR=C:\prj\mkera\mdmpim_9102_16_combined_unix\etc -DTOP=C:\prj\mkera\mdmpim_9102_16_combined_unix -classpath $CLASSPATH
    Figure 10. Java API Class Runtime Configuration
    Figure that shows the Java API Class Runtime Configuration
  4. Click Run.

Output from running the class

Once the Java class run completes, the output shown in Listing 2 can be seen on the Console window of Eclipse. The value of the context variable is printed, followed by the Spec name and Catalog name.

Listing 2. Output from running JAPISampleApp class
Context: com.ibm.ccd.api.context.DefaultContextImpl[Admin][trigo]
Spec name: JavaAPI Demo Spec
Catalog name: JavaAPI Demo Catalog

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.

To debug the code in the Java class, perform the following steps.

  1. Double-click the side bar of the code line, or position the cursor on the line of code where you want to set the breakpoint and select Run, Toggle Breakpoint.
  2. Click Run, Debug Configurations.
  3. Select JAPISampleApp, and then click Debug.
  4. Eclipse will switch to the Debug perspective, and the code flow will stop at the first breakpoint, as shown in Figure 11.
    Figure 11. Setting breakpoints for debugging and inspecting variables in Eclipse
    Figure that shows setting breakpoints and debugging Java API code in Eclipse
  5. The variable values (ctx) can be inspected using the Expressions view, or by right-clicking the variable name and selecting Inspect.
  6. Breakpoints can be set on different lines, and different variable values can be inspected.

Conclusion

This article showed how MDM Collaboration Server Java APIs can be used to develop classes that make use of the MDM Collaboration Server functionality. Along the lines of simple stand-alone Java applications demonstrated here, MDM Collaboration Server Java APIs can be used to develop extension points that can be deployed within the MDM Collaboration Server to extend the out-of-the-box functionality. Eclipse-based development is also demonstrated in this article, which helps in faster development of the code, and also facilitates easy debugging to resolve issues in the code.

MDM Collaboration Server Java APIs provides 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 expanded further to make use of the full system capabilities and provide rich extensions to the system using a Java API-based extension point mechanism. In addition, since Java APIs are pure Java functionality, third-party libraries can be easily used for integration with other systems or to make use of Java code libraries.

Resources

Learn

Get products and technologies

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. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. 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=851195
ArticleTitle=Using InfoSphere MDM Collaboration Server Java APIs
publish-date=12132012