Having problems with your account or logging in?
A lot of changes are happening in the community right now. Some may affect you. READ MORE HERE

Visual COBOL 2.2 - SOAP Web Services Tutorial

Visual COBOL 2.2 - SOAP Web Services Tutorial

Introduction

A lot of investment has been put into COBOL applications in terms of lines of code tested and man power. The business logic is essential to the business. There is the desire to make the business logic available to new platforms especially the internet. Re-writing is expensive again in man power and especially re-validating the software. However, re-use reduces the risks dramatically and deployment to the Java Virtual machine opens up many more opportunities. If a COBOL program has an interface, which there is a desire to expose in a server like fashion, then turning it into a web service may be of benefit.

This tutorial will walk through the process of deploying an existing COBOL application as a SOAP web service within the JBoss Application Server. To achieve this, the COBOL application will be deployed as Java byte code so that it is easily accessible by a Java class that provides the web service interface.

The web service interface will be designed by reviewing the interface to the COBOL program. From this the web service operations and parameters will be created using a visual editor. Once the web service is designed, a Java class can be automatically generated which represents the implementation of the web service.

Thanks to the Web Toolkit Plug-in, Axis2, JBoss and of course Micro Focus Visual COBOL for Eclipse, this is a reasonably straightforward process.

Some of the concepts will be briefly explained. There are links in the reference section for more detail. Some experience with Eclipse in terms of creating projects and files and importing items will be of benefit, although this tutorial does present a step by step process. If you are not familiar with web services concepts it may be worth reading some of the links in the reference section first.

There are four parts to the overall web service application.

  1. COBOLBook project which will contain an unmodified legacy COBOL program.
  2. BookWrapper project which will contain a simple COBOL wrapper to improve the interface of the legacy COBOL program.
  3. A project to contain the definition of the Web Service to the outside world
  4. A Web Project which will contain the Java server code which interfaces with the outside world and a JAVA class to bridge the gap between the service code and the COBOL application.
  5. The client, in this walk through will be an automatically generated test harness.

Fig 1. Deployment components

Prerequisites

Please see the Installation and Configuration sections at the end of the tutorial on how to install and configure the prerequisites.

  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 Plug-in) - This is pre-installed with Visual COBOL for Eclipse 2.2
  5. JBossAs Tools (Eclipse Plug-in)

Book Legacy Application

This tutorial will use the Book.cbl application to demonstrate several modernization options available with Visual COBOL. Book.cbl is a simple stock control system for a library or bookstore and provides standard operations to create, read, update and delete entries which are stored using an indexed file. The interface to this application has several parameters:

       procedure division using by value lnk-function
                                by reference lnk-b-details
                                by reference lnk-file-status.

Table 1 Summary of COBOL Interface
Input lnk-function
“1”: read-record
“2”: add-record
“3”: delete-record
“4”: next-record
01 pic x.
Input/Output lnk-b-details
(author, title, etc)
01 group.
Output lnk-file-status
(Micro Focus File Status)
01 pic xx.

Four operations are represented by this interface: add book, next book, read book and delete book. These operations will be exposed as part of the web service and available to the outside world. Part of the design process will be to represent this COBOL interface in a manner more suitable for a web service called a WSDL.

Web Service Description Language

A web service is defined within an XML document using the Web Services Description Language (WSDL). This document describes all the operations, their parameters, an optional endpoint URL and what protocol to use. The WSDL document is used by tooling to generate code both the server side implementation of the web service as well as client side code to access the service. This part of the tutorial will outline the steps to create a WSDL document for the operations used by the Book application.

Before creating the WSDL document, let’s consider the main operations provided by the service. The COBOL program contains 4 separate functions, which are read, add, delete and next but which are exposed by a single entry point in a program. In our design, we will break these functions out into separate discrete operations.

The parameters to these operations will be based upon the parameters required by the COBOL program for the specified operation. We can also take this opportunity to express some parameters differently. For example, the file status code can be changed to a more readable error message.

The following tables show the operations of the web service and the parameters used by each operation.

Type: BookDetail
Title string
Type string
Author string
StockNo string
ISBN long
Retail string
Onhand int
Sold int
Table 2 Type: BookDetail
Type: BookReturn
Book BookDetail
Status string
StatusNo int
Table 3 Type: BookReturn
Operation: nextBook
Input string
Output BookReturn
Operation: addBook
Input BookDetail
Output BookReturn
Operation: deleteBook
Input string
Output BookReturn
Operation: readBook
Input string
Output BookReturn
Table 4 List of Operations and Parameters

With these operations, only stockNo is being used for readBook even although the Book application is capable of looking up records based on other fields. If desired, we could create other operations that enable you to retrieve records using different fields.

Creating the WSDL Document

In this section, the WSDL document will be created using the Eclipse WSDL editor. A workspace will be created to hold all the projects for this tutorial, starting with one for the WSDL document.

  1. Open Visual COBOL for Eclipse. This will bring up the Workspace Launcher dialogue.
  2. In the Workspace textbox, enter a folder for the workspace: workspace.webdemo and click OK (a new workspace is recomended for this tutorial).
  3. Change the perspective to JAVA EE by Window > Open Perspective > Other. In the Open Perspective dialogue, select Java EE and press OK.
  4. Open the Project wizard with File > New > Project.
  5. To create a new project select General > Project and click Next.
  6. Type wsdl into the Project name and click Finish.
  7. In the Project Explorer pane, right click on the project folder wsdl and select New > Other.
  8. In the New dialogue type in wsdl where it says type filter text. The dialogue will now display the WSDL File item. Select with the mouse and click Next.
  9. For the file name type: BookLegacy.wsdl and click Next.
  10. The Target namespace is a URL to make the types unique to the web service. Update this keeping the BookLegacy part. For example: http://project.company.com/BookLegacy.
  11. All the other defaults will be used (of note: Protocol: SOAP, Binding Options: document literal) so just click Finish.

This will open up a new WSDL document in the WSDL Editor giving a template with one operation to get started.

Figure 1 WSDL Editor - New WSDL with Operations Diagram

This next section will provide a guide through the details of using the editor to fill in the WSDL based on the tables formed earlier. This will involve adding new operations and creating new types.

It is worth looking at the next three diagrams showing the intermediate and final stages before starting as to get an idea of how things will turn out because there is going to be a lot of clicking to construct the WSDL diagram. Note that double-click in most cases is actuallyy a gain focus of the box and then select for editing. If double-click does not work, then increase the time between clicks.

Setting the Service Endpoint

  1. The service endpoint is the URL Used by the client to locate the implementation of the web service at run time. To set the endpoint, modify the BookLegacySOAP address property to point to the location of your JBOSS server. This is usually http://localhost:8080

Creating addBook Operation with Parameters (Table 4)

  1. To define the first operation addBook double click on the row with NewOperation in the BookLegacy table and typeaddBook.
  2. To give the parameter a name, in the input row, double click on parameters and type newBook.
  3. To set the element in the third column double click and select New. In the New Element dialogue type in newBook then click OK.
  4. In the output row, double click on the second column and type in bookReturn.
  5. Then in the third column: double click, select New, type in BookReturnE and click OK.

Creating the BookDetail Type (Table 2)

The rest of the operations will be created later. This next section will create the type BookDetail based on Table 2.

  1. At the end of each row in the operations diagram is an arrow pointing right. Click on the one corresponding to newBook. This will open an Inline Schema view showing the element newBook.
  2. Right click on this and select Set Type > New.
  3. In the New Type dialogue, select Complex Type (the default) and type BookDetail then click OK. This adds a new diagram to the editor.
  4. The information from Table 2 will be entered. Right click on BookDetails and select Add Element. This creates a new row.
  5. The editor should automatically highlight text NewElement and allow it to be changed. Change it to Title. If focus is lost, simply double click on NewElement and change to Title. Leave the type as string.
  6. Again right click on BookDetail (the actual heading row) and select Add Element. Change the name to Type.
  7. Repeat for 2 more elements:
  • Author                     string
  • StockNo                   string
  1. Create one more element named ISBN. This will become type long. Click on string (double click if focus is lost). This causes a drop down menu to appear, click on the arrow and select Browse. Type in long in the text box which will highlight long in the type list and click OK.
  2. Add the remaining elements (using the Browse option as per previous to select the int type).
  • Retail                      string
  • Onhand                   int
  • Sold                         int

The diagram should now look like this:

Figure 2 Inline Schema View of BookDetail

  1. Close the Inline Schema view by clicking on the cross in the top right hand side of the pane. Click Yes when prompted to save.

Creating the BookReturn Type (Table 3)

This next section will create the type BookReturn based on Table 3.

  1. In the BookLegacy.wsdl view (operations diagram), click on the arrow after the row for the output parameter. There should be a new Incline Schema view with an element called BookReturnE.
  2. Right click on this and select Set Type > New.
  3. In the New Type dialogue, select Complex Type and type BookReturn then click OK. This adds a new diagram to the editor.
  4. The first element to add to BookReturn is called Book of type BookDetails. Right click on BookReturn and select Add Element. Type in Book.
  5. To change the type, click on string, then the down arrow to bring up the menu. Select Browse (used to find existing types), type in Book, which should be enough to highlight BookDetail in the Types list. Select BookDetail and click OK.
  6. Continue to add elements to BookReturn, the final two are
  • Status                      string
  • StatusNo                 int

The diagram should now look like this:

Figure 3 Inline Schema for type BookReturn

  1. Close the Inline Schema view, clicking Yes to save when prompted.

Adding the Rest of the Operations (Table 4)

The three remaining operations will now be created, nextBook, deleteBook, readBook.

  1. In the BookLegacy.wsdl view, right click on addBook and select Add Operation. A new input and output row is created.
  2. The text NewOperation should be highlighted. Change it to nextBook.
  3. In the input row, double click on parameters and type stockNo.
  4. In the third column, right click and select Set Element > New Element. Type in stockNo again and click OK.
  5. Click on the arrow pointing right to the side of stockNo. This opens up an Inline Schema view.
  6. Right click on the stockNo element and select Set Type > New. Click Simple Type. Type stockNo into the Name textbox. The default type for the element is string.Click OK.
  7. Close the Inline Schema view and select Yes to save.
  8. In the output row, double click on parameters and change to bookReturn.
  9. In the third column, right click and select Set Element > Existing Element. Type in BookReturnE and click OK. Here we are reusing a previous element and its type.
  10. To add the remaining two operations deleteBook and readBook repeat the steps 1-4 and 8-9. However at step 4 instead of New Element select Existing Element instead and select stockNo from the Elements list.

The completed diagram should look like this:

Figure 4WSDL Editor - Completed Operations

Binding Information

Each operation needs to be linked to the server URL. In the diagram is a small box linking the URL to the operations. Right click on this and select Generate Binding Content. This brings up a Binding Wizard. All the defaults are ok so just click on Finish.

The effect of this can be seen in the source view of the editor (see the Design|Source tabs at the bottom on the editor window), which shows the generated XML. Hereis a fragment of the XML.

        <wsdl:operation name="addBook">
  		<soap:operation
  			soapAction="http://project.company.com/BookLegacy/addBook" />
  		<wsdl:input>
  			<soap:body use="literal" />
  		</wsdl:input>
  		<wsdl:output>
  			<soap:body use="literal" />
  		</wsdl:output>
  	</wsdl:operation>

Validation Stage

At the point it is important to use the validation tool to ensure the WSDL conforms to the standards else problems will arise during the creation of the server code from the Axis2 tool.

  1. Right-click on BookLegacy.wsdl inthe Project Explorer view and select Validate. A dialogue will pop up and report any errors. They can also be viewed in the Markers pane under the editor. There should only be one warning which can be ignored (see Addendum for more information).

This completes the creation of the WSDL. It will be used later to generate the server side code.

JVM COBOL Application

This section will set up two JVM COBOL projects to hold the overall COBOL parts of the application. A small wrapper COBOL program will be created to present the slightly new interface which was designed at the WSDL document creation stage. This was to make the file status more helpful to a caller.

This wrapper program will use SMARTLINKAGE to expose its interface to JAVA. SMARTLINKAGE makes it possible to call a procedural COBOL program from JAVA by exposing the linkage parameters as native Java types.

Download the zip file for this tutorial and unzip to a folder. This folder will be referred to as [WebServiceFiles] throughout the steps. There should be four folders, BookWrapper, COBOLBook, DynWebTest1, DataFiles To ease some of the process, files will be imported via Eclipse into the various projects.

COBOLBook Project

  1. Change to the COBOL Perspective by Window > Open Perspective > Other. In the Open Perspective dialogue, select COBOL and press OK.
  2. To create the first COBOL project: File > New > COBOL JVM Project. Type in COBOLBook for the Project Name. Click Finish.
  3. A new project has just been created in the COBOL Explorer view. Double click on COBOLBook to expand the Project Tree.
  4. Right click on the src folder and select Import > Import… > General > File System then click Next.
  5. This brings up an Import dialogue with two panes. In the From Directory enter [WebServiceFiles]\COBOLBook\src and press Enter (or use Browse to navigate) which should bring up a src folder in the left pane and a book-rec.cpy in the right pane.
  6. Click on the checkbox beside book-rec.cpy to select it.
  7. Expand the src folder then the com and microfocus folders. This will reveal the book folder. Clicking on book will show book.cbl in the right. Click on the checkbox. Click Finish to import the files into the project.

The COBOL Explorer view should look like this:

Figure 5 Populated COBOLBook Project

BookWrapper Project

  1. Create the second project: File > New > COBOL JVM Project. Type BookWrapper in the Project Name. Click Finish.
  2. This adds BookWrapper to the COBOL Explorer view. Double click on BookWrapper to expand the Project Tree.
  3. Right click on the src folder and select Import > Import… > File System then click Next (if File System is not visible then select General first).
  4. This brings up an Import dialogue with two panes. In the From Directory enter [WebServiceFiles]\BookWrapper\src and press Enter which should bring up a src folder in the left pane.
  5. Expand the src folder and sub folders until bookwrapper is shown. Clicking on bookwrapper will show BookWrapper.cbl in the right pane. Click on the checkbox to select this file.
  6. Click Finish to import the file into the project.
  7. The copy book path needs to be set to point to the COBOLBook project. Right click on the BookWrapper in the Project Explorer. In the Properties dialogue select Micro Focus. Expand this and select JVM Build Path.
  8. In the JVM Build Path dialogue click on the Projects tab. Click Add. Click on the checkbox to select COBOLBook and click OK.
  9. While in the Properties dialogue, project directives need to be set. Click on Build Configuration (this will prompt to save the previous changes, click Apply). A Build Configuration tab will be displayed. In the Additional directives text box type in: ilnamespace(com.microfocus.bookwrapper) ilsmartlinkage ilcutprefix(lnk-b) ilcutprefix(lnk-) warnings(3) and click OK. The ILCUTPREFIX directive allows the COBOL data names in the linkage section to be exposed as something more meaningful and easier to use in JAVA. For example lnk-b-details is exposed simply as details.

In the Console view should be a message indicating everything builds with no errors.

  cobol.cfg.New_Configuration:
  [cobol]
  [cobol] Compiling BookWrapper.cbl...
  [cobol] Compilation complete with no errors.

The BookWrapper.cbl interface has a similar interface to the Book.cbl but updated to turn the file status into a string and a numeric value and pass it back in lnk-status-group. The setup-status section does the conversion.

       procedure division using by value lnk-function by reference lnk-b-details lnk-status-group.

The BookWrapper.cbl program is compiled with ILSMARTLINKAGE directive which creates classes to represent the PROCEDURE DIVISION parameters. In the bin folder will be a Details.class and StatusGroup.class. This will be seen in action in the creation of the bridge code between the server code and the COBOL application.

Dynamic Web Project

The next stage is to create a project that will implement the web service operations defined in the WSDL document. Eclipse will use Axis2 tooling under the covers to generate the Java code based on the WSDL.

We will create a Dynamic Web Project. The steps involved will be assigning the application server and configuring the Project Facet which details what features and their versions the web service will use.

We will select Axis2 because this is a SOAP web service. This will include the Axis2 libraries in the project which handle the SOAP requests.

Dynamic Web Module 2.5 is also selected which relates to the Servlet 2.5 API used by the web service.

Project Creation

Note Problems at this stage may arise due to not having Eclipse configured to the location of Axis2 or the JBoss Community Plugin installed (see the configuration section). Make sure this has been set up before creating the project.

The project configuration stage will involve selecting the appropriate JAVA, JBoss, Servlet and Axis2 versions.

  1. Change the perspective to JAVA EE by Window > Open Perspective > Other. In the Open Perspective dialogue, select Java EE and press OK.
  2. From Eclipse select File > New > Dynamic Web Project. This opens a New Dynamic Web Project dialogue.
  3. Type in DynWebTest1 in the Project Name.
  4. Click on New Runtime. In the New Server Runtime Environment type in JBoss 6 into the text box. This will show JBoss 6.x Runtime (under JBoss Community). Select this and click Next.
  5. A New Server Runtime Environment dialogue is now displayed. The home folder needs to be set. Click on Browse and navigate to the root folder to where JBoss has been installed.
  6. If this is correct, the text warning message at the top of the dialogue will disappear and new information will appear in the Configuration section. Make sure the folder is server and default is selected. Click Finish to return to the main Dynamic Web Project dialogue.
  7. Click on Dynamic web module version and select 2.5 from the menu.
  8. Click on Modify. This brings up the Project Facet dialogue. Select Axis2 Web Services. Make sure Java 1.6 is selected (click on down arrow to change). Make sure the Dynamic Web Module is set to 2.5.

Figure 6 Settings for Project Facet

  1. Click OK to close the Project Facet dialogue.
  2. Click Finish to generate the project.
  3. If the Open Associated Perspective dialogue appears click Yes.
  4. A new project DynWebTest1 should be added to the workspace.
  5. Additionally DynWebTest1EAR is added which is Eclipse's way of handling the packaging of the project for deployment into the applicaiton server.

Generation of Server Side Code

Now the WSDL will be put through the Axis2 tool to generate the server code. This server code contains logic to receive XML from the http server via SOAP (which contains the input data), parse it and create the types to pass to the main application. It also contains code to turn the types back to XML and return to the web server which will return a SOAP response.

  1. Right click on BookLegacy.wsdl. This indicates to the code generation that a Top Down Web Service is required, else the Bottom Up Web Service dialogue is presented. Select New > Other to bring up the New dialogue.
  2. Type in web service in the text box. This will show Web Service under Web Services. Select Web Service and click Next which brings up the Web Services dialogue.
  3. The dialogue should have: Web service type: Top down JAVA bean Web Service, Service definition: /wsdl/BookLegacy.wsdl.
  4. If the first time configuration for Axis2 has been done, then Web service runtime will show Apache Axis2. If it instead shows Apache Axis, then click on it to change. This will open the Service Deployment Configuration dialogue. Select Apache Axis2 and click OK. Note it is very easy to miss the correct setting when repeating this process the wizard may revert back to Apache Axis. Check that the dialogue has Apache Axis2 set.
  5. Click Finish. A progress bar may appear while it generates the code.
  6. Once the code is generated the file BookLegacySkeleton.java should appear in an Editor Pane.
  7. It is a good idea to reformat the source code at this point. Right click in the Editor Pane, select Source > Format.

The expanded Navigator view of DynWebTest1 should look like this:

Figure 7 Project Explorer view - Source Generated by Axis2 tool From the WSDL

The classes BookDetail, BookReturn, BookReturnE, NewBook, StockNo hold will hold instances of the types represented in the WSDL. In the outline view for BookLegacySkeleton.java are four methods, nextBook(), readBook(), deleteBook() and addBook(). These are the methods which are called by the web service for the operations which were defined and are where user code goes.

Because it may be desired to regenerate this code, it is a good idea to keep the user code in this file to a minimum and have all the logic in a separate class. Each of these methods will contain one line to invoke an appropriate method in a new class called BookOperation. Therefore the next step is to create this class which interfaces between the web service and the COBOL application.

Bridge Code

This code will convert the instance data types from the web service to types for the COBOL application and do the appropriate initialization for the COBOL application.

  1. Copy the data file in [WebServices]\DataFiles\bookfile.dat to another folder to preserve the original.
  2. Importing the BookOperation.java from the extracted source download. Right click on src in the DynWebTest1 project select Import > Import > General > File System. Click Next. Then Browse to the folder [WebServiceFiles]\DynWebTest1\src. Expand the src folder in the left pane until the folder book is revealed. In the right pane BookOperation.java will be shown. Click on the checkbox to select and click Finish.
  3. Click on DynWebTest1 in the Project Explorer and press F5 to refresh the view and reveal the newly added folders.
  4. The code will have compiled with errors. This is because some of the types used are in the COBOL projects. To fix this, right click on DynWebTest1 in the Project Explorer view and select Properties then select Java Build Path.
  5. In the Java Build Path dialogue, click on the Projects tab.
  6. Click on Add. Click Select All (BookWapper and COBOLBook). Click OK.
  7. BookOperation.java references classes in the COBOL JVM Runtime System. This needs to be added.
  8. Still in the Java Build Path dialogue, click on the Libraries tab.
  9. Click Add Library.
  10. Select COBOL JVM Runtime System and click Next.
  11. Click Finish then OK to close the Java Build Path dialogue.
  12. The project should now rebuild with no errors.
  13. In BookOperation.java near the top of the file, update the following line to hold the locaiton of the bookfile.dat on the server machine (from step 1).
       public static final String BOOK_FILE = "[user path]/AxisDEMO/bookfile.dat"; // UNIX
       public static final String BOOK_FILE = "[user path]\\AxisDEMO\\bookfile.dat"; // WIN

In the outline view are the methods readBook(), nextBook(), deleteBook(), addBook(), which will receive the instance data from the web service. Each in turn calls a doOperation() method which then converts the data into type of a similar structure for the COBOL application.

The conversion to COBOL is made easier by the types created by SMARTLINKAGE (Details and StatusGroup) allowing a transfer of fields between the web service types and the ones for the COBOL application. These transfers are done in the methods, getDetails(), getBookReturnE().

The final method of note is this overload of doOperation().

       static private BookReturnE doOperation(String action, Details details, IRunUnit runUnit)
       {             
              StatusGroup statusGroup = getObject(StatusGroup.class, runUnit);
              
              BookWrapper bookWrapper = getObject(BookWrapper.class, runUnit);           
              bookWrapper.setfilename(BOOK_FILE);
              bookWrapper.BookWrapper(action, details, statusGroup);
             
              return getBookReturnE(details, statusGroup);
       }   

The method invoke bookWrapper.BookWrapper(action, details, statusGroup); calls into the COBOL application and was added to the class by the SMARTLINKAGE feature.

The methods of this class can be static as they don’t have any instance data and it reduces the number of objects which will be created and garbage collected.

Note the use of run units. These are used to isolate one web service request from another. Each COBOL program, the subprograms it calls and any resources such as data files are all self contained within the run unit and separate from other run units using the same programs.

The next step is to update the four methods in BookLegacySkeleton class to call the appropriate methods in BookOperation class.

Updating BookLegacySkeleton

  1. Open BookLegacySkeleton.java in the editor.
  2. To allow the methods which will be added, to be found, after the package line type in:
import com.company.project.Book.BookOperation;
  1. Each of the methods will have code
              // TODO : fill this with the necessary business logic
              throw new"Please implement "
                           + this.getClass().getName() + "#nextBook");

  1. The new code for each method is below. Replace the appropriate throw statement with the appropriate return statement. This can be done by highlighting a line with the mouse, copy (ctrl-c). Then after highlighting the appropriate lines in the Editor Pane, paste (ctrl-v).

    Note: Axis2 may generate the methods in a different order and so care is needed in pasting the correct return statement to the correct method. Altering the parameter may be necessary.
       public com.company.project.booklegacy.BookReturnE nextBook(
                     com.company.project.booklegacy.StockNoE stockNo) {
              return BookOperation.nextBook(stockNo);
       }

       public com.mysite.machine.booklegacy.BookReturnE readBook(
                     com.company.project.booklegacy.StockNoE stockNo0) {
              return BookOperation.readBook(stockNo0);
       }

       public com.company.project.booklegacy.BookReturnE deleteBook(
                     com.company.project.booklegacy.StockNoE stockNo2) {
              return BookOperation.deleteBook(stockNo2);
       }

       public com.company.project.booklegacy.BookReturnE addBook(
                     com.company.project.booklegacy.NewBook newBook) {
              return BookOperation.addBook(newBook);

       }
  1. Save All (ctrl-shift-s).

Everything should build cleanly and is almost ready to deploy.

Deployment

The Dynamic Web Project now needs to be configured to include the class files from the COBOL projects. This is done via the Deployment Assembly dialogue. This allows resources from different projects to be deployed together. The Micro Focus JVM Runtime System also needs added to this project.

  1. Right click on DynWebTest1 in the Project view and select Properties.
  2. In the Properties dialogue select Deployment Assembly to show the Web Deployment Assembly dialogue.
  3. Click Add.
  4. Select Project and click Next.
  5. Select both BookWrapper and COBOLBook. Hint pressing the shift key while clicking to select multiple items. Click Finish.
  6. Click Apply.

Adding the COBOL JVM Runtime System

  1. In the Properties dialogue select Java Build Path.
  2. Select Deployment Assembly again.
  3. Click Add.
  4. Select Java Build Path Entries.
  5. Click Next.
  6. Select COBOL JVM Runtime System and click Finish and then Apply.

The Web Deployment Assembly dialogue should look like this:

Figure 8 Adding All Resources

  1. Click OK to close the dialogue.

The project is now ready to export the contents as war file into the JBoss deployment folder.

  1. Make sure Eclipse is in the Java EE perspective, Window > Open Perspective. Select Java EE and click OK.
  2. Right click on DynWebTest1 in the Project Explorer.
  3. Select Export > WAR file.
  4. This opens a WAR Export dialogue. Click on Browse.
  5. In the Save As dialogue, click on Browse Folders and navigate to the installation of JBoss Web Server.
  6. Continue to navigate to the [jboss-install]\server\default\deploy folder.
  7. Click Save then Finish.
  8. If prompted to save any changes from previously modified source files, click Save.
  9. A progress bar maybe shown.
  10. The application has now just been deployed to the JBoss web server.
  11. Expand the JBoss 6.x Runtime Server in the Servers tab to view.

Figure 9 Deployed COBL Web Service

Running the Application

To run the application:

  1. Right click on DynWebTest1 in the Project Explorer select Run As > Run On Server.
  2. The first time this is done a Run On Server dialogue will be displayed with a list of possible servers.
  3. Select JBoss 6.x Runtime Server and click Finish.
  4. This should start the service and a welcome page should be displayed.

Figure 10 Welcome Page

 

  1. Click on Services will display information about the BookLegacy Service.

Figure 11 List Services

Web Service Explorer

This next section will use the Web Services Explorer in Eclipse to see the Web Service in action and the fruits of all the labour!

  1. Click on the BookLegacy link in the List Services view.
  2. This will bring up the WSDL in XML format.
  3. Copy the URL http://localhost:8080/DynWebTest1/services/BookLegacy?wsdl by clicking on the URL text box and ctrl-c.
  4. In the toolbar click on the Launch the Web Services Explorer button (also found at the bottom of the Run menu).
  5. A Web Services Explorer pane should appear. Click on this window to gain focus.
  6. In the top right are several buttons. Click on the WSDL Page icon.
  7. In the Navigator pane, an item called WSDL Main should appear. Click on this.
  8. Then in the right pane an Open WSDL page will appear.
  9. Click in the text box and paste (ctrl-v) or type in http://localhost:8080/DynWebTest1/services/BookLegacy?wsdl.
  10. Then click Go.
  11. This brings up a WSDL Binding Details page. This has a table with all the operations: deleteBook, addbook, nextBook and readBook.
  12. Click on readBook. This brings up an Invoke a WSDL Operation page.
  13. Type 1111 into the stockNo and click Go.
  14. The results are shown in the Status pane below the Actions pane. Resize the window to view the results.

 

Figure 12 Results of the readBook Operation

  1. To navigate between different operations, click on the desired one in the Navigator pane.
  2. Clicking on addBook will bring up a form to enter the details for a new book. One can see how the Explorer has used the WSDL to generate a form for this operation.
  3. Enter the details of this book and click Go.

Title:

The Hobbit

Type:

Fiction

Author:

J. R. R. Tolkien

StockNo:

7777

ISBN:

0007487282

Retail:

9.99

Onhand:

10

Sold:

20

  1. The book details should be returned in the Status pane.
  2. For interest, in the Status pane there is a Source link to view the SOAP Request and Response Envelopes. Shown will be the XML which is sent via HTTP POST and received back from the server.

Debugging

The web service can be debugged in both the JAVA and COBOL programs.

  1. Stop the JBoss Server. Under the main views should be a series of tabs. Click on the Servers tab.
  2. Along the border will be a red square. Click on this to stop the server.
  3. Set a break point in the return statement of the readBook() method in the BookLegacySkeleton.java file. Right click in the margin and select Toggle Breakpoint.
  4. In the COBOLBook project set a break point in the do-read-record section of book.cbl.
  5. Right click on the DynWebTest1 project and select Debug As > Debug on Server.
  6. This brings up a Debug On Server dialogue. Click on the Always use this server when running this project checkbox then click Finish.
  7. The Services page should appear however go to the Web Services Explorer as in the previous section.
  8. Click on readBook. This brings up an Invoke a WSDL Operation page.
  9. Type 1111 into the stockNo and click Go.
  10. This may bring up a Confirm Perspective Switch dialogue. Click Remember my decision and Yes.
  11. The Eclipse Debugger should now stop in the readBook() method in BookLegacySkeleton.java.
  12. Open the Variables view from Window > Show View > Variables. As debugging proceeds through the applications current variables will be shown.
  13. F5 (Step), F6 (Step Over) can be used to. Press F8 (Resume) to continue to the next break point.
  14. Eclipse will now show a Source not found message with an Edit Source Path button.
  15. Click on Edit Source Path bringing up the Edit Source Lookup Path dialogue.
  16. Select Add bringing up the Add Source dialogue.
  17. Select COBOL Project then OK.
  18. Click Select All then click OK, then click OK a second time to close the Edit Source Lookup Path dialogue.
  19. Now the COBOL source code for book.cbl will displayed.
  20. Use F5 to step through the application to investigate further.
  21. Press F8 to complete the operation and show the results in the Status pane of the Web Services Explorer.
  22. Use the Navigator pane in the Web Service Explorer to try other operations.

In Conclusion

One of the major challenges for creating a Web Service is simply gaining familiarity with all the configuration options and using the tools. This tutorial has pulled together all the necessary information on this topic. Once the WSDL has been defined and the bridge layer created, it is remarkably quick to generate and deploy a new web service based on a JVM COBOL procedural program. The important aspect of the JVM COBOL application of course is having an interface which is functional in style lending it’s self to the WSDL operation design.

References

A lot of concepts are only covered briefly in this document. This section gives links to more information on the WWW.

Addendum

Starting JBoss

When starting JBoss there are known issues with classes from the Axis2 jar files conflicting with the same named classes in the JBoss jar files. JBoss issues warning messages for these. See https://community.jboss.org/thread/160881which may be ignored. However the large number of exceptions may hide other more serious issues. One solution is to delete the org/w3c/dom directory from DynWebTest1\WebContent\WEB-INF\lib\xmlbeans-2.3.0.jar. A neater solution is to exclude these classes from being loaded by adding the file jboss-classloading.xml to the DynWebTest1\WebContent\WEB-INF directory with this XML:

<classloading xmlns=urn:jboss:classloading:1.0"
 domain="DynWebTest1.war"
 parent-domain="DefaultDomain"
 export-all="NON_EMPTY"
 import-all="true"
 parent-first="false"
 excluded="org.w3c.dom">
</classloading>

For more info see https://community.jboss.org/thread/178170. This should be done after step 11 in the Deployment section.

WSDL Validation Warning

The Validation tool may have generated a warning which can be ignored.

WS-I: (BP2120) A binding has operations that are not unique.    BookLegacy.wsdl /wsdl/wsdl      line 81 WSDL Problem

This is in fact a incorrectly presented message which is indicating there are multiple operations which have the same parameter types. It is not an issue for this application Eclipse Bug 70481.

Installation

  • JBOSS 6.1: An application server for hosting web services.
  • JBOSS 6.1 is found on http://www.jboss.org/jbossas/downloads/.
  • Scroll down to 6.1.0.Final and click on Download. Save the jboss-as-distribution-6.1.0.Final.zip file and unzip into a directory on your computer.
  • Axis2: Web Services tooling to generate server and client code to handle web services protocols.
  • JBossAs Tools needs to be installed into Visual COBOL for Eclipse: This allows Eclipse to managed JBoss Application Server.
  • Start Micro Focus for Eclipse
  • In Eclipse select Windows > Preferences.
  • Select Server > Runtime Environments.
  • In the Server Runtime Environments view click Add which brings up a New Server Run Time Environment dialogue.
  • Click on Download additional server adapters which brings up a Install New Extension dialogue.
  • Find and click on JBossAS Tools (by Red Hat) then Next.
  • Accept the license agreement and then click Finish.
  • Click OK on any security warnings.
  • A confirmation dialogue will pop up, click Yes. This will download the plug-in and offer the option to restart Eclipse.

Configuration

  • Axis2 and JBoss first time configuration in Eclipse. Note this needs to be done for each new workspace.
  • Window > Preferences > Web Services.
  • Axis2 Preferences: Click on Browse and select the top level folder for the Axis2 install location. Click OK to close the Browse for Folder dialogue. Then Apply.
  • Server and Runtime: Click on Web service runtime and change to Apache Axis2.
  • Click on Server runtime and change to JBoss Enterprise Application Platform 6.x.
  • Click Apply and OK to close the Perference dialogue.
  • JBoss Configuration View
  • Once a Dynamic Web Project has been created and Eclipse is in Java EE Perspective a Servers tab is available.
  • JBoss can be started and stopped in the Servers tab with the green circle and red square icons. Expanding the line JBoss 6.x Runtime Server will show what applications have been deployed. Double clicking on the text JBoss will open a JBoss Information and Configuration view in Eclipse.

DISCLAIMER:

Some content on Community Tips & Information pages is not officially supported by Micro Focus. Please refer to our Terms of Use for more detail.
Comments

good day

I am very grateful to anyone who can collaborate with a tutorial or example to generate a Web service, but in VISUAL STUDIO 2015, I must also generate the WSDL. I can not generate it in VIsual since I can not find how to generate the WSDl or .War file

Thanks

Version history
Revision #:
1 of 1
Last update:
‎2013-11-08 16:49
Updated by:
 
The opinions expressed above are the personal opinions of the authors, not of Micro Focus. By using this site, you accept the Terms of Use and Rules of Participation. Certain versions of content ("Material") accessible here may contain branding from Hewlett-Packard Company (now HP Inc.) and Hewlett Packard Enterprise Company. As of September 1, 2017, the Material is now offered by Micro Focus, a separately owned and operated company. Any reference to the HP and Hewlett Packard Enterprise/HPE marks is historical in nature, and the HP and Hewlett Packard Enterprise/HPE marks are the property of their respective owners.