Build it yourself

This section describes the steps how to generate a simple J2EE client that makes use of the Web service API delivered with the WebSphere® Process Server. All this client does is to display the list of Business Processes installed on your WebSphere Process Server.

The following steps are described in this section:

Prepare your WebSphere Integration Developer

In order to prepare the WebSphere Integration Developer for this sample, you have to adjust one option responsible for the way how the Java Proxy is generated from Web Services Description Language (WSDL) files.

To set the option, follow these steps:

  1. From the Menu, select Window > Preferences.
  2. In the Preferences window, expand Web Services > WebSphere.
  3. Select JAX-RPC Code Generation.
  4. Select the WSDL2Java tab.
  5. Enable Use –noWrappedOperations for Skeleton Generation.

  6. Click Ok.

Export WSDL files from WebSphere Process Server

In this section, we export the Web Services Description Language files (WSDL files) from the server on which we want to call the Web service interface later.

Note: In this sample, we restrict ourselves to the Business Flow Manager API (BFM API), which can be used to interact with the BPEContainer. If you rather want to use the Human Task Manager API (HTM API), which can be used to interact with the TaskContainer, all steps are similar conceptually, but you will export the WSDL files from the TaskContainer application instead.

To export the WSDL files for the BFM API, follow theses steps:

  1. Make sure your WebSphere Process Server is started.
  2. In a browser, open the administrative console.
    The default URL is
  3. In the navigation pane, select Applications > Application Types > WebSphere enterprise Applications.
  4. Locate the application named BPEContainer_{your_nodename}_server1 and click on this application name.

  5. The configuration page for this application appears:

  6. Under Web Services Properties, click on Publish WSDL files.
  7. A page for downloading a zip file appears:

  8. Click on the zip file name and save this zip file to a directory of your choice, for example C:\temp\.
  9. Using the unzip program of your choice, extract all the files inside this zip file, for example again into directory C:\temp\.
  10. In the subdirectory BPEContainer_{your_nodename}_server1.ear you will find a nested directory tree; you will import the wsdl subtree into your Web Project later.

Create a new Web Project

We will create a simple Web client that uses the Web service interface. To do this, we first create the Web project named WebServiceClient. Follow these steps:

  1. Switch to the J2EE perspective. To switch to the J2EE perspective, select Window > Open Perspective > Other from the Menu. In the Open Perspective dialog, select J2EE and click OK.
  2. In the Project Explorer, right-click the canvas.
  3. From the pop-up menu, select New > Dynamic Web Project.
  4. In the New Dynamic Web Project window, enter WebServiceClient as value for Project name.

  5. As Target Runtime, select WebSphere Process Server v7.0.
  6. Click Next.
  7. Click Next.
  8. In the Context Root field, enter wsclient.

  9. For all other fields, accept the default values.
  10. Click Finish.
  11. If the Open Associated Perspective dialog appears, click No.

Create the Web service Proxy

Import WSDL files

In this section, we use the Web Services Description Language files (WSDL files) we unzipped earlier to prepare the generation of the Java proxy. Later on, we can use Java methods to call the Web service operations in our client code.

First, we import the WSDL files to the Web project. Perform the following steps:

  1. Switch to the J2EE perspective.
  2. In the Project Explorer, right-click your project WebServiceClient.
  3. From the pop-up menu, select Import > Import.
  4. In the Import window, select General > File System and click Next.
  5. Next to the From directory field, click Browse.
  6. In the Import from directory window, navigate to the directory that you have used above in the section Export WSDL files from WebSphere Process Server, for example C:\temp\.
  7. Further navigate to the subdirectory BPEContainer_{your_nodename}_server1.ear\b.jar\META-INF:

  8. With the META-INF directory selected, click OK.
  9. In the Import window, check the checkbox next to META-INF subdirectory and make sure that the radio button is switched to Create selected folders only. The dialog window looks like this:

  10. Click Finish. This will create the folder wsdl and a subdirectory tree in your Web project.

Create Java Proxy

Next, we create a Java proxy from the imported WSDL files.

Note: Before performing the following steps, make sure that the server WebSphere Process Server v7.0 is started.

Follow these steps:

  1. Switch to the J2EE perspective.
  2. In the Project Explorer, expand WebServiceClient > wsdl > com > ibm > bpe > api > sca.
  3. Right-click on the file BFMWS.wsdl and select Web Services > Generate Client.

    4. The Web Service Client window opens.

  4. Accept the default values and click Finish. This will generate several files in the Java Resources subdirectory.
  5. If a Warning dialog appears, click OK.
  6. If prompted, allow to overwrite the file web.xml.

The Java proxy has been generated.

Create a simple Web Application

In this section, we create a very simple Web application, consisting of one HTML page and one Java Server Page (JSP).

Create a HTML page

Complete the following steps:

  1. Switch to the J2EE perspective.
  2. Switch to the Project Explorer view.
  3. Right-click WebServiceClient and select New > HTML. The New HTML Page window opens.
  4. In the File name field, enter index.html and click Finish. The Page Designer window opens.
  5. From the tabs [Design, Source, Preview] select the Source tab.
  6. Replace the default code by the following code:

    7. <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
    <HTML>
    <HEAD>
    <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
    <META name="GENERATOR" content="IBM Software Development Platform">
    <TITLE>index.html</TITLE>
    </HEAD>
    <BODY style="background-color:#FFFFFF">
      <CENTER>
      <H1>Web service API - Sample</H1>
      <HR width="100%">
      <BR><BR><BR>
      <BR>Please press the button to see all process templates installed on the server:
      <FORM action="invoke.jsp" method ="get">
      <INPUT type="submit" value="List process templates"></FORM>
      </CENTER>
    </BODY>
    </HTML>

    The important code snippet here is the <FORM> element, which triggers a call to the JSP that we will define next.

  7. On the toolbar, click the Save button .

Create a JSP page

  1. In the navigation tree, right-click WebServiceClient and select New > JSP. The New JavaServer Page window opens.
  2. In the File name field, enter invoke.jsp and click Finish. A Page Designer window opens.
  3. From the tabs [Design, Source, Preview] select the Source tab.
  4. Just before the first <META> element insert the following line:

    5. <jsp:useBean id="MyBFMAccess" class="com.ibm.www.BFMIFProxy" scope="session"></jsp:useBean>

    This line allows to use the generated Java proxy during the remainder of the browser session.

  5. In addition, replace the default <BODY>...</BODY> code by the following code snippet:

    6. <BODY>
      <CENTER>
      <H1>Web service API - Sample</H1>
      <HR width="100%"><BR><BR>
    <%
    try {
      com.ibm.www.QueryProcessTemplates parameters = new com.ibm.www.QueryProcessTemplates();
      com.ibm.www.QueryProcessTemplatesResponse bfmResponse = MyBFMAccess.queryProcessTemplates(parameters);
      com.ibm.www.ProcessTemplateType[] templates = bfmResponse.getProcessTemplate();

      if (templates == null || templates.length == 0) {
        out.println("No process templates found on server.");
      } else {
        out.println(templates.length +" process template(s) found, details following:<BR><BR>");
        out.println("<TABLE border='2'>");
        out.println("<TR><TD><B>Name</B></TD><TD><B>Auto-delete</B></TD><TD><B>Long running</B></TD></TR>");
        for (int i=0; i<templates.length;i++) {
          out.println("<TR>");
          out.println("<TD>" + templates[i].getName() + "</TD>");
          out.println("<TD>" + templates[i].isAutoDelete() + "</TD>");
          out.println("<TD>" + templates[i].getExecutionMode() + "</TD>");
          out.println("</TR>");
        } // end for
        out.println("</TABLE>");
      } // end if
    } catch (Exception e) {
      out.println("Error while doing call: "+e);
    }
    %>
      <BR><BR><A href="index.html" target="_self">Basic sample - Home</A>
      </CENTER>
    </BODY>

    This code shows just the usage of one of the Web service operations, namely the queryProcessTemplates() operation.

  6. On the toolbar, click the Save button .

Click on the links to see the complete source code of index.html and invoke.jsp and an additional page to manipulate the service endpoint used for the Web Service calls setEndpoint.jsp.

A more comprehensive sample application consisting of the files startprocess.html, startprocess.jsp, and viewprocess.jsp is discussed in the other chapters of this sample, Code Review and Run the sample.

Enforce Authentication for the Web Application

In this section we add configuration information to the Web application, so all users have to authenticate prior to using this Web application. This is a prerequisite to use the Web service interface (which is a secured interface).

Create a new J2EE role

First, we define in our Web project our own J2EE role, which represents the authorization to access our pages. Follow these steps:

  1. Switch to the J2EE perspective.
  2. Switch to the Project Explorer view.
  3. In the navigation tree, expand WebServiceClient.
  4. Right-click Deployment Descriptor: WebServiceClient and select Open With > Other ...
  5. Choose this version of the available Deployment Descriptor Editor versions and click OK:

  6. In the editor, select the Security Tab.

  7. In the Security Roles section, click Add. The Add Security Role window opens.
  8. As Name, enter Web Service API user and click Finish. The Add Security Role window closes.
  9. Down in the Security Constraints section, in the lower left corner, click Add to add a new security constraint. The Add Security Constraints window opens.
  10. As Constraint name, enter Web Service API constraint and click Next.
  11. As Resource name, enter All my pages.
  12. For entering the Pattern, click Add. The Pattern window opens.
  13. In the Name field, enter the wildcard pattern /* to cover all pages.
  14. Click OK. The Pattern window closes.
  15. Click Finish. The Add Security Constraints window closes.
  16. In the subsection Authorized Roles click Add to associate the new resource to the new J2EE role. The Define Authorization Constraint window opens.
  17. In the Description field, enter All API users.
  18. Check the checkbox next to Web Service API user under Role Name.
  19. Click Finish. The Define Authorization Constraint window closes.

    20. Your security settings should now look similar to this:

  20. On the toolbar, click the Save button and close the Deployment Descriptor editor.

Map J2EE role to users

Next, we define in our application project that "all authenticated users" (and thus only authenticated users) are allowed to impersonate our new J2EE role. Follow these steps:

  1. Switch to the J2EE perspective.
  2. Switch to the Project Explorer view.
  3. In the navigation tree, expand WebServiceClientEAR.
  4. Right-click Deployment Descriptor: WebServiceClientEAR and select Open With > Deployment Descriptor Editor.
  5. In the editor, select the Security Tab.

  6. Click Gather to get a complete list of all J2EE roles defined in all modules inside this EAR project (in this sample just one role).
  7. Select the Web Service API user role in the list to enable the checkboxes.
  8. Under WebSphere Bindings, check the checkbox All authenticated users.

    9. Your security settings should now look similar to this:

  9. On the toolbar, click the Save button .

Due to the changes made in this section, the first request to a page of this Web application will automatically include a login dialog.

Enable Web service security

In this section we make sure that the credentials from the login dialog are passed properly to the secured Web service interface.

Follow these steps:

  1. Switch to the J2EE perspective.
  2. Switch to the Project Explorer view.
  3. In the navigation tree, expand JSR-109 Web Services > Clients.
  4. Right-click WebServiceClient: service/BFMWSService and select Open With > Deployment Descriptor Editor.
  5. In the editor select the WS Extension Tab.
  6. Make sure that service/BFMWSService is added to the Service References list.
  7. Make sure that BFMWSPort is selected in the Port Qualified Name Bindings list.
  8. Expand Request Generator Configuration > Security Token and click Add.

    9. The Security Token window opens.

  9. In the Name field, enter LTPA.
  10. As Token type, select LTPA Token.
  11. Click Ok. The Security Token window closes.

  12. In the editor select the WS Binding Tab.
  13. Make sure that service/BFMWSService is added to the Service References list.
  14. Make sure that BFMWSPort is selected in the Port Qualified Name Binding list.
  15. Expand Security Request Generator Binding Configuration > Token Generator and click Add. The Token Generator window opens.
  16. Complete the Token Generator dialog:
    1. For Token generator name, specify LTPA_Token_Gen.
    2. For Token generator class, select com.ibm.wsspi.wssecurity.token.LTPATokenGenerator.
    3. For Security token, select LTPA.
    4. Check the Use value type checkbox.
    5. For Value type, select LTPA Token.
    6. For Call back handler, select com.ibm.wsspi.wssecurity.auth.callback.LTPATokenCallbackHandler.

    7. Click OK.
  17. On the toolbar, click the Save button .

    18. Now you have made sure that your client will pass an LTPA token to the Web service interface.

    Note that no further coding for accessing and examining the LTPA token is needed from your side, this is all done for you automatically by the WebSphere infrastructure.

    For more details about securing Web services, you may refer to the developerWorks article Web services security with WebSphere Application Server V6 that can be applied as well to WebSphere Application Server V7.

Next, you can do the export, deployment, and test of the application as described in detail in the Getting Started > Hello World sample.