Invoking a Java EE application from a CICS program

You can invoke a Java™ EE application running in a Liberty JVM server either as the initial program of a CICS® transaction or by using the LINK, START, or START CHANNEL commands from any CICS program.

To be linked to by a CICS program, the Java EE application is required to be a plain Java object (POJO) packaged in a Web ARchive (WAR) or Enterprise Application Archive (EAR). You cannot link to an EJB, a CDI bean, or an OSGi application. Dependency injection in the POJO is not supported, including injecting EJBs using @EJB. Instead, you can use a JNDI lookup to obtain a reference to a resource such as an EJB. This information applies to CICS integrated-mode Liberty only.

There are three main reasons why you would want to invoke a Java EE application from a CICS program:
  • Java code is part of an existing web application and you want to link it to a CICS application. You only need to maintain a single piece of logic and your code can access CICS resources by using JCICS APIs.
  • You want to write a new piece of function in Java as part of your CICS application. For example, you want to use third party libraries or APIs that already exist in Java.
  • You want to re-implement existing COBOL applications in Java. For example, you might want to reduce the cost of maintenance and make the most of your Java skills, or you might want your applications to be eligible to run on specialty engines rather than general processors.

When you link to a Java EE application from a CICS program, CICS sends a message to a JCA resource adapter running inside Liberty. The JCA resource adapter links to the target Java EE application on the same CICS task as the calling program. The Java EE application runs under the same unit-of-work (UOW) as the calling program, so any updates made to recoverable CICS resources are committed or backed out when the transaction ends. However, when the Java EE application is invoked, there is no JTA transaction context. If the application starts a JTA transaction, a syncpoint is performed to commit the CICS UOW, and create a new one. This also occurs if a JTA transaction is started by the container on behalf of the application, for example if the application calls an EJB with the REQUIRED transaction attribute.

As best-practice, the code that is linked by the CICS program should be part of your application's business logic (rather than presentation logic). For example, it would not make sense to link a servlet from a CICS program because there is no HTTP request involved.

Configuring a Liberty JVM server to invoke Java EE applications from CICS programs

To configure your Liberty JVM server to support invoking Java EE applications, add the cicsts:link-1.0 feature to server.xml. Ensure that you add the feature before deploying the Java EE applications.

Security

When you link a Java EE application to a CICS program, the user ID of the CICS task is passed into the Java EE application. Liberty does not authenticate the user, but trusts the identity tha t is passed in by CICS. However, Liberty does check that the user ID is present in the configured user registry. Where possible, use the SAF registry in Liberty because it checks the user ID passed in from CICS. If you are using another type of user registry other than the SAF registry, and the same user ID is present in the registry, then that user ID will be passed to the Java EE application. If the user ID is not present in the user registry, the Java EE application is linked with the unauthenticated user ID.

To configure security when you are linking a Java EE application, include the cicsts:security-1.0 feature in your server.xml. If you do not include this feature, the Java EE application will be linked without being authenticated. As a result, any authorization checks in your Java EE applications might not apply. However, access to any CICS resources using the JCICS API will still run under the user ID of the CICS task.

The following web security mechanisms do not apply when you are invoking a Java EE application from a CICS program:

The Java EE application is able to perform additional authorization checks by calling an EJB and applying EJB security. For example, authorization can be applied to session bean methods using the @RolesAllowed annotation. For more information about EJB security, see The Java EE Tutorial.

For more information about security in Liberty, see Configuring security for a Liberty JVM server.