Welcome Serena Central users! CLICK HERE
The migration of the Serena Central community is currently underway. Be sure to read THIS MESSAGE to get your new login set up to access your account.

Tutorial: Calling JVM COBOL programs as part of an Axis Web service

Tutorial: Calling JVM COBOL programs as part of an Axis Web service

Introduction

This tutorial walks through the process of deploying an existing COBOL application as a Web service within the JBoss Application Server. To achieve this, the COBOL application is 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 is designed by reviewing the interface to the COBOL program. From this the Web service operations and parameters are created using a visual editor. Once the Web service is designed, a Java class can be automatically generated that represents the implementation of the Web service.

The overall Web service application comprises:

  • A project that contains an unmodified legacy COBOL program.
  • A small wrapper COBOL program that makes the file status more helpful to a caller. This wrapper program uses smart linkage, which makes it possible to call a procedural COBOL program from Java by exposing the linkage parameters as native Java types.
  • A project that contains the definition of the Web service to the outside world
  • A Web project that contains 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.
  • The client, an automatically generated test harness.

About the Book application

This tutorial uses the BookLegacy.cbl application to demonstrate several modernization options available with Visual COBOL. BookLegacy.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.

Input parameters

lnk-function 01 pic x.

Corresponds to either:

1 read-record

2 add-record

3 delete-record

4 next-record

Input/output parameter

lnk-b-details 01 group.

Contains the author, title, and related information.

Output parameter

lnk-file-status 01 pic xx.

The Micro Focus file status code.

Four operations are represented by this interface: add book, next book, read book and delete book. These operations are exposed as part of the Web service. The part of the design process that represents this COBOL interface in a manner more suitable for a Web service is called a WSDL.

Prerequisites

You must install and configure the following in order to complete this tutorial:

  • This tutorial requires your projects to target Java 8.
  • JBoss Tools, a plugin that enables Eclipse to manage the JBoss Runtime.
  • JBoss EAP 6.4, for hosting Web services.
  • Apache Axis2 1.7.8, a tool to generate server and client code to handle Web services protocols.
  • The JVM Micro Focus COBOL Runtime.
  • You also need to download from the Micro Focus Community Web site a .zip file containing source files.

JBoss Tools

Before installing JBoss Runtime you must download and install the JBoss Tools from the Eclipse Marketplace:

  1. Click Help > Eclipse Marketplace.

    This opens the Eclipse Marketplace dialog box.

  2. In the Find field, type JBoss Tools, and then press Enter.
  3. Find the JBoss Tools 4.5.3.Final plugin in the returned results list, and then click Install.
  4. In the Confirm Selected Features page, click Confirm.
  5. Accept the license agreement, and then click Finish.

    If you receive a security warning, click Install anyway.

  6. When prompted to restart Eclipse, click Restart Now.
    Note: If this is the first time the workspace settings have been changed then Eclipse might prompt you to store preference information.

JBoss

Download and install JBoss EAP

  1. In a browser, open the 3.3. DOWNLOAD AND INSTALL JBOSS EAP USING THE ZIP page located on the Red Hat Web site.
  2. Follow the instructions provided to download and install the Red Hat JBoss Enterprise Application Platform. See Additional Software Requirements in the product Help for more information on supported versions.
    Note: This download might require a Red Hat subscription.

Install JBOSS AS tools in Eclipse

To enable Eclipse to manage JBoss Application Server, you need to add the server runtime environment:

  1. Start Eclipse.
  2. Click Window > Preferences > Server > Runtime Environments.
  3. Click Add.

    This opens the New Server Runtime Environment dialog box.

  4. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Application Platform 7.1 Runtime.
  5. Click Next.

    This opens the New Server Runtime Environment dialog box.

  6. Next to the Home Directory field, click Browse, and then select the folder containing JBoss EAP.
  7. Click OK.
  8. Ensure that you are using a Java 8 JRE runtime.
  9. Click Finish.
  10. Click Apply and Close.

Configure JBoss for each new workspace

  1. Start Eclipse.
  2. Click Window > Preferences > Web Services > Server and Runtime
  3. In the Server runtime list, click JBoss version.
  4. Click OK.

Micro Focus COBOL Runtime

The JVM Micro Focus COBOL Runtime (mfcobolrts.jar) is located by default in the Micro Focus COBOL install directory %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin (Windows) or $COBDIR/bin (UNIX).

The COBOL Runtime file must be added to the Deployment Assembly later in the tutorial.

Axis2

To download Axis2:

  1. Click here to download Axis2.
  2. Click axis2-1.7.8-bin.zip, and download from a suitable mirror site.
  3. Extract into a directory.

You need to configure Axis2 for each new workspace in Enterprise Developer:

  1. Click Window > Preferences > Web Services > Axis2 Preferences.
  2. On the Axis2 Runtime tab, click Browse and navigate to the Axis2 top-level folder.
  3. Click Apply and Close.
  4. Click Window > Preferences > Web Services > Server and Runtime.
  5. In the Web service runtime list, click Apache Axis2.
  6. Click Apply and Close.

Source files

  1.  At the top of this tutorial, click Download.
  2. Save the JVMCOBOLWebServices.zip archive and unpack its contents into a directory.
    Note: The extract directory is referred to in this tutorial as <tutorial_source_folder>.

Create a Web Service Description Language document

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 for the server side implementation of the Web service as well as client side code to access the service.

About the Web service description

The COBOL program contains four separate functions, read, add, delete and next. These functions are exposed by a single entry point in a program. The functions are broken out into separate discrete operations.

The parameters to these operations are based upon the parameters required by the COBOL program for the specified operation. You can 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:

Operations

Operation Input Data Type Output Data Type
nextBook string BookReturn
addBook BookDetail BookReturn
deleteBook string BookReturn
readBook string BookReturn

BookDetail type

Parameter Data Type
Title string
Type string
Author string
StockNo string
ISBN long
Retail string
Onhand int
Sold int

BookReturn type

Parameter Data Type
Book BookDetail
Status string
StatusNo int

With these operations, only StockNo is being used for readBook, even though the Book application is capable of looking up records based on other fields. You can create other operations that enable you to retrieve records using different fields.

Create the WSDL document using the editor

You need to create the WSDL document using the Eclipse WSDL Editor. You need to start by creating a workspace to hold all the projects for this tutorial.

Remember: In the topics describing how to use the WSDL Editor, the phrase "double-click" means one click to select the required box and another click to place the cursor in the text box for editing.
  1. Start Enterprise Developer.
  2. Change the perspective to JAVA EE, click Window > Perspective > Open Perspective > Other.

    This opens the Open Perspective dialog box.

  3. Click Java EE, and then click Open.
  4. Click File > New > Other > General > Project, and then click Next.

    This opens the New Project dialog box.

  5. In the Project name field, type wsdl, and then click Finish.
  6. In the Project Explorer, right-click the wsdl project, then click New > Other.

    This opens the New dialog box.

  7. Type wsdl, and then click WSDL File.
  8. Click Next.
  9. In the File name field, type BookLegacy.wsdl.
  10. Click Next.
  11. In the Target namespace field, type http://project.company.com/BookLegacy/.

    This URL makes the types unique to the web service. Update the URL keeping the "BookLegacy" part.

  12. Use the other defaults and then click Finish.

This opens a new WSDL document in the WSDL editor, giving a template with one operation.

Note: Click the Design tab to see the WSDL diagram.

 Setting the service endpoint

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:

  1. In the Design tab of the WSDL editor, overwrite the BookLegacySOAP address property of the BookLegacy service with the location of your JBoss server. This is typically http://localhost:8080.
    Note: If BookLegacy.wsdl is not open in the WSDL editor, double-click on BookLegacy.wsdl. Alternatively, right-click BookLegacy.wsdl, and then click Open With > WSDL Editor.
  2. Click File > Save.

Create the addBook operation with parameters

To define the first operation:

  1. In the second row of the BookLegacy operations table, double-click NewOperation, and then type addBook.
  2. To give the parameter a name, in the input row, double-click parameters and type newBook.
  3. To set the element in the third column, double-click the addBook list, and then click New.

    This opens a New Element dialog box.

  4. In the Name field, type newBook and then click OK.
  5. In the output row, double-click parameters and type bookReturn.
  6. In the output row, double-click the addBookResponse list, and then click New.

    This opens the New Element dialog box.

  7. In the Name field, type BookReturnE, and then click OK.
  8. Click File > Save.

Create the BookDetail type

You now need to create the BookDetail type for the addBook operation input:

  1. At the end of each row in the operations diagram is an arrow pointing right. Click on the arrow next to newBook input element.

    This opens an Inline Schema editor showing the newBook element.

  2. Right-click anywhere in the view, and then click Set Type > New.

    This opens the New Type dialog box.

  3. Click Complex Type (the default).
  4. In the Name field, type BookDetail, and then click OK.

    This adds a new diagram to the editor.

  5. Right-click BookDetail, and then click Add Element.

    This creates a new row.

  6. The editor automatically highlights the text NewElement enabling you to edit it. Type Title, and leave the type as string.
    Note: If focus is lost, double-click NewElement and type Title.
  7. Right-click BookDetail (the header row), click Add Element, and then type Type.
  8. Repeat step 7 to add two more elements, Author and StockNo. All of these elements should be of type string.
  9. Create one more element named ISBN. This element must be type long.
  10. Right-click string, and then click Set Type > Browse.

    This opens the Set Type dialog box.

  11. In the Types list, click long, and then click OK.
  12. Add the following three elements and set their type by double-clicking string and selecting from the list:
    Element Name Data Type
    Retail string
    Onhand int
    Sold int

    Your diagram should now contain:

    Element Name Data Type
    Title string
    Type string
    Author string
    StockNo string
    ISBN long
    Retail string
    Onhand int
    Sold int
  13. Click File > Save and close the Inline Schema editor.

Create the BookReturn type

  1. In the BookLegacy.wsdl editor (operations diagram), click on the arrow next to BookReturnE output element.

    This opens an Inline Schema editor showing the element BookReturnE.

  2. Right-click anywhere in the view, and then click Set Type > New.

    This opens the New Type dialog box.

  3. Click Complex Type (the default).
  4. In the Name field, type BookReturn, and then click OK.

    This adds a new diagram to the editor.

  5. Right-click BookReturn, and then click Add Element.

    This creates a new row.

  6. In the highlighted NewElement field, type Book.
  7. To change the type, right-click on the row and click Set Type > Browse.

    This opens the Set Type dialog box.

  8. In the Name field, type Book.

    This lists the BookDetail and BookReturn types.

  9. Click BookDetail in the Types list, and then click OK.
  10. Continue to add the following elements:
    Element Name Data Type
    Status string
    StatusNo int

    Your diagram should now contain:

    Element Name Data Type
    Book BookDetail
    Status string
    StatusNo int
  11. Click File > Save, and then close the Inline Schema editor.

Add the rest of the operations

You now need to create the three remaining operations, nextBook, deleteBook, readBook:

  1. In the BookLegacy.wsdl editor, right-click addBook, and then click Add Operation.

    This creates new input and output rows.

  2. The text NewOperation should be highlighted, type nextBook.
  3. In the input row, double-click parameters and type stockNo.
  4. In the input row, right-click nextBook, and then click Set Element > New Element.

    This opens the New Element dialog box.

  5. In the Name field, type stockNo, and then click OK.
  6. Click on the arrow next to the stockNo input element.

    This opens an Inline Schema editor showing the stockNo element.

  7. Right-click the stockNo element, and then click Set Type > New.

    This opens the New Type dialog box.

  8. Click Simple Type.
  9. In the Name field, type stockNo.
  10. Click OK.
    Note: The default type for the element is string.

  11. Click File > Save, and close the Inline Schema editor.
  12. In the output row, double-click parameters and change to bookReturn.
  13. In the output row, right-click nextBookResponse, and then click Set Element > Existing Element.

    This opens the Set element reference dialog box.

  14. In the Name field, type BookReturnE.
  15. In the Elements list, click BookReturnE.
  16. Click OK.

    Here we are reusing a previous element and its type.

  17. To add the remaining two operations deleteBook and readBook repeat the steps 1 through 10. At step 4, click Existing Element, and then click stockNo in the Elements list.
  18. Click File > Save.

The completed diagram should look like this:

 Binding information

Each operation needs to be linked to the server URL:

  1. Right-click  and then click Generate Binding Content.

    This opens the Binding Wizard dialog box.

  2. You can use the default values, click Finish.

You can see the generated XML in the Source tab of the WSDL Editor:

  <wsdl:binding name="BookLegacySOAP" type="tns:BookLegacy">
  	<soap:binding style="document"
  		transport="http://schemas.xmlsoap.org/soap/http" />

Validate the WSDL

It is important to use the validation tool to ensure the WSDL conforms to the standards, otherwise you might encounter issues during the creation of the server code from the Axis2 tool.

  1. From Project Explorer, right-click BookLegacy.wsdl, and then click Validate.

    This opens the Validation Results dialog box, reporting any warnings or errors. You can see the detail of the warnings and errors in the Markers view.

You should only have one warning:

WS-I: (BP2120) A binding has operations that are not unique.

This is an incorrectly presented message that indicates there are multiple operations which have the same parameter types. It is not an issue for this application and the warning can be ignored. See Eclipse Bug 70481 for more information.

This completes the creation of the WSDL, it is used later to generate the server side code.

Create the JVM project

First you need to create a project to contain the procedural COBOL program and make it available for execution from a Java program:

Create the project

  1. Click File > New > Other.

    This opens the New dialog box.

  2. Expand Micro Focus COBOL, and then click COBOL JVM Project.
  3. Click Next.

    This opens the New COBOL JVM Project dialog box.

  4. In the Project name field, type CobolBook.
  5. Ensure Use default location is checked.
  6. Ensure that the project is set up to use a Java 8 JRE.
  7. Click Finish.

This creates a blank JVM COBOL project to contain the procedural COBOL program that you are to import into the Web application.

Note: If Eclipse prompts you to switch to the COBOL perspective then do so. In general, any action that uses the CobolBook project is expected to be carried out in the COBOL perspective. The dynamic web project that comes later in this tutorial is expected to be done in the Java EE perspective. To change perspectives later, click on the appropriate option in the top right of the Eclipse main window.

Add the COBOL source files

The project uses two source files, BookLegacy.cbl and book-rec.cpy, that need to be imported into your project:

Important: Before you import the files from the file system you need to rename <tutorial_source_folder>\COBOLBook\src\book.cbl to BookLegacy.cbl.
  1. In Application Explorer, right-click the CobolBook project, and then click Import.

    This opens the Import dialog box.

  2. Expand General folder, and then click File System.
  3. Click Next.
  4. Click Browse and navigate to <tutorial_source_folder>\COBOLBook\src.
  5. Click OK.
  6. Check src in the left pane.
  7. Click Finish.

    This imports the files into the project.

Create the wrapper project

The BookWrapper.cbl interface has a similar interface to BookLegacy.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 the ILSMARTLINKAGE directive which creates classes to represent the PROCEDURE DIVISION parameters. In the bin folder are the Details.class and StatusGroup.class files. These files are used in the creation of the bridge code between the server code and the COBOL application.

Create the project

To create the wrapper project:

  1. In the COBOL perspective, click File > New > COBOL JVM Project.

    This opens the New COBOL JVM Project dialog box.

  2. In the Project name field, type BookWrapper.
  3. Click Finish.

To set the compiler directives:

  1. Right-click the BookWrapper project, and then click Properties.

    This opens the Properties for BookWrapper dialog box.

  2. Click Micro Focus > Build Configuration.
  3. In the Additional directives field, type:

    ilnamespace(com.microfocus.bookwrapper) ilsmartlinkage ilcutprefix(lnk-b) ilcutprefix(lnk-) jvmdecimal(scaledinteger) warnings(3)

  4. Click Apply and Close.

Add the COBOL source files

The project uses one source file, BookWrapper.cbl, that needs to be imported into your project:

    1. In the COBOL Explorer, expand the BookWrapper project, and then right-click src.
    2. Click Import > Import.

      This opens the Import dialog box.

    3. Click General > File System.
    4. Click Next.
    5. Next to the From directory field, click Browse and navigate to <tutorial_source_folder>\BookWrapper\src.
    6. Click OK.
    7. Check src in the left pane.
    8. Click Finish.

      This import the files into the project.

Set the copybook path

The copybook path needs to be set to point to the CobolBook project:

  1. Open the BookWrapper project's Properties dialog box.
  2. Click Micro Focus > JVM Build Path.
  3. Click the Projects tab, and then click Add.

    This opens the Required Project Selection dialog box.

  4. Check CobolBook, and then click OK.
  5. Click Apply and Close.

Create the dynamic Web project

Next you need to create a project that implements the Web service operations defined in the WSDL document. Axis2 automatically generates the Java code for this.

Create a new project

The project configuration stage involves selecting the appropriate Java, JBoss, Servlet, and Axis2 versions.

Important: Problems may arise at this stage due to incorrectly installed and configured Axis2 or JBoss AS, see Before you start for more information.
  1. Change to the JAVA EE perspective. Click Window > Perspective > Open Perspective > Other.

    This opens the Open Perspective dialog box.

  2. Click Java EE, and then click OK.
  3. Click File > New > Dynamic Web Project.

    This opens the New Dynamic Web Project dialog box.

  4. In the Project name field, type DynWebTest1.
  5. Click New Runtime.

    This opens the New Server Runtime Environment dialog box.

  6. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Applcation Platform 7.1 Runtime.
  7. Click Next.
  8. Next to the Home Directory field, click Browse and navigate to the root folder where JBoss EAP has been installed.
  9. Click OK.
  10. Ensure the Runtime JRE is set to a Java 8 JRE.
  11. Click Finish.
  12. In the Dynamic web module version list, click 2.5.
  13. Click Modify.

    This opens the Project Facets dialog box.

  14. Check Axis2 Web Service.
  15. In the Java row, click the Version list, and then click 1.8.
  16. Click OK.
  17. Click Finish.

    This generates the project.

Generate the server-side code

Next the WSDL is put through the Axis2 tool to generate the server code. This server code contains logic to receive XML from the HTTP server using SOAP (which contains the input data), parse it, and create the types to pass to the main application. It also contains code to turn these types back to XML and return to the Web server, which returns a SOAP response.

You must start the JBoss EAP 7.1 server before generating the server-side code:

  1. Click Window > Show View > Servers.
  2. Right-click in the Servers tab, and then click New > Server.

    This opens the New Server dialog box.

  3. Click Red Hat JBoss Middleware > Red Hat JBoss Enterprise Application Platform 7.1.
  4. Click Next.
  5. Click Finish.
  6. Right-click Red Hat JBoss EAP 7.1 on the Server tab.
  7. Click Start.

    You must wait till the server has started before continuing with the steps to generate the server-side code.

    Tip: You can check that the server has started successfully by looking in the console tab.

To generate the server-side code:

  1. In Project Explorer, right-click BookLegacy.wsdl.
  2. Click New > Other.
  3. Expand Web Services, and then click Web Service.
  4. Click Next.

    This opens the Web Service dialog box.

    Important: If the Web service runtime was correctly configured then it displays Apache Axis2. If it does not click on the link it to change it. This opens the Service Deployment Configuration dialog box. Click Apache Axis2, and then click OK. By default, the Web services type field should be set to Top down Java bean Web Service and the Service definition field should be set to /wsdl/BookLegacy.wsdl.
  5. Click Finish.

    A progress bar might appear while it generates the code.

    Important: When using Axis2 1.7 and onwards, you might generate the following exception:
    Exception occurred during code generation for the WSDL  : java.lang.NoClassDefFoundError:

    This is because Eclipse does not copy the xmlschema-core-n.n.n.jar file to your dynamic Web project. To avoid this exception, copy the xmlschema-core-n.n.n.jar file located in your $AXIS2_HOME/lib folder to the DynWebTest1/WebContent/WEB-INF/lib folder. You need to restart Eclipse before attempting to run the server-side code generation steps again.

  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.
  8. Click File > Save.

Comments

The classes BookDetails, BookReturn, BookReturnE, NewBook, and StockNo 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 that are called by the web service for the operations that were defined and is where you place your code.

Because you might want 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 contain one line to invoke an appropriate method in a new class called BookOperation. The next step is to create this class which interfaces between the Web service and the COBOL application.

Add the bridge code

The project uses a Java class, BookOperation.java, that needs to be imported into your project.

This code converts the instance data types from the Web service to types for the COBOL application and do the appropriate initialization for the COBOL application:

  1. In the DynWebTest1 project, right-click on the Java Resources\src folder in Project Explorer, and then click Import > Import.

    This opens the Import dialog box.

  2. Click General > File System.
  3. Click Next.
  4. Next to the From directory field, click Browse and navigate to <tutorial_source_folder>\DynWebTest1\src\.
  5. Click OK.
  6. Expand src > com > company > project.
  7. Highlight Book.
  8. Check BookOperation.java in the right pane.
  9. Click Finish to import the file into the project.
  10. Open BookOperation.java in the editor.
  11. Near the top of the file, update the following line with the location of bookfile.dat:
     public static final String BOOK_FILE = "\\DataFiles\\bookfile.dat"; 
    Note: Ensure that you use double backslashes so that the path has a valid escape sequence.
  12. Click File > Save.

    The project builds automatically, but in this case the code compiles with errors. This is because some of the types used are in the COBOL projects.

Comments

In the outline view are the methods readBook(), nextBook(), deleteBook(), and addBook(), which 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) enabling a transfer of fields between the Web service types and the ones for the COBOL application. These transfers are done in the methods getDetails() and getBookReturnE().

The final method of note is the 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 do not have any instance data and it reduces the number of objects that are created and garbage collected.

Note: Run units are used to isolate one Web service request from another. Each COBOL program, the sub-programs 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 the BookLegacySkeleton class to call the appropriate methods in the BookOperation class.

Configure the project

To add the class folder to the project's build path:

  1. In Project Explorer, right-click the DynWebTest1 project, and then click Properties.
  2. Click Java Build Path.
  3. Click the Libraries tab.
  4. Click Add Class Folder.

    This opens the Class Folder Selection dialog box.

  5. Check the bin folders under BookWrapper and CobolBook.
  6. Click OK.
  7. Click Add Library.

    This opens the Add Library dialog box.

  8. Click COBOL JVM Runtime System, and then click Next.
  9. Click Finish.
  10. Click Apply and Close.

    The project rebuilds without error.

Update the BookLegacySkeleton class

  1. In the DynWebTest1 project, open BookLegacySkeleton.java in the editor.
  2. To enable the methods that are being added to be found, after the package line type:
    import com.company.project.Book.BookOperation; 
  3. Each of the methods have the following code:
    // TODO : fill this with the necessary business logic
     throw new java.lang.UnsupportedOperationException( "Please implement " 
        	 + this .getClass().getName() + "#nextBook" ); 

    Replace the appropriate throw statement with the appropriate return statement.

    Important: Axis2 may generate the methods in a different order and so care is needed when pasting the return statement into the correct method. Alter the stockNon parameter so that it fits with the one in that particular method.
    public com.company.project.booklegacy.BookReturnE nextBook(
    			com.company.project.booklegacy.StockNoE stockNon) {
    		return BookOperation.nextBook(stockNon);
    	}
    
    	public com.company.project.booklegacy.BookReturnE readBook(
    			com.company.project.booklegacy.StockNoE stockNon) {
    		return BookOperation.readBook(stockNon);
    	}
    
    	public com.company.project.booklegacy.BookReturnE deleteBook(
    			com.company.project.booklegacy.StockNoE stockNon) {
    		return BookOperation.deleteBook(stockNon);
    	}
    
    	public com.company.project.booklegacy.BookReturnE addBook(
    			com.company.project booklegacy.NewBook newBook) {
    		return BookOperation.addBook(newBook);
    }
  4. Click File > Save All.

Everything builds cleanly.

Using JBoss

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.

In the Servers tab, expand Red Hat JBoss EAP 7.1 This displays the applications that have been deployed.

Double-click Red Hat JBoss EAP 7.1 opens a JBoss Information and Configuration view in Eclipse.

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 which may be ignored. The large number of exceptions generated 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 the following 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 >

See the discussions on the JBoss community Web pages for more information:

Configure for deployment

You now need to configure the environment ready for deployment:

Include the class files

You need to include the class files from the COBOL projects and the cobconfig.properties file to enable resources from different projects to be deployed together:

  1. In Project Explorer, right-click on the DynWebTest1 project, and then click Properties.

    This opens the Properties for DynWebTest1 dialog box.

  2. Click Deployment Assembly.
  3. On the Deployment Assembly tab, click Add.

    This opens the New Assembly Directive dialog box.

  4. Click Java Build Path Entries, and then click Next.
  5. Select bin - \CobolBook, bin - \BookWrapper, and COBOL JVM Runtime System.
    Note: You can use Ctrl+Click to select multiple paths.
  6. Click Finish.
  7. Click Apply and Close.

Export the content

To export the content as a .war file into the JBoss deployment folder:

  1. Make sure Eclipse is in the Java EE perspective, click Window > Perspective > Open Perspective > Other. Click Java EE and then click Open.
  2. In Project Explorer, right-click the DynWebTest1 project.
  3. Click Export > WAR file.

    This opens the Export dialog box.

  4. Click Browse.

    This opens the Save As dialog box.

  5. Navigate to the [jboss-installation]\standalone\deployments folder.
  6. Click Save.
  7. Click Finish.

The application is now deployed to the JBoss EAP server. In the Servers tab, right-click Red Hat JBoss EAP 7.1 Runtime server and then click Start.

Run the application

To run the application:

  1. In Project Explorer, right-click the DynWebTest1 project, click Run As > Run On Server.

    The first time this is done a Run On Server dialog box is displayed with a list of the available servers.

  2. Click Red Hat JBoss EAP 7.1 Runtime server, and then click Finish.

    This opens a browser within Eclipse and displays an Apache Software Foundation welcome page.

  3. Click Services in the Web page to see information about the BookLegacy service.

Use the Web Service Explorer

You can use the Web Services Explorer in Eclipse to see the Web service in action:

  1. In the list of available services, click BookLegacy .

    This displays the WSDL in XML format.

  2. Copy the URL http://localhost:8080/DynWebTest1/services/BookLegacy?wsdl from the field at the top of the browser.
  3. Click Run > Launch the Web Services Explorer.

    This opens the Web Services Explorer view.

  4. In the top-right of the Web Service Explorer page, click WSDL Page icon  .
    Note: You need to click the Refresh icon  if the operation or action is not displayed first time.

    This displays WSDL Main in the Navigator pane of the Web Service Explorer.

  5. Click WSDL Main.

    This displays Open WSDL in the Actions pane of the Web Service Explorer.

  6. Paste the copied URL into the WSDL URL field, and then click Go.

    This displays the WSDL Binding Details, which includes a list of all the operations and endpoints.

  7. In the Name column, click readBook.

    This displays Invoke a WSDL Operation in the Actions pane.

  8. In the stockNo field, type 1111, and then click Go.
  9. The results are displayed in the Status pane of the Web Service Explorer.
  10. Clicking on addBook brings up a form to enter the details for a new book. You can see how the Explorer has used the WSDL to generate a form for this operation.
  11. 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
  12. The book details should be returned in the Status pane.
  13. Try the other operations in the Navigator pane.
Note: In the Status pane there is a Source link to view the SOAP Request and Response Envelopes. The XML displayed which is sent via HTTP POST and received back from the server.

Debug the Web service

The web service can be debugged in both the Java and COBOL programs:

  1. Stop the JBoss Server.
    1. Click the Servers tab.
    2. Right-click Red Hat JBoss EAP 7.1, and then click Stop.
  2. Set some breakpoints:
    1. 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.
    2. In the COBOLBook project set a break point in the do-read-record section of BookLegacy.cbl.
  3. Right-click on the DynWebTest1 project and select Debug As > Debug on Server.

    This opens a Debug On Server dialog box.

  4. Click Finish.
  5. Click Run > Launch the Web Services Explorer.
  6. Click on readBook. This brings up an Invoke a WSDL Operation page.
  7. Type 1111 into the stockNo field and click Go. The Eclipse Debugger should now stop in the readBook() method in BookLegacySkeleton.java.
  8. Open the Variables view from Window > Show View > Variables. As debugging proceeds through the applications current variables are displayed.
  9. Press F8 (Resume) to continue to the next breakpoint. Eclipse shows a "Source not found" message with an Edit Source Path button.
  10. Click on Edit Source Path bringing up the Edit Source Lookup Path dialog box.
  11. Select Add.
  12. Select COBOL Project then OK.
  13. Click Select All then click OK, then OK a second time to close the dialog box.

    Now the COBOL source code for BookLegacy.cbl is displayed.

  14. Use F5 to step through the application to investigate further.
  15. Press F8 to complete the operation and show the results in the Status pane of the Web Services Explorer.
  16. Use the Navigator pane in the Web Service Explorer to try other operations.
Attachments

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.
Version history
Revision #:
1 of 1
Last update:
‎2018-10-15 06:36
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.