Introduction

This article is part of a series of IBM ® VisualAge® for Java™ CCF to WebSphere® Studio J2C migration articles that describe the typical activities for migrating CCF CICS® ECI, IMS™, or WebSphere MQ into J2C applications. This series includes the following articles:

• CCF to J2C migration: Part 1: CCF application limitations on WebSphere Studio Application Server V5
• CCF to J2C migration: Part 2: Overview of migrating VisualAge for Java CCF applications into WebSphere Studio J2C applications
• CCF to J2C migration: Part 4: Migrating VisualAge for Java CCF IMS applications into WebSphere Studio J2C IMS applications
• CCF to J2C migration: Part 5: Migrating of VisualAge for Java CCF MQ applications into WebSphere Studio J2C JMS applications

Updates to this article

• Guideline for accessing ConnectionSpec or InteractionSpec (May 2004)
• Exploiting Managed Connections (May 2004)

Back to top

Overview

VisualAge for Java uses the Common Connector Framework (CCF) to simplify the creation and maintenance of Java applications that access host Enterprise Information Systems (EIS's). These EIS resources are typically Customer Information Control System (CICS®) transactions, Information Management System (IMS) transactions, or WebSphere MQ message queues. The VisualAge for Java Enterprise Access Builder (EAB) feature supports this CCF framework by providing tools to create CCF connector objects (Java command and record classes), and applications that use these CCF connector objects.

As the value of the CCF framework became recognized and accepted, IBM submitted it for consideration as an industry standard. After review and modification, it became J2EE Connector Architecture (J2C). While J2C is similar to its predecessor CCF, there are significant differences between the two and migration is not trivial. It is desirable to migrate existing VisualAge for Java CCF applications into WebSphere Studio J2C applications whenever there are J2C equivalents. This article covers two main topics:

• Migration of EAB tool-generated CCF CICS-ECI connector artifacts
• Migration of developer-written applications using those objects

If you have fewer than 10 or so CCF CICS-ECI commands and records, then the best approach is to just manually regenerate the J2C artifacts within Application Developer, and manually migrate your applications. If you more than 100 or so CCF commands and records, then using this article and the CCF Migration Assistant (CMA) is your easiest migration route to Application Developer J2C. If you have between 10 and 100 CCF commands and records, it is recommended that you read this article and then decide which route to take.

Back to top

Migration assistance services

IBM WebSphere Services has a range of migration assistance that customers can purchase:

1. On-site training or assistance for WebSphere Application Server V3.5 => V4 => V5 application migration
2. On-site assessment of CCF application migration, description of work, and scope of effort
3. Installation and familiarization with the CCF Migration Assistant (CMA) program
4. Pilot migration of small applications or application components
5. Optional migration of larger applications

For further information, contact:

• In North or South America: Mitch Johnson via e-mail at mitchj@us.ibm.com or via phone at 1-919-254-0065
• In Europe or the Middle East: Richard Johnson via e-mail at richardj@uk.ibm.com or via phone at 44-1962-817714
• In Asia Pacific: Rick Jones via e-mail at at rick.jones@au1.ibm.com or via phone at 61-2-9478-8219

Back to top

Best practices for artifact (services) and application (Web or Java) projects

The VisualAge for Java Adder sample has the generated CCF artifacts and its ExecuteAdder application together in one project (since in total there are only six Java files). Your specific VisualAge for Java CCF applications may have only one VisualAge for Java project, or many, depending on how your CCF application VisualAge for Java projects are organized.

During migration to Application Developer is the ideal time to ensure your ongoing project structure follows a simple "best practice." We recommend that you have one or more Application Developer service projects to contain groups of related J2C Services, and one or more Web or Java projects to contain your application (typically, one Web or Java project for each major subsystem of your overall application):

• For example, you might have one Application Developer service project, PersonnelServices, containing a group of services accessing CICS personnel programs and IMS personnel programs.
• In addition, you might have one Application Developer Web project, PersonnelWeb, using the PersonnelServices project, an InventoryWeb project using some other InventoryServices project, and an AdminJava project accessing administration programs via both Services projects.
• Together, the collection of these Services and Web or Java projects make up your overall application.

A little logical organization greatly simplifies long-term understanding and maintenance of these projects.

Back to top

CCF to J2C CICS-ECI migration steps

This article describes in detail how to migrate a CCF CICS-ECI application into a J2C application, and includes the following steps:

1. Set up VisualAge for Java and Application Developer.
2. Export from VisualAge for Java the CCF CICS-ECI class artifacts and CCF application source.
3. Import and migrate CCF CICS-ECI artifacts (using Application Developer CMA) into J2C artifacts.
4. Import and manually migrate CCF CICS-ECI applications (using the CCF to J2C CICS-ECI coding guidelines). This application migration activity includes any application lifecycle maintenance to accommodate new JDK levels, new Server APIs, and so on.
5. Deploy and test.
6. Lifecycle maintenance of the migrated J2C artifacts and applications.

Back to top

Step 1. Set up VisualAge for Java and Application Developer

1. As described in Part 2: Migration overview, ensure that you have VisualAge for Java V3.5.3 or V4.0 set up appropriately:
   • The system must include your CCF CICS-ECI applications and generated CICS-ECI artifacts (commands and records).
   • Optional: The CCF CICS-ECI Adder sample (if you wish to migrate it as described in this article):
2. As described in Part 2: Migration overview, ensure that you have Application Developer V5.1.1 set up appropriately:
   • Ensure that the required fix pack and all required interim fixes are installed as shown below:
     
   • Follow the installation instructions in the CICS-ECI sample:
     and ensure that all required resource adapters (CICS for this article) are installed into RAR projects (CicsEci, Ims, and Hod3270 projects are shown below):
     
   • Ensure that the CCF Migration Assistant (CMA) plug-in is installed:
     • Part 2: Migration overview describes how to request and obtain the CMA plug-in.
       The CMA plug-in is not part of Application Developer and is not supported -- you cannot call IBM Support and request assistance or report problems related to it.
     • Please allow one to two weeks for:
       • Your e-mail to searle@ca.ibm.com requesting the plug-in.
       • Our return e-mail containing the "As-Is" license.
       • Your return e-mail stating your agreement.
       • Our return e-mail containing the current CMA plug-in (or FTP instructions).
     • The above steps are necessary to ensure that you understand the that plug-in is provided "As-Is", and to enable us to send you CMA updates if any become available. The screen capture below shows how your plug-in registry will appear after you have installed the CMA plug-in:

Back to top

Step 2. Export VisualAge for Java CCF artifacts and CCF applications

You can export the CCF artifact classes (and optional source files) plus the CCF application source (and optional classes) all together in one Java Archive (JAR) file. In fact, this is the easiest approach if you are going to follow the unsupported approach of importing the artifacts plus applications into Application Developer and then editing the source and recompiling everything. As noted in Part 2: Migration overview, this procedure seems to work for most applications, but it is not supported as it has not been extensively system tested by IBM. There may be subtle problems because of different JDK compiler levels, different support libraries, and so on.

The XxxxBeanInfo helper classes are used only within VisualAge for Java and are not needed during migration (just the XXXXRecord, XXXXRecordType, and XxxxCommand classes are needed). The XxxxBeanInfo artifacts can be included in the exported JAR, but they will be bypassed by the CMA program and a warning to this effect will be written into the CMA log. It is cleaner to just export the Command, Record, and RecordType classes. Source Java files can also be included in the exported JAR file, but they will also be ignored by the CMA program.

Typically, for the CCF Migration Assistant (CMA) migration processes, you would migrate all of your CCF-generated artifacts into a JAR file. If you are migrating the CCF Adder sample, you might export the generated CCF artifact classes into a JAR file named AdderClasses. Therefore, to export the Adder artifacts:

1. Expand the com.ibm.ivj.eab.sample.eci.adder package and right-click to multi-select the required AdderCommand, AdderRecord, and AdderRecordInfo files.
2. Then click Export => JAR file => Next => .class (your can leave .java selected if you wish -- CMA will ignore them).
3. In the Jar file field, type C:\CCF\ECIAdderClasses.jar and then click Finish. The CCF artifacts are exported.

Similarly, for the CCF application migration process, select ExecuteAdder and export its one .java source file into C:\CCF\ECIAdderExecute.jar.

For this small sample, you may prefer just to export all the required .class and .java files together into one C:\CCF\ECIAdderEverything.jar file. This approach is the easiest if you want to try the unsupported import, then edit and rebuild within Application Developer.

Back to top

Not supported: Application Developer source import and rebuild of CCF artifacts and applications

Most CCF applications and CCF artifacts seem to properly rebuild in Application Developer and then run successfully on WebSphere Application Server. This is not tested and not supported because of differences in the Java compiler level, other updated libraries, and system API changes. Therefore, one unsupported approach to short-term CCF application maintenance is to install the CCF connectors into Application Developer and WebSphere Application Server (see the previous limitations article, and note that the actual CCF connectors require run-time licenses for installation and use within WebSphere Application Server), and then to export the EAB-generated CCF artifacts (Java source for generated commands and records) into Application Developer.

The Java source for developer-written VisualAge for Java CCF applications, and the generated CCF artifacts, can be exported as a JAR file and then imported into an Application Developer Java project, the same as for any other Java program. You can then use the default Application Developer Java editor to manually edit them, since they are just Java source files, but Application Developer cannot regenerate any CCF artifacts. For example, assuming that you exported all of the VisualAge for Java ECI Adder files into ECIAdderEverything.jar, then within Application Developer, follow these steps:

1. Create a Java project. Click File => New => Project => Java => Java project => Next, then for Project Name type CCFAdderECI, and click Finish to create the Java project.
2. Import the CCF source:
   1. Select the CCFAdderECI project, and then click File => Import => Zip file => Next. Browse to your C:\CCF\ECIAdderEverything.jar, and click Finish to populate the Java project.
   2. If you also exported the XxxxBeanInfo files (AdderCommandBeanInfo and AdderRecordBeanInfo) then you can select them and delete them.
3. Eliminate errors due to dependencies:
   1. Right-click the CCFAdderECI project and select Properties => Java build path. Then click the Projects tab. Ensure that your CICS-ECI RAR project (you set it up during the Application Developer Setup) is on the build path.
   2. Click the Libraries tab. CICS ECI RAR\connectorModule\ctgclient.jar and the four WebSphere Application Server main run-time CCF jars (ccf.jar, eablib.jar, j2ee.jar, recjava.jar) should all be on the build path:
4. Execute -- right-click the ExecuteAdder class and select Run. You should have a successful CCFAdderEci execution in the Console view. If the CCF ExecuteAdder class runs correctly, this also means your CICS ECI RAR and CICS Transaction Gateway (CTGateway or CTG) files are set up correctly and functioning properly, which you will need for the J2C CICS ECI operations.
5. Deploy and Test -- you can also deploy the recompiled CCFAdderEci application to a remote WebSphere Application Server and run it. You need a CTGateway connector run-time license to install the CICS ECI RAR onto a run-time server, and you also need to be aware of the CCF on WebSphere Application Serve V5 limitations.

Back to top

Step 3: Migrate CCF artifacts into J2C using Application Developer CCF Migration Assistant (CMA)

1. Import the CCF artifacts as a file system file (to keep them as a JAR file) into the desired Service project.
2. Migrate these CCF artifacts into J2C artifacts using the program.
3. Finally, do normal ongoing lifecycle maintenance within Application Developer.

1. Import CCF artifacts JAR into Application Developer Service project

1. Ensure that the Application Developer CMA plug-in was installed was during Application Developer setup.
2. Create the desired J2C Service project:
   1. Click File => New => Project => Business Integration => Service Project => Next, and then enter AdderServices as the Project Name.
   2. Click Next => Projects => CicsEci => Finish. This adds the CicsEci RAR project run-time dependency.
3. Import CCF artifact JAR file as a file system file:
   1. Select your new AdderServices project, and then click File => Import => File system => Next. Browse to your C:\CCF\ECIAdderClasses.jar file and click Finish to import and retain it as a JAR file.

2. CMA migrate CCF artifacts into J2C service

1. Right-click ECIAdderClasses.jar and select Migrate CCF artifacts.
2. Select the Shorten names compatibility option radio button and then click Next:
   
3. Select the Do not generate JNDI Name entry and then click Finish:
   
4. The CMA migration proceeds and finishes, resulting in the creation of Command, Record, and RecordFormatHandler Java classes, and WSDL metadata files:

At this point there is a J2C service proxy, and a data bean plus Format Handler helper classes for the CICS ECI Adder program. You still need to migrate an application (Step 4) that actually uses it.

3. Ongoing J2C artifact maintenance within Application Developer

Now, you just do normal ongoing lifecycle maintenance of your J2C artifacts with Application Developer. The only special considerations are:

• Whenever you regenerate a J2C artifact, remember to use the same options (name style, and so on) to retain existing application compatibility.
• If you used the CMA-generated CCF compatibility methods to speed your initial application migration, then they will be automatically retained within the service proxy anytime it is regenerated with Application Developer.

Back to top

Step 4: Migrate CCF applications to use J2C artifacts using migration coding guidelines

1. Import the CCF application into the desired Web or Java project.
2. Modify the CCF application to use the migrated J2C artifacts using the CCF to J2C application guidelines.

1. Import CCF applications into Web or Java projects

1. Create the desired application Web or Java projects:
   1. Click File => New => Project => Java => Java Project => Next , and then type AdderApplication for the Project Name.
   2. Click Next and then click the Projects tab. Select AdderServices and then click Finish. The build and run-time dependent AdderServices project is added.
2. Import the CCF application from its JAR file:
   1. Select your new AdderApplication project.
   2. Click File => Import => Zip file => Next, and then browse to your C:\CCF\ECIAdderExecute.jar file.
   3. Click Open => Finish to import the application (just one ExecuteAdder.java file for the Adder sample).

2. Migrate application using CCF to J2C application guidelines

1. One typical error (shown below) results from requiring build and run-time access to org.apache.wsif.WSIFException and other WSIF classes:
   
   1. A typical time-saver is to define a workbench environment variable (to do so, click Window => Preferences => Java => Classpath Variables, and then click New and name it WAS_50_LIB to permit adding Library JAR files as Add Variable => Extend => WAS_50_LIB\lib extensions:
   2. Right-click the AdderApplication project, then click Properties => Java build path. Click the Libraries tab and click Add External JARs to add the WebSphere Application Server run-time library JAR files j2ee.jar, qname.jar, wsatlib.jar, wsif.jar, and wsif-j2c.jar.
2. Another standard set of errors requires removing all old com.ibm.connector.* imports:
3. Another standard set of errors requires removing all old JavaRuntimeContext code:
4. The CCF to J2C application guidelines describe application changes needed to manipulate commands and records. The optional CMA-generated CCF Compatibility Methods are available to minimize short-term application changes (to speed initial CCF to J2C application migration). Application usage of these short-term (deprecated) CCF compatibility methods should be removed during application lifecycle maintenance, to use the current J2C invocation style:
   • For example the old CCF Command.setOperand() plus Command.execute(CommandEvent) pattern ...
   • ... is deprecated compatibility invocation new Record() plus Record.setOperand() plus Command.setCeInput(Record) plus Command.execute()...
   • ... but best practice is the new J2C invocation new Record() plus Record.setOperand() plus Command.setAdderCommandRequestPart(Record) plus Command.execute().
   • Another example, the old old CCF Command.getRes() pattern (which was Command.getCeOutput0().getRes() internally) ...
   • ... is deprecated compatibility invocation Command.getCeOutput().getRes() ...
   • ... but best practice is the new J2C invocation Command.getAdderCommandRequestPart().getRes().
5. Another set of standard errors (shown above) requires org.apache.wsif.WSIFException handling and also requires adding an import org.apache.wsif.WSIFException statement:
6. Best practice: A WSIFException, by itself, is typically not very informative. Since they include a TargetException, that should be obtained and displayed since it may be more informative (it is the real error). Also, many of the TargetException errors are actually javax.resource.ResourceException errors that have a LinkedException containing the root error. A best practice is to always try to extract the most informative message from any caught WSIFException:

Back to top

Step 5. Deploy and test (execute) the migrated application

1. Open the ExecuteAdder.java program and click Run:

If your execution fails due to a WSIFException -- Port 'AdderCommandCICSECIPort' is not available error, then your AdderServices project does not have its Properties => Java Build Path => Projects set to include the CicsEci CICS-ECI RAR project. This does not cause any build errors, since it is a run-time dependency.

Important: During Application Developer execution, if the Run => Classpath => Use default classpath option is not checked, then you may get a WSIFException failure due to codepage 437 not being available. Ensure that you are running with the default classpath, which includes full codepage support.

Back to top

Step 6. Ongoing lifecycle migrated application maintenance within Application Developer

Now, you just perform normal ongoing lifecycle maintenance of your J2C application within Application Developer. One special consideration is if you used the CMA-generated CCF compatibility methods to speed your initial application migration, then you should replace them with the normal J2C style command and record invocations whenever convenient. They can be done a few at a time since both invocation styles work.

Back to top

CMA limitations and guidelines

This section will be updated if significant new CICS-ECI CMA limitations or guidelines are discovered. The CMA plug-in contains online documentation, which is the most detailed and most current definition of known CMA limitations, issues, and guidelines.

The currently known, most significant CMA limitations and guidelines can be summarized as follows:

1. CCF CICS-ECI (or IMS or Beta-JCA) artifacts only (see IMS article for IMS specifics). No CICS-EPI, HOD-3270, or MQ artifacts.
2. COBOL records only. No C nor PL/I.
3. Only single-segment records. Manual application changes required for IMS multi-segment records.
4. Fixed-length and dynamic records must use the normal generated accessors. Any base framework access requires manual migration.
5. Must have a RecordType for all records -- otherwise they are skipped and need manual migration.
6. Only the default mapping is supported for RecordTypes. A changed preferred type requires manual migration.
7. No hierarchical style records. Manual migration is required.
8. Custom Methods in CCF artifacts are not preserved and need to be manually copied.
9. No CCF Navigator migration. Manual migration is required, most likely to Processes.
10. No CCF mapper migration. Manual migration is required, most likely to Transformers.
11. No EAB session bean nor business object migration. Manual migration is required:
    • If EAB session beans were generated using command bean wrappering, those command beans can be migrated, and deploy code generated within Application Developer.
    • If EAB session beans were generated using CustomUserMethods, all code was inline with user method names, so no automated migration is possible
    • If matching session beans are manually regenerated within Application Developer, then user applications should migrate easily, and typically require no session bean invocation changes
12. CCF Commands generated with promote record properties may require manual application changes.
13. Group and export CCF artifacts by server and transaction name (CMA assumes common JNDI ConnectionFactory).
14. Group and export CCF artifacts by name style (CMA assumes single name style throughout CCF JAR file).
15. CMA and its documentation are English only -- it is not a production product.
16. Important: The CMA online documentation is the ultimate source for current limitations and guidelines. If in doubt, consult it and not this article (which may have become out of date).

Back to top

Application limitations and guidelines

This section may be updated if significant new CICS-ECI application limitations or guidelines are discovered.

The currently known, most significant, application limitations and guidelines can be summarized as follows:

1. Catch WSIFException (instead of old CCFException).
2. Initially, use new CMA CCF compatibility methods to emulate the old CCF Command superclass hierarchy to speed short-term application migration:
   • These CCF compatibility methods within CMA-generated service proxies provide many of the features from the old CCF command superclass hierarchy, and simplify the migration of applications that use those deprecated features.
   • These CCF compatibility methods are added by the CMA into the "user code" section of proxies (without the @generated tag), and therefore that code is retained whenever the same proxies are regenerated within Application Developer Integration Edition.
   • Important: To maximize long-term compatibility, during ongoing application maintenance, change any migrated applications to use the new J2C style of invocation and stop using the short-term (deprecated) CMA CCF compatibility methods.
3. Slight changes in data bean getters and setters (cannot get attribute after command execution, and so on).
4. No record cloning (can use FormatHandler getBytes() if really needed).
5. BigDecimal replaced by int (signature changes, precision may require application rewrite).
6. Record field attributes (example length) are not accessible.
7. Use new WebSphere Application Server APIs (new security model, no run-time context, and so on).
8. Currently cannot catch DataRangeExceptions (under investigation as possible J2C tooling enhancement).
9. Subrecords are not always initialized (could cause NullPointer exceptions).
10. In J2C, there are two types of EIS sign-on: component managed and container managed. These types did not exist in the CCF architecture, where the CCF sign-on was more like component-managed sign-on:
• With J2C component-managed sign-on, the userID, password, and optional (IMS) groupName can be passed in the ConnectionSpec (which is normally not programmatically accessible).
• To access the ConnectionSpec, modify the WSDL files using the instructions in the WebSphere Studio online help.
• Search the online help for "Exposing the InteractionSpec and ConnectionSpec".
• This section lists the ConnectionSpec and InteractionSpec properties you can access, and tells you how to access them.
• Or, you can associate a component alias with the connection factory, which lets you provide userID and password (see the note below).
11. In J2C, one of the significant enhancements is managed connections:
• In WebSphere, managed connection factories can provide details of the servername, CTG URL, username, password, and so on.
• This information is therefore kept out of the application code and can easily be altered by a system administrator (with no code changes).
• The application makes a JNDI lookup that is bound (by the administrator) to the address of the appropriate managed connection factory.
• The lookup can be re-bound anytime (by the administrator) to a different managed connection factory.
• And/or the managed connection factory itself can be easily changed (by the administrator).

Back to top

Conclusion

WebSphere Studio Application Developer Integration Edition has a completely new set of tools optimized to create and maintain J2C objects and applications. It is desirable to migrate existing VisualAge for Java CCF applications into WebSphere Studio J2C applications whenever there are J2C equivalents. This article has covered two main topics: migrating EAB tool-generated CCF CICS-ECI connector artifacts, and migrating developer-written applications using those artifacts

About the authors

Ellen Matheson McKay is an Information Developer for IBM Canada Ltd. She writes online help and publications for WebSphere Studio Application Developer.

Barry Searle is the Migration Team Leader for WebSphere Studio Application Developer. He is a Professional Engineer who has worked at the IBM Canada Lab for over ten years on various application development tools. Prior to that he had many years of industry experience developing command and control systems and leading communications development projects.

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Overview
• Migration assistance services
• Best practices for artifact (services) and application (Web or Java) projects
• CCF to J2C CICS-ECI migration steps
• Step 1. Set up VisualAge for Java and Application Developer
• Step 2. Export VisualAge for Java CCF artifacts and CCF applications
• Not supported: Application Developer source import and rebuild of CCF artifacts and applications
• Step 3: Migrate CCF artifacts into J2C using Application Developer CCF Migration Assistant (CMA)
• Step 4: Migrate CCF applications to use J2C artifacts using migration coding guidelines
• Step 5. Deploy and test (execute) the migrated application
• Step 6. Ongoing lifecycle migrated application maintenance within Application Developer
• CMA limitations and guidelines
• Application limitations and guidelines
• Conclusion
• About the authors
• Comments

Next steps from IBM

Rational Application Developer features provide the comprehensive Integrated Development Environment (IDE) used to develop J2EE applications requiring Servlets and JavaServer Pages (JSPs).

---

• Try: Try the free Rational Application Developer, which helps developers quickly design, develop, test, analyze, and deploy high-quality Java, Javaserver pages, and J2EE applications.
• Article: Learn how you can deliver accurate, higher-quality J2EE apps with Rational Application Developer, open source JUnit and JUnitEE test frameworks.
• Tutorial: Build a Facebook application using PHP, the Spring framework, and J2EE.
• Buy: Rational Application Developer

My developerWorks community

Dig deeper into WebSphere on developerWorks

Cloud computing for developers

Virtual workshop: Learn how to build a cloud infrastructure and develop/deploy cloud-based applications. (6-8 Apr 2010)

Special offers