Introduction

Enterprise services allow access to enterprise information systems (EISs), such as the IBM IMS and CICS products, via J2EE Connector Architecture (J2C) resource adapters. (You can find out more about enterprise services in the Help documentation for WebSphere Studio Application Developer, Enterprise Edition. Select "Process of building an enterprise service" in WebSphere Studio --> Business integration --> Building enterprise services --> Concepts. Check out the Resources section below for more on IMS, CICS, and J2C.) Such services can be built with WebSphere Studio Application Developer, Integration Edition 5. An enterprise service can be offered to clients as a web service, a session EJB (Enterprise JavaBean) component, or a message-driven bean. But each enterprise service interface only represents the interface of its corresponding EIS. You may want to add some logic to your enterprise services for adding values, integrating multiple EISs, or integrating with other Java components. You may also want each interface to represent a unit of work -- that is, the execution of a transaction, or a set of activities that are related to each other and must be completed or undone completely together. Some units of work may involve multiple applications in an EIS or multiple EISs.

In this article, you'll learn about enterprise services and discover a way to add some logic by providing a component called a Facade JavaBean, which can interact with multiple enterprise services and other Java components. You'll also see a simple example that will illustrate the concepts in more detail: a web service that accesses the sample PhoneBook application that is packaged with IMS.

Back to top

What is an enterprise service?

Enterprise services are based on a service-oriented architecture (SOA). An enterprise service has an enterprise service definition written in WSDL files. You can create WSDL files yourself and generate a skeleton of your service from the WSDL files, then write application code in the skeleton; this is known as top-down development. Alternately, you can generate WSDL files from existing assets, then generate deployment code from the WSDL files; this is known as bottom-up development. You can also create an enterprise service that combines other enterprise services by creating a process. (For more on processes, check out two documents in the WebSphere Studio Application Developer Integration Edition documentation: "What is a process," at WebSphere Studio --> Business integration --> Building processes --> Concepts, and "Travel Agency scenario" at WebSphere Studio --> Business integration --> Scenarios. You can also consult the IBM Redbook "Exploring WebSphere Studio Application Developer Integration Edition 5.0" (see Resources for a link).

In this article, I will use bottom-up development to build a sample application. The first steps to build an enterprise service for accessing an EIS are as follows:

1. Create a service project.
2. Create an enterprise service definition by defining relevant EIS connection information.
3. Update the enterprise service definition by importing an interface definition file for accessing an EIS.

In following these steps, you will generate the following WSDL files:

• An interface WSDL file. This describes the interfaces of the service, including data types and data structures.
• A binding WSDL file. This describes how the service interfaces are implemented.
• A service WSDL file. This describes the EIS connection information and the JNDI lookup name. In a non-managed environment, the EIS connection information is used but the JNDI lookup name is not used. In a managed environment, the JNDI lookup name is used but the EIS connection information is not used; you would use the JNDI lookup name to look up the J2C connection factory configured in the Web application server.

The next step is to generate an implementation of the enterprise service. An enterprise service can be offered to clients as a web service, a session EJB component, or a message-driven bean. Any of these implementations can be generated from the enterprise service definition. A service proxy JavaBean component can also be generated from this definition.

An enterprise service definition can also be generated from a JavaBean component. So a JavaBean component can be deployed as a web service, as a session EJB component, and so on by becoming an enterprise service.

Back to top

Provide a Facade interface for enterprise services

Figure 1 shows an overview of providing a Facade interface for enterprise services. In this figure, enterprise services 1 and 2 exist to access the EISs on the back end. Enterprise service 3 is a Facade interface that invokes enterprise services 1 and 2.

The steps to provide a Facade interface for enterprise services, as numbered in Figure 1, are:

1. Create enterprise services and generate service proxy JavaBean components that access the corresponding EISs.
2. Create a Facade JavaBean component to invoke the service proxy beans that access the EISs.
3. Generate an enterprise service definition from the Facade JavaBean component.
4. Generate a web service from the enterprise service created in Step 3. Generating the web service automatically generates the EJB component, which can be used to manage transactions that are performed by the EJB container.
5. Configure the EJB component for transaction management and the resource references to the J2C connection factories.

This probably seems a bit abstract right now. To illustrate the process concretely, you can look at an example in the next few sections.

Back to top

Example: Provide a Facade interface for the IMS PhoneBook application

In this example, let's assume you're developing with WebSphere Studio Application Developer Integration Edition Version 5.0.1, updated to Interim Fix 004 (see Resources for more on Application Developer updates).

The help system of WebSphere Studio Application Developer Integration Edition provides a sample for creating an enterprise service for an IMS transaction. The relevant document is called "Sample: Creating an enterprise service for an IMS transaction," and you can access it at WebSphere Studio --> Business integration --> Building enterprise services --> Samples --> IMS samples. Throughout the rest of the article, I'll refer to this as the Application Developer documentation sample. You can follow this sample, with modifications as you go along, to create a web service that accesses the IMS PhoneBook application.

With the PhoneBook application, you can display, add, and delete a PhoneBook record. The PhoneBook interface consists of the input and output messages outlined in Tables 1 and 2.

The generated web service has only one operation (interface) for the enterprise service definition created by importing the above IMS interface. Clients accessing this enterprise service would need to input all the input field values illustrated in the table above, regardless of whether they are displaying, adding, or deleting a PhoneBook record. And the clients will receive all the output field values, which may include any number of values that are meaningless to them. For example, when a client wants to display a PhoneBook record, it would need to input all input field values, even though IN-NAME1 is the only variable input.

Let's change the web service interface of the IMS PhoneBook application to have the following interfaces by using a Facade JavaBean component:

• displayPhoneBook
• addPhoneBook
• deletePhoneBook

Each interface will have only those input and output messages that will be meaningful to the client.

Example overview

This example web service will provide the interfaces mentioned above for the IMS PhoneBook application. Figure 2 shows an overview.

The steps to create the web service, as numbered in Figure 2, are:

1. Create an enterprise service for the IMS PhoneBook application.
2. Create a Facade JavaBean component that invokes the service proxy bean for accessing the IMS PhoneBook application.
3. Generate an enterprise service definition from the Facade JavaBean component.
4. Generate a web service from the enterprise service definition created in Step 3. An EJB component is also generated at this point.
5. Configure the EJB for the transaction management and the resource reference to the J2C connection factory. To support two-phase commit, you'll need the following software:
   • IMS Connector for Java (IMS resource adapter), Version 2.1
   • IMS Connect, Version 2.1
   • IMS, Version 8.1 or later
   Consult the Application Developer Help documentation for more on this. The relevant document is "Prerequisites for using the IMS resource adapter," located at WebSphere Studio --> Business integration --> Resource adapters --> IMS resource adapter --> Concepts.
6. Test the web service.
7. Deploy the enterprise service.

You can look at each of these steps in more detail in the following sections.

Step 1: Create an enterprise service for the IMS PhoneBook application

This step is described in the Application Developer documentation sample. In the connection properties of the enterprise service, you can leave the JNDI lookup name field blank as described in the sample, but it is a good idea to specify the same name as the JNDI name configured in the WebSphere application server, because you need to associate the JNDI lookup name with the JNDI name later when you configure the EJB resource references. If you leave this field blank, this name is automatically constructed. In the sample, you are asked to specify myIMSTarget for the JNDI name in the WebSphere application server. So, specify myIMSTarget for the JNDI lookup name.

Follow the instructions in the Application Developer documentation sample up to and including the point of "Testing the Java service proxy." Ensure that the Java service proxy works correctly.

Step 2: Create a Facade JavaBean component that invokes the service proxy bean for accessing the IMS PhoneBook application

In Step 1, you created the service proxy JavaBean component, sample.ims.myPhoneBookIMSProxy, in the myIMSPhoneBookService service project. Any Java programs in the service project can invoke this service proxy JavaBean. So, create the Facade JavaBean class in Listing 1 in the facade package of the service project, which invokes the service proxy JavaBean component. You need to create the facade package under the myIMSPhoneBookService service project before creating the Facade JavaBean class. This example just focuses on providing the interfaces mentioned above, displayPhoneBook, addPhoneBook, and deletePhoneBook.

package facade;
import org.apache.wsif.WSIFException;
import sample.ims.*;

public class myPhoneBookFacade {
  public static void main(String[] args) {
    try {
      // Test program
      myPhoneBookFacade me = new myPhoneBookFacade();
      PhoneBookInfo info;
      info = me.displayPhoneBook("LAST1");
      System.out.println("LAST NAME: " + info.getLastName());
      System.out.println("FIRST NAME: " + info.getFirstName());
      System.out.println("EXTENSION: " + info.getExtn());
      System.out.println("ZIP: " + info.getZip());
      System.out.println("MSG: " + info.getMsg());
    } catch (Exception e) {
      System.out.println("Error! " + e.getMessage());
    }
  }
  public PhoneBookInfo displayPhoneBook(String lastName) throws Exception {
    INPUTMSG input = new INPUTMSG();
    input.setIn__ll((short)59);
    input.setIn__zz((short)0);
    input.setIn__trcd("IVTNO");
    input.setIn__cmd("DISPLAY");
    input.setIn__name1(lastName);
    OUTPUTMSG output = runPhoneBook(input);
    PhoneBookInfo info = new PhoneBookInfo();
    info.setLastName(output.getOut__name1().trim());
    info.setFirstName(output.getOut__name2().trim());
    info.setExtn(output.getOut__extn().trim());
    info.setZip(output.getOut__zip().trim());
    info.setMsg(output.getOut__msg().trim());
    return info;
  }
  public String addPhoneBook(String lastName,
                             String firstName,
                             String ext,
                             String zip) throws Exception {
    INPUTMSG input = new INPUTMSG();
    input.setIn__ll((short)59);
    input.setIn__zz((short)0);
    input.setIn__trcd("IVTNO");
    input.setIn__cmd("ADD");
    input.setIn__name1(lastName);
    input.setIn__name2(firstName);
    input.setIn__extn(ext);
    input.setIn__zip(zip);
    OUTPUTMSG output = runPhoneBook(input);
    return output.getOut__msg().trim();
  }
  public String deletePhoneBook(String lastName) throws Exception {
    INPUTMSG input = new INPUTMSG();
    input.setIn__ll((short)59);
    input.setIn__zz((short)0);
    input.setIn__trcd("IVTNO");
    input.setIn__cmd("DELETE");
    input.setIn__name1(lastName);
    OUTPUTMSG output = runPhoneBook(input);
    return output.getOut__msg().trim();
  }
  private OUTPUTMSG runPhoneBook(INPUTMSG input) throws Exception {
    OUTPUTMSG output;
    try {
      myPhoneBookIMSProxy proxy = new myPhoneBookIMSProxy();
      output = proxy.runPhoneBook(input);
    } catch (Exception e) {
      String msg;
      msg = e.getMessage();
      System.out.println(msg);
      throw e;
    }
    return output;
  }
  private OUTPUTMSG setErrMsg(String msg) {
    OUTPUTMSG output = new OUTPUTMSG();
    output.setOut__name1("");
    output.setOut__name2("");
    output.setOut__extn("");
    output.setOut__zip("");
    output.setOut__msg(msg);
    return output;
  }
}

This Facade JavaBean class has the following interfaces (methods):

• PhoneBookInfo displayPhoneBook(String lastName): This displays a PhoneBook record.
• String addPhoneBook(String lastName, String firstName, String ext, String zip): This adds a PhoneBook record.
• String deletePhoneBook(String lastName): This deletes a PhoneBook record.

The main() routine can be used for testing this class as a Java application that runs in a non-managed environment.

In the displayPhoneBook() method, the PhoneBookInfo class, shown in Listing 2, is used as the return class, which is also created and used for storing the meaningful return values. It has methods for setting and getting the meaningful values. Because the PhoneBookInfo class object is passed through the EJB container, it must implement java.io.Serializable.

package facade;

public class PhoneBookInfo implements java.io.Serializable {
  private String lastName;
  private String firstName;
  private String extn;
  private String zip;
  private String msg;
  public String getLastName() {
    return lastName;
  }
  public String getFirstName() {
    return firstName;
  }
  public String getExtn() {
    return extn;
  }
  public String getZip() {
    return zip;
  }
  public String getMsg() {
    return msg;
  }
  public void setLastName(String s) {
    lastName = s;
  }
  public void setFirstName(String s) {
    firstName = s;
  }
  public void setExtn(String s) {
    extn = s;
  }
  public void setZip(String s) {
    zip = s;
  }
  public void setMsg(String s) {
    msg = s;
  }
}

You can test the myPhoneBookFacade class by running it as a Java application in a non-managed environment.

Step 3: Generate an enterprise service definition from the Facade JavaBean component

To generate the enterprise service definition from the Facade bean:

1. In the Service pane of the Business Integration Perspective, right-click myPhoneBookFacade.java under Service Projects --> myIMSPhoneBookService --> facade. Select New --> Service built from...
2. Select Java in the Create Service panel. Click Next.
3. Select the following methods to be published:
   • addPhoneBook(String, String, String, String)
   • deletePhoneBook(String)
   • displayPhoneBook(String)
   Then click Next.
4. Accept the defaults on the final screen. Click Finish.

Step 4: Generate a web service from the enterprise service definition

To generate the web service from the enterprise service definition:

1. In the Service pane of the Business Integration Perspective, right-click the service WSDL file, myPhoneBookFacadeJavaService.wsdl, under Service Projects --> myIMSPhoneBookService --> facade. Select Enterprise Services --> Generate Deploy Code...
2. In the Deployment panel, ensure that SOAP is selected for the Inbound binding type. Accept all other defaults. Click Next.
3. In the Inbound Service Files, EJB Inbound Service Files, EJB Port, SOAP, and SOAP Port panels, accept all defaults. Click Finish.

With these steps, the web service is generated in the myIMSPhoneBookServiceWeb project and the EJB is generated in the myIMSPhoneBookServiceEJB project.

Step 5: Configure the EJB component for transaction management and resource references

To configure the EJB:

1. In the Service pane of the Business Integration Perspective, right-click the myIMSPhoneBookServiceEJB project under Deployable Services. Select Open With --> Deployment Descriptor Editor.
2. Click the Assembly Descriptor tab in the deployment descriptor editor. Click Add... in the Container Transactions section.
3. In the Enterprise Bean Selection panel, enable the MyPhoneBookFacadeService checkbox. Click Next.
4. In the Container Transaction Type and Method Elements panel:
   • First, find out if your environment meets the prerequisites to support two-phase commit. You can do this by consulting the Application Developer help; the relevant document is "Prerequisites for using the IMS resource adapter," located at WebSphere Studio --> Business integration --> Resource adapters --> IMS resource adapter --> Concepts. If you do meet the prerequisites, select Required or RequiresNew for the Container transaction type. Otherwise, select NotSupported. For more information about the container transaction type, you can refer to another document in the Application Developer help system: "Adding container transactions," located at WebSphere Studio --> Java and Web development --> EJB development --> Tasks --> Configuring EJB modules using the EJB deployment descriptor editor --> Working in the Assembly Descriptor page. You can also refer to Richard Monson-Haefel's Enterprise JavaBeans (see Resources for a link).
   • Enable the checkboxes of the following methods for the Methods found:
     • addPhoneBook(...)
     • deletePhoneBook(...)
     • displayPhoneBook(...)
5. Click Finish.
6. Click the References tab. Select the MyPhoneBookFacadeService, and click Add.
7. In the Reference panel, select the EJB resource reference radio button. Click Next.
8. In the EJB Resource Reference panel:
   • In the Name field, type the name you specified for the JNDI lookup name in the connection properties of the enterprise service for accessing the IMS PhoneBook application in Step 1. If you didn't specify the JNDI lookup name, this name is automatically constructed. For the Application Developer documentation sample, the constructed name is sample/ims/myPhoneBookIMSServicemyPhoneBook. Type this name if you haven't yet specified the JNDI lookup name. (For more information, consult the Application Developer help document "Management of J2C resource adapter services," located at WebSphere Studio --> Business Integration --> Building enterprise services --> Concepts --> Process of building an enterprise service. You can also consult the IBM Redbook "Exploring WebSphere Studio Application Developer, Integration Edition 5.0"; see Resources for a link.)
   • Select javax.resource.cci.ConnectionFactory for Type.
   • Select Container for Authentication. You need to specify JAAS authentication when configuring your WebSphere Application Server.
   • Select Shareable for Sharing scope. For more information about the sharing scope, refer to the Application Developer help document "Unshareable and shareable connections," located at WebSphere Application Server Enterprise --> Product features --> Resources --> Data access --> Accessing data from applications --> Connection management architecture.
9. Click Finish.
10. In the WebSphere Bindings section, type myIMSTarget for JNDI name.
11. Press Ctrl-S to save your changes.

Step 6: Test the web service

To test the web service, you need to first create the test server, as described in the Application Developer documentation sample. Walk through the following sections in the sample:

1. Create and configure the server instance.
2. Add a connection factory to the server configuration.
3. Add the EAR project to the server configuration.

You also need to configure the authentication, as follows:

1. Open the myIMSServicesServer configuration editor by double-clicking myIMSServicesServer in the Server Configuration tab of the Server Configuration view.
2. Select the Security tab. In the JAAS Authentication Entries section, click Add.
3. In the Add JAAS Authentication Entry panel:
   • Type myIMSAuth for Alias.
   • Type the IMS user ID for User ID.
   • Type the IMS password for Password.
4. Click OK.
5. Select the J2C tab. Select IMSConnector in the J2C Resource Adapters section. Select ims_cf in the J2C Connection Factories section. Click Edit besides this section. Select myIMSAuth for Container-managed authentication alias. You can also select it for Component-managed authentication alias, which is used for component-managed environments if the user ID and the password are not provided by the application. Click OK.
6. Press Ctrl-S to save the changes.

To create the web service client:

1. In the Services pane of the Business Integration Perspective, right-click the myIMSPhoneBookServiceWeb project under Deployable Services. Select New --> Other...
2. In the Select panel, select Web Services in the left pane. Then, select Web Service Client in the right pane. Click Next.
3. In the Web Services panel, ensure that the Client proxy type is Java proxy. Click Next.
4. In the Web Service WSDL File Selection panel, click Browse... Select myIMSPhoneBookServiceWeb --> Web Content --> wsdl --> facade --> myPhoneBookFacadeSOAPService.wsdl, then click OK. Click Next.
5. In the Web Service Binding Proxy Generation panel, enable the Generate proxy checkbox. Disable other checkboxes. Accept other defaults. Click Next.
6. In the Web Service Test panel, enable the Test the generated proxy and the Run test on server checkboxes. Accept other defaults. Click Finish.

Now the Web page shown in Figure 3 automatically comes up for testing the web service you just created in the above steps. To see how it works, click displayPhoneBook in the Methods pane. Type LAST1 for the lastName in the Inputs pane, then click Invoke. Return values are shown in the Result pane.

If you want to test the web service later, you can access it with the following steps:

1. In the Package Explorer tab of the Business Integration Perspective, expand myIMSPhoneBookServiceWeb --> Web Content --> sample --> myPhoneBookFacadeSOAP.
2. Right-click TestClient.jsp. Select Run on Server...

Step 7: Deploy the enterprise application

You can deploy the enterprise service in the same manner as the Application Developer documentation sample.

When you complete the deployment, you can use a Web browser to test the web service, using the same Web page you tested with Application Developer Integration Edition. You can add, delete, or display a PhoneBook record, as illustrated in Figure 4.

Back to top

Conclusion

This article described a way to provide a Facade interface for enterprise services. A Facade JavaBean component can be used for invoking multiple enterprise services and JavaBean components. By using the facade JavaBean component, you can also provide clients with interfaces (operations), each of which represents a unit of work. You can use this when you want to integrate multiple EISs, change the interfaces generated by enterprise services, or add some logic that works with enterprise services or JavaBean components. Hopefully, you now have a better understanding of how to create web services that unlock the power of back-end enterprise systems while filtering out extraneous information and options that the end user won't need.

Resources

• Learn more about the IBM IMS and CICS product families.
  
  
• Read up on the J2EE Connector Architecture at Java.sun.com.
  
  
• Read Exploring WebSphere Studio Application Developer Integration Edition 5.0, Osamu Takagiwa et al.
  
  
• You can download all needed WebSphere Studio Application Developer updates from the WebSphere Studio Application Developer Integration Edition product support page.
  
  
• For more on EJB technology, read Enterprise JavaBeans, Third Edition, Richard Monson-Haefel.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Introduction
• What is an enterprise service?
• Provide a Facade interface for enterprise services
• Example: Provide a Facade interface for the IMS PhoneBook application
• Conclusion
• Resources
• About the author
• Comments

Local resources

• IBM Innovation Center - Austin, TX
• IBM Innovation Center - Chicago, IL
• IBM Innovation Center - Dallas, TX
• IBM Innovation Center - San Mateo, CA
• IBM Innovation Center - Waltham, MA
• Technical Briefings in North America

Dig deeper into SOA and Web services on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers