Optimizing your MDM Server workspace using binary modules (DRAFT)
Catherine Griffin, December 2011
IBM Infosphere Master Data Management Server provides a complex data model for Party, Account and Product master data and a large number of services (known as transactions) for querying and modifying master data records. A variety of extension mechanisms are supported to allow the data model and transaction behavior to be customized, or to add completely new transactions if required.
MDM Server includes MDM Server Workbench, tooling which supports development of extensions to MDM Server. The workbench allows you to define the desired data model and transactions and then generates the code required to implement the MDM Server extensions.
MDM Server Workbench is installed as an add-on to Rational Application Developer (RAD). To develop extensions to MDM Server, you need to import into the RAD workspace the MDM Enterprise Application Archive (EAR).
The default development environment setup results in a large number of projects being created in the workspace. 55 projects are created when importing the MDM EAR, and then on top of that you may be creating a number of additional projects for extensions.
The large number of projects in the workspace can be confusing and adds to the overhead of building the code, managing it in source control, and deploying the code.
In this article, I will describe how you can reduce the number of projects in the workspace by changing some of them into binary modules.
The instructions given here apply to the MDM Workbench with MDM Server 9.0.1 (WebSphere version) on RSA 126.96.36.199. If you have different versions, the approach should still work but there may be some differences in the user interface.
Development and Test Environment Setup
Use the MDM Workbench Development and Test Environment Setup wizard to set up your development environment to start with.
When DEST has finished, there are 55 projects in the workspace.
Some of these projects are used for the initial set up of the MDM Server but are not part of the MDM EAR. You do not need to have them in the workspace once the development environment is set up.
Once you are satisfied that your development environment is set up correctly and the IVT is passing, then you can close the following projects:
This project contains the Install Verification tool used by the Development Environment Setup wizard to run the Validate Installation task.
This project contains the ManagementAgent tool used by the Development Environment Setup wizard to run the Deploy Configuration task.
This project contains the ManagementConsole tool used by the Development Environment Setup wizard to run the Deploy Configuration task.
This project contains the database creation scripts used by the Development Environment Setup wizard to run the Create Application Database task.
Closed projects remain in the file system but are by default not visible in the workspace. You can re-open closed projects if you want to re-run the development environment setup later.
Setting up Shared EAR development
Now, in the folder MDM/.settings, create a file named com.ibm.etools.j2ee.teamshare. This is a marker file – the contents do not matter, only the name.
The MDM project contains a number of JAR files which are the modules of the EAR. Some of these are expanded into the workspace as projects, which allows you to modify the files they contain. When the MDM EAR is exported or published to the server, the projects in the workspace replace the JARs in the EAR.
Normally, if you delete a project from the workspace which is an EJB module, Web module or Utility module, then the module is removed from the EAR. But once the teamshare marker file is in place, deleting a project will not remove it from the EAR. As long as the module JAR file is still present in the EAR, the EAR will function just the same as before.
This means that now you have added the teamshare marker file to the EAR, you can delete from the workspace out-of-the-box projects that you don't actually need for extension development. Note that when you delete a project, Eclipse asks if you want to also delete the files from the file system – generally, it is a good idea to delete the files.
A bit of terminology – the JARs in the EAR project are called binary modules.
Working with binary modules
If you have a project in the workspace which is new or modified and want to change it into a binary module, right-click on the MDM project and select Java EE > Repackage Projects to Binary Modules.
The packaged JAR includes any Java source files that were in the source project, but it won't include other files such as a module.mdmxmi file that was in the project root.
The binary module JARs are not automatically updated when you modify the source projects.
If you need to modify files in a binary module, you can just import the project into the workspace from source control and start working with it. If it was an out-of-the-box project which you deleted from the workspace, then to recreate the project, right-click on the MDM project , select Java EE > Extract Binary Modules to Projects.
If you delete from the workspace a utility JAR project, such as BusinessServicesWS, then the corresponding EJB project disappears with it. When you add it back, the EJB project comes along.
Deciding which projects are required
Projects you definitely don't need
The following projects in the workspace are modules that do not need to be expanded as projects:
These projects can now be deleted from the workspace – delete the files from the file system too.
Which of the out-of-the-box MDM Web services are you planning to use in your deployment ?
If you do not intend to use MDM Web services at all, then you can delete from your workspace all projects with names ending in WS, WS_HTTPRouter and WSEJB. If you do this then when you create new module projects you must disable web service generation.
If you do not intend to use the EvaluateTermConditions web service, then the CrossDomainServices* projects can be deleted from your workspace.
If you are using Web services and the test server has security disabled, you will need to modify the WSEJB projects to swap in the _SecurityDisabled versions of the WebSphere deployment descriptor files.
You should keep the WS, WSEJB and WS_HTTPRouter projects for the same module together – all in the workspace, or all as binary modules.
What extensions to MDM Server are you planning to develop?
Depending on what kinds of extension you are developing, some of the out-of-the-box projects are required in the workspace. Projects which are not required can be deleted.
The following projects are always required:
We recommend that you also keep the projects:
If you are generating web services, then you need DWLCommonServicesWSEJB.
If you have references to out-of-the-box entities and are generating web services, then you need the WSEJB project which contains the WSDL files for that entity.
For example, if you introduce a new transaction taking Person as the request object, the PartyWSEJB project is required.
If you are generating web services, then you need DWLCommonServicesWSEJB.
Identify the out-of-the-box modules which define the entities that you are extending. For example, the Person entity is located in Party. Grouping is located in DWLBusinessServices.
Whichever module you are extending, you need all the projects related to it in the workspace. For example, if you are extending Person, that means the projects:
You could do without the WS projects if you are not using web services.
If you are creating a data extension, for example to Person, then the workbench will generate updates to the Party web services to handle the extended data. If you don't want this done, then disable web service generation for the module.
The Party web services are not the only web services affected though, because Person data can also be used in the FinancialServices and Product web services. The workbench will also re-generate these web services if they are in the workspace. If you don't want these web services to be regenerated, you should delete the WS, WS_HTTPRouter and WSEJB projects from the workspace.
If you were extending Person and are accessing Person records with the FinancialServices web services, then you need both the Party web service projects and the FinancialServices web service projects in the workspace – but you could omit the Product web service projects if you don't use those services.
For each WS project in the workspace, you also need in the workspace all the WS and WSEJB projects for the modules listed in the table below in the column Depends on web services.
These are the dependencies between the web services:
|Extended domain||Affected web services||Depends on web services|
Create new module projects as usual. If you do not want to generate web services for the new module, then disable web service generation by editing the mdmgen.xml file before generating code for the first time.
When you generate code, if any errors occur or projects with the same name as out-of-the-box projects have been created in the workspace unexpectedly, then you have deleted from the workspace a project that was needed by code generation. Review which projects are required and correct any problems.
To recover an out-of-the-box project which you may have deleted in error, right-click on the MDM project , select Java EE > Extract Binary Modules to Projects.
Disabling web service generation for a module project
To do so, edit the mdmgen.xml file and locate the line:
<target name="all" depends="sql, implementation, createReferenceModel, webservices, merge" description="--> description">
and change to:
<target name="all" depends="sql, implementation, createReferenceModel, merge" description="--> description">
Save the change and generate code as usual.
Team development process
If different team members are working on different module projects, does everyone have to have all the projects in their workspace, or can each team member just have the projects they are working on?
Every team member should have in their workspace all the base module projects. They don't necessarily need the generated projects for every module – some could be present as binary modules. Note that if you want to do this, you will need a process to ensure that the binary modules are updated regularly from the source projects.
You also need to keep track of the dependencies between modules, which can be complicated (particularly with web services). When deciding which module to add new extensions to, trying to keep these dependencies as simple as possible is a good aim.
Circular dependencies should be avoided!
To generate web services for ModuleB, ModuleAWSEJB is required in the workspace if:
ModuleB uses a code table which is defined in ModuleA
Module B uses an entity which is defined in ModuleA - in a containment, as a transaction request or response, or as a supertype.
The project ModuleAWS_HTTPRouter is only needed in the workspace if you are generating web service code for ModuleA – in which case, you need all three of the ModuleAWS* projects.
If ModuleA defines a data extension, and ModuleB defines another data extension against the same out-of-the-box module (for example, one extends Person and the other extends Address), then both the projects ModuleAWS and ModuleBWS must be in the workspace when generating code for either. Generally, I would recommend keeping all the data extensions targeting the same out-of-the-box module in one module.
Otherwise, the project ModuleAWS is only needed in the workspace if you are generating web service code for ModuleA.
If your module defines subtypes, then the EJB projects for all of the referenced supertypes must be in the workspace. I would recommend keeping the complete subtype hierarchy in the same module (that is, the root supertype and all its subtypes), as generating web services is not supported otherwise.