Introduction Now that we have a SOAP Web service containing our Legacy COBOL application, the next question is, how can we access it from a client? This tutorial gives a possible client-side scenario of how to use JSP to present the server information. The tutorial uses client-side Web services code to connect to the Web service. The JSP side of the application is based on Visual COBOL 2.2 - JSP Web Services Tutorial and explains the JSP and servlet areas in depth. So this tutorial focuses mainly on the client Web services code and the layer which joins the two sides together. The different parts of the client are: 1. A servlet which is used to receive the user requests using a Web browser. This uses JSP to present the HTML. 2. Bridge code which takes the servlet request and transforms it into an object for the client-side SOAP request, receives the server response and passes it back to the servlet. 3. Client-side code (generated from the WSDL) which handles the SOAP request to the server and the response back. Prerequisites You need the following software installed: 1. Micro Focus Visual COBOL for Eclipse 2.2 2. JBoss 6.1.0 Server (Download) 3. Axis2 1.6.2 (Download) 4. WTP 3.3.2 (Eclipse Plugin – This is pre-installed with Visual COBOL for Eclipse 2.2) 5. JBossAs Tools (Eclipse Plugin) In addition, you need to have completed the Visual COBOL 2.2 - SOAP Web Service Tutorial available on the Micro Focus Community Web site. Client-Side From Axis2 The first stage is to generate the client-side Axis2 code. This will send SOAP requests to the Web service and receive SOAP responses from the Web service. This code will be generated from the WSDL created in the Visual COBOL 2.2 - JSP Web Services Tutorial . The entire client-side code will be created in a new Dynamic Web Project. 1. Start Visual COBOL for Eclipse and specify a workspace (to change the current workspace click File Switch Workspace Other ). 2. In the Workspace Launcher dialog, enter an appropriate path and folder in the Workspace field such as [path]\workspace.clientdemo and click OK . 3. For each new workspace, you need to set the preferences for Axis2 and the Web Services. For instructions, see the configuration page in the Visual COBOL 2.2 - SOAP Web Service Tutorial . 4. The steps to set up the Dynamic Web Project are exactly the same as the Web Service Tutorial – follow steps 1-11 Visual COBOL 2.2 - SOAP Web Service Tutorial . For a project name use ClientTest1 instead of DynWebTest1 . 5. To import the WSDL project from the Web service workspace, click File Import 6. Expand General , click Existing Projects into Workspace and then click Next. 7. Use Browse button to select the Web service workspace. 8. Make sure only the wsdl project is selected. 9. Check Copy projects into workspace and then click Finish . This will add the wsdl project that contains BookLegacy.wsdl to Project Explorer . Generation of Client-Side Code Now the WSDL will be run through the Axis2 tool to generate the client code. The client code contains the logic to turn types into XML and pass them to the server using SOAP. It also contains the code to receive XML from the server using SOAP (which contains the response data), parse it, and create types to pass to the main application. 1. Right-click BookLegacy.wsdl in the wsdl project. 2. Click New Other . 3. Type web service in the text box. 4. This will show Web Service Client under Web Services . Click this and then click Next to open the Web Services dialog. Figure 1 Web Service Client Make sure the Web service runtime shows Apache Axis2 . Click it to change this if necessary. 5. Click Next . 6. On the next page click Generate a synchronous client . 7. Click Finish . Axis2 will now generate the client-side stub program. 8. In the Project Explorer view, expand the src folder and all sub folders to display the file added by Axis2: The following file has been generated: BookLegacyStub.java . This is the synchronous client which waits for a response from the server after sending a request. BookLegacyStub.java To view some of the methods we will use in our own Java code open the Outline View. 1. In the IDE, click Window Show View Outline . 2. Double-click BookLegacyStub.java in the Project Explorer . The Outline View displays these methods: The deleteBook() , nextBook() , readBook() and addBook() methods call the web service using the stock number as input and return the information received from it in a BookReturnE object. These methods will be used in the BookInterface.java class which bridges the JSP layer to the client web service layer. BookInterface.java This class sits between the BookServlet class and the BookLegacyStub class. It will move the book details between the BookBean object used by the BookServlet and the objects used by BookLegacyStub ( stockNoE , NewBook , BookReturnE ). These last three classes were created by the Axis2 tool in response to the types in the WSDL document. Download the zip file for this tutorial [link] and unzip it into a folder. This folder will be referred to as [ClientFiles] throughout the rest of this tutorial. You should have one folder, TestClient1 , in the [ClientFiles] directory. To facilitate the process, you will import the files in the Eclipse project. To add all the classes to the project: 1. Right-click src folder in the TestClient1 project and click Import Import . 2. Expand General , click File System , and then click Next . 3. In the Import dialog, type [ClientFiles]\TestClient1\src in From Directory and press Enter . This loads a src folder in the left-hand pane. 4. Select the check box for src , and then click Finish . This will add all the files to the project. 5. Press F5 to refresh the Project Explorer view which should now show four new source files. BookInteface.java contains four methods - addBook() , deleteBook() , nextBook() and readBook() which are called in response to the user action in the JSP page. Two other helper methods bookBeanFromDetails() and bookBeanToDetails() convert one object type to the other. The BookDetail object is the most interesting one because it contains all the details of the book information received from the server. It does need to be unwrapped from its containing objects. A third helper method, getStockNoE() , converts a string holding the stock number to a StockNoE object which is used for the input of most of the server operations. Updating the Service Endpoint The constructor for BookInterface tells the client where the service end point is. This assumes localhost and the web service was deployed in a project called DynTest1. public BookInterface() { try { bookLegacyStub = new BookLegacyStub( "http://localhost:8080/DynWebTest1/services/BookLegacy" ) } catch (AxisFault e) // TODO Auto-generated catch block e.printStackTrace(); } } Adding BookJsp.jsp This file contains the information to present the HTML view to the user. See Creating the View in the Visual COBOL 2.2 - JSP Web Services Tutorial . The file is included in the .zip file. We will add it to the project. 1. In the IDE, right-click the WebContent folder and click Import Import. 2. Expand General ,click File System and then click Next . 3. In the Import dialog, type [ClientFiles]\TestClient1\WebContent in the From Directory and press Enter . This loads the webcontent folder in the left-hand pane and BookJsp.jsp in the right-hand pane. 4. Select the check box for BookJsp.jsp , and click Finish . The Deployment Descriptor (web.xml) This is used by the servlet container. Again see The Deployment Descriptor in the Visual COBOL 2.2 - JSP Web Services Tutorial for more information. The existing web.xml file needs to be updated. 1. In Project Explorer , expand the WebContent folder. 2. Expand the WEB-INF folder. 3. Double-click web.xml to open it in the editor. 4. Click the Source tab to view the raw XML. 5. Change the XML for the welcome-file-list tag: welcome-file-list welcome-file view / welcome-file / welcome-file-list 6. Add a new servlet tag changing the servlet-class contents to match your application. servlet servlet-name BookServlet / servlet-name servlet-class com.company.project.book.BookServlet / servlet-class / servlet 7. After the last servlet-mapping tag, add a new servlet-mapping tag as follows: servlet-mapping servlet-name BookServlet / servlet-name url-pattern /view / url-pattern / servlet-mapping 8. Click File Save to save the changes. Jboss-classloading.xml Follow the instructions in the Addendum of the Visual COBOL 2.2 - SOAP Web Service Tutorial to add this file to the WebContent/WEB-INF folder. Deploying and Running To get the client and server working will require two Eclipse sessions - one for the server and one for the client. It is possible to have the client and server in the same workspace but using separate workspaces allows a level of isolation which could be useful. 1. Start up a new instance of Visual COBOL for Eclipse with the workspace previously created for the Web service. 2. Click the Servers tab. 3. Double-click JBoss to open the JBoss Information and Configuration . 4. Check Server is externally managed. Assume server is started . This allows the client-side to manage the JBoss server. Note that, if you go back to use the server workspace in isolation, you will need to uncheck this box again. 5. Check Listen on all interfaces to allow remote web connections . 6. In the Eclipse for the client, click the Servers tab. 7. Double-click JBoss to open the JBoss Information and Configuration view. 8. Ensure Server is externally managed. Assume server is started is unchecked. 9. Check Listen on all interfaces to allow remote web connections . To run the Client-side application: 1. In Project Explorer , right-click TestClient1 and click Run As Run On Server . 2. In the Run on Server dialog, select the check box for Always use this server when running this project, and then click Finish . This loads http://localhost:8080/TestClient1/ with a HTML form in a Web browser. If you do not see the page, there might be an error in the web.xml. The .zip file you downloaded contains a version of the file you can check to help you compare and spot any errors in the XML. 3. In the instance of Eclipse for the server-side code, right-click DynTest1 in Project Explorer , and click Run As Run On Server . This opens the Apache Software Foundation Welcome page as in the section Running the Application in the JSP Web Services Tutorial. 4. Switch back to the instance of Eclipse for the client-side code. Enter 1111 in the Stock Number text box, and then click Read . The details of the book “Lord of the Flies” should be displayed. Debugging the Client The client-side code is easy to debug. The server needs to be restarted in debug mode. 1. Stop the JBoss Server. 2. In the IDE, there is a series of tabs at the bottom of the window. Click on the Servers tab. 3. Click the red square to stop the server. 4. On the first line of the readBook() method in BookInterface.java , right-click in the margin and click Toggle Breakpoint . 5. In the same manner, set a breakpoint on the first line of the bookBeanFromDetails() method in BookInterface.java . 6. In Project Explorer, right-click TestClient1 and click Debug As Debug On Server . This opens the JSP Web page view as before. 7. Enter 1111 into the Stock Number text box, and then click Read . 8. If the Confirm Perspective Switch dialog, click Remember my decision , and then click Yes . The Eclipse debugger should now stop in the readBook() method in BookInteface.java . 9. Press F8 ( Resume) to continue which will send the request to the server and stop on the next break point. 10. Press F5 (Step) or F6 (Step Over) to explore the application. 11. Press F8 to complete the user request and have the JSP view updated. In Conclusion This client has been written to help mainly COBOL programmers see a complete end-to end scenario when using a JVM COBOL application as a Web service. The main complexity (aside from designing the JSP side) is unpacking and packing the objects from the different sides of the application. This tutorial showed how to reuse the WSDL and that the generated code could be the basis of any number of client-side scenarios.
↧