Export (0) Print
Expand All
3 out of 3 rated this helpful - Rate this topic

Migrating Java Applets to Microsoft J# Browser Controls

Visual Studio .NET 2003
 

Visual J# .NET Team
Microsoft Corporation
April 2004

Summary: Microsoft J# Browser Controls allow developers to migrate Java applets that were written to run on a Java Virtual Machine to the .NET Framework. This paper introduces developers to J# Browser Controls and explains the steps to migrate Java applets to the .NET Framework. It also covers topics such as security and debugging for J# Browser Controls and the unsupported features in the current release.

Download the HTML Applet to Object Tag Converter (95KB)


This paper assumes that the developer is familiar with the .NET Framework and Visual J# .NET. To download the J# Browser Controls runtime, see http://msdn.microsoft.com/vjsharp/downloads/browsercontrols/)

Contents

Introduction
New Features
Compiling a Java Applet to a J# Browser Control
Updating the HTML Page to Use J# Browser Controls
Deploying J# Browser Controls
Running J# Browser Controls on User Computers
Unsupported Features in the Current Release
Conclusion

Introduction

A Java applet that has been migrated to the .NET Framework using Visual J# .NET is called a J# Browser Control. J# Browser Controls are intended to allow customers to migrate their existing Java applets to the .NET Framework.

A J# Browser Control has similar run-time behavior as the Java applet it was migrated from and preserves Java-language semantics. If the J# Browser Control runtime is installed on the computer, a user might not even be aware that a particular Web site has upgraded its Java applets to J# Browser Controls.

To migrate Java applets to J# Browser Controls, you must install the Visual J# .NET version 1.1 Redistributable Package and the .NET Framework SDK version 1.1 or Visual Studio® .NET 2003. Similarly, users who want to run J# Browser Controls hosted by a Web site must have the .NET Framework 1.1 Redistributable and the J# Browser Control runtime installed on their computers. J# Browser Controls are not intended to be run on a Java Virtual Machine. J# Browser Controls can only be run in Microsoft Internet Explorer (version 5.1 and later).

Migrating a Java applet to a J# Browser Control involves three steps:

  1. Compiling the Java applet to a J# Browser Control using the Visual J# compiler
  2. Updating the HTML Page to use the J# Browser Control instead of the Java applet.
  3. Copying the J# Browser Control and HTML page to the Web server.

New Features

The following features are added in J# Browser Controls v1.1b

Offline Support

Microsoft J# Browser Controls v1.1b now supports loading controls in Internet Explorer without a Web server. The following scenarios are now enabled:

  • Loading controls from a local file system
  • Loading controls from network shares
  • Loading controls from network drives

In all of the above scenarios, J# Browser Controls will run with Intranet permissions by default.

Scripting Support

Microsoft J# Browser Controls v1.1b supports the following scripting scenarios.

  • Scripts invoking methods and accessing properties of J# Browser Controls
  • Invoking scripting events from J# Browser Controls
  • J# Browser Controls accessing elements within the page exposed by Internet Explorer object model using Netscape JavaScript APIs.

J# Browser Controls v1.1b also provides full support for the Netscape JavaScript API functionality. The netscape.javascript applet API package has the following classes:

  • netscape.javascript.JSObject
  • netscape.javascript.JSException

Compiling a Java Applet to a J# Browser Control

A Java applet can be migrated to a J# Browser Control by compiling it to a managed library using the Visual J# compiler (vjc.exe). Java applet sources can be compiled to a J# Browser Control either from the command prompt or from Visual Studio .NET. If the Java applet was developed using Microsoft Visual J++ 6.0, it may simply involve upgrading the project to Visual J# .NET using Visual Studio .NET.

Compiling a Java applet to a managed library is similar to compiling any other library in Visual J#. In most cases, compiling a Java applet to a managed library will not require any changes to the Java applet source code because the J# Browser Controls runtime provides support for much of the functionality in the Microsoft Java Virtual Machine. This includes support for the functionality in the JDK 1.1.4 level packages and the java.applet package.

Managed libraries containing J# Browser Controls are no different from other managed libraries in the .NET Framework. When a user visits a Web site hosting a J# Browser Control, the J# Browser Controls runtime will download the managed library and run it in Internet Explorer.

Creating J# Browser Control using Applet Class Files

If only the Java-language bytecode (.class files) exists for the Java applet, the Visual J# Binary Converter Tool (JbImp.exe) can be used to convert the Java applet to a managed library.

Compiling a Java Applet from the Command Prompt

You can compile a Java applet from the command line using the Visual J# compiler (vjc.exe). For example:

C:\AppletSources>vjc.exe /target:library /out:MyApplet.dll *.java

This command will compile Java applet source files (with the .java extension) to a new .NET Framework DLL named MyApplet.dll

You can also use the Visual J# Binary Converter Tool:

C:\AppletSources>jbimp.exe /target:library /out:MyApplet.dll *.class

If you have Visual Studio .NET installed, the Visual J# compiler (vjc.exe) and the Visual J# Binary Converter Tool (JbImp.exe) are accessible from the Visual Studio .NET command window. If you do not have Visual Studio .NET installed, you must ensure that these tools are in the path in your command prompt.

When migrating Java applets that use resources, you must follow the steps described in Upgrading Visual J++ 6.0 Applications That Use Resources and HowTo:Resources in Visual J# .NET.

Migrating a Java Applet Using Visual Studio .NET

If the Java applet is a Visual J++ 6.0 project, it can also be migrated using Visual Studio .NET.

To upgrade a Visual J++ 6.0 project using Visual Studio .NET

  1. Open the Visual J++ 6.0 project in Visual Studio .NET. This starts the Visual J# .NET project upgrade wizard.
  2. Click Next through all steps of the upgrade wizard. The upgrade wizard converts the Visual J++ project to a Visual J# .NET Class Library project.
  3. Open the upgrade report to see if the wizard detected any issues during the upgrade.
    Note   The report will say Applet projects are not supported. You can ignore this error. You must fix any other issues listed in the upgrade report before building the project.
  4. Build the project. This compiles the Java applet to a managed library.

You cannot start J# Browser Controls in Internet Explorer from Visual Studio by clicking Debug and then Start or pressing F5. You must copy the control to a virtual directory on a Web server to run it. For more information, see Deploying J# Browser Controls and How to: Debug J# Browser Controls.

For more information on upgrading Visual J++ 6.0 projects to Visual J# .NET, see Upgrading from Visual J++ 6.0.

Additional Steps for Applets Using the Netscape LiveConnect API

In addition to the migration steps found in the white paper above, developers will need to reference an additional assembly while compiling applets that use the Netscape LiveConnect API. Support for the LiveConnect API functionality is provided in J# Browser Controls v1.1b.

Note   To include a reference to this assembly, developers migrating applets utilizing the Netscape Jscript API need to install J# Browser Controls v1.1b on their development machines.

To compile from the command line, include the reference in the following manner:

vjc /r:"%ProgramFiles%\Microsoft JSharp Browser Controls v1.1\vjsjbc.dll"/t:l MyApplet.java

If you are using Visual Studio® .NET 2003, you need to add a reference to this assembly in your reference list. For more information, see Add Reference Dialog Box.

If you are using JbImp, use the following to convert your Java applet .class file to a J# Browser Control assembly.

jbimp /r:"%ProgramFiles%\Microsoft JSharp Browser Controls 
v1.1\vjsjbc.dll" /t:l MyApplet.class

Updating the HTML Page to Use J# Browser Controls

After a Java applet is compiled to a J# Browser Control, the next step is to update the HTML pages to now use the migrated control. The <APPLET> tag or the Java <OBJECT> tag in the HTML page must be converted to an <OBJECT> tag referring to the J# Browser Control.

This white paper includes a sample tool called the HTML Applet to Object Tag Converter (TagConvert.exe) that automatically upgrades HTML pages to use J# Browser Controls. The link to download this sample tool is at the top of this whitepaper. Download and run TagConvertSetup.exe to install the HTML Applet to Object Tag Converter (TagConvert.exe).

The tool can be used as follows:

TagConvert [options] <source files>

For example:

TagConvert.exe MyAppletPage.html

The input to the tool can be any text file and can include files with the .html, .htm, .asp, and .aspx extensions.

The tool replaces the <APPLET> tag or the Java applet<OBJECT> tag with HTML code that contains the following J# Browser Control <OBJECT> tag:

<OBJECT   
CLASSID="clsid:a399591c-0fd0-41f8-9d25-bd76f632415f"
WIDTH= pixels
HEIGHT= pixels
ID=browserControlName
ALIGN= alignment
HSPACE= pixels
VSPACE= pixels
VJSCODEBASE = codebaseURL
>   
<PARAM NAME = parameter1 VALUE = value>   
<PARAM NAME = parameter2 VALUE = value>   
   . . .   
alternateHTML   
</OBJECT>   

where:

CLASSID
The CLASSID of the ActiveX control that downloads and executes J# Browser Controls. This exact CLASSID must be used in the J# Browser Controls <OBJECT> tag.
VJSCODEBASE
The URL of the J# Browser Control class and the managed library containing this class. The '#' token separates the managed library file name and the J# Browser Control class name. The VJSCODEBASE attribute value needs to be enclosed in quotes if the file name includes a space character. The file name must also include the file extension. For example:
VJSCODEBASE = 
http://www.microsoft.com/MyApplet/MyAppletClass.dll#MyAppletClass

The codebase can also be a relative URL. For example: If the page is at http://www.microsoft.com/MyApplet/MyAppletPage.htm

VJSCODEBASE = 
MyAppletClass.dll#MyAppletClass

refers to the browser control MyAppletClass in MyAppletClass.dll at http://www.microsoft.com/MyApplet/.

If you choose to manually update your HTML pages, you can do so by replacing the <APPLET> or Java applet <OBJECT> tag with the above J# Browser Control <OBJECT> tag. However, it is recommended that you use the sample tool as it generates additional HTML code that enhances your browsing experience.

Conversion Process

When converting HTML pages, the tool deletes the original <APPLET> tag or Java applet <OBJECT> tag and replaces them with HTML code that also includes the J# Browser Control <OBJECT> tag previously described.

The tool creates a backup of the original files before converting the tags. Backup copies of files will have the .vjsbak extension. For example, index.htm will be backed up as index.htm.vjsbak. The backup file is created in the directory of the original file.

The tool uses the values in the CODE and CODEBASE attributes of the original <APPLET> tag (or Java applet <OBJECT> tag) to create the value of the VJSCODEBASE attribute. For example:

CODE = "MyAppletClass"
CODEBASE = http://www.microsoft.com/MyApplet

is modified to:

VJSCODEBASE = 
http://www.microsoft.com/MyApplet/MyAppletClass.dll#MyAppletClass

By default, the tool assumes that the name of the J# Browser Control class (for example, MyAppletClass) to be the same as the name of the DLL (MyAppletClass.dll). If the names of the J# Browser Control class and the DLL are different, you will have to modify the VJSCODEBASE attribute value appropriately. Therefore, when using this tool, it is recommended that you compile the Java applet to a managed library with the same name as the applet class. For example:

C:\MyAppletClassSources>vjc /target:library /out:MyAppletClass.dll *.java

The J# Browser Controls runtime only supports the HTTP, FILE and HTTPS protocols in the VJSCODEBASE attribute. When a relative path is specified, the J# Browser Control is loaded using the protocol with which the html page is loaded. J# Browser Controls do not support loading controls from a location that is different from the DOCBASE. The value in VJSCODEBASE must be the same as the DOCBASE or must be one of the subdirectories of DOCBASE. DOCBASE refers to the location from where the HTML page is loaded.

Many attributes of the OBJECT are left intact during the conversion. The details of attributes converted by TagConvert are specified in the following section. Many parameters in the J# Browser Controls <OBJECT> tag are the same as the corresponding parameters of the <APPLET> or Java applet <OBJECT> tag.

Command-Line Options

The supported command-line options are:

/recurse:<wildcard>
Search the current directory and all subdirectories for files to convert according to the wildcard specifications. For example:
TagConvert /recurse *.htm *.html 

upgrades all files with the .htm and .html extensions in the current directory and its subdirectories.

/verbose
Print the names of files changed during the conversion run. The file name includes the fully qualified path to the file. The tool also prints the total number of files parsed and total number of files converted. For example:
TagConvert /verbose \AppletSources\Pages\*.htm > changedfiles.txt 

upgrades all files with the .htm extension in the specified directory and dumps the names of files modified to the changedfiles.txt file.

/nologo
Suppresses the copyright message from being shown. For example:
TagConvert /nologo \AppletSources\Pages\*.htm 

upgrades all files with the .htm extension in the specified directory and suppresses the copyright message.

Attribute Mapping Between <APPLET> Tag and J# Browser Controls <OBJECT> Tag

The following table shows the mapping between the attributes in the <APPLET> tag and the attributes in the J# Browser Control <OBJECT> tag.

<APPLET> tag syntax (includes Internet Explorer extensions) J# Browser Controls <OBJECT> tag syntax
CODEBASE VJSCODEBASE
CODE VJSCODEBASE
WIDTH WIDTH
HEIGHT HEIGHT
NAME ID
ID ID
ALIGN ALIGN
VSPACE VSPACE
HSPACE HSPACE
ARCHIVE Deleted and unsupported in the current release
ALT ALT
<PARAM> <PARAM>
<PARAM NAME = FireScriptEvents VALUE = True> Left intact but unsupported in the current release
<PARAM NAME = cabbase VALUE = cabFileName>
<PARAM NAME = cabinets VALUE = cabFileNames>
Left intact but unsupported in the current release
<PARAM NAME = useslibrary VALUE = DUFriendlyName>
<PARAM NAME = useslibrarycodebase VALUE = DUFileName>
<PARAM NAME = useslibraryversion VALUE= DUVersionNumber>
Left intact but unsupported in the current release
<PARAM NAME = namespace VALUE = applicationNamespace> Left intact but unsupported in the current release

In the current release, the following attributes in the <APPLET> tag are unsupported and have no equivalent attributes in the J# Browser Controls <OBJECT> tag:

  • The archive, cabbase and cabinets attributes. Packaging J# Browser Controls into .cab, .zip, or .jar files is not supported in the current release. J# Browser Controls must be deployed to the Web server as stand-alone .dll files.
  • The useslibrary, useslibrarycodebase, useslibraryversion and namespace attributes. The J# Browser Controls runtime does not support the Java Package Manager semantics of MSJVM.

The attributes in the <APPLET> tag that have direct equivalents in the <OBJECT> tag can be copied as is. They have the same meaning in the J# Browser Controls <OBJECT> tag as in the original <APPLET> tag.

When the <APPLET> or Java applet <OBJECT> tags have the NAME as well as the ID attributes then the NAME attribute is deleted and the value in the ID attribute is used.

Deploying J# Browser Controls

Deploying a J# Browser Control is as simple as copying the managed library and updated HTML page to the appropriate directory on either the Web server or the user’s machine. The Web Server is no longer a requirement to deploy J# Browser Controls. The managed library must be copied either to the same directory as the HTML page or to a subdirectory.

When using the IIS Web server, the Execute Permissions field on the virtual directory must be set to Scripts only, the default permission level of a virtual directory in IIS.

Deploying a Multi-DLL Browser Control

A J# Browser Control can be split into multiple DLL files. In such cases, the DLL containing the main J# Browser Control class must be referenced in the HTML page. The J# Browser Controls runtime will download additional DLLs as required at run time.

When deploying a multi-DLL control, all files related to the same J# Browser Control must be copied to the same directory. The files must be copied as standalone files and cannot be packaged into .cab, .zip, or .jar files.

Packaging Multiple J# Browser Controls into the Same Library

Multiple J# Browser Controls can also be packaged into the same managed library. In such cases, the <OBJECT> tag for each J# Browser Control must point to the same managed library but different class names. For example, if MyApplets.dll in the virtual directory called AppletDir contains J# Browser Controls with the names MyApplet1 and MyApplet2, you can refer to the two J# Browser Controls as shown in the following example:

VJSCODEBASE="http://www.microsoft.com/AppletDir/MyApplets.dll#MyApplet1"
VJSCODEBASE="http://www.microsoft.com/AppletDir/MyApplets.dll#MyApplet2"

Because J# Browser Controls can only be downloaded from the same location as the HTML page or one of its subdirectories, you may need to copy the managed library to multiple locations if the directories of the HTML pages differ.

Running J# Browser Controls on User Computers

End users do not need to know about J# Browser Controls other than installing the J# Browser Controls runtime on their computers.

Installing J# Browser Controls Runtime Support on User Computers

Before users can view and use J# Browser Controls in Internet Explorer, the J# Browser Controls runtime must be installed on user computers. You and your site administrator need to provide a way for end users to download and install J# Browser Controls. The J# Browser Controls runtime also supports installation using SMS or Group Policy. For more information on deploying J# Browser Controls using SMS or Group Policy, see http://www.microsoft.com/smserver/techinfo/deployment/20/default.asp or http://www.microsoft.com/windows2000/techinfo/reskit/dpg/default.asp.

Security Behavior of J# Browser Controls

By default, the J# Browser Controls runtime prompts end users before running controls hosted on Web pages in the Internet. When a user browses to an Internet Web site that contains a J# Browser Control, the following dialog box is displayed:

The J# Browser Control will be downloaded and run if the user clicks Yes. Clicking No will prevent the J# Browser Control from being run.

Selecting the Add this site to the list of sites allowed to run J# Browser Controls and don't ask me again check box and clicking Yes will add the Web site to the list of sites allowed to run J# Browser Controls, and the user will not be prompted for pages on the Web site on subsequent visits. The default value of this checkbox is set to selected.

The J# Browser Controls runtime does not prompt the user when running from Web sites on the Intranet.

The user can also use the J# Browser Controls security options dialog box available under Administrative tools in Control Panel to manage the list of sites allowed to run J# Browser Controls. In Windows XP, you can access this dialog box from Performance and Maintenance in Control Panel. In Windows 98 and Windows Millennium Edition, you can access this dialog box from the Administrative tools menu in the Start menu. Double-click the J# Browser Control Security icon to open the following dialog box:

The options are:

Disable J# Browser Controls
Prevents J# Browser Controls from any Web site from being run on the computer.
Only from Web sites in this list
Only J# Browser Controls from Web sites in the list are allowed to run.
Only on the Intranet and from Web sites in this list
Only J# Browser Controls from the Intranet or from Web sites in the list are allowed to run on the computer. This is the default setting.
On any Web site
J# Browser Controls from any Web site are allowed to run on the computer. This option is not recommended and should be selected with care.

Entering the address of a Web site in the Add Web site text box and clicking Add adds the Web site to the list of sites allowed to run J# Browser Controls. Similarly, selecting a Web site from the Web sites allowed to run J# Browser Controls list and clicking Remove removes the site from the list. When a Web site is added to the list of sites allowed to run J# Browser Controls, the user is not prompted before running J# Browser Controls on the Web site.

By default, the Prompt to add new Web sites to this list in the future check box is selected, which causes the J# Browser Controls runtime to prompt the user before running J# Browser Controls from Web sites not in the list. When this check box is cleared, J# Browser Controls from Web sites not in the list are not run and the user is not prompted.

Unsupported Features in the Current Release

The following features are unsupported in the current release of J# Browser Controls:

  • Trust-based security

    There is no support for trust-based security semantics as supported by MSJVM. When Java applets are migrated to J# Browser Controls, they use the security semantics described in Security Semantics for J# Browser Controls.

  • Java Package Manager

    The Java Package Manager functionality as supported in MSJVM is unsupported in J# Browser Controls. J# Browser Controls do not support an object cache that can be used to install classes locally and then run them with a restricted set of permissions using permission signing. Therefore, there is also no support to install and run Distribution Units.

  • Archive files

    Archive files are unsupported. A J# Browser Control can be split into multiple managed libraries. However, when deploying a multilibrary control to a Web server, the files must be copied as stand-alone files and must not be packaged into .cab, .zip, or .jar files.

  • Java Console Support

    The Java Console in Internet Explorer is not supported with J# Browser Controls v1.1b. However, for debugging a J# Browser Control using console print statements from code, the output of Internet Explorer can be redirected to a file.

    %Program Files%\Internet Explorer\IExplore.exe [html address] > 
    [output file path] 2> [error file path]
    
  • Support for all event syntax

    All event syntax is not supported in this release. Only the following syntax is supported.

    <SCRIPT language="JavaScript" for="MyAxClass1"        
    event="dataUpdated(atTime, msg)">
    alert("Event occurred. Event Name= dataUpdated, " +              
    "Time= " + atTime + ", Message= " + msg );
    </SCRIPT>
    
  • No designer support

    There is no designer support in Visual Studio .NET for J# Browser Controls.

Conclusion

J# Browser Controls provide developers with a way to migrate their Java applets to run on the .NET Framework. J# Browser Controls have the same runtime behavior as the Java applets they were migrated from and preserve Java-language semantics. J# Browser Controls also have full access to the .NET Framework, including the ability to access native support for XML Web services. They also provide J# developers with a way to enable rich, client-side functionality within a Web-based application.

See Also

Visual J# .NET Articles | Classes Accessible to a J# Browser Control | How to: Debug J# Browser Controls | Security Semantics for J# Browser Controls | Supporting J# Browser Controls and Java Applets in the Same Page

Show:
© 2014 Microsoft. All rights reserved.