Tutorial: Deploying JVM COBOL to an Application Server

It is possible to preserve your existing JVM COBOL business logic when deploying to an application server.

In order to build a multi-user application suited for an application server, you build your existing JVM COBOL code into the Enterprise JavaBeans (EJB) architecture (version 3.x or later).

A broad overview of the process is as follows:

  1. From a Java class that implements the EJB interface, you can call JVM COBOL business logic by wrapping it in a Micro Focus RunUnit class, which will provide the required multi-user environment.
  2. To ensure the JVM COBOL run-time system works correctly, each .jar file that is built into your packaged application must be deployed with a cobconfig.properties file with the contents:

    ejb=true

  3. Package this information into a deployable format, such as an enterprise archive file (.ear) or Web archive file (.war) and deploy it to your application server.

For a more detailed explanation of the process, using JBoss as the application server, see Tutorial: Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server.

In addition to the resources built into your deployed application, you must also consider how you are going to deploy the JVM COBOL run-time system.

 

Run-time Considerations

When choosing how to deploy the JVM COBOL run-time system that is required by JVM application code, consider the deployment options illustrated in this diagram:

 

Shared Runtime Deployment Style

     Deploy the run-time system separately, as a shared module or object in your application server.

Per Bean Runtime Deployment Style

     Package the run-time system in a deployed archive file, such as an enterprise archive file (.ear) or web archive file (.war).

Each Runtime Deployment Style has its advantages:

Shared Per Bean
  • Uses less memory, because the run-time file (mfcobolrts.jar) is shared by all applications.
  • Tracing can be performed centrally.
  • For application servers that provide versioning, you can deploy multiple versions of the run-time system.
  •  Administrative rights are not required to configure the application server.
  • For application servers that do not provide versioning, you can deploy different applications that use different run-time systems.
  • Remote deployment is easier as all required resources are self-contained.

 In this tutorial, you deploy your JVM COBOL runtime using the Per Bean Runtime Deployment Style, meaning that the runtime is packaged as an archive file and deployed with the application.

Restrictions

When using a class that implements the EJB specification to run your JVM COBOL code, the following are not currently supported:

  • COBOL file handling (including ACUCOBOL-GT file handling and Fileshare)
  • COBOL database handling
  • Threading syntax, such as START and WAIT, and the CBL_THREAD library routines
  • The PC_PRINTER library routines
  • CALLing native COBOL library routines or OS-native APIs
  • The STATIC keyword for class members
  • Enhanced ACCEPT/DISPLAY statements

Install and Configure an Application Server

If you decide to deploy the JVM COBOL run-time system as part of your application server, you need to add it to the application server, and then add an application configuration file to one or more projects in your application.

Configuring JBoss

To install the JVM COBOL run-time system (mfcobolrts.jar) in JBoss or later, you must configure it as a module of the application server.
  1. Set the environment variable JBOSS_HOME to point to the JBoss EAP 6.4 installation location, for example: %Program Files%\JBoss\jboss-version (Windows) or /usr/jboss/jboss-version (UNIX).
  2. Create the following folder structure: JBOSS_HOME\modules\system\layers\base\com\microfocus\cobol\runtime\main (Windows) or JBOSS_HOME/modules/system/layers/base/com/microfocus/cobol/runtime/main (UNIX).
  3. Copy mfcobolrts.jar from the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\bin (Windows) or $COBDIR/bin (UNIX) folder to the main folder created in the previous step.
  4. In the main folder, create a new file called module.xml, and add the following to it:
    <module xmlns="urn:jboss:module:1.1" name="com.microfocus.cobol.runtime">
        <dependencies>
            <module name="javaee.api"/>
        </dependencies>
        <resources>
            <resource-root path="mfcobolrts.jar"/>
        </resources>
    </module>

    The main folder should contain the following files:

    • mfcobolrts.jar
    • module.xml

Configuring WebLogic

Note:

  • These details only explain how to enable use of the JVM COBOL run-time system with WebLogic; any other WebLogic configuration is out of the scope of this topic.
  • The manifest file (manifest.mf) in mfcobolrts.jar already contains the information required to be recognized as a shared library in WebLogic.

To install the JVM COBOL run-time system (mfcobolrts.jar) in WebLogic 12.1.1 or later, you can add it as a shared library from the weblogic.Deployer command line utility.

To install the run-time system from the command line

Note: The weblogic.Deployer utility only registers the JVM COBOL run-time system with the application server; it does not copy it to the server's directory structure.

  • Ensure the application server is running.
  • To set up your environment for the command line tool, run the setWLSEnv.cmd (Windows) or setWSLEnv.sh (UNIX) script, located in the server\bin (Windows) or server/bin (UNIX) sub-directory of the WebLogic server installation directory.
  • Copy mfcobolrts.jar from %COBDIR%\bin (Windows) or $COBDIR/bin (UNIX) to a new location.
  • Enter the following command:
    java weblogic.Deployer -adminurl t3://localhost:7001 -username USER_NAME 
                           -password PASSWORD -deploy -library PATH\mfcobolrts.jar

    Replace USER_NAME and PASSWORD with details supplied by the administrator of the application server. Replace PATH with the path that you used in the previous step.

Configure the application configuration file

In Eclipse, in the project that will be deployed, in the META-INF directory, add a weblogic-application.xml file that contains the following code - 2.3 is the version of Enterprise Developer:

<weblogic-application
xmlns="http://xmlns.oracle.com/weblogic/weblogic-application"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
  <library-ref>
    <library-name>mfcobolrts</library-name>
    <specification-version>2.3</specification-version>
    <implementation-version>2.3</implementation-version>
    <exact-match>false</exact-match>
  </library-ref>
</weblogic-application>

Note: 2.3 in this file is the version of Enterprise Developer. If you bind your application to a newer version of the COBOL run-time system than was supplied in a more recent version of Enterprise Developer, that must be reflected in the specification-version and implementation-version settings.

To uninstall the run-time system from the command line

  1. Ensure the application server is running.
  2. Enter the following command:
    java weblogic.Deployer -adminurl t3://localhost:7001 -username USER_NAME 
                           -password PASSWORD -undeploy  -name mfcobolrts

Replace USER_NAME and PASSWORD with details supplied by the administrator of the application server.

Deploying an Enterprise JavaBean Containing JVM COBOL to a JBoss Application Server

The following tutorial guides you through deploying a dynamic web project that implements the EJB 3.0 specification, and that has JVM COBOL business logic at its heart, to a JBoss application server.

Tutorial Prerequisites

This tutorial guides you through three projects that have been configured to work together to form one deployed application. For that reason, a lot of the tutorial steps are highlighting pertinent actions that have already been performed.

However, to complete this tutorial, a certain degree of experience is still required in a number of areas.

Firstly, some project configuration may be required outside of these steps, because the projects were configured to work in a certain Java environment (using JRE 1.8, installed with Enterprise Developer by default). Where your environment differs (for example, you use a different Java run-time version), you may be required to reconfigure project settings to suit your environment.

Also, familiarity with the EJB specifications, REST services, and other Java EE APIs may be required to fully understand the configurations.

Before you start the tutorial, ensure you have the following prerequisites installed and/or configured:

  • Java 8
  • JBoss EAP 6.4 application server - this tutorial assumes that the application server is already correctly configured, running in standalone mode.
  • The Eclipse JBoss Tools plugin - this can be installed as part of the tutorial, as detailed in Creating the Workspace.
  • The Eclipse plugin WTP 3.3.2 or later - this is included as part of Enterprise Developer.
  • If you are deploying the JVM COBOL run-time system as a standalone module, configure the application server; refer to Configuring JBoss for more information.

Copying the Tutorial Files

The source files required to run the tutorial are attached to this sample.

Note: To download the files, you do not need to be a registered user of the Community web site, but to post comments or questions about the tutorial, on the forum, you will need to register and join the Visual COBOL group.
  1. Create a folder on your machine in which you will copy the tutorial files attached to this sample (EJBDemo.zip).
  2. Save the file, and then extract the contents of the .zip file to the folder that you created earlier.

    The folder now includes the folders for the following projects:

    • TemperatureConverter - The JVM COBOL project containing the business logic of the application.
    • TemperatureConverterEJB - The EJB implementation that uses the RunUnit specification to wrap around the JVM COBOL code.
    • TemperatureConverterPrj - The dynamic web project that packages the other two projects in a .war file, and is deployed to the application server.

Creating the Workspace

You need to create and configure an Eclipse workspace capable of interacting with the JBoss application server when you are running or debugging the application.

  1. Launch Enterprise Developer for Eclipse.
  2. When prompted for a workspace, specify the path to the folder that you extracted the source files to.
  3. If you are presented with the Welcome page, click Open Team Developer Perspective.

    This loads a set of views within the IDE that are associated with COBOL and PL/I development. The Project Explorer shows that the workspace is empty as you have not yet imported the projects into Eclipse.

  4. If you have not already installed the JBoss tools plugin:
    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.

  5. Once you have downloaded the JBoss tools plugin you need to add the server runtime environment:
    1. Click Window > Preferences > Server > Runtime Environments.
    2. Click Add.
      This opens the New Server Runtime Environment dialog box.
    3. Expand Red Hat JBoss Middleware, and then click Red Hat JBoss Enterprise Application Platform 7.1 Runtime.
    4. Click Next.
      This opens the New Server Runtime Environment dialog box.
    5. Next to the Home Directory field, click Browse, and then select the folder containing JBoss EAP.
    6. Click OK.
    7. Ensure that you are using a Java 8 JRE runtime.
    8. Click Finish.
    9. Click Apply and Close.

Importing the Project Files

  1. Ensure Eclipse is open in the workspace that you created in the previous step.
  2. On the File menu, choose Import.

    The Import dialog box appears.

  3. Choose General > Existing Projects into Workspace, then click Next.
  4. On the Import Projects pane, click Browse to the right of Select root directory and choose the directory in which you extracted the projects:
  5. Ensure all three projects are selected, then click Finish.

    The workspace now contains the three projects.

    If Eclipse is set to build projects automatically, the three projects build successfully.

  6. Click the Project Explorer view to see all three projects:

Stepping through the Projects

The following projects combine to produce an Enterprise JavaBean with JVM COBOL business logic at the heart of it, deployable to a Java Enterprise application server.

The COBOL Project - TemperatureConverter

The JVM COBOL project that contains the business logic for the application.

The following steps introduce you to the features that enable you to deploy this project alongside the other two projects.

 

  1. In the Project Explorer pane, navigate to TemperatureConverter > COBOL Sources > src > com > microfocus > converter and double-click TemperatureConverter.cbl.

    The JVM COBOL program appears.

  2. Open the Outline pane to show the two methods. Click each entry to jump to the code in the editor.

    The toCelsius and toFahrenheit methods both contain the conversion algorithms, accepting and returning primitive data types compatible with Java.

  3. In the Project Explorer pane, navigate to TemperatureConverter > resource and double-click cobconfig.properties.

    This file is required to ensure the JVM COBOL run-time system works correctly in the EJB environment; each .jar file that is packaged into the deployed .war file requires one of these files. If one does not exist, use the File > New > File options to add a new resource file.

  4. You must ensure that the resource file cobconfig.properties is deployed as part of the project:
    1. Right-click TemperatureConverter then choose Properties.
    2. Choose Deployment Assembly.

      The cobconfig.properties file is in the resource directory, and so is set to be included in the assembly when it is deployed.

    3. Click Cancel to close the Properties page.

The EJB Project - TemperatureConverterEJB

The Java EJB project that contains a stateless EJB 3.0 Java class. It uses the RunUnit class to wrap around the JVM COBOL code.

The following steps introduce you to the features that enable you to deploy this project alongside the other two projects.

  1. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic and double-click TemperatureConverterBean.java.

    This opens the Java class in an editor.

    This is the EJB class, as denoted by the @Stateless annotation. It imports the com.microfocus.cobol.runtimeservices API, which provides the Micro Focus RunUnit class. The following code shows a TemperatureConverter instance being wrapped in a RunUnit. Each instantiated RunUnit contains its own resources that enable it to run independent of other RunUnit instances, thus enabling the application to provide a multi-user environment.

    import com.microfocus.cobol.runtimeservices.*;
    ...
    private TemperatureConverter createTemperatureConverter()
     {
      rununit = new RunUnit();
      TemperatureConverter tempConverter = new TemperatureConverter();
      rununit.Add(tempConverter);
      return tempConverter;
     }

    The RunUnit syntax includes a try...finally block containing a call to the StopRun method, ensuring that the resources used by the JVM COBOL are freed up when required, even in the event of an exception.

    ...
    TemperatureConverter temperatureConverter = createTemperatureConverter();		
     try
     {			
    	 c  = temperatureConverter.toCelsius(f);
     }
     finally
     {		
      rununit.StopRun();
     }
    ...
  2. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.business and double-click ITemperatureConverter.java.

    The interface implemented by the previous class appears.

    The interface imports the JAX-WS-RS API to create a RESTful application. This can be seen by the annotations (@GET, @Path, @Produces) used throughout the TemperatureConverterBean class. For example, the following toCelsius method uses the annotations to configure how the request is handled:

    The annotations help to build the URL that forms the request in the deployed application. The return phrase indicates that the response to the client will be returned in JSON format using a simple Temperature class.

  3. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic and double-click Temperature.java.

    The class is annotated with @XmlRootElement (name = "Temperature" ), which allows the build() API to use reflection on the class to build up the JSON output based on the fields and their values. The build() method then adds the appropriate header information to pass back to the client.

  4. In the Project Explorer pane, navigate to TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic and double-click TemperatureConverterApp.java.

    This is the wrapper class that enables the EJB to be deployed to the application server.

    @ApplicationPath("/")
    public class TemperatureConverterApp extends javax.ws.rs.core.Application {
    @Override
     public Set<Class<?>> getClasses(){
      Set<Class<?>> s = new HashSet<Class<?>>();
      s.add(TemperatureConverterBean.class);
      return s;
     }
    }
    By extending the JAX-WS-RS API this time, it uses the getClasses() method to register the TemperatureConverterBean EJB class with the application server, as a REST Web service.
  5. In the Project Explorer pane, navigate to TemperatureConverterEJB > resource.

    As with the JVM COBOL project, this project contains a cobconfig.properties file configured in the same way. If one does not exist, use the File > New > File options to add a new resource file.

  6. You must ensure that cobconfig.properties is deployed as part of the project:
    1. Right-click TemperatureConverterEJB, then choose Properties.
    2. Choose Deployment Assembly.

      The cobconfig.properties file is in the resource directory, and so is set to be included in the assembly when it is deployed.

    3. Click Cancel to close the Properties page.

The Dynamic Web Project - TemperatureConverterPrj

The Dynamic Web project that packages up the other two projects into a Web application archive (.war file), which is then deployed to the application server.

  1. In the Project Explorer pane, navigate to TemperatureConverterPrj.
  2. If you are not deploying the JVM COBOL run-time system as part of the application (that is, the application uses the shared run-time system in the application server), in the Project Explorer pane, navigate to TemperatureConverterPrj > WebContent > META-INF and double-click MANIFEST.MF.

    The project manifest file appears:

    Manifest-Version: 1.0
    Dependencies: com.microfocus.cobol.runtime
    Class-Path:

    Note: If you are including the JVM Runtime System as part of your .war file then this dependency is not needed in the MANIFEST.MF file.

    If the Dependencies entry is not set as shown above, you must add it.

    Note: Ensure the order of the properties is as shown here.

  3. Ensure that the MANIFEST.MF file, and the two other projects are deployed as part of this project, and to the correct paths:
    1. Right-click TemperatureConverterPrj, then choose Properties.
    2. Choose Deployment Assembly.

      The MANIFEST.MF file is in the WebContent directory, and so is set to be included in the assembly when it is deployed.

    3. Click Cancel to close the Properties page.

Deploying the JVM COBOL Run-time System within the Application

In this tutorial, you are deploying the run-time system on a per-bean basis. Therefore, you must deploy it from within the dynamic Web project. 

Note: Outside of this tutorial, if you are deploying the JVM COBOL run-time system (mfcobolrts.jar) as a shared module in the application server, you do not need to perform these steps.

  1. To ensure that the application does not attempt to locate the run-time system on the application server:
      1. In the Project Explorer pane, navigate to TemperatureConverterPrj > WebContent > META-INF, then double-click MANIFEST.MF.

        The manifest file for the application appears.

    1. If present, delete the line that starts Dependencies:, then save the file.
  2. Add the run-time system to the project:
    1. Right-click TemperatureConverterPrj then choose Properties.

      The Properties for TemperatureConverterPrj dialog box appears.

    2. Click Java Build Path.
    3. On the Libraries tab, click Add Library.

      The Add Library dialog box appears.

    4. Choose COBOL JVM Runtime System, click Next, then click Finish.
    5. Click OK to save the changes.
  3. Set the run-time system to be deployed with the application:
    1. In the Properties for TemperatureConverterPrj dialog box, click Deployment Assembly.

      The Web Deployment Assembly pane appears.

    2. Click Add.

      The New Assembly Directive dialog box appears.

    3. Click Java Build Path Entries, then click Next.
    4. Click COBOL JVM Runtime System, then click Finish.

      The JVM COBOL Runtime System will be deployed with the Web application.

    5. Click OK to save the changes and close the Properties page.

Deploying the Application

  1. In the Project Explorer pane, right-click TemperatureConverterPrj, then choose Run As > Run on server.

    This opens the Run On Server dialog box.

  2. Click Red Hat JBoss EAP 7.1.
  3. Click Finish.

    The application server is started and the application is deployed. Details of these steps are relayed to the Console pane.

    If publishing on the server fails, check to ensure the server is using the JBoss EAP 7.1 runtime:

    1. In the Servers view, double-click Red Hat JBoss EAP 7.1.

      This opens the server's overview page.

    2. Look in the General Information section on the server page and ensure that the Runtime Environment field is set to JBoss EAP 7.x Runtime.
    3. Save your changes then repeat from Step 1.

    Note: Depending on your default browser, you may receive an HTTP 404 error; this is because the application does not contain a user interface, and so has no screen to display on startup. You can ignore this error and proceed with running the application.

Showing the Server Status

  1. On the Window menu, click Show View > Other.

    The Show View dialog box appears.

  2. Choose Server > Servers, then click OK.

    The Servers view appears showing the JBoss server and it status:

  3. To display server details, double-click the server entry.

    Details for the server appear in the main pane.

Running the Application

Eclipse has a built-in browser window that opens when the server is started, but you can use any external browser to enter the URLs.

In your browser, enter the following URLs:

  • To run the Fahrenheit (212°F) to Celsius conversion, enter:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getCelsius?fahrenheit=212
  • To run the Celsius (36.8°C) to Fahrenheit conversion, enter:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getFahrenheit?celsius=36.8

Depending on your browser, the results are either returned in the browser or you are prompted to save the results to a text file.

Debugging the Application

You can debug both the JVM COBOL and Java code in the same process.

  • Set a breakpoint in the JVM COBOL code:
    1. In the Project Explorer, choose TemperatureConverter > src > com.microfocus.converter > TemperatureConverter.cbl.

      The JVM COBOL business logic appears in the main pane.

    2. Double-click the marker bar to the left of the compute statement in the toCelsius method.

      The breakpoint is set.

  • Set a breakpoint in the Java code:
    1. In the Project Explorer pane, choose TemperatureConverterEJB > ejbModule > com.microfocus.businesslogic > TemperatureConverterBean.java.

      The Java code appears in the main pane.

    2. Double-click the marker bar to the left of the c declaration in the toCelsius method.

      The breakpoint is set.

  • Right-click TemperatureConverterPrj, then choose Debug As > Debug on Server.

    This opens the Debug On Server dialog box.

  • Ensure that Red Hat JBoss EAP 7.1 is selected and click Finish.

    You receive a notification that the server is not running in debug mode.

  • Ensure Switch mode (will restart if necessary) is selected and click OK.

    The server is restarted in debug mode. A browser window is opened in the IDE, showing the following URL:

    http://localhost:8080/TemperatureConverterPrj/

    You can ignore the HTTP Status code message. EJB does not have a landing page and you need to enter the URL for the application manually.

  • In the browser window, load to the following URL:
    http://localhost:8080/TemperatureConverterPrj/RestApp1/getCelsius?fahrenheit=212
  • If you are prompted to switch to the Debug perspective, click Yes.

    The breakpoint is hit and execution breaks in the Java program. At this point, you can step through the program as normal.

  • Press F8 to resume execution.

    The compute breakpoint is hit and execution breaks in the JVM COBOL program.

    Note: If you get a Source not found message, perform the following steps:

    • Click Edit Source Lookup Path.

      This opens the Edit Source Lookup Path dialog box.

    • Click Add.
    • Click COBOL Project.
    • Click OK.

      This opens the Selection Needed dialog box.

    • Check the TemperatureConverter project.
    • Click OK.
    • Click OK.
  • Continue debugging, or press Ctrl+F2 to terminate. You can click COBOL in the right upper corner of the IDE to switch back to the Team Developer perspective.