Migration can sometimes be a difficult task. To effectively migrate an application, you must have a good understanding of both what you currently have and what form the migrated application will take. To help make the planning and process easier for you, this article compares and contrasts three products:

• IBM® VisualAge® for Java™

• IBM® WebSphere® Studio Application Developer Integration Edition (sometimes referred to elsewhere as WSAD-IE)

• IBM® Rational® Application Developer

The authors also describe migration to evolve from the Java™ Web Services Invocation Framework (WSIF) that the first two products are based on to the JavaBeans™ technology that Rational Application Developer uses.

Assumptions and requirements

This article will be helpful to you if this is your situation:

• You have developed IBM® Customer Information Control System (CICS®) IMS applications that are based on the Web Services Invocation Framework (WSIF) in WebSphere Studio Application Developer Integration Edition V5.1 or previous versions.

• You are planning to migrate these applications to IBM Rational Application Developer Version 6.0.1 or later or to Version 7.

If you are using Rational Application Developer V6.0.1, install the optional Java™ 2 Platform, Enterprise Edition (J2EE™ platform) Connector Architecture (J2C) tools after you have installed Rational Application Developer. The IBM® WebSphere® Application Server, Version 6.0, which is the default server, is installed as part of Rational Application Developer.

If you are using Rational Application Developer V7, you need to select J2EE Connector tools and WebSphere Application Server V6.1 during installation.

Back to top

Necessity and benefits of migration

Some of the older versions of products are already retired and no longer supported, so migration is a necessity if you want to keep up with the evolution of technology.

• VisualAge is out of service for a while.
• VisualAge for Java V3.5.3: End of June 2003 (was Dec 2002, extended six months recently).
• VisualAge for Java V4: End of July 2003 (two years after shipment).
• WSIF is not deprecated but is no longer strategic. A replacement for the runtime is in the works. It may appear in WebSphere Application Server 7.0, in which case WSIF may be marked for deprecation, but will continue to be shipped and supported in two further major WebSphere Application Server releases. You can still execute your WSIF-based applications, but cannot make enhancements to them.

For more detailed information on the deprecation date, please refer to the WebSphere Application Server InfoCenter.

As an incentive to tackle the migration process, these are among the numerous benefits:

• The J2EE Connector Architecture (J2C) tools are easier to use.
• The J2C programming model is not tied to services nor to WSIF. Instead, it relies on a simple Java bean.
• You do not need special knowledge of WSDL or XSD.
• It is faster, because the J2C bean talks directly to EIS through the common console interface (CCI) call.
• J2C technology uses an annotation builder, based on doclet tags, to generate code. This is a very powerful new feature. You need to modify only the doclet tags, and the code regenerates automatically.
• From the J2C bean, you can deploy to a Web service, an Enterprise JavaBeans™ (EJB™) component, JavaServer™ Faces, or JavaServer Pages™ (JSP™) by using the J2C deployment wizard.
• There are several other features and upgrades in Rational Application Developer V7.0 that you will find useful.

Back to top

Migration Planning

Evolving from VisualAge for Java applications

There is no direct migration path nor any migration tools for migrating CCF, CICS, and ECI IMS applications from VisualAge for Java to Rational Application Developer. The procedure varies, depending on how many transactions you need to move.

• If you have only a few transactions, and the COBOL and C source files are available, then it will be better to create the J2C JavaBeans and data binding beans from scratch from the J2EE Connector Architecture tool in Rational Application Developer.
• If you have a lot of transactions in VisualAge for Java, you need to perform a two-step migration.
  1. First, use the CCF Migration Assistance (CMA) to migrate existing VisualAge for Java CCF applications to WebSphere Studio Application Developer J2C applications.
  2. Then, use the J2C Service Migration wizard to migrate WSDL files to J2C JavaBeans and data binding beans.

Note: These two Java™ Archive (JAR) files have not been supported since the VisualAge for Java expiration:

• eablib.jar
• recjava.jar

Evolving from WebSphere Studio Application Developer WSIF-based CICS and ECI IMS applications

The procedure varies, depending on how many transactions you need to move.

Note: Be sure to plan ahead and find out which server runtime the migrated application will be running on, because this will affect how you install your products.

• If you have only a few transactions, and the COBOL and C source files are available, you have two choices:
  • Use the J2C Service Migration wizard to migrate your application.
  • Create the J2C JavaBeans and data binding beans from scratch from the J2EE Connector Architecture tool in Rational Application Developer.
• If you have a lot of transactions in WebSphere Studio Application Developer, use the migrate-by-folder alternative to move a group of files at once, rather than moving single files one at a time.
  • You should group all the WSDL files that belong to one Application (EAR) and migrate them together.
  • Start with a clean new workspace.
  • Try migrating a single WSDL service file first so that you are comfortable with what is created with the migration tool and that you can test it in your environment.
  • When you are comfortable and familiar with the process, you can then migrate groups of WSDL service files together.
• WSIF is still supported in WebSphere Application Server, if you decide not to migrate yet. You can import your WebSphere Studio Application Developer application into the Rational Application developer workspace and continue to run it. However, you cannot make enhancements to your WebSphere Studio Application Developer applications. In the mean time, you can start migrating part of your applications and still have an environment to execute your old applications.

Note: These two JAR files have been removed in Rational Application Developer V7, so do not use them:

• eablib.jar
• recjava.jar

Back to top

Overview of product differences

In the WebSphere Studio Application Developer Integration Edition (hereafter referred to as WebSphere Studio Application Developer), access to enterprise information systems (EIS) applications through J2EE Connector Architecture consisted of creating WSDL and XSD files. These files contained the metadata that represented the interface and EIS operations, as well as the data format for the input and output messages. They also included all of the information required to create the various artifacts: command proxy beans, client stub proxy beans (remote procedure call, or RPC), Helper classes (along with the FormatHandler class), and session Enterprise JavaBeans.

In Rational Application Developer, by contrast, the main artifacts that hold all of the metadata are the J2C bean and the data binding beans. The J2C bean is also an RPC bean. (See Figure 1.)

Comparison of J2C support in different products

Table 1 and Table 2 give you overviews of the differences in EIS support among the different generations of products.

Back to top

Migration paths

Table 3 shows the migration paths for Microsoft® Windows and Linux® operating systems.

Back to top

Migration process

You can migrate your files by using either the wizard provided or by using the command line, or a combination of the two, and you can migrate the files individually or as a group. See Figure 2, and read on for details.

Migration methods and tools

In Rational Application Developer V6.0.1 and V7, the J2EE Connector Architecture tool provides a J2C Service Migration wizard. This tool transforms the J2C services created in WebSphere Studio Application Developer into J2C JavaBeans, data binding beans, or command-line beans, as appropriate. The J2C migration tool also supports command-line mode.

Using the command line for migration. Although the Service Migration wizard is easier, faster, and more efficient to use, Rational Application Developer also provides a command-line migration tool. It enables you to migrate a single WSDL file or to migrate a folder of several WSDL files by using the J2Cmigration.bat file. See the product documentation for details.

Using the Service Migration wizard. The J2C Service Migration wizard layout and flow are the same for Rational Application Developer V 6.0.1 and V7, but there are a few minor differences:

• The default WebSphere server runtime selection (see Tips for success, the last section of this article)
• The location of the resource adapters
• The installation location of the plug-ins

To use the J2C Service Migration wizard, select File > New > J2C > Other > J2C > Migration > J2C Service Migration Wizard.

Artifacts to generate for migration

You can generate the following J2C artifacts from the J2C Service Migration wizard. You can also generate the command and J2C beans, depending on the options that you select and the content of the source WSDL service files.

• J2C Java bean interface files
• J2C Java bean implementation files
• Data binding Java files
• Command beans (optional)
• Migration summary report XML file and the J2CMigration.xsl XML stylesheet file to format the migration summary report (both optional)

Note: The default name of the migration implementation class is the name of your WSDL interface with the word Proxy appended. In Rational Application Developer, the default for implementation classes is the class name appended by the abbreviation Impl. The reason for preserving the proxy name is for backward compatibility, so that any existing WebSphere Studio Application Developer client application code is not affected.

Migrating WSDL files

These three WSDL files generated in WebSphere Studio Application Developer projects will be used in the migration process:

• Interface WSDL file: Contains the portType, operation, input, and output (including the interface for the operations and its input and output parameters and types).
• Service WSDL file: Contains all of the connection information.
• Binding WSDL file: Contains platform, encoding, type mapping, interaction properties, and any other information that the implementation requires.

There are two ways to migrate your WSDL files using the wizard. (See Figure 3.)

• You can migrate one service WSDL file at a time.
• You can migrate all of the service WSDL files in a selected folder.

In the Additional migration options field, you have two choices:

• Create command beans. Select this option if you want to generate command beans.
• Generate data binding beans only. Select this option if you want to create data binding beans only, without creating J2C beans and command beans.

Migration Summary page

After migration, you will see a J2C Service Migration Summary page. (See Figure 4.)

Back to top

Additional Information

Resource adapters

Keep these facts in mind:

• JCA 1.5 Resource Adapter will not deploy into a JCA 1.0 application server.
• CICS TG V6 supports only JCA 1.5 resource adapters.
• CICSECI V700. Resource Adapters will require CICS TG V7
• You must use JCA 1.0 resource adapters from CICS TG V5.1 to work with WebSphere Application Server V5.0 and V5.1.

If you are using Web services and Enterpise Java Beans in WebSphere Studio Application Developer, please read the following.

Web services

The process for creating Web services is different now:

• In WebSphere Studio Application Developer V5.1, you created your Web service from WSDL files.
• But in Rational Application Developer V6 and V7, you create a Web service for the migrated Java bean as Web service from the J2C > Web Page, Web Service or an EJB from the J2C JavaBeans wizard.

Enterprise JavaBeans

In WebSphere Studio Application Developer V5.1, you created an EJB skeleton service by following these steps:

1. Create a service project.
2. Import the WSDL file.
3. Create an EJB project.
4. Generate the service skeleton.

However, in Rational Application Developer V6 and V7, you can create an EJB for the migrated Java bean as a Web service through the J2C > Web page, Web service or EJB from J2C JavaBeans wizard.

Exposing Interaction and Connection specifications

In WebSphere Studio Application Integration Edition, to expose the InteractionSpec and ConnectionSpec properties, you need to modify the WSDL files and regenerate the deployed code. The WSDL binding file contains the part where the functionName (an InteractionSpec property) is exposed, as code Listing 1 shows.

<input name="getCustomerRequest">
<cicseci:interactionSpecProperty part="partB"
propertyName="functionName"/>
</input>

If you migrate the WSDL files by using the Rational Application Developer V7 J2C Service Migration wizard, the exposed properties will migrate automatically. However, in Rational Application Developer V6, there is no wizard support to expose the InteractionSpec and ConnectionSpec, so you need to do it manually. Read the IBM® developerWorks® article called "Generating a J2C bean using Rational Application Developer J2C tools" for more information. (See Resources.)

In Rational Application Developer V7, you can expose the InteractionSpec and ConnectionSpec by using the J2C JavaBeans wizard. This is a new feature of J2EE Connector Architecture tool in Rational Application Developer V7. See the same developerWorks article for details.

Back to top

WebSphere Application Server

Multiple standalone versions of the same EIS resource adapter should not be installed in WebSphere Application Server, especially if they are for the same EIS type. For example, if you install both a CICS ECI 5.1 and CICS ECI 6.0, there may be a conflict. This is because all standalone resource adapters share the same class loader.

WebSphere Application Server runtime

When you are migrating your applications, there are some default behaviors in server runtime selection. The behavior in Rational Application Developer V6 and V7 is not the same.

The server runtime selection order is quite complex, and it all depends on the configuration of your environment. IBM developerWorks will cover these advanced topics in other migration articles.

In general, if you are migrating a single WSDL file, you can select the server runtime if you are creating a Web or EJB project by clicking the Show Advanced button in the project creation wizard. If you are migrating by folder, you do not have much control over the runtime, but you have two options:

• Before migration. You can either create the Web or EJB project in advance, with the server runtime you want, and then select that project explicitly during migration. You do this when you create the project by choosing the option to Generate all migration output into a single project in the Service Migration wizard, and then selecting the runtime.

• After migration. To modify the server runtime in the migrated project, the steps differ depending on which version of Rational Application Developer you are using.
• In Rational Application Developer V6 (see Figure 5):
1. Set the JRE level.
2. Right click on your project, and select Properties.
3. Select Java Build Path, and click the Libraries tab.
4. Optional: You can also select WebSphere Application Server and modify runtime there, as well, if you wish.
5. Set the JDK level. To modify the JDK level, click Java Compiler.

You can set the JDK level for both your workspace and your project. (See Figure 6.)

• In Rational Application Developer V7 (see Figure 7):
1. Set the JRE level.
2. Right-click on your project, and select Properties.
3. Select Java Build Path, and click the Libraries tab.
4. Select JRE library system and click Edit to change the JRE runtime.
5. Optional: You can also select WebSphere Application Server and modify runtime there, as well, if you wish.
6. Set the JDK level. To modify the JDK level, click Java Compiler.

Here, too, you can set the JDK level for both your workspace and your project (Figure 8).

Back to top

Post-migration steps (Optional)

Note: Not everyone is required to perform these post-migration steps. In most cases, executing the above migration process should be sufficient.

Depending on the type of program you are migrating, you may need to perform a few tasks after you have completed the J2C service migration process.

• Replace part of the Exception code. Because the org.apache.wsif.WSIFException is no longer thrown from the J2C Java bean, you need to replace WSIFException in your WebSphere Studio Application Developer client applications that invoke the migrated J2C Java bean with Exception.

• Transfer any customized code. Because the migration tool does not migrate user-customization code, you need to retrofit your code into your new project.

• Modify the message-format handler. If you are using the message-format handler in your client application code, you need to replace references to formatHandler. Instead, use the generated input or output bean to get the byte size directly. Listing 2 provides an example.

// ---------------------------------------------------
 // Populate the IMS transaction input message with
 // data.  Use the input message format handler method 
 // getSize() to set the LL field of the input message.
 // ---------------------------------------------------		 
 //INPUTMSGFormatHandler inFmtHndlr =new 

INPUTMSGFormatHandler();
 //INPUTMSG input = (INPUTMSG) inFmtHndlr.getObjectPart();
 // input.setIn__ll((short) inFmtHndlr.getSize());

//new J2C code
INPUTMSG input = new INPUTMSG();
 input.setIn__ll((short) input.getSize());		 

// ---------------------------------------------------
  // Retrieve the multi-segment output message as a 
 // byte array using the output message format
  // handler method getBytes().
  // ---------------------------------------------------
 // OutMsgFormatHandler outFmtHndlr =
//		 (OutMsgFormatHandler) 

output._getFormatHandler();
 // segBytes = outFmtHndlr.getBytes();

//new J2C code
  segBytes = output.getBytes();

//-----old wsadie 

code----------------------------------------------
// Create and populate segment object from byte array.
//-------------------------------------------------------------------------
 //OUTPUTSEG1FormatHandler outSeg1FH =
//new  OUTPUTSEG1FormatHandler();
// outSeg1FH.setBytes(buff);
//OUTPUTSEG1 S1 =
//(OUTPUTSEG1) outSeg1FH.getObjectPart();

//new J2C code		 		 		   
  OUTPUTSEG1 S1 = new OUTPUTSEG1();
  S1.setBytes(buff);

• Adding artifacts: If you want to generate additional artifacts, such as JSPs, EJBs, or Web services, you can do so by invoking the Web page, Web service, or EJBs from the J2C JavaBeans wizard.

Back to top

Tips for success

Installing multiple Rational products on the same workstation

You can install multiple Rational Software Delivery Platform products on the same workstation and in the same package group. For example, you can install Rational Application Developer V7.0 with J2EE Connector Architecture tools and IBM® Rational® Software Architect V7.0 with J2C tools to the same package group, where the two products share the the same J2C tool functions. There will be only one shared directory, and the connector tool will be installed there and shared by both Rational Application Developer and Rational Software Architect.

If you are using the J2EE connector command-line migration tool and need to modify the J2Cmigration.bat file to update the configurations, make a copy of it rather than using the source file. Rename the copy by using a naming convention that is tied to the Rational product instance so that you will not mix up which product instance uses which batch file.

Workaround for a command-line migration limitation

We recommend that you use the J2C Service Migration wizard to migrate all of your WSDL files, because it handles folder-based migration easily and painlessly. You typically run the migration only once. However, if you need to use the migration tool from the command line, here is a tip:

When migrating a folder of WSDL services files by the command-line migration tool's migrate-by-folder option, you cannot set individual WSDL projects to different types of projects. All of the migrated projects under the same folder source must be same type of project. Therefore, group all of the WSDL service files that you want in the same type of project into a separate folder. For example, if you need to create all of your CICS-ECI applications inside of EJB projects and all of your IMS applications inside of Web projects, group all of the CICS-ECI WSDL service files into one folder and all of the IMS WSDL service files into another folder. Then run the command-line migration once for each folder, with the options that you want to use.

For more information

As we stated earlier in this article, WebSphere Application Server V5.0 is out of service, as of September 2006. To find the out-of-service date of your version of the WebSphere Application Server, check IBM Software Support: Product Life Cycle.

For information on which WebSphere Application Servers will work on which CICS transaction gateways, see Supported Software for CICS Transaction Gateways (CICS TG).

You'll find links to these sources and other helpful information at the end of this article in Resources.

Resources

Learn

• To learn about how to migrate from VisualAge Java to WebSphere Studio Application, go the following links:
  • CCF to J2C Migration Part 1:CCF application limitations on WebSphere 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 3:Migrating VisualAge for Java CCF CICS-ECI applications into WebSphere Studio J2C CICS-ECI 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 VisualAge for Java CCF MQ applications into WebSphere Studio J2C JMS applications
  
  
• To find the out-of-service date of your version of the WebSphere Application Server, check IBM Software Support: Product Life Cycle.
  
  
• For information on which WebSphere Application Servers will work on which CICS transaction gateways, please see Supported Software for CICS Transaction Gateway (CICS TG)..
  
  
• Browse the technology bookstore for books on these and other technical topics.
  
  
• Stay current with developerWorks technical events and Webcasts.
  
  
• IBM Rational Application Developer product page: Find technical documentation, how-to articles, education, downloads, and product information about Rational Application Developer.
  
  

Get products and technologies

• Download a free trial version of Rational Application Developer V7.0.
  
  
• Download a free trial version of WebSphere Application Server Version 6.0.
  
  
• Complete your next development project with IBM trial software, available for download directly from developerWorks.
  
  
• Download IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
  
  

Discuss

• Participate in developerWorks blogs and get involved in the developerWorks community.
  
  
• Rational Software Architect, Data Architect, Software Modeler, Application Developer and Web Developer forum: Ask questions about Rational Application Developer.
  
  

About the authors

Ivy leads the Java Connector Tools team for Rational software. She earned a degree in mathematics with honors (major in computer science, minor in statistics) from the University of Waterloo and, in 1995, became a certified Project Management Professional (PMP).

Ernest is the chief architect and senior development manager of the Java Connector Tools team for Rational software. He has a master's degree in computer science.

Rate this article

Comments

Back to top

Table of contents

• Assumptions and requirements
• Necessity and benefits of migration
• Migration Planning
• Overview of product differences
• Migration paths
• Migration process
• Additional Information
• WebSphere Application Server
• Post-migration steps (Optional)
• Tips for success
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Buy: Rational Application Developer for WebSphere Software

Dig deeper into Rational on developerWorks

IBM SmartCloud trial. No charge.

Unleash the power of hybrid cloud computing today!

---

Public and private solutions in one trial.

Special offers