Linking to a Java EE application from a CICS program

You can link to 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. The Java EE application is required to be a plain Java object (POJO) packaged in a Web ARchive (WAR) or Enterprise Application Archive (EAR). This topic applies to CICS integrated-mode Liberty only.

There are three main reasons why you would want to link to a Java EE application from a CICS program:
  • If you have some Java code as 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 using JCICS APIs.
  • If you want to write a new piece of function in Java as part of your CICS application. For example, if you want to use third party libraries or APIs that already exist in Java.
  • If you have existing COBOL applications, and you want to re-implement those applications in Java. For example, if you want to reduce the cost of maintenance and make the most of your Java skills, or, if you 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 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 will be committed or backed out when the transaction ends. The Java EE application is linked using the DPL subset of the CICS API and SYNCONRETURN is ignored. The Java EE application cannot use JTA if CICS JTA integration is enabled; however, other applications running within the same JVM server can still use JTA integration. When you use a Type 2 JDBC connection to DB2® , the Java EE application cannot call methods on the java.sql.Connection class to commit or rollback the updates. Instead, the application should return normally and the updates will be committed when the CICS transaction reaches the next syncpoint. To rollback the updates, the application should abend.

To be linked 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 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.

As best-practice, the code 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 as there is no HTTP request involved.

Configuring a Liberty JVM server to link Java EE applications to CICS programs

To configure your Liberty JVM server to support linking 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. If you remove the feature from server.xml, you must disable and re-enable the JVM server.

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 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 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 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 linking a Java EE application to 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.



link_2_liberty.html | Timestamp icon Last updated: Monday, 5 June 2017