The problem

WebSphere Process Server is a platform to create and integrate services based on Service Component Architecture (SCA) and Service Data Objects (SDO), or Business Objects (BO). Most of the time, you will be dealing with Web Services Definition Language (WSDL) interfaces combined with XML Schema Definitions (XSD) when working with service components, exports, and imports in IBM WebSphere Integration Developer. We call this category W-typed service. At the same time, before the SCA and SDO world, lots of assets or services had already been created using pure Java interfaces and Java beans. We call this category J-typed service.

Clearly, we don't want to have to create all services from scratch using the new SCA and SDO programming model. Instead, we want to reuse existing Java-based assets as much as possible from SCA components. An example is an SCA component that needs to invoke a session EJB. This invocation requires a conversion between WSDL types and Java types. However, you cannot directly wire a component with a WSDL type of reference to another component that has a Java interface. There is, it seems, a gap here.

Before Version 6.0.2

Prior to Version 6.0.2 of WebSphere Process Server and WebSphere Integration Developer Version, developers primarily used these two approaches to handle this problem:

1. The obvious solution is just to write an SCA-to-Java bridge. This requires manually creating an intervening POJO (WSDL port type described) that has a reference to the J-type component. But you will need to create the WSDL itself, and the BOs which correspond to the parameters of the Java beans, manually. The most important -- and most time-consuming -- part is to write the mapping code for the Java bean and data object back and forth.

   The problems with this approach are too many manual steps and custom code, which are very error-prone.

2. Another approach is to utilize the tooling in WebSphere Integration Developer to expose the existing Java/EJB assets as Web services, which will give you a WSDL interface automatically. Once you have the SOAP Web services interfaces, integrating them with SCA components becomes very easy.

   This approach has less manual steps than the other, but turning all Java assets into Web services might not be a practical solution; it also introduces additional performance overhead.

An improvement

Neither of the above approaches is entirely satisfactory. Fortunately, the 6.0.2 versions of WebSphere Process Server and WebSphere Integration Developer introduce the ability to automate and intermediate between a W-typed component and an existing J-type interface artifact: when an EJB or Java class is dropped on the WebSphere Integration Developer assembly editor, a helper component bridging the invocation of a Java-typed interface from a component referencing a WSDL-typed interface is automatically generated. This mapping component will convert BO to Java bean on invocation, call the corresponding method on the Java services, and convert the Java bean back to BO on return.

This automation feature also generates the WSDL for the bridging component and BOs using the same base WebSphere java2WSDL (JAX-RPC 1.1) tool.

As you can see, this is a major improvement over the previous version, and it increases productivity tremendously by more easily integrating with Java and J2EE infrastructures, using automatically generated helper components. This also frees you from low-level data conversion and mapping tasks, and enables you to focus more on business logic development.

The next section describes a scenario to illustrate how easily this feature can be used. This article assumes a good understanding of the WebSphere Process Server programming model.

Back to top

Business scenario explained

Assume you are tasked to implement a book ordering process. After some study and comparison, you decide to use WebSphere Process Server BPEL to implement this process. During the process modeling phase, you determine that the following services are needed in the process:

1. getRecommendedBooks
2. checkStock
3. chargeCreditCard
4. fullfilRequest

Further analysis reveals that you have an existing EJB service that provides book recommendations given a particular category. Since this service meets your task 1 requirement, you decide to reuse this EJB service in your BPEL process. We will see how the WebSphere Integration Developer tooling can help you with the other requirements.

Setting up the environment

Before continuing with the scenario, you should load and test the initial artifacts. You will need to have WebSphere Integration Developer (hereafter referred to as Integration Developer) installed, and you will use the embedded WebSphere Process Server (hereafter referred to as Process Server) for testing purposes.

1. Import the sample. You don't need to start from scratch here. Instead, download the sample included with this article first.

   1. Start Integration Developer with a new workspace.
   2. In the Business Integration view, select File => Import.
   3. Select Project Interchange as the type to import in the wizard window.
   4. Browse to find the project interchange file you have downloaded, select all three projects, and click Finish (Figure 1).
   
   
   Figure 1. Import projects
   
   
   

2. Test the EJB services. The packages you just imported include the EJB services and the BPEL process skeleton discussed in the scenario. Test the EJB services first:

   1. Start the Process Server embedded inside Integration Developer.
   2. Add the BookManager application to the server, and click Finish (Figure 2).
      
      Figure 2. Add project to Process Server
      
      
      
   3. You can now test the BookManager EJB using the Universal Test Client. The EJB has a method getRecommendedBooks which returns a list of books in a particular category (Figure 3).
      
      Figure 3. Universal Test Client
      
      
      

Overview of the BPEL process

Let's take a quick look at the skeleton BookOrdering BPEL process. In the Business Integration view, double click to open it in the process editor (Figure 4).

This simple BPEL process models a book ordering scenario, including a couple of different tasks mentioned in the scenario. For the purpose of this article, you will not implement all of these services, but you do want to utilize the BookManager EJB service you tested earlier to implement the task GetRecommendedBooks.

Back to top

The simplified approach

How do you integrate the BookManager EJB services with your BPEL process? Well, if you were using Integration Developer V6.0.1 or earlier, you would have lots of manual work to do, including creating a business object for the EJB method parameter Java beans, creating a WSDL interface matching the EJB interface, and creating a Java bridge SCA component. (See Resources for information on how to achieve this goal with an earlier previous version of the tool.) That process is very time consuming and error prone, which greatly affects the reuse of existing Java or EJB artifacts.

Fortunately, with the advanced tooling support in Integration Developer V6.0.2, all the above tasks can be automated, thus making consuming any Java or EJB services from an SCA component much easier.

Let's continue with the sample using the new approach and tooling support.

Drag and drop

1. First, create an EJB client project out of BookManagerEJB. Open the Navigator view by selecting Window => Show views => Other..., then right-click on the BookManagerEJB project (Figure 5).

   
   
   Figure 5. Create EJB client project
   
   
   

2. Return to the Business Integration view, open the assembly diagram of the module BookOrderingProcess. The diagram should be empty.

3. Open the Navigator view, expand the BookManagerEJBClient project, select BookManager.java, and then drag and drop it onto the empty canvas (Figure 6).

   
   
   Figure 6. Add project to assembly diagram
   
   
   

4. A dialog box will display, asking what kind of component to create. In this case, it is an Import with Stateless Session Bean Binding (Figure 7).

   
   
   Figure 7. Create an EJB import
   
   
   

5. Click OK. You will be asked again if you need to create a map component. Click Yes (Figure 8).

   
   
   Figure 8. Create a map component
   
   
   

6. The final steps will ask you to add BookManagerEJBClient project as a dependent Java project to the process module. Click OK. (Figure 9)

   
   
   Figure 9. Manage project dependencies
   
   
   

7. Figure 10 shows the diagram after the drag and drop is done. You have one Java mapper component and one EJB import component.

   
   
   Figure 10. Completed assembly diagram
   
   
   

Examine the generated artifact

As you can see above, two components were automatically generated and placed onto the assembly diagram. There is one SCA POJO component, which is the bridging/mapping code discussed earlier. It has a W-typed interface, but it also has a J-typed reference which is wired to an EJB import component. If you open the Navigator view, you will see the underlying artifacts (Figure 11).

Complete the BPEL

You can now complete the BPEL to use the generated artifacts to access the EJB services (Figure 12). (Explaining the details of BPEL development is beyond the scope of this article, so only the high level steps are listed here.)

1. Open the BookOrderProcess in the BPEL editor. Find the BookManager interface in the Business Integration view, and drag and drop it to the references partner palette.

2. Create two variables: BookList of type ArrayofBook, and Category of type String.

3. Create an AssignCategory, which maps the category attribute of OrderInput to the variable Category.

4. Change the GetRecommendedBooks node to an Invoke activity, and fill the details in properties.

   
   
   Figure 12. Completed BPEL
   
   
   

5. Enter some sample data detail in the DisplayBooks Java snippets, using the code below as a guide, and save the change.

   System.out.println("Get result from EJB services"); List books = BookList.getList("Book"); DataObject bookBO = (DataObject)books.get(0); System.out.println("Book Name: " + bookBO.getString("title")); System.out.println("Book Author: " + bookBO.getString("author"));

   
   

6. Return to the assembly diagram and drop the BPEL process component there. Draw a wire from the business process component to the WSDL interface of the bridge component in the assembly. The editor creates a matching WSDL reference on the BusinessProcess component to complete the bridge. The facade map component does not contain any business logic; it just enables a connection between the Java interface and the WSDL reference. The assembly diagram in Figure 13 shows that the BusinessProcess component is wired through the Bridge component to the SLSBImport Java import.

   
   
   Figure 13. Completed business process
   
   
   

Back to top

Run and test the completed application

You are ready to test your solution:

1. Start the server if it is not already started.

2. Add the BookOrderingProcessApp projects to the server.

3. In the assembly diagram, right click on the BookOrderProcess, and select Test Component.

4. In the Configuration tab in the testing window, remove the simulators.

5. From the Events tab, enter a value for category field as RCP, and click Continue.

   
   
   Figure 14. Test the completed application
   
   
   

6. Check the WebSphere server logs. You should see messages similar to the ones shown here, indicating that our BPEL process has successfully invoked the BookManager EJB servers, and get results back.

   [5/18/07 10:56:23:831 EDT] 00000086 SystemOut O Get result from EJB services [5/18/07 10:56:23:831 EDT] 00000086 SystemOut O Book Name: Eclipse Rich Client Platform - Designing, Coding and Packaging Java Applications [5/18/07 10:56:23:831 EDT] 00000086 SystemOut O Book Author: Jeff McAffer and Jean-Michel Lemieux

   
   

Back to top

Tips and best practices

Here are some helpful hints to supplement your use of this feature:

• Java interfaces requirement

  There are restrictions on the Java class or interface that you can drag onto the assembly editor canvas to generate a bridge component:

  • You can use a plain Java interface.
  • You can also use a stateless session bean remote interface.
  • You can even use a Java implementation class itself. But this class needs to implement one -- and only one -- interface. If the class does not implement one interface (or if it implements more than one interface), the assembly editor will not offer you the option to generate the bridge component.
  • If you want the generated WSDLs to have meaningful operation parameter names that correspond to the method parameters in the Java interfaces, you will most likely need the source code for the interfaces and classes in the workspace.

• Java input and output requirement

  If the input or return of the Java artifact is a user-defined Java class, it must adhere to Section 5.4 of the JAX-RPC 1.1 conventions. The JAX-RPC specification has implications for the generated code.

• Interface with Java vector, collection, and array

  The Integration Developer tooling relies on the underlying Java2WSDL utility to convert between Java types and XML type. By default, collection and vector are mapped to XSD array of anyType, while Java array of types is mapped to XSD array of ComplexTypes, which match closely to the Java types. Apparently, strongly typed XSDs are much easier to use and map, so it is preferable you use an array of types in your Java interfaces, rather than a vector or collection.

• Bean with constructors

  It seems that if your beans have a non-default constructor, the tooling will not generate the correct complexType for you. It instead generates anyType. If you have a Java bean like this:

  public class Book implements Serializable{ public String title; public String author; public String publishDate; public Book(String title, String author, String publishDate) { super(); this.title = title; this.author = author; this.publishDate = publishDate; } }

  
  

  then the generated XSD will look like this:

  <complexType name="ArrayOfBook"> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="Book" nillable="true" type="xsd:anyType"/> </sequence> </complexType>

  
  

  Therefore, avoid using constuctors in your Java beans.

• Re-factor

  The drag and drop tool will generate a WSDL with inline schemas for the corresponding Java interfaces. You cannot share the inline schema with other WSDLs in other projects. Now, in Version 6.0.2, inline XSD definitions inside WSDL files can now be split out or externalized for better consumption. Integration Developer V6.0.2 will automatically recognize WSDLs with inline schemas by highlighting Extract Inline Business Objects from the refactoring context menu. Overall, this makes for easier sharing of XSD/BO across modules.

• Overwriting

  Occasionally, the default mapping the system creates between a Java code and a Service Data Object (SDO) might not meet your needs, or sometimes you want to have a more customized or controlled way to handle business exceptions in the mapper. In all of these cases, you can replace the default mapper class implementation with your own -- but you need to have generated the Java-to-WSDL type conversion using either Integration Developer or the genMapper command.

  private commonj.sdo.DataObject javatodata_getRecommendedBooks_output(java.lang.Object result, javax.xml.namespace.QName primitiveNameSpace) { // User can override this code to do custom mapping. // Just comment out the existing code and write your custom code. return com.ibm.wbiserver.mediation.jtow.SDOJavaObjectMediator.java2Data(result, primitiveNameSpace); }

  
  

Back to top

Conclusion

This article showed you how easy it is now to consume existing Java artifacts from SCA components, thanks to the new tooling support from WebSphere Process Server and WebSphere Integration Developer Version 6.0.2. These enhancements will greatly improve your development productivity, plus encourage reuse of existing Java services.

Back to top

Downloads

Information about download methods

Resources

Learn

• Integrating EJB Service with WebSphere Process Server
  
  
• Using EJB and BPEL together
  
  
• Java and XSD Conversion
  
  
• developerWorks: WebSphere business integration zone
  
  
• developerWorks: WebSphere Process Server and WebSphere Integration Developer resources
  
  

Discuss

• WebSphere Integration Developer forum
  
  
• IBM developerWorks blogs
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The problem
• Business scenario explained
• The simplified approach
• Run and test the completed application
• Tips and best practices
• Conclusion
• Downloads
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Integration Developer (in the SOA Sandbox: Connect)
• Demo: Process automation, adoption pattern
• Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Integration Developer (in the SOA Sandbox: Connect)

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers