Porting JEE applications to a CICS Liberty JVM server
This chapter describes considerations for porting existing Oracle Java Enterprise Edition (Java EE) and other existing Java applications to an IBM CICS Liberty profile Java virtual machine (JVM) server. It also explains considerations for developing Java applications that use features that are unique to a CICS Liberty JVM server and other Liberty features.
It includes the following topics:
4.1 Porting a Java application to a CICS Liberty JVM server
The features in a release of CICS Liberty JVM server are a subset of the features supported by the corresponding release of the Liberty profile that is provided in IBM WebSphere Application Server for z/OS. Existing JEE and other Java applications can be ported or migrated to a CICS Liberty JVM server if the applications use only features that are supported by the currently installed release level of the CICS Liberty JVM server.
The supported server features for a release are determined by which features have been verified by the CICS Transaction Server (CICS TS) development organization. For a list of the currently supported features, see the “Liberty features” web page:
Other enhancements may be available and should work in a CICS Liberty JVM server, with certain caveats or restrictions. For information about these enhancements, check the CICSdev Community blog on IBM developerWorks:
One example of such an enhancement is the addition of support for IBM WebSphere MQ messaging software, which is described in the article titled “Using the WebSphere MQ classes for Java with a CICS JVM server:”
 
Note: To determine which features are available in a particular instance of CICS Liberty JVM server, locate the product service signature string in the Liberty startup messages, such as this example:
product = CICS Transaction Server for z/OS 5.2.0, CICS Liberty JVM server NOTUSAGE, WebSphere Application Server 8.5.5.1, WAS FOR Z/OS 8.5.5.1 (wlp-1.0.4.cl50120140502-1451)
In this example, the features included with release 8.5.5.1 of the WebSphere Application Server for z/OS Liberty profile are available.
4.1.1 Which Java applications should be migrated to CICS TS
Not every Java application that meets the previously described criteria should be ported to CICS Liberty JVM server. Consider porting Java applications only when there is a logical reason or a need for the application to run in a CICS TS JVM server.
For example, a Java application should be migrated to CICS Liberty JVM server in these situations:
•If you have an Java application that interacts with a CICS TS application using CICS TS Transaction Gateway, CICS TS MQ Bridge, or a JEE Connector (J2C) connection factory. Consider moving this Java application to Liberty JVM server to take advantage of being colocated with the CICS TS application that is being accessed by the user interface.
•If you want to start using some of the features to Liberty JVM server in CICS. For example, the JDBC features that allow dynamic binding of a data source at run time or the feature that coordinates the commits or rolls back updates made to remote data sources (JDBC Type 4) in the same logical unit of work as other CICS TS managed resource.
•If you want to take advantage of using CICS bundles for your applications. Using bundles means that application artifacts can be packaged with the corresponding CICS TS resource definitions (that is, definitions for TRANSACTIONs, PROGRAMs, URIMAPs, and so on) so that both the application and its resource definitions can be managed or deployed as a single administrative entity.
Because CICS Liberty JVM server runs in a CICS TS JVM server, all of the inherent advantages provided to Java applications by the CICS JVM server are available to CICS Liberty JVM server applications. For example:
•Rather than having multiple JVMs running a CICS TS task, there is a single JVM in a JVM server that can spawn up to 256 threads, with each thread executing a CICS TS task. This provides vertical scaling as workload increases. A CICS Liberty JVM server can also be configured with only the features required by an application to execute. Eliminating the features not required in the server avoids loading unnecessary functions and reduces server startup time and storage use.
•Multiple JVM severs can coexist is a single CICS TS region, with each JVM server configured independently and running different applications. Each JVM server (CICS Liberty and non-Liberty), running different applications, can horizontally scale application workload within a CICS region. Currently, there can be only one CICS Liberty JVM server in a CICS region that interacts with a Liberty angel process, using IBM z/OS security features. For horizontal scaling of CICS Liberty applications that required z/OS security, the CICS Liberty JVM server needs to be replicated in another CICS region.
For more information about running Java in CICS TS JVM servers and the Open Service Gateway initiative (OSGi), download the white paper titled “Running Java workloads with JVM servers and OSGi:”
4.1.2 Using the OSGi framework
Another consideration for consolidating applications in CICS Liberty JVM server is to use the OSGi framework for deploying and administering Java applications. The framework restructures the components of an application as individual bundles of components or packages that are loosely coupled but constitute an application when combined. This contrasts with packaging solutions where all components are packaged and administered in a single Java archive (JAR) file that must be included in the class path. This separation of the application into bundles enables independent deployment and management of the different bundles that compose an application and, potentially, reuse of selected bundles by other applications.
This flexibility has key benefits:
•Different versions or levels of the same package can coexist in CICS Liberty JVM server concurrently.
•Because the Java class path is not used to load the Java classes, changes can be implemented without the need to stop and restart the JVM.
There are various development tools available (such as CICS TS Explorer or Eclipse integrated development environment [IDE] tools, such as Luna or Kepler) to aid in refactoring existing Java artifacts, such as JARs, into OSGi bundles for deployment to bundle repositories and packaging applications into CICS TS bundles for deployment to a CICS Liberty JVM server run time.
For more information about OSGi packaging in CICS Liberty JVM server, see “The OSGi Service Platform” in the IBM Knowledge Center:
For more information about Liberty application development in general and to download Eclipse and Liberty development plug-ins, go to the following web pages:
or
To download the CICS Explorer system management tool, start at this web page:
 
 
Note: Both Eclipse tools and CICS Explorer work with common source code management products, such as IBM Rational® Team Concert.
4.2 Developing new application using JCICS classes
CICS TS provides Java interfaces to most of the same standard CICS TS application programmer interfaces (APIs) that are in traditional CICS TS application programs. New Java applications can be developed or existing Java applications can be modified to access almost the full set of CICS TS APIs. Use of these APIs gives Java applications running in a CICS TS JVM server full access to VSAM files, the ability to link to COBOL and other CICS application programs passing common data areas and containers, the ability to access transient data and temporary storage queues, and so on.
Example 4-1 and Example 4-2 are Java code that shows some the Java class library for CICS (JCICS) classes and methods that can be used in a CICS Liberty JVM server application.
Example 4-1 JCICS example of accessing a key sequenced VSAM file
// Instantiate an instance of a JCICS record holder
com.ibm.cics.server.RecordHolder record = new
com.ibm.cics.server.RecordHolder();
// Instantiate an key sequence VSAM file
com.ibm.cics.server.KSDS file = new com.ibm.cics.server.KSDS();
// Set the file name
file.setName("FILEA");
// Retrieve and delete a record in a Try/Catch block
try {
file.read(key.getBytes(),record);
file.delete(key.getBytes());
catch (Exception e) {
Example 4-2 JCICS examples of using channels and containers in linking to a CICS TS program
// Instantiate an instances of a JCICS channel and a JCICS container
Channel channel = task.createChannel("MINICICS-Channel");
Container requestContainer = channel.createContainer("MINICICS");
// Copy contents of the CICS commarea area to the JCICS request container
requestContainer.put(commarea.getByteBuffer());
// Invoke program and pass the channel with the request container
progName.link(channel);
// Retrieve the response container from the channel
Container responseContainer = channel.getContainer("MINICICS");
// Copy contents of the response container to the CICS commarea area
commarea = new com.ibm.ats.odm.COMMAREA(responseContainer.get());
 
CICS Explorer and Eclipse development tools can also be used to develop Java applications that use JCICS. Accessing CICS TS resources by using JCICS classes should be more understandable to Java programmers than the EXEC CICS equivalents used in other languages.
 
Note: Some JCICS classes and methods should not be used in CICS Liberty JVM server. For example, any API that deals with a terminal (that is, methods such clear, converse, erase, and so on) would not be used because these require a principle facility or terminal and there would be no terminal associated with a task running in CICS Liberty JVM server.
4.2.1 Java access to records and their fields
Eventually, most applications running in CICS TS need to work with a record and its fields when accessing a VSAM file, a DB2 database row, and so on. Most Java development on other platforms work with stream-oriented data rather than with record-oriented data as typical applications in CICS TS. Because of this, there are options for generating a Java class that represents the layout of records and the corresponding set and get methods for accessing the individual fields in the record. Example 4-3 shows use of set and get methods.
Example 4-3 Example of the using of get and set methods with a COMMAREA class
commarea.setName(request.getParameter("custName"));
commarea.setEffectdate(request.getParameter("effectDate"));
commarea.setAmount(Long.parseLong(request.getParameter("amount")));
commarea.setAge(Long.parseLong(request.getParameter("age")));
 
// Invoke a CICS COBOL program passing a common area
commarea = MiniCICS.invoke(commarea);
request.setAttribute("custName",commarea.getName());
request.setAttribute("age", commarea.getAge());
request.setAttribute("amount", commarea.getAmount());
request.setAttribute("effectDate", commarea.getEffectdate());
The subsections that follow describe some of the options for generating Java classes from record-oriented layouts.
Rational Application Developer J2C wizard
In IBM Rational Application Developer, the Java EE Connectors feature has a J2C component that includes a wizard that generates a Java data bean with get and set methods. These methods can be used to access individual fields within a record. Supported languages include COBOL, C, and PL/I (see Figure 4-1).
Figure 4-1 Rational Application Developer J2C wizard
The Java methods generated by the wizard include support for code page conversion and conversion between Big and Little Endian data types (Figure 4-2).
Figure 4-2 Rational Application Developer J2C wizard import options
Record Class Generator utility
Another option for generating a Java class with get and set methods for fields from an existing record layout is the JZOS Assembler and COBOL Record Generator utility that is part of the IBM experimental JZOS batch toolkit for z/OS SDKs (see Example 4-4). This utility runs on z/OS and can be used to generate Java classes from COBOL copybooks and Assembler DSECTs.
Example 4-4 Snippet of JCL executing the RecordClassGenerator utility
//* Generate a .java file for each copybook
//JAVA EXEC PROC=EXJZOSVM,VERSION='50'
//MAINARGS DD *
com.ibm.jzos.recordgen.cobol.RecordClassGenerator
bufoffset=false
package=com.ibm.ats.cobol.records
outputDir=~/cobgen
//SYSADATA DD DSN=&&ADATA,DISP=(OLD,DELETE)
For more information, see the “IBM Experimental Version of the JZOS Batch Toolkit and a Cookbook for z/OS SDKs” page in the IBM developerWorks Communities section:
Note: Notice the Java statement in Example 4-2 on page 37 where the responseContainer was “moved” to the COMMAREA using a constructor method. This was required because this Java class was generated by the JZOS Record Generator utility, which did not generate a set method that accepts a byte array for updating the entire record. Only set methods for individual fields are generated. The Rational Application Developer J2C wizard does generate all of required methods.
You can find details about both of these techniques in Chapter 8 of the Redbooks publication titled IBM CICS and the JVM server: Developing and Deploying Java Applications, SG24-8038.
 
Note: Bean Validation 1.0 is one the features supported by the CICS Liberty JVM server, but neither of these two methods include bean validation annotations. If you want to include bean validation support, the annotations must be added manually.
4.2.2 Debugging Java in CICS Liberty JVM server
Both the CICS TS Explorer and Eclipse integrated development environments (IDEs) provide means to debug remote Java applications by stepping thought lines of code, setting breakpoints, inspecting the contents of variables and so on. This technique can be used to also debug Java applications running in CICS Liberty JVM server. Figure 4-3 shows remotely debugging a CICS Liberty JVM server application in CICS TS Explorer.
Figure 4-3 Debug perspective of a Java applications running in CICS Liberty JVM server
The setup for a remote debugging session for CICS Java from a developer’s IDE is the same as when debugging on any other remote platform. Remote debugging can be very useful when migrating an existing application to CICS Liberty JVM server or the development of a new application for CICS Liberty JVM server.
 
Note: To enable remote debugging of a CICS Liberty server the following statement must be included in the JVM profile of the CICS Liberty JVM server resource definition:
-agentlib:jdwp=transport=dt_socket,server=y,address=<port>
4.3 Developing new applications using other Liberty features
There are Liberty features that are unique to CICS TS. Others provide functions that are used by CICS Liberty JVM server for better integration with CICS Transaction Server for z/OS and IBM CICS Transaction Server for z/OS Value Unit Edition.
4.3.1 CICS Liberty JVM server Java Database Connectivityoptions
CICS Liberty JVM server supports two different features for accessing Java Database Connectivity (JDBC) data sources.
•The first JDBC feature (cicsts:jdbc-1.0) is unique to CICS Liberty JVM server. It is tightly integrated with CICS TS for using the existing CICS TS DB2 connection resource (the DB2CONN resource). This feature supports only a DB2 local connection (JDBC Type 2).
•The second JDBC feature (jdbc-4.0) is supplied by IBM WebSphere Application Server for z/OS Liberty profile and supports remote connections (JDBC Type 4).
 
Note: Use of the JDBC feature provided in the base Liberty product is discouraged for local or JDBC Type 2 connections in CICS Liberty JVM server.
Local Connections (JDBC Type 2)
The CICS TS JDBC connection feature (cicsts:jdbc-1.0) is used when an application accesses a local DB2. The access is automatically included in a logical unit work managed by the CICS TS transaction manager. Commits and rollbacks of updates made to DB2 are automatically coordinated with commits and rollbacks of other CICS TS resources with no additional coding required. Security for these applications is also managed by the CICS TS DB2 connection definition.
Remote Connections (JDBC Type 4)
CICS TS Liberty uses the Liberty JDBC feature (jdbc-4.0) for accessing remote DB2 subsystems (JDBC Type 4). Java applications that use this feature must use the Java Transaction API (JTA) to integrate commits and rollbacks for remote JDBC system with CICS TS transaction management. This allows a remote DB2 connection to participate in the same global transaction as other CICS TS resource, such as access to VSAM files, transient data queues, temporary storage queues, and so on. It also supports other JDBC drivers, such as Derby.
 
Note: The -DISPLAY DDF command display provides the information required to configure JDBC Type 2 and Type 4 connections. The LOCATION value provides the location name, and DOMAIN and TCPPORT values provide the server name and port number:
DSNL080I #DI2C DSNLTDDF DISPLAY DDF REPORT FOLLOWS:
DSNL081I STATUS=STARTD
DSNL082I LOCATION LUNAME GENERICLU
DSNL083I DSNV10P2 GBIBMIYA.IYCWZDB0 -NONE
DSNL084I TCPPORT=40100 SECPORT=30100 RESPORT=50101 IPNAME=-NONE
DSNL085I IPADDR=::9.20.5.0
DSNL086I SQL DOMAIN=winmvs2c.hursley.ibm.com
DSNL086I RESYNC DOMAIN=winmvs2c.hursley.ibm.com
DSNL089I MEMBER IPADDR=::9.20.5.0
DSNL105I CURRENT DDF OPTIONS ARE:
DSNL106I PKGREL = COMMIT
DSNL099I DSNLTDDF DISPLAY DDF REPORT COMPLETE
4.3.2 JDBC connection options
There are two ways to identify the DB2 system to which the application is to connect:
•Use a JDBC-provided DriverManager by providing a Uniform Resource Locator (URL) to provide connection properties.
•Use a data source by doing a Java Naming and Directory Interface (JNDI) lookup of the data source name to obtain connection properties at execution time.
DriverManager JDBC connections
The driver manager technique uses one of two types of URLs to identify the target DB2 subsystem and optional connection properties:
•The default URL (see Example 4-5) does not provide an explicit DB2 location name and no properties and defaults to the DB2 system are specified by the CICS TS DB2CONN resource.
Example 4-5 Example of connecting to the default DB2 subsystem using a Default UR
Connection connection = DriverManager.getConnection("jdbc:default:connection");
•The other URL format provides a DB2 location name in the URL (see Example 4-6). The location name can be the location name of the local DB2 subsystem or the location name of a remote DB2 subsystem if DB2 distributed data facility (DDF) has been configured between the local and remote DB2 subsystem.
Example 4-6 Example of requesting an explicit connection to DB2 subsystem by location name
Connection connection = DriverManager.getConnection("jdbc:db2os390:location");
 
Note: In a Liberty JVM server, DriverManager connections require the enablement of the CICS TS JDBC (cicsts:jdbc-1.0) Liberty feature.
DataSource JDBC connections
The DataSource method allows an application to use the Java Naming and Directory Interface (JNDI) to look up data sources defined in the Liberty server.xml file. A special JNDI name of jdbc/defaultCICSDataSource (see Example 4-7) is used by the CICS TS JDBC feature for CICS TS JDBC connections.
Example 4-7 JNDI lookup for the default CICS TS JDBC data source
context = new InitialContext();
dataSource = (DataSource) context.lookup(jdbc/defaultCICSDataSource);
Connection connection = dataSource.getConnection();
Connections to remote DB2 subsystems use the JNDI name of the data source defined in the server.xml file (see Example 4-8).
Example 4-8 JNDI lookup for a remote JDBC data source
context = new InitialContext();
dataSource = (DataSource) context.lookup(jdbc/myDataSource);
Connection connection = dataSource.getConnection();
Example 4-9 is a snippet of the server.xml file that show the JDBC JNDI configuration required for these examples.
Example 4-9 Contents of server.xml file related to JDBC
<featureManager>
.....
<feature>cicsts:jdbc-1.0</feature>
<feature>jdbc-4.0</feature>
.....
</featureManager>
.......
<dataSource jndiName="jdbc/MyDataSource">
<jdbcDriver libraryRef="defaultCICSDb2Library"/>
<properties.db2.jcc databaseName="DSNV10P2" driverType="4"
password="{xor}Lz4sLCgwLTs=" portNumber="40100"
serverName="winmvs2c.hursley.ibm.com" user="DB2USER”/>
</dataSource>
 
<cicsts_dataSource id="defaultCICSDataSource" jndiName="jdbc/defaultCICSDataSource"/>
 
<cicsts_jdbcDriver id="defaultCICSJdbcDriver" libraryRef="defaultCICSDb2Library"/>
 
<library id="defaultCICSDb2Library">
fileset dir="/usr/lpp/db2/jdbc/classes" includes="db2jcc4.jar
DB2jcc_license.jar”/>
<fileset dir="/usr/lpp/db2/jdbc/lib" includes="libdb2jcct2zos4_64.so"/>
</library>
 
Note: The cics_ts_jdbcDriver and library elements are required for both DriverManager and DataSource connections. They identify the libraries where the JDBC driver components reside and the Java JAR files and shared object library to be used.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.118.209.121