Microsoft Visual J#® 2.0 Redistributable Package – Second Edition (x86/x64/IA64) Readme

Microsoft Visual J#® 2.0 Redistributable Package – Second Edition (x86/x64/IA64) Readme

Table of Content

1. Introduction

2. 32-bit Feature Set

3. 64-bit Feature Set

3.1 Enabled Components
3.2 Non-Enabled Components
3.3 Visual J# Compiler Changes
3.4 MSBuild Support

4. Leveraging Existing 32-bit Visual J# Code

5. Leveraging Existing Windows Investments

6. Known Issues

7. New Compiler Messages

-------------------

1. Introduction
Microsoft Visual J# 2.0 Redistributable Package – Second Edition enables Visual J# applications to run natively on 64-bit platforms. This document outlines the various features of the Microsoft Visual J# 2.0 Redistributable Package – Second Edition. It also outlines the known issues of the product.

2. 32-bit Feature Set
Microsoft Visual J# 2.0 Redistributable Package – Second Edition(x86) supports all runtime features shipped in the previous versions of Visual J# Redistributable (v2.0). The MSDN Visual J# Documentation details the features shipped as a part of the previous version of the J# Redistributable.

3 64-bit Feature Set
Microsoft Visual J# 2.0 Redistributable Package – Second Edition for 64-bit platforms (x64 and IA64) contains support for a subset of features that shipped in previous 32-bit versions of Visual J# Redist (v2.0 and earlier). This section discusses the feature set enabled for the 64-bit Editions.

3.1 Enabled Components

The following Visual J# components are now enabled for 64-bit platforms:
• Class library support: Class library support equivalent to most of the Java Development Kit (JDK) level 1.1.4 packages that were included in Visual J++ 6.0 are enabled to run natively on 64-bit platforms. Some classes which support functionality equivalent to that of JDK level 1.2 (for more information, see Additional Class Library Support) are also enabled for native 64-bit execution using Visual J#.
• Visual J# compiler: The changes are discussed in detail in the section named Visual J# Compiler Changes.
• MSBuild support: The changes are discussed in detail in the section named MSBuild Support.
• WoW support: Apart from support for native 64-bit execution, Windows on Windows (WoW) support is also enabled for J# applications after you install Microsoft Visual J# 2.0 Redistributable Package – Second Edition on 64-bit platforms (x64 and IA64).

3.2 Non-Enabled Components

The following Visual J# components are not enabled for native execution on 64-bit platforms:
• JavaCOM support: There is no support for JavaCOM. A compile-time error occurs if you use the @com directive when targeting anything but the 32-bit platform. The “/jcpa” option is supported by 64-bit Visual J# compiler only when specified with “/platform:x86” option.
• J/Direct® support: There is no support for J/Direct. A compile-time error occurs if you use the @dll directive when targeting anything but the 32-bit platform.
• J++ delegates support: There is no support to author J++ delegates. A compile-time error occurs if you reference the com.ms.lang.Delegate type when targeting anything but the 32-bit platform. Use of “multicast” keyword is deprecated.
• WFC support: There is no support for Windows Foundation Classes (WFC). A 64-bit specific vjswfc*.dll is not part of the 64-bit versions of Microsoft Visual J# 2.0 Redistributable Package – Second Edition. A compile-time error occurs if you use WFC except when targeting the 32-bit platform.
• Jbimp tool (Java Bytecode to MSIL Converter): There is no support for the tool to generate 64-bit ready MSIL.
• Design-time application development: There is no certified support for Visual J# application development from the Visual Studio integrated development environment (IDE).

3.3 Visual J# Compiler Changes

The Visual J# compilers (both 32-bit and 64-bit) now support a new command-line switch “/platform” with the following available options for cross-compilation:
• x86: for use when target platform is x86.
• x64: for use when target platform is AMD64 (or x64).
• itanium: for use when target platform is IA64.
• anycpu: for use when application is portable across architectures.

To be compatible with the previous releases of Visual J# Redistributable, the code generated by the 32-bit and WoW Visual J# compiler that ships with Microsoft Visual J# 2.0 Redistributable Package – Second Edition targets the x86 platform by default. To run the existing Visual J# applications natively on 64-bit platforms, rebuild the existing applications by using the /platform switch and create anycpu or 64-bit platform-specific applications.

The code generated by the 64-bit Visual J# compiler that ships with Microsoft Visual J# 2.0 Redistributable Package – Second Edition targets the anycpu platform by default. Use the option that is specific to the particular 64-bit platform architecture type (x64 or itanium) while compiling for that 64-bit platform. Similarly, use the x86 option when compiling the application for a 32-bit platform from the 64-bit Visual J# compiler.

3.4 MSBuild Support

MSBuild is a build platform for Microsoft and Visual Studio. Details about MSBuild tasks are documented here.

Microsoft Visual J# 2.0 Redistributable Package – Second Edition comes with MSBuild support enabled (including cross compilation) from the command-line. This enables you to build Visual J# projects (.vjsproj) and solution (.sln) files that are created with Visual Studio 2005 from the command-line by using MSBuild.

All Visual J# project and solution files that are created with Visual Studio 2005 default to the x86 architecture type. Modify the project and solution files to build them to a different architecture type as specified below:
• anycpu, x64, or IA64 architecture types if using the 32-bit (or WoW) MSBuild task.
• x86, x64, IA64 or anycpu type if using the 64-bit MSBuild task.

The reason for the above behavior is that the 32-bit or WoW MSBuild task, which is present at %SystemRoot%\Microsoft.Net\Framework\v2.0.50727, by default emits 32-bit (x86) architecture type binaries. The 64-bit MSBuild task, which is present at %SystemRoot%\Microsoft.Net\Framework64\v2.0.50727, by default emits anycpu binaries. This behavior is different from the default behavior that is expected from Visual J# project and solution files that are generated by Visual Studio 2005.

To build applications for a specific platform architecture type by using MSBuild, follow either of the following procedures:

1. Build the *.vjsproj files with the “/property:platform=XXX” option.
2. Build the *.sln files with the “/property:platform=XXX” option.

XXX above specifies the targeted platform type (anycpu/x86/x64/itanium).

For Option1 (building the *.vjsproj file), add a new Property Group section to the *.vjsproj file that is generated by Visual Studio 2005 as illustrated below:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'YYY|XXX' ">
<DebugSymbols>true</DebugSymbols>
<DebugType>full </DebugType>
<Optimize>false</Optimize>
<OutputPath>bin\Debug\</OutputPath>
<PlatformTarget>XXX</PlatformTarget>
<DefineConstants>DEBUG;TRACE</DefineConstants>
</PropertyGroup>

The value of YYY is the Configuration (Debug/Release), and the value of XXX is the Platform (anycpu/x86/x64/itanium). For example:

<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|x64' ">
<DebugSymbols>true</DebugSymbols>
<DebugType>full </DebugType>
<Optimize>false</Optimize>
<OutputPath>bin\Debug\</OutputPath>
<PlatformTarget> x64</PlatformTarget>
<DefineConstants>DEBUG;TRACE</DefineConstants>
</PropertyGroup>

If you are building for the x86 platform type, ensure that x86 PlatformTarget is inserted in the existing PropertyGroup condition for x86 platform.

Values other than PlatformTarget should also be changed as desired in the Property Group section.

For Option 2 (building the *.sln file), modify all the *.vjsproj files which are a part of the solution as explained above and modify the *.sln file as described below:

• In the GlobalSection(SolutionConfigurationPlatforms) and GlobalSection(ProjectConfigurationPlatforms) sections, add the "Configuration>|<Platform>" preSolution and postSolution that you have included in your *.vjsproj files. For example, imagine that you had added Debug|x64 as above, and the original *.sln file resembled the following example:

GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|x86 = Debug|x86
Release|x86 = Release|x86
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Debug|x86.ActiveCfg = Debug|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Debug|x86.Build.0 = Debug|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Release|x86.ActiveCfg = Release|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Release|x86.Build.0 = Release|x86

EndGlobalSection

Following is the modified result:

GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|x86 = Debug|x86
Release|x86 = Release|x86
Debug|x64 = Debug|x64
EndGlobalSection
GlobalSection(ProjectConfigurationPlatforms) = postSolution
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Debug|x86.ActiveCfg = Debug|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Debug|x86.Build.0 = Debug|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Release|x86.ActiveCfg = Release|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Release|x86.Build.0 = Release|x86
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Debug|x64.ActiveCfg = Debug|x64
{E2D2EA3E-0E77-4C82-8AA4-D94FFC1EB7F6}.Debug|x64.Build.0 = Debug|x64
EndGlobalSection

Note: For Option 2 (building the *.sln file), the following points need to be addressed:
• Because adding new options at the beginning of the .sln file changes the default compile properties of the file, this is not the recommended approach.
• If a solution has multiple projects which must be compiled for different platforms, iterate through each J# project and compile them separately instead of compiling them as a single solution file.

Note: Visual Studio is not certified to recognize and open project and solution files that are edited manually. To use Visual Studio 2005 to open and edit the project or solution files, the recommended approach is to maintain a separate copy of the files for manual editing.

4 Leveraging Existing 32-bit Visual J# Code

The 64-bit editions (x64 and IA64) of Microsoft Visual J# 2.0 Redistributable Package – Second Edition enable users to take full advantage of the 64-bit .NET Framework (v2.0 and v3.0) and the underlying 64-bit hardware platform without having to deal with differences between the 32-bit and 64-bit hardware platforms. To know more about the differences on the two platforms see the whitepaper here.
In most cases, Visual J# applications that were developed by using previous versions of Visual J# Redistributable targeting the 32-bit platform can be recompiled by using the Visual J# compiler that ships with Microsoft Visual J# 2.0 Redistributable Package – Second Edition and can be executed as 64-bit native applications without source code modifications. However, 32-bit Visual J# applications that have dependencies on floating-points, native code (for example, DLLs or COM InProc Servers) or the feature set that is not supported may require modifications when porting to 64-bit platforms.
To use the existing 32-bit code on the 64-bit platform, the application must be recompiled on a computer with the Microsoft Visual J# 2.0 Redistributable Package – Second Edition compiler by using the ‘/platform’ compiler switch as discussed in Visual J# Compiler Changes.
Though it would be great to never know about the differences of the underlying platforms, a few scenarios which developers must address are available in the whitepaper here.
Following are a few more feature areas supported by Visual J# for which a source code change would be needed to execute the applications natively on 64-bit platforms:

32-bit vs. 64-bit Platform Difference	Recommendation(s)
JavaCOM	Use .NET COM interop instead of COM interop.
J/Direct	Use .NET PInvoke instead of making native calls.
J++ delegates	Use .NET delegate to author delegates.
WFC	Use Windows Forms to write controls.

5 Leveraging Existing Windows Investments

There are two mainstream 64-bit processor architectures available today:
• The Intel Itanium (IA64) processor family which is based on Explicitly Parallel Instruction Computing (EPIC).
• The x64 processors like the AMD Opteron and Intel Xeon with Extended Memory 64 Technology (EM64T) which are based on extensions to the x86 instruction set.

The 64-bit versions of the Microsoft Visual J# 2.0 Redistributable Package – Second Edition run on Windows® Server 2003 SP1 64-bit Edition, Windows XP 64-bit Edition, and Windows Vista 64-bit Editions. While the first two operating systems support both mainstream 64-bit processor architectures, the Vista Editions are only available for the x64 processor family.

Apart from executing 64-bit applications, all the above operating systems can execute existing 32-bit applications by using the Windows on Windows 64 (WoW64) x86 emulator. Wow64 enables 32-bit productivity applications developed by using the Visual J# (v1.0, v1.1 and v2.0) and Win32 to run on 64-bit Windows and take advantage of the 64-bit Windows kernel which offers a larger number of kernel handles and window handles. WoW64 supports 32-bit console, GUI, and service application. Although some 32-bit server applications may be certified to run on WoW64, WoW64 is NOT intended for 32-bit server applications. WoW64 does NOT support 16-bit Windows applications. WoW64 emulation is performed natively (on the chip) by the x64 micro-architecture, which means WoW64 performance on x64 is similar to that of 32-bit Windows. However, because the Itanium (IA64) architecture does not support native WoW64 emulation, WoW64 performance on the Itanium is substantially less than that of 32-bit Windows.

6 Known Issues
Following is the list of issues you might encounter while using Microsoft Visual J# 2.0 Redistributable Package – Second Edition.

1. Setup Experience for Microsoft Visual J# 2.0 Redistributable-Second Edition Package is not completely localized.
The Setup experience for Microsoft Visual J# 2.0 Redistributable-Second Edition Package is not completely localized. This means apart from the EN-US download page, no separate localized download pages are available for the Second Edition of the J# Redistributable. The Setup language is also US-English. Parts of the user interface prompts and messages in the Setup UI are displayed in US-English when installing the product on non US-EN operating systems.

Platforms Affected: x86, x64, IA64

To resolve this issue:

No action is needed. The redist will STILL install and operate on non US-EN operating environments.

2. A synchronized method that has security callouts may not save a return value after control returns to the calling function in an application that is built by using the 64-bit version of the .NET Framework 2.0.
In an application that is built by using the 64-bit version of the Microsoft .NET Framework (v2.0 and v3.0), a synchronized method that has security callouts may not save a return value after control returns to the calling function. This breaks the AWT, Swing and Zip functionality of Visual J# applications on 64-bit platforms.

Platforms Affected: x64, IA64

To resolve this issue: Install the hot-fix for the issue, which is detailed in the KB article KB917882 over .NET Framework (v2.0 and v3.0).

3. java.lang.Thread behavior is inconsistent and threads do not start at times.

The behavior of java.lang.Thread is inconsistent and at times the thread does not start.

Platforms Affected: IA64

To resolve this issue: Install the hot-fix for the issue, which is detailed in the KB article KB913469 over .NET Framework (v2.0 and v3.0).

4. Values between System.Double.Epsilon (4.94065645841247E-324) and approximately 1/2 Epsilon (2.470328229206232730000E-324) are rounded off to zero instead of Epsilon.
On 64-bit platforms, values between System.Double.Epsilon (4.94065645841247E-324) and approximately 1/2 Epsilon (2.470328229206232730000E-324) are rounded off to zero instead of Epsilon.

Platforms Affected: x64, IA64

To resolve this issue:

Change the application code-base to suite the above behavior.

5. 64-bit Visual J# applications that reference v1.1 Visual J# binaries (compiled with v1.1 Visual J# compiler) crash.
Applications built with the 64-bit Visual J# compiler (targeting anycpu or IA64 platform type) when executed on 64-bit Itanium platform crash if an assembly compiled with v1.1 Visual J# compiler is passed as reference.

Platforms Affected: IA64

To resolve this issue: Build the application as 32-bit platform specific by using the /platform:x86 switch on the 64-bit Visual J# compiler and execute them in WoW mode on Itanium architecture.

6. java.util.GregorianCalendar.add method returns wrong value when one month is added to a date like Jan 31st 2004.

The java.util.GregorianCalendar.add method returns a wrong value when one month is added to a date like Jan 31st 2004. The date is moved to March 2nd 2004 instead of Feb 29th 2004.

Platforms Affected: x86, x64, IA64

To resolve this issue:
Applications by default continue to use java.util.GregorianCalendar.add in a similar way as with the previous releases.

To achieve the new functionality, use the setMonthJustified() method added to com.ms.vjsharp.util.GregorianCalendarHelper class. Calling this method enables the modified behavior for the GregorianCalendar class in the appdomain.

7 New Compiler Messages

This section provides information about compiler messages that are added in the Microsoft Visual J# 2.0 Redistributable Package – Second Edition release.

1. New Compiler Error VJS1857

Description	Invalid option for /platform; must be x86, x64, Itanium or anycpu.
Modification Needed	To remove the error, make sure a valid option amongst x86/x64/Itanium/anycpu is passed to the /platform compiler switch.

2. New Compiler Error VJS1858

Description	<feature-set> feature-set is supported by Visual J# only on <platform type>-bit platform. Use /platform: <platform type> option to generate <platform type>-bit specific binaries for this feature.
Modification Needed	To remove the error, either modify the code-base to remove the unsupported feature-set to compile and execute the application on 64-bit platform natively, or compile and execute the application as a WoW (or 32-bit) application by using the x86 /platform switch option.

3. Compiler Warning VJS1859

Description	Usage of <feature-set> feature-set is deprecated. Use <feature-set> instead.
Modification Needed	To remove this warning, change the application to adapt the recommended feature-set.

4. Compiler Error VJS1860

Description	<option> option is supported by Visual J# only on <platform type>-bit platform. Use /platform: <platform type> option to generate <platform type>-bit specific binaries for this option.
Modification Needed	To remove the error, use the specified option to generate only specified platform type applications.

5. Compiler Warning VJS1861

Description	Assembly generation — Referenced assembly <reference> targets a different processor.
Modification Needed	No modification needed. The warning is emitted while cross compiling to a specific platform type.