Many if not most businesses use both Java and Microsoft platforms and products. But there is a barrier of incompatibility, of language and platform differences, that prevents re-use of of VB.Net components and applications in a Java context. VBeeJ is designed to bridge this barrier.

VBeeJ allows you to leverage your software investment across platforms according to your business requirements. VBeeJ is a platform translation tool. It not only translates VB.Net to Java (see features ). VBeeJ creates an interface layer in Java which resolves all unknowns, whether they be .Net unknowns or unknowns from 3rd party components or application classes referenced but not presented to VBeeJ. VBeeJ creates a complete object oriented interface in pure Java for any VB.Net program. VBeeJ contains significant innovations in state of the art translation technology, including an advanced type inference engine which creates types, signatures, and hierarchies for all unknowns. This gives VBeeJ unparalleled flexibility and range.

VBeeJ has complete support for translation to pure Java source of all VB.Net event and event handling capabilities. VBeeJ handles .Net services invoked on primitive Java types (int, boolean, etc). It also issues diagnostic and informational messages so you have a complete and in depth understanding of the process and result of translation.

VBeeJ creates a directory, the beelucid directory, where any unresolved references to types, methods, or system libraries are resolved. It resolves all references within your program, whether they be .Net references or any other references, whether declarations are available or not available. This means you do not have to translate a whole application. Instead you can translate classes or modules on an as needed basis. This approach suits contemporary software design philosophies, which stress modular and interoperable components.

How does VBeeJ resolve all references in your program even when the declarations are not available? VBeeJ contains an advanced type inference engine which enables it to resolve platform differences and unavailable type declarations in the beelucid directory. The results of type inference are reflected in the contents of the beelucid directory. The Java Target Files shown above can be divided into two sets, those in the beelucid directory and those not in the beelucid directory. All unresolved references are resolved in the beelucid directory.

The beelucid directory also contains any Bridge type definitions which VBeeJ determines is needed. Bridge classes provide a 'bridge' between similar classes on the different platforms. Click the link to show the contents of the beelucid directory for a typical test case. A few Bridge classes are shown, including the Bridge classes which support Events and EventHandlers. Bridge classes may also be generated for primitive types. The SystemBridge class supports platform and library functionality. The contents of the beelucid directory will vary depending on the characteristics and requirements of the source program. All class definitions are in the form of Java source files.
Back to top

1. Installing on Windows

   Select the Windows option for the download of VBeeJ. This will result in the download of a Windows installer which will install VBeeJava.exe into a directory of your choice.

2. Installing on other platforms

   Select the tar.zip option for the download of VBeeJ. You will unzip and extract VBeeJava.jar into a location of your choice. The syntax is gzip -d VBeeJava.tar.gz followed by tar xvf VBeeJava.tar.

VBeeJ can be run with the gui, or from the command line, or as an external tool within the Eclipse Platform. All the examples show VBeeJ used as an external tool within the Eclipse Java IDE, Version 3.2. Note that VBeeJ requires a jre of version 1.6.0 or higher to run.

1. Running the VBeeJ gui on Windows

   Click on the VBeeJ icon and the gui will execute. You can select files to translate, target directory, and hints files in the gui.

2. Running the VBeeJ gui on other platforms

   If no options and no input files are present on the command line, executing the jar brings up the gui:

   java -jar /path/to/VBeeJava.jar

3. Options for running VBeeJ on the command line

   On Windows the command line form is:

   VBeeJava.exe [options] input files

   On other (Unix-based) platforms the command line form is:

   java -jar VBeeJava.jar [options] input files

   The options are

   -d directory_name The target directory for the generated Java files, optional.

   -hints file_name.vb A hints file, optional. Can specify multiple times (discussed here).

4. Running VBeeJ within the Eclipse Platform

   The Eclipse Platform supports a powerful Java IDE. Running VBeeJ within this environment allows you to utilize the Eclipse Java IDE for your translated files. Click the link to see the External Tools menu within Eclipse.

   Note that in the linked image above, Run_VBeeJava appears at the top of the External Tools Run Menu. It has already been defined. Click this link to see how to define the command Run_VBeeJava on the Windows platform. (This command uses the Windows file separator in paths and the Windows executeable. Click this link for a Unix example.) The Location text field specifies the location of VBeeJ executeable for your installation. Note that the Working Directory specifies the path to the Eclipse workspace, followed by the project directory, followed by the topmost package directory. All these components of the Working Directory are required. Note that the input file is located in the topmost package directory, and it is specified by name as an argument in the Arguments text box. If more input files or any options (-d or -hints) are used, they should be entered into the Arguments text box. (For an example that specifies -d in the Arguments text box, click this link .)

   The results of executing the Eclipse command Run_VBeeJava are shown here . The topmost_package_dir, which originally contained the source to be translated, now also contains the translated file. Note that translated file specifies the topmost_package_dir as its package. Visual Basic namepaces are translated into Java packages. If the input source has namespaces, their packages will be relative to the topmost package directory.

Back to top

Hints files provide hints to VBeeJ. A hints file is any VB.Net file preceded by "-hints" on the command line to VBeeJ or selected as a hints file in the gui. Any number of hints files can be provided, but note that in the command line form, every hints file must be preceded by "-hints". A hints file will not be translated, but the declarations it contains can be used by VBeeJ for the purposes of translation.

The type inference engine infers type hierarchies and method signatures for types which are used in the VB.Net source but whose definitions are not present in the VB.Net source. In certain circumstances, a hints file can be useful for the type inference engine in understanding undeclared types, as will be shown with an example.

The example will use the VB.Net expression If TypeOf MyController Is VoiceControl...

where, if MyController is of type VoiceControl, then the expression is true. The Java equivalent if (MyController instanceof VoiceControl)

requires that the type of MyController and VoiceControl be known to be related.

Click the link to view the example. Notice the 'Beelucid error' messages that occur because VBeeJ cannot infer a type relationship between the operands to the TypeOf conditional expressions. This will cause errors to be reported in the generated Java code. These errors and the generated Java code you can see here .

VBeeJ generates class definitions for all the types used but not declared. VBeeJ identifies which class defines which methods and infers correct signatures for those methods. What it cannot do with this test is infer a type hierarchy for the types whose definition is not available, because that information is not implied in the VB.Net source. Click the link to view the Java generated for the types in the example which are used but not declared. You can see that the types are not related.

These errors can be fixed by using a hints file. A hints file must contain correct syntax but it does not need to contain the whole type definition. In this case all that is needed is the inheritance relationships. Click link to see both the hints file and the Run_VBeeJ command modified to use a hints file. Note that all the hints file does is define the inheritance relationships.

Running VBeeJ with this hints file eliminates the Beelucid errors and the Java errors (click here ). Click here to see the classes generated for the types which are used but not declared. These classes now have inheritance relationships, as specified in the hints file, but otherwise they are the same: the type inference engine has inserted the same methods with the same signatures as before.

How do you know if a hints file is necessary? In general, if your code relies on a subtyping relationship between types whose definitions are not present in your VB.Net input, then that relationship will be exposed in the code. That means that the type inference engine in VBeeJ will detect it, and a hints file is not necessary. In those cases where VBeeJ is uncertain, the VBeeJ messages will tell you that there could be an issue (as happened above) and you can use a hints file to address that issue.

Back to top

Here is a simple example, where the input and output is shown in the Eclipse Platform (version 3.2).

1. VB.Net Input

   Click the link to view a simple test program which defines a property. The source file contains a base class and a derived class. Note Option Strict On. This is not required but it is recommended.

   VBeeJ accepts all of VB.Net 2003 (VB 7.1) and many of the features in VB.Net 2005 (VB 8.0), including inheritance of generic types, the Using keyword, and more. Unsupported features in VB 8.0 may get parse errors for unrecognized syntax and the translation will not occur. Implementation of VB.Net 2005 is ongoing. Please contact Beelucid Support if you have particular requirements.

2. Java Output

   Click the link to view the result of translation. Three files are created, for each class in the input source. Each defines a Java class with the same name as the class in the input source. Note that the Module is translated to a final class.

   The translated code includes the comments from the original source.

   The Java produced by VBeeJ conforms to Java version 1.6.0.

3. The beelucid Directory

   VBeeJ also creates a beelucid directory which contains Bridge classes as well as stubs for classes and methods whose definition is not available in the VB.Net source. Bridge classes provide a 'bridge' between similar classes on the different platforms. Click the link to show the contents of the beelucid directory for this test case. A few Bridge classes are shown, including the Bridge classes which support Events and EventHandlers. Bridge classes may also be generated for primitive types. The SystemBridge class supports platform and library functionality. The contents of the beelucid directory will vary depending on the characteristics and requirements of the source program. All class definitions are in the form of Java source files.

Back to top

VBeeJ produces messages to clarify the process and results of translation.

1. Info Messages

   'Info' messages are messages which describe the translation choices made by VBeeJ. They are for infomational purposes, to help you understand the generated code better. In general no response is required.

   In the message, the source file name is followed by a line number and message category, and followed by the message text.

   [TestRedim.vb] 1: Beelucid info: Every Visual Basic namespace creates a package directory in the Java context (namespace 'TestRedim')

2. Warning Messages

   'Warning' messages are messages which notify the user that the Java translation may not completely match the VB.Net functionality for all cases. You should check the code indicated by these warning messages. The more common cases will most likely require no modification.

   In the message, the source file name is followed by a line number and message category, and followed by the message text.

   [TestRedim.vb] 6: Beelucid warning: Visual Basic operator 'GetType(<className>)' translated to Java '<classname>.class', which has equivalent but not identical functionality and syntax.

3. Error Messages

   'Error' messages are messages which notify the user there is no Java construct or functionality that can be automatically translated to implement the VB.Net statement. There aren't many of these and they are mostly generated for features included in VB.Net for VB6 compatibility. You will need to check the code and manually translate.

   In the message, the source file name is followed by a line number and message category, and followed by the message text.

   [TestRedim.vb] 8: Beelucid error: 'ReDim' statement requires manual translation if the operand has not been declared with specific dimensions but is an object of 'Array' type (array name 'my3DIntArray').

Click the link to view an example of VB.Net source with its translation and translation messages. The linked example shows info messages, warning messages, and an error message.

Back to top

VB.Net supports primitive types Boolean, Char, Byte, Short, Integer, Long, Single, and Double. Java's parallel types are boolean, char, byte, etc. Basic types in Java and VB.Net behave identically in some contexts but not in others. Where they behave identically, the translation is direct. Where they do not behave identically, a Bridge type wrapper object is created, that wraps the underlying basic value. The Bridge type definitions are contained in the beelucid directory.

For example, a VB.Net statement of the form

Dim II As Integer = 3

translates directly into the Java variable initialization statement

int II = 3;

VB.Net primitive types and Java basic types are parallel but they do not behave identically in all contexts. The VB.Net variables are objects which support services. An int variable in Java is a simple value. When this difference results in a difference of functionality or behavior, VBeeJ uses bridge types to bridge the difference. The goal is to have your VB.Net program translate into legal Java.

For example, in VB.Net, the following variable initialization relies on the fact that Integer variables are object of class Integer:

Dim II As New Integer(3) 'Integer is a class and 'New' creates a new Integer object

A direct translation of this into a Java initialization would not be legal because int is a value not an object type:

int II = new int(3); // Illegal Java because 'new' can't be used to create a value

In this example, VBeeJ will generate a IntegerBridge class in the beelucid directory in order to create the int value:

int II = new IntegerBridge(3).intValue();

The IntegerBridge class creates an object which is a wrapper for the underlying Java basic int value, and the method intValue() returns that underlying value.

Back to top

The SystemBridge contains stubs as well as some implementations for library and system functions, some generated by default and others generated because they were identified in code. Click this link to view the default SystemBridge class.

Back to top

VBeeJ implements complete and robust support of support of events and event handling. For events, the class EventBridge is generated. This class associates an event object with a set of handlers, which can be added and removed. For event handling, the class EventHandlerBridge is generated, which supports associating a handler with an event object.

VBeeJ will generate all the code needed to fully implement in Java the event and event handling functionality in your VB.Net program. Click this link to view a VB.Net example Test.vb which has a WithEvents variable, an event class, an event handler, and raises an event.

Click this link to view classes in Test.vb after they've been translated into Java. The translated classes use the bridge classes. The VB.Net Event variable MyEvent has the type in Java of EventBridge, which associates MyEvent with a set of handlers. The class declaring this event, MyEventClass, utilizes the class EventHandlerBridge, to support associating handlers with MyEvent. For a high level view of EventBridge and EventHandlerBridge click this link .

After running the source through VBeeJ, this example compiles and executes identically on both platforms with no modification.

Back to top

Bridge types may be generated for VB.Net types String, Object, Array, Date, Type, Decimal and Exception. They are generated if VBeeJ identifies a need for them. Often there is no need for them. For example, if a String object has the method trim() invoked on it, no Bridge type is generated because Java supports this method.

What happens if an method that Java does not support is invoked on a String object? Click this link to see an example in which a method, LastIndexOfAny() is invoked on a String object. The Java String does not support the LastIndexOfAny() method. VBeeJ generates a StringBridge type which does contain a stub for the LastIndexOfAny() method. A StringBridge object is created and initialized with the original String, and then the method LastIndexOfAny() is invoked on the StringBridge object. Click this link to see the Java code generated for this program by VBeejava, including the StringBridge type definition. Note that the body of LastIndexOfAny() remains to be implemented.

An ArrayBridge type is generated to bridge differences between Java array implementation and VB.Net array implementation. Click this link to view the original VB.Net source as well as the Java translation for an example which uses the VB.Net Array.CreateInstance() method of creating an array. Functionality which does not directly map to Java is supported by the ArrayBridge class in the beelucid directory. Click here to view the ArrayBridge class. After running the source through VBeeJ, this example compiles and executes identically on both platforms with no modification.

Bridge types have these goals:

• To produce legal Java from VB.Net.
• To support robust and powerful mappings across platforms for these foundation types.
• To be robust and extensible with respect to future changes in the .Net platform.
• The Bridge type is the only place where type differences on the platforms will require special handling. In this example, the special handling required would be the implementation of the body of the LastIndexOfAny() method in the StringBridge class.

Back to top

VBeeJ is designed to be flexible, powerful, and robust even when information about class definitions and interfaces used by the source program is missing or incomplete. It contains a powerful type inference engine. This allows it to handle missing classes and interfaces in source programs and also allows VBeeJ to gracefully and consistently handle changes in the .Net platform itself or in the VB libraries.

Click the link to view an example that shows a VB.Net source program which contains references to a class whose definition is not available. The translated code is also shown.

Note the last message is an 'info' message that indicates that VBeeJ found references to a class whose definition is not available. The user is directed to the beelucid directory where a stub class for this type has been created, with methods inserted as appropriate. Method signatures were inferred by the type inference engine. Click the link to view the stub class in the beelucid directory.

VBeeJ creates a beelucid directory which contains Java support for .Net functionality as well as stubs for classes whose definition is not available in the VB.Net source. Click the link to show the contents of the beelucid directory for a test case. This example shows only the minimum default contents of the beelucid directory. This example does not contain any references to classes whose definitions are not available. Note that the Bridge classes which support Events and EventHandlers are listed, as well as a few Bridge classes. The latter provide a 'bridge' between similar classes on the different platforms. The SystemBridge class supports platform and library functionality.

Click the link to show the contents of the beelucid directory for a test case which does contain references to a class whose definition is not available (the class called UnknownClass). Note method stubs for the class have been generated. The signatures of the method stubs have been inferred by the type inference engine.

The contents of the beelucid directory will vary depending on the characteristics and requirements of the source program. All class definitions are in the form of Java source files.

Back to top

The VBeeJ type inference engine performs several functions. It identifies classes, methods, and properties whose definitions are not available in the VB.Net source program. For these unknowns, it infers method and property signatures and creates a type hierarchy if one is needed. This extracts all the unknowns in your VB.net class or module into the beelucid directory, which then acts as an interface layer between your module and the Java platform.

Back to top

VB.Net supports several styles of parameters that are not supported in Java, including passing by name, specifying Optional parameters with default values, and ParamArray. All of these are matched to the appropriate method and translated into legal Java. Click the link to view an example.

Back to top

VBeeJ may transform the code in order to translate it properly. For example, VB.Net has a convention allowing the value assignment of a Boolean to an Integer and vice-versa. In Java this is not a legal assignment. Insertion of a test with the ? operator addresses this issue. Click the link to view an example.

Note: Microsoft, Microsoft .Net, Windows, and Visual Basic .Net are registered trademarks of Microsoft Corporation in the United States and other countries.

Note: Java is a registered trademark of Sun Microsystems, Inc. in the United States and other countries.