Migration Assistant V1.0

The Migration Assistant is part of the VisualAge WebRunner Toolkit from Taligent, Inc. The WebRunner Toolkit is a suite of tools, class libraries, and components created for developers of client-server applications using internet technologies. Taligent is a subsidiary of IBM specializing in products for builders of component-based applications in the enterprise.

Updates to the Migration Assistant documentation can be found at the Taligent WebRunner site.

• Migration Assistant description
• Installation instructions
• Migrate an ActiveX or OCX control
• Supported platforms
• Important notes

Migration Assistant

The Migration Assistant contains an automated tool that uses ActiveX information, available in the registry or a disk file, to create a set of methods, properties and enums that an equivalent Java bean would implement to achieve the same function. Data types are mapped from Windows-specific types to their equivalent Java types. 

The Migration Assistant provides a graphical interface that displays the individual elements of an ActiveX component that is loaded. You can choose either to produce a bean that implements the entire ActiveX component using provided default mappings or to customize the output. For creating a custom bean, the elements of the ActiveX are displayed in three categories - properties and methods, events and enums. You select the elements you want to include in the created bean. 

Once elements are selected to migrate, Java source code is generated as a framework for subsequent 100% Java implementation. Generated event code is incorporated into the JavaBeans event handling model. The Java bean is fully compliant with the JDK 1.1 and JavaBeans specifications. 

The Java bean is now ready to accept the component implementation code. Typically this will involve copying C++ code into the generated bean, converting the language constructs to Java (mostly trivial) and adapting code to Java libraries. 

Installation and De-installation Instructions

To install the Migration Assistant tool, choose one of the following methods:

• from a Windows command line
  1. use the CD command to move to the directory containing the downloaded file
  2. type mgrt10
     
• from the Windows Start menu
  1. choose Run
  2. in the Run dialogue box, type in the location of the downloaded mgrt10.exe file (or choose Browse to locate it), then click on OK

To de-install the Migration Assistant tool:

• from the Windows Start menu
  1. choose Settings then Control Panels
  2. double-click the Add/Remove Programs icon and follow its instructions

Migrate an ActiveX or OCX control

1. Launch the Migration Assistant

   From the Windows Start button, select Migration Assistant.

2. Choose an ActiveX control to migrate
   1. In the Migration Assistant dialog box, choose Select OCX from the File menu. (Alternatively, click the Select OCX icon on the toolbar.) The Available Controls dialog box appears.

   2. In the Available Controls dialog, which shows all the ActiveX controls installed on your machine, select a control from the list. (Alternatively, click on the Browse button in this dialog to bring up an Open dialog where you can select an .ocx or .tlb file directly.)

      When you click OK to close the dialog, the properties and methods, events, and enums interfaces of the control chosen appear in the left-hand listboxes of the Migration Assistant dialog box.

3. Choose the control's interfaces you wish to migrate
   1. From the listboxes titled Available... in the Migration Assistant dialog box, choose the interfaces you wish to migrate
      • To add interfaces one at a time to the list of interfaces selected for migration, click on the interface item and then the Add button. The interface will be added to the Selected Interfaces list on the right hand side of the dialog box.
      • To add all the available interfaces to the list of interfaces selected for migration, simply click the Add All button. All the Available Interfaces will be added to the Selected Interfaces list.
      • To remove an interface from the Selected Interfaces list, select the entry in the list and then click the Remove button.
      • To examine the details of the properties, methods, or enums associated with an interface, simply select the interface in either the Available or Selected interface lists. The details will appear in the middle box of the dialog box.
        
   2. Fill in the Package Name text field with the name you wish the package to have. The default package name is ocx.

4. Generate the Java bean files
   1. From the File menu, choose Generate JavaBean. (Alternatively, you can click the Generate JavaBean icon on the toolbar.)
   2. In the resulting Save dialog box, indicate the directory into which you wish the generated files placed then click OK. The Migration Assistant's status bar will read Code Generation Complete when this operation is finished.

   The target directory will now contain the generated source files and a build.bat file.

5. Fill in the skeleton

   Add the necessary Java code to the generated skeleton (source files) to allow the bean to fulfill the semantics of the original ActiveX control.

   Note 1: For help in porting C++ code to Java, see Taligent's Java Cookbook.
   Note 2: If you just want to build the skeletal bean to view in the Bean Tools Tester, you can proceed to the next step without filling in the bean's functionality.

6. Build a bean
   1. Move to the directory that you chose for the generated files
   2. To build the bean, execute the build.bat file you find in that directory. Be patient, this may take a few minutes. When the build is finished, you will have a .jar file in the directory.

   After you have built the bean, use Sun's BeanBox or Taligent's Bean Tools Tester to try it out.

7. Finally, use the JavaBeans bridge to ActiveX provided by JavaSoft to replace the original ActiveX control with the new bean.

Important Notes

• The code that is generated by Migration Assistant may need to be modified or added to in order for it to compile and/or work with the JavaBeans Bridge for ActiveX from JavaSoft. In order for the generated bean to fulfill the semantics of the original ActiveX control, Java code will very likely need to be added to the generated skeleton.

• The bean will be generated as a subclass of awt.Component if there are "stock events" in the ActiveX control that map to Component-related events. "Stock properties" will also be mapped to Component-related properties. Stock ActiveX properties that match exactly in name with Component properties or are mapped by the JavaBeans Bridge for ActiveX (e.g. "Font") will not be generated and a comment will indicate this.

• While every attempt has been made to avoid collisions with methods defined in base classes, generated methods may collide with methods already defined in Java base classes such as awt.Component or EventObject that have different signatures. If this happens, change the name of the generated method. This may cause the interface under the JavaBeans bridge to appear different from the original ActiveX control.

• If an ActiveX type library has multiple controls inside it, the control you want must be selected from the "Available Controls" listbox (as opposed to "browsing" to it from the "Open" file dialog). If the control has not already been installed, it will need to be installed and then selected from the "Available Controls" listbox.

• If there is no type information in the file specified, a message box will alert you to this fact. Currently, you will need to locate the associated .tlb file manually, using the "Open" file dialog.

Platform Notes

Migration Assistant is intended for use on the Windows NT 4.0 and Windows 95 platforms. If you use Migration Assistant on the Windows 95 platform, you may find the following hints helpful: 

• You might encounter an "Out of environment space" problem when launching the applications from the Program group. To correct this problem, add the following line to your config.sys file: 

  shell=X:\command.com /e:4096 /p 

  where "X:" is the drive path to where your Windows 95 operating system is installed. 

• You may get a "MSVCRT.DLL not Found" error. This file is required to run java.exe. To correct this problem, copy your Windows 95 MSVCRT40.DLL over to MSVCRT.DLL as follows (in a single command string):

  copy X:\WINDOWS\SYSTEM\MSVCRT40.DLL X:\WINDOWS\SYSTEM\MSVCRT.DLL  

  where "X:" is the drive path to where your Windows 95 operating system is installed. 

• If you open the Migration Assistant, generate files, and then close the Assistant, the DOS window which brought up the Assistant will say the Assistant is finished but will not close automatically. Simply close the window manually by clicking on the close button (X) in the extreme upper right corner of the DOS window.