Chapter 3: Deploying Interfaces

This chapter describes how to deploy service interfaces from a .car file for use in a production environment and how to deploy EJBs and resource adapters for EJB service interfaces.

Service Interfaces

Before you can run a service interface that has been generated using the Interface Mapping Toolkit, it needs to be deployed to an enterprise server. The service interface comprises the mapping information and might include the COBOL program and any required data.

During development the developer usually deploys the interface automatically using the Deploy tool in the Interface Mapping Toolkit. Once it is ready for use in a production environment however, you should deploy it using the .car file that was produced when the Deploy tool was run for the last time.

There are two methods of deploying the .car file:

• Using the mfdepinst command
• Using a manual process

Deploying Using the mfdepinst Command

The mfdepinst command handles the server-side part of the process of deploying a service to enterprise server. The tool installs the services contained in a .car onto the enterprise server. It is the equivalent of unpacking the .car file manually and adding the files using Enterprise Server Administration as described in the section Deploying the .car File Manually.

The mfdepinst command extracts the files (.int .idt and so on) from the .car file, updates the Directory Service directory for the new services and packages, and if the enterprise server is running tells it about the new services so they're available for use.

For full details see the topic mfdepinst.

Deploying the .car File Manually

You can also deploy manually, by unpacking the files in the COBOL archive file .car for your service and adding these to enterprise server, using Enterprise Server Administration. The .car file is created when the Deploy tool is used.

The .car file is in your deployment folder myservice\Repos\ myservice.deploy. The significant files in the COBOL archive are:

• The interface definition table (IDT). For example myservice.idt.
• The implementation package. For example myprogram.int and myprogram.idy
• The data required. For example mydata.idx and mydata.dat
• The manifest file manifest.mf, which controls the deployment process.

To deploy the service interface manually, you use Enterprise Server Administration to:

1. Add the implementation package. Among other things, you specify the path and name of the IDT, the executable file and the data files.
2. Add the service. Among other things, you specify the listener to use on this service, and the implementation package that is to provide the service functionality.

How to

EJBs and Resource Adapters

An EJB running a COBOL service runs in two places: the COBOL service runs under an enterprise server, and the EJB and client run under a third party J2EE application server, such as WebSphere or WebLogic.

You deploy the COBOL service from the .car file (or, if you are a developer, by using the Deploy tool in the Interface Mapping Toolkit). See the section Service Interfaces.

You deploy the EJB and client by deploying the following to a J2EE application server:

• The enterprise archive file myservice.ear. This file is created automatically when you generate a Java client. The file contains the:
  • EJB archive file myservice.jar. This file is created when you generate a client and also when you use the Deploy tool to deploy the service interface.
  • Client archive file myservice.war. This file is created when you generate a client.

  If you haven't generated an .ear file, but have only the .jar file, you might be able to deploy the .jar file instead. Your J2EE application might require you to package the .jar file into an .ear before deploying it, or you might find it simpler to do that.

• One of the supplied resource adapters, mfcobol*.rar. A resource adapter enables the EJB to communicate through its J2EE application server with an enterprise server. Resource adapters are also known as J2EE connectors and they are packaged in resource archive (.rar) files.

Many J2EE application servers are supported, such as BEA WebLogic and IBM WebSphere. Each application server has different deployment requirements and different utilities to help. For details of the supported application servers see Third Party Software.

You can bypass the J2EE application server in two ways, by:

• Generating a Java bean that accesses the COBOL enterprise server directly, without using a resource adapter. Although this avoids the overhead of administering a J2EE application server, you lose its advantages such as transaction support. For more information see the section Using an Unmanaged Connection under J2SE in the chapter Mapping a Java Interface and Using Resource Adapters in your Java and COBOL book, which is supplied with your COBOL development system.
• Writing your own code to call the resource adapter and send the request to an enterprise server. In this case, the connection is unmanaged. Your code runs in a Java 2 Standard Edition (J2SE) environment with the libraries from the J2EE server, rather than under a J2EE application server. For more information see the section Using an Unmanaged Connection under J2SE in the chapter Mapping a Java Interface and Using Resource Adapters in your Java and COBOL book, which is supplied with your COBOL development system.

Resource Adapters

The Micro Focus resource adapters enable EJBs deployed on J2EE to communicate with COBOL on an enterprise server. Resource adapters are also known loosely as J2EE connectors.

Before an EJB can communicate with the COBOL code running on Micro Focus Server, you need to:

• Deploy a resource adapter to the J2EE application server. Only one resource adapter can be deployed at a time. This resource adapter then handles all the binary requests being sent to the enterprise server.

  You must deploy a resource adapter appropriate to your application server and the J2EE version it uses. The following resource adapters are supplied for each supported application server and J2EE version:

  • mfcobol-notx.rar - does not support transactions
  • mfcobol-localtx.rar - supports local transactions
  • mfcobol-xa.rar - supports XA transactions

  How to

• Ensure that support for the resource adapter is available, by adding the archive files mfcobolpure.jar and mfconnector.jar to your classpath environment variable. Again, you must add support for the resource adapter appropriate to your application server and the J2EE version it uses.

  How to

The information needed to deploy the resource adapters is set up in deployment descriptors. Different deployment descriptors are supplied for each application server. You can view the deployment descriptors in a text editor. For example, the deployment descriptor weblogic-ra.xml, which is in the archive file mfcobol-notx.rar, contains the following lines:

<connection-factory-name>CCIMFCobol_xxx</connection-factory-name>
<jndi-name>eis/MFCobol_xxx</jndi-name>

Where xxx is 1.0 for j2ee13 and 1.5 for j2ee14.

Deployment Descriptors

Deployment descriptors are xml files that describe the component to be deployed. J2EE application servers require deployment descriptors for the archive files (.jar, .war and .ear) to be deployed. At run time, the application server reads the descriptors and acts accordingly.

When you generate an EJB or client, generic deployment descriptors are created and packaged into the relevant archive files. Some J2EE application servers require additional deployment descriptors and these are generated automatically for the supported application servers.

For more information see the section Deployment Descriptors in the chapter Mapping a Java Interface and Using Resource Adapters in your Java and COBOL book, which is supplied with your COBOL development system.

CustomRecord and the RuntimeProperties Support

Support for the CustomRecord and the RuntimeProperties interfaces is provided in mfejblib.jar for EJBs and in mfj2se.jar for J2SE Java beans.

For J2SE Java beans, you need to make sure that the mfj2se.jar is available to the Java run-time system and is on the Java classpath.

For EJBs, this support is automatically included in the application .ear file when you generate a client for the EJB. If you create a client manually, you need to add the mfejblib.jar to your .ear file, manually. Specific versions of this file are supplied for each supported application server and J2EE version.

How to

Deploying EJBs

Deploying EJBs involves configuring them in the third party application server on the J2EE machine, so that the EJBs, resource adapter and Enterprise Server can locate each other.

When you deploy an EJB you use the interface for your third-party application server. Many application servers provide a Web-based interface, such as the WebLogic Server Console, which takes you step by step through the deployment process. Most third-party application servers require the EJB to be packaged in an application .ear file, together with the client and all the necesssary deployment descriptors and other files. This .ear file is generated automatically when you generate a client using the Interface Mapping Toolkit.

If you don't have an application .ear file, you can often use your application server's administration interface to create one, or you can use the jar command.

How to ...

Third Party Application Server Deployment

Several third party application servers are supported for use during development and in production. For example WebSphere and WebLogic. For details of the supported application servers see Third Party Software.

Most third party application servers come with a Web-based administration console, which you use to deploy EJB and resource adapters. These take you step by step through deployment and provide information online.

How to

When you have changed the modules deployed on the server, we recommend that you stop and restart the server.

Troubleshooting

If your deployed EJB does not work, check the following things:

• Have you stopped and restarted the application server? Sometimes this is required to pick up changes to deployments and configuration. Whenever you reboot the WebLogic machine, you also need to restart the WebLogic server from the Start menu.
• Is the enterprise server you require running?
• Are the required services deployed to the enterprise server? Were they deployed successfully? You can check this by looking in the Enterprise Server Administration console, http://locahost:86, in deploy\...\deploylog.txt and also in workarea\myes\console.log, in the installation directory of your COBOL development system where myes is your enterprise server name, such as ESDEMO.
• Was any information written to the resource adapter log file cobcon.log? This log file is located in the directory defined in your Java system's user.home property. This directory equates by default to your user profile directory. If there wasn't any information written to the log file, the failure occurred before the resource adapter was invoked. The failure might lie in the application server setup. Notice that there are backup log files cobcon1.log and cobcon2.log.
• Was any information written to the communications server log file log.html? See the section Communications Server Log Files in the Troubleshooting chapter.
• When you generated your EJB using the Deploy tool, did you use the J2EE connector classes specific to your application server? For example, you must use WebLogic.jar for WebLogic EJB generation and j2ee.jar for WebSphere EJB generation. You specify these classes in the Classpath settings of the Deploy tool.
• Is the JNDI name of the resource adapter set to eis/MFCobol_v1.0? Is this JNDI name mapped to the resource references of the EJB.
• Is the JNDI name for each EJB the same wherever it is referred to? When you assign a JNDI name to an EJB, any client or other software that uses that EJB must use that same JNDI name.
• Are the EJB and the resource adapter successfully deployed in your application server?
• What failures are recorded in your application server's log files? All the supported application servers have a logs subdirectory.

Copyright © 2008 Micro Focus (IP) Ltd. All rights reserved.