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.
- 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.
- Java EE web security mechanisms. For example:
<auth-constraint>
inweb.xml
or@HttpConstraint
on a servlet. - Trust Association Interceptors (TAIs).
- The JVM server profile property
com.ibm.cics.jvmserver.unclassified.userid
. - URIMAPs.
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.