Linking to a Java EE or Spring Boot application from a CICS program

You can link to a Java™ EE or Spring Boot 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, a Java EE application needs to be a plain Java object (POJO) packaged in a Web ARchive (WAR) or Enterprise Application Archive (EAR). A Spring Boot application can be packaged in a WAR or a JJava Archive (JAR). You cannot link directly 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. In a Spring Boot application, injection using an annotation such as @Autowired is fully supported.

There are three main reasons for linking to a Java 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 might want to use third-party libraries or APIs that already exist in Java.
  • You want to reimplement 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 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 application on the same CICS task as the calling program. The Java 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 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 must 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 no HTTP request is involved.

Configuring a Liberty JVM server to link from CICS programs to Java EE or Spring Boot applications

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

Security

When you link to a Java or Jakarta EE, or a Spring Boot application from a CICS program, the Java application runs under the same CICS security context as the calling task. This means that the user ID of the calling CICS task is used to authorize access to any resources accessed by using the JCICS API from the application. Web security authentication mechanisms such as <auth-constraint> rules in the web.xml do not apply in this situation.

In addition to the CICS task user ID, Liberty also creates a Java security Subject for the linked to application. This Subject can be used for Java security role authorization on called components such as EJB session beans by using the @RolesAllowed annotation. This Subject is set to the same user ID as the CICS task user ID when the cicsts:security-1.0 feature is present in your server.xml. Liberty does not authenticate the Subject user ID. Liberty checks that the user ID is present in the Liberty security registry, and then asserts the CICS task user ID as the Subject user ID. For more information, see The Java EE Tutorial.

If you exclude the cicsts:security-1.0 feature from your server.xml, the Java application is linked to with the Liberty unauthenticated user ID, which by default is WSGUEST.

If you are not using a SAF registry for the Liberty server, but the task user ID is present in the non-SAF Liberty registry, then the task user ID is still passed to the application. If the task user ID is not present in the non-SAF Liberty registry, the Java application is linked to with the Liberty unauthenticated user ID.

If your Liberty server requires that the cicsts:security-1.0 is configured for Web application security, but the linked to Java application does not perform Java security role authorization, setting the Java system property com.ibm.cics.jvmserver.wlp.security.subject.create=false is recommended. This improves performance by ensuring that the assertion of the CICS task user ID as the Java Subject is not attempted.

When you link to Spring Boot applications from a CICS program, the CICS user ID is not passed to Spring security by default. Spring Boot offers configuration and programmatic options to achieve this. For more information, see Spring Boot Java applications for CICS, Part 2: Security, and Configuring security for a Liberty JVM server.