Best practices: Modules and packaging for business services

When developing business integration applications, you may need to work with resources such as JSP files, JAR files, Web projects, Java™ projects, and J2EE projects. This topic provides information to help you set up your projects and resources so that they can be successfully built and deployed to WebSphere® Process Server.

JavaServer Pages files working with stand-alone references

JavaServer Pages (JSP) files invoke Service Component Architecture (SCA) components using stand-alone references in the module assembly. The JSP file has to be deployed in the same EAR file as the module assembly. Here are the steps for adding the JSP file to the module:
  1. Create Web project.
  2. Build the JSP file in the Web project. If you are importing the code, import it into this Web project. See Sample JSP code.
  3. Open the module (which has the stand-alone references) with the dependency editor. Add a dependency on the Web project as a J2EE project. Make sure that the Deploy with Module check box option is selected so that the Web project will be added to the EAR file.
Note: Do not copy the sca.references file to another EAR file. The file will not work outside of the module that it belongs to.

If the Web project is in another EAR file, then the JSP file is in another module, and imports and exports are required for it to work with services in another module.

Sample JSP code

Here is some sample JSP code that uses the stand-alone references in the module assembly:

com.ibm.websphere.sca.Service bankService = (com.ibm.websphere.sca.Service)com.ibm.websphere.sca.ServiceManager.INSTANCE.locateService("BankServicePartner");
=> The "BankServicePartner" reference name comes from the sca.references file in the module (e.g. <reference name="BankServicePartner">...).  This file will exist after creating a stand-alone reference in the wiring editor.

com.ibm.websphere.sca.scdl.OperationType operationType = bankService.getReference().getOperationType("openAccount");
=> We will use the operation type to get the DataObject types that need to be passed into the invoke operation
com.ibm.websphere.bo.BOFactory factory = (com.ibm.websphere.bo.BOFactory) new  com.ibm.websphere.sca.ServiceManager().locateService("com/ibm/websphere/bo/BOFactory");
=> Standard way to obtain factory for creating business objects.

commonj.sdo.DataObject input = factory.createByType(operationType.getInputType());
=> create the proper kind of data object that the operation expects as input
commonj.sdo.DataObject customer = input;
=> assume that we don't have a wrapped input, for now
if(operationType.isWrapperType(operationType.getInputType()))
{
=> In order to call the reference in this case, the wrapper defined in the interface's WSDL file must be passed in.  So we create the wrapped data object and set it on the wrapper (the property name comes from the inlined schema in the WSDL file).
	customer = factory.createByType(operationType.getInputType().getProperty("customer").getType());
	input.set("customer", customer);
}

customer.setString("firstName", "Bob");  
customer.setString("lastName", "Smith");
customer.setString("address", "7 Holly Drive");
customer.setBoolean("isGold", true);
customer.setInt("birthYear", 1976);
=> The above 5 lines set the attributes on Customer.

commonj.sdo.DataObject output  = (commonj.sdo.DataObject)bankService.invoke("openAccount",input);
commonj.sdo.DataObject account = null;
if(operationType.isWrapperType(operationType.getOutputType()))
	account = output.getDataObject("account");
else
	account = output;
=> The output returned may or may not be wrapped.

Working with Java code

If you need to import a JAR file that will be used in your business integration application, you can just drag and drop the file into a module, mediation module, or library artifact in the Business Integration view (you can also import or copy and paste). You will be prompted to confirm that you want to have the JAR set up for use by the library or module. A wizard will create a separate Java project and configure it to hold the JAR file. The wizard will also set up a dependency from the module or library to the Java project. The properties of this generated project will be automatically set up to allow for easy deployment.
Important: Do not alter the Java properties of the business integration library, module, or mediation module, because alterations are likely to cause problems in deployment code generation.
If you need to develop a Java application that will be used in a business integration module or mediation module, you should create a Java project for the code and add a dependency on the Java project to the module that will be using the Java code. Here are some instructions for the Java development in a Java project:
  1. Create a Java project.
  2. Develop your Java code in that Java project.
  3. Add a dependency from a module, mediation module, or library to this Java project. To do that in the dependency editor, open the module that will use the Java code. Add the Java project as a dependent and make sure that the Deploy with Library or Deploy with Module check box is selected. The dependency editor will add the Java project to the module's classpath.

When you generate Java implementations for components in an assembly diagram, the generated Java implementations should be used as a launch point to call other Java classes.

The Business Integration view only shows Java implementations and interfaces that are used in an assembly diagram. They are listed under the module that uses them. If you need to work with Java projects you can switch to work in the Java perspective.

Switching to the Java perspective

Open the Java perspective by following these steps:

  1. From the menu, select Window > Open Perspective > Other.
  2. Select Java and click OK.

In the Java perspective, the two opened perspectives are shown at the top right corner of the Workbench window, you can switch to the Business Integration perspective by clicking the Business Integration perspective button, as shown in this image:

top right corner of the Workbench window showing the two perspective buttons

Avoid changing dependencies without the editor

You should avoid modifying module dependencies outside the dependency editor.

When you add a dependency on a library, Java project, or J2EE project, changes are made to the module's properties. That is, the module's properties are changed in the following ways:
  • The Java Build Path would have the library or project added to its build path.
  • The Project References determines which J2EE projects or utility JAR files are to be included in the resulting EAR file for the module. If in the dependency editor, the library or project is also selected to be Deployed with the Module, then the Project References will have the library or project selected so that it will be added to the EAR file for deployment.

Use the dependency editor to manage project dependencies for your modules and libraries instead of editing their properties. There are important Java assumptions set in the properties of modules and libraries, so you should not modify the Java properties, for example, to change their source and output folders.

Public and private artifacts

Artifacts in a library are public. Artifacts in a module are private. Designers of WID applications should organize artifacts by taking into consideration logical function and visibility. For example, related data types that are used by various pieces of a system should be placed into a library. Other modules may then easily reuse this library. Only one copy of each artifact needs to be created and maintained using this method. Likewise, related business logic features of the application should be grouped into modules. Componentizing an application in this way will yield a more flexible, easily maintained application. Adding new features to the application will also be easier.

Business objects and interfaces for imports and exports

If you plan to use imports and exports in assembly diagrams, it is a good practice to put the business objects and interfaces that are used by the import and exports into a library so that they can be shared. Then, add a dependency on the library to all of the modules that use these common resources. Avoid copying the same business objects and interfaces into different modules to use them.

Library resources that are shared

After deployment, if shared resources change in the library, modules using the resources have to be updated. For example, two modules share some resources in a library. The applications are deployed. One of the modules has to be updated resulting in changes to some of the shared resources in the library. In this case, the second module also needs to be updated to reflect the changes in the shared resources. Libraries are copied at deploy time. In a production environment where you are exporting the modules, you need to recreate the EAR by using the serviceDeploy command or by some other means.

WSDL files must be in a module or a library

If you need to use a WSDL file in a module, copy it to the module. Optionally, copy the WSDL file to a library and, in the module, set a dependency on the library so that you can use the library's resources. If you tried to drag a WSDL file from another type of project, for example a Web project, an error message will prompt you to copy the WSDL to the module or library.

Avoiding namespace resolution problems

Take particular care when you organize artifacts into namespaces. Namespaces should not overlap between dependent projects. For example, if a business object exists in a module, {http:/mytns}Customer, and another business object exists in a library {http://mytns}Address, then you might be tempted to add the library as a dependent of the module. However, if you yield to that temptation, "Address" will not resolve at run time, because the program will only look for one source for a particular type of artifact in each namespace. Keeping unique namespaces for like artifacts, and keeping these artifacts in one project will help avoid these situations.

J2EE module names

The business integration module is a simple project which produces a J2EE EAR file consisting of J2EE projects. If the module is named MyApp, then J2EE projects with these names are generated and you should not use them for your own J2EE projects:
  • MyAppApp
  • MyAppEJB
  • MyAppEJBClient
  • MyAppWeb

Do not modify the generated J2EE module. Direct modifications might be overwritten the next time the integration module project is built in WebSphere Integration Developer. Also, direct modifications to this module can result in an invalid application.

Performing a clean build after deleting J2EE staging projects

If the J2EE staging projects are manually deleted for a module, then all staging projects may not be re-created after saving an editor (for example, the assembly editor). This problem only arises when auto-build is turned on. Only artifacts that have changed will have their deployment code regenerated as the build incrementally processes deltas.

To solve this problem, perform a clean build.

Related concepts
Modules and libraries
Modules and libraries dependencies
Business integration capabilities and roles
Business integration cheat sheets
Best practices: Sharing projects
Business services: Components and modules
Mediation services: Components and mediation modules
Related tasks
Creating a module for business services
Creating a mediation module
Changing default namespaces
Enabling tools capabilities
Adding dependencies to modules and libraries
Creating the library
Creating exports
Related reference
WSDL and Java interfaces and references

Related information

Tutorial: Work with modules and libraries

Feedback
(C) Copyright IBM Corporation 2005, 2006. All Rights Reserved.