Using a Converter Class in OSB

Converter Classes

A reader of my book recently asked about using a converter class within the Oracle Service Bus. A converter class is used to help convert data types that cannot automatically be converted using the JAX RPC engine that ships with OSB. Usually, data conversion between an EJB and OSB is done for you in OSB. However, when dealing with EJBs there are times when automatic conversion is simply not possible. For example, if the EJB returns any of the following, the JAX RPC engine will not be able to infer the true type being returned:

  • java.lang.Object
  • java.lang.Object[]
  • Java Collections that are not strongly typed
  • Java classes that do not follow JavaBean conventions (like the Map class)

The OSB converter class is designed to help you deal with just such return values from an EJB. For our example, we will create an EJB that returns a java.util.List of customers from a method named getCustomerList(). Since the List is not parameterized, there is no way for OSB to know what the List contains. However, as developers with access to the code, we know that the List object returned contains Customer objects. So our task is to create a JAR file that converts the List into an array of Customer objects. You can see the definition of a Customer object in Listing 1.

Listing 2 shows the rather simple EBJ that we are using. The SampleEJB session bean has a single operation (other than the ejbCreate()): public List getCustomerList() {. Since the List return value is not parameterized, the JAX-RPC engine has no idea what the data type is in the List. In the sample code included with this blog, look in the SampleEJB project for the details on how the EJB is project is put together. You deploy the SampleEJB project to the WebLogic Server using the normal process.

Also in the sample code you will see the ConverterClass project. This is the project that should answer the most common questions on creating a converter class. Listing 3 shows the code to the converter class. The important things to remember about the converter class are:

  • It must implement the interface. This interface resides in the sb-kernel-api.jar file which is found in the osb_10.3\lib directory of your OSB installation.
  • As per the ITypeConverter interface definition, the converter class must have a public static method named convert. The return value of this method may be any type at all, but the arguments to the method must be an Object, Object[], Collection, List, Map, etc. Note that you cannot use an ArrayList as an argument. I tried this at first and it simply did not work. While the converter class compiled just fine using the ArrayLlist as an argument, later on OSB did not recongize the convert(ArrayLlist) operation as being valid.

To make life easy, I also copied and pasted the Customer class (Listing 1) from the SammpleEJB project into the ConverterClass project, keeping the same package name. Converter classes are deployed as JAR files, so right-click on the ConverterClass project and export it as a jar. At this point it should be clear how you make a converter class. Our next step is to get everything plugged into Oracle Service bus so we can use it when calling the EJB.

In the OSB_Config configuration project you will find the EJBConverter project. This project contains a single business service called However, you will also notice that it contains a folder called JAR and in that folder you will find both the CustomerConverter.jar file (that contain the ConverterClass project compiled into a JAR) and the SampleEJB.jar file. OSB really only needs the client JAR for an EJB, but the project was so trivial I decided to use the original EJB JAR file to keep things simple.

Configuring the business service you define it as a Transport Typed Service in the General configuration tab. This is shown in Figure 1, below.


Figure 1. The General tab of the business service.

The next tab to configure is the Transport tab. On this tab you start by selecting EJB as the protocol. You can leave the load balancing algorithm as the default (round-robin) for our purposes here. Next, you need to specify the Endpoint URI. Since we are running this code on a single developer machine, we will use a pretty simple endpoint URI of ejb::ejb.SampleEJBRemoteHome. The endpoint is made up of 3 parts:


For EJBs, the [protocol] will always be ejb. We leave the provider blank because we are calling this EJB on our local machine. The [jndi_name] is defined in Listing 2 by the @JndiName() attribute as ejb.SampleEJBRemoteHome. Once you have that endpoint URI in the list of endpoints, as shown in figure 2, you can move onto the next tab: EJB Transport.


Figure 2. The Transport tab of the business service.

Configuring the EJB transport (figure 3) is straightforward. You start by selecting the client jar for the EJB, which is in the JAR/ folder of our OSB project. You need to use the associated Browse button to select the correct JAR file. You will need to select the Converter Jar the same way. With those two JAR files selected, fill in the rest of the form as shown in figure 3.


Figure 3. The EJB Transport tab of the business service.

NOTE: If you did not define the convert() method in the ConverterClass as accepting an .Object, Object[], Collection, List, Mapcode>, etc. as the argument then the Converter drop-down will not appear.


Listing 1 - The Customer Class



public class Customer implements Serializable {
  private int id;
  private String firstName;
  private String lastName;
  public Customer(int theID, String first, String last) { = theID;
    this.firstName = first;
    this.lastName = last;
  public int getId() { return id;}
  public void setId(int id) { = id; }
  public String getFirstName() { return firstName; }
  public void setFirstName(String firstName) { this.firstName = firstName;}
  public String getLastName() { return lastName; }
  public void setLastName(String lastName) { this.lastName = lastName;}

Listing 2 - SampleEJB Session Bean


import java.util.ArrayList;
import java.util.List;
import javax.ejb.SessionBean;
import weblogic.ejb.GenericSessionBean;
import weblogic.ejbgen.Session;
import weblogic.ejbgen.JndiName;
import weblogic.ejbgen.FileGeneration;
import weblogic.ejbgen.Constants;
import weblogic.ejbgen.RemoteMethod;

 * GenericSessionBean subclass automatically generated by Workshop.
 * Please complete the ejbCreate method as needed to properly initialize new instances of your bean and add
 * all required business methods. Also, review the Session, JndiName and FileGeneration annotations 
 * to ensure the settings match the bean's intended use.
@Session(ejbName = "SampleEJB")
@JndiName(remote = "ejb.SampleEJBRemoteHome")
@FileGeneration(remoteClass = Constants.Bool.TRUE, remoteHome = Constants.Bool.TRUE, localClass = Constants.Bool.FALSE, localHome = Constants.Bool.FALSE)
public class SampleEJB extends GenericSessionBean implements SessionBean {
  private static final long serialVersionUID = 1L;

  /* (non-Javadoc)
   * @see weblogic.ejb.GenericSessionBean#ejbCreate()
  public void ejbCreate() {
    // IMPORTANT: Add your code here

  // IMPORTANT: Add business methods
  public List getCustomerList() {
    ArrayList customerList = new ArrayList();
    customerList.add(new Customer(1"Jack""Benny"));
    customerList.add(new Customer(2"Lucille""Ball"));
    customerList.add(new Customer(3"Bob""Hope"));
    return customerList;

Listing 3 -


// The following interface can be found in sb-kernel-api.jar which is located in your
// %OSB_HOME%/osb_10.3/lib/ directory
import java.util.List;

public class CustomerConverter implements ITypeConverter {
  public static Customer[] convert(List customerList) {
    int listSize = customerList.size();
    Customer[] custArray =  new Customer[listSize];
    custArray = (Customer[])customerList.toArray(custArray);
    return custArray;

Source Code

Download the source code. After you download the source code you can import it into a OSB workspace as follows:

  1. Run the WorkShop IDE that was installed when you installed your OSB or ALSB product.
  2. When the IDE is fullly loaded and running, select File -> Import from the main menu bar. This will launch the Import Wizard.
  3. Select the Existing Projects into Workspace inside of the General folder. Press the Next button.
  4. Select the Select archive file radio button, and then browse to the source code file that you downloaded. Be sure to select all projects within the archive file.
  5. Press OK to import the soruce code. After you import all of the source code, wait until the IDE has finished rebuilding its workspace.
  6. Once the workspace is completely rebuilt, you may see a number of error messages next to some of the projects. This is because these projects are using some additional libraries that Workshop cannot find on your machine. If you do not see these errors, your import is complete. If you see these errors, then keep reading.
  7. To help Workshop find the missing libraries, you need to define the OSB_HOME variable within the Workshop IDE. To do that, right-click on one of the projects and select the Properties entry from the popup menu.
  8. In the Properties dialog, select the Java Build Path entry in the list on the left side of the dialog and then be sure the Libraries tab is selected.
  9. Press the Add Variable button. This will display the New Variable Classpath Entry dialog.
  10. Press the Configure Variables... button. This brings up yet another dialog that lists the existing classpath variables.
  11. Press the New... button and create a new variable named OSB_HOME and then press the Folder... button to enter the main directory of the OSB 10gR3 installation folder. If you used the default installation folder, then the correct path is C:\BEA on a windows machine.
  12. Press OK to all open dialogs until you get back to the main Workshop interface. You errors should now disappear after Workshop rebuilds the project.
That's all for this installment. Keep your code clean and your hands dirty!


That's great.

Posted by Adrian on August 08, 2011 at 03:54 PM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed

A site for SOA thought and discussion.


« April 2014