# ActiveX Bridge Developer Guide

## Implementation for SDK/JRE 1.4.2 and Above

This document includes the following topics:

- Overview
- Supported OSs and ActiveX Containers
- Packaging the Bean
- Using the Bean in an Application
- Deployment
- Java Objects in the ActiveX Bridge Environment
- Other Topics
  - Methods
  - Properites
  - Ambient properties
  - Events
  - Security
  - JVM Configuration

The Example Applications chapter describes two example applications.

## Overview

The ActiveX Bridge allow a component based on JavaBeans(TM) component architecture ("bean") to be effectively packaged as an ActiveX control, thereby allowing it to be used as a functional component in an ActiveX container.

Note that this implementation of the ActiveX Bridge may not be compatible with the previous implementation for SDK/JRE 1.1 through 1.3.1. In order to use the new bridge, beans will need to be repackaged.

## Supported OSs and ActiveX Containers

For development purposes, this implementation supports the following OSs and ActiveX Containers:

OSs: Windows NT, 2000, XP.

ActiveX Containers: Visual Studio 6.0 with SP3.

Note that packaged beans should run on any Windows platform and in any ActiveX container—not just those platforms and containers listed above.

## Packaging the Bean

Notes 1. Running the packager (`packager.exe`) requires that you have the following installed on your computer: SDK 1.4.2 or higher Microsoft Visual C++ 6.0 with SP3 2. In order for `packager` to work you must first run `VCVARS32.BAT`. `cd` to the `/bin` directory where it is located in your Microsoft Visual C++ installation and type `VCVARS32`.

Use `packager.exe` to generated the `.dll` for the bean.

Use of `packager.exe` is as follows:

> ### `Packager` Usage
>     Usage: packager [-options] <jar file name> <bean name>

>     where options include:
>        -clsid <class-id>         CLSID for the packaged bean
>        -out <output directory>   destination directory for the packaged bean
>        -reg                      consent to register the Active-X control

### Additional Information

- A `.dll` can contain only one packaged bean. Thus, a separate `.jar` file is required for each bean.
- If one `.jar` file depends on another `.jar` file or `.class` file(s), then you will need to set `CLASSPATH`.
- `<jar file name>` needs to include the path to the `.jar` file. The path may be full or relative.
- `<bean name>` needs to be the fully qualified package name of the bean (e.g., `sunw.demo.jelly.JellyBean`.).
- If the `-clsid` option is not used, the packaged bean `CLSID` will be generated randomly. This `-clsid` option allows you to specify the same `CLSID` for a given bean every time.
- Default: Unless `-out` is specified, `packager.exe` will generate the `.dll` fill in the same directory in which it is executed. If you specify the `-out` parameter, then `packager` places the `.dll` file in the directory you specify. For example, you might want to place the `.dll` in a directory called `<jre_home>\axbridge\bin` where it could be deployed with an application. (Note that `<jre_home>` would be the public JRE, not the private one. The public JRE on Windows is normally located at `C:\Program Files\Java\j2re1.4.2`. The private JRE, associated with the SDK, is normally located at `C:\j2sdk1.4.2\jre`.)
- If `-out` is not specified, or `-out` does not specify `<jre_home>\axbridge\bin`, then the `-reg` option should not be used.

#### Example

For example, suppose `<bean>.jar` is `jelly.jar`; `jelly.jar` is located at `C:\my_bean_jars`; the fully qualified bean name is `sunw.demo.jelly.JellyBean`; and the SDK is `j2sdk1.4.2`. You could run `packager.exe` as follows:

> `C:\j2sdk1.4.2\bin\packager -clsid` `{D824B185-AE3C-11D6-ABF5-00B0D07B8581}` `-out C:\Program Files\Java\j2re1.4.2\axbridge\bin -reg C:\my_bean_jars\jelly.jar sunw.demo.jelly.JellyBean`

The packager would:

- generate a `.dll` file with the bean name (`JellyBean.dll`) and put it in the `j2re\axbridge\bin` directory;
- create a `j2re1.4.2\axbridge\lib` directory and place `jelly.jar` there;
- register the bean `.dll` with the `CLSID` `D824B185-AE3C-11D6-ABF5-00B0D07B8581`.

### Manually Registering the bean `.dll`

If you don't use the `-reg` option with `packager.exe` as shown above, you can manually register the `.dll` with `regsvr32.exe`. `cd` to the directory where the `.dll` file is located (e.g., `C:\Program Files\Java\j2re1.4.2\axbridge\bin`) and type:

> `<path_regsvr32>\regsvr32 <bean name>.dll`

Suppose you are running Windows 2000. `regsvr32.exe` is located at `C:\winnt\system32` on Windows 2000. Then to register `JellyBean.dll` you would do this:

> `C:\Program Files\Java\j2re1.4.2\axbridge\bin>C:\winnt\system32\regsvr32 JellyBean.dll`

This will:

- create a `CLSID` registry entry for `JellyBean.dll` under `HKEY_CLASSES_ROOT`;
- create a `j2re1.4.2\axbridge\lib` directory and place `jelly.jar` there.

## Using the Bean in an Application

Now that the bean is registered as an ActiveX control, you should be able to insert it into an ActiveX container. In the case of the ActiveX Control Test Container that comes with Visual Studio, on the main menu go to `Edit>Insert New Control...` and scroll down the list until you find the bean control. In the case of the `JellyBean.dll` control, it shows up as `JellyBean Bean Control`. Below it is shown inserted into the Visual Studio test container.

## Deployment

To deploy a bean packaged as an ActiveX control in an application, you will need to include registration of the `.dll` as part of the installation process. The `.dll` should be installed into the `<jre_home>axbridge\bin` directory, and it should be registered there with `regsvr32.exe`. As stated previously, when the `.dll` is registered, the bean `.jar` will be placed in the `<jre_home>\axbridge\lib` directory.

## Java Objects in the ActiveX Bridge Environment

Java objects are accessible via wrapper objects supporting the `IDispatch` interface; i.e., they are accessed indirectly through the ActiveX Bridge. For example, if you are working with a packaged bean in Visual Basic (VB) and want to pass a Java object as an argument to a bean method, it is necessary that either (1) the bean has a method that returns the required type of Java object; or (2) the Java object is available as a bean property.

For example, consider the calendar example, JCalendarPanel, in the Examples chapter.

If you were working directly in Java with this bean, you would create a `Date` object, set its properties, then pass it as an argument to the `setSelectedDate()` method of `JCalendarePanel`. The way this is done with the ActiveX Bridge as follows:

Assuming you are working in VB and have an instance of `JCalendarPanel` called `JCalendarPanel1`, in VB you could use the `JCalendarPanel1.``selectedDate` property to get a `Date` object:

> `Set dat = JCalendarPanel1.selectedDate`

Then you would use the VB methods of the `Date` object (`dat`) to set it. For instance:

> `dat.setYear (1986 - 1900)
> dat.setMonth (11 - 1)
> dat.setDate 24`

Finally, you would use the `setSelectedDate` method of `JCalendarPanel1` to set the date:

> `JCalendarPanel1.setSelectedDate dat`

## Other Considerations

### Methods and Method Overloading

All the methods provided by the `BeanInfo` via `getMethodDescriptors()` are accessible from ActiveX containers.

However, if a method is overloaded, only the method which takes the highest number of arguments will be available. This is because COM IDL does not support overloading. However, the argument and return value type will be `VARIANT`. Each argument is optional. For any overloaded method you will need to refer to the bean documentation to know the exact number of arguments and their types. Methods or property names which are identical to any MIDL keyword are dropped.

### Properties

All the properties are accessible though the bridge with the same access right as defined in the `BeanInfo` via `PropertyDescriptor`. The ActiveX bridge will invoke the accessor methods as defined in the `PropertyDescriptor`.

If the bean property is `bound` or `constrained`, the `bindable` or `requestedit` flags are set in the attributes of the COM property. The container is notified of the property change through `IPropertyNotifySink` interface. If the property is constrained and the container denies the property change, then the bean `PropertyVetoException` is thrown by the bridge.

For primitive types and for string, font, and color properties, most ActiveX containers like Visual Basic will allow direct manipulation of properties in their `PropertySheet`. For all other properties, such as arrays or objects, the properties will not be accessible in the `PropertySheet` but can still be invoked through the scripting language associated with the container.

### Ambient Properties

The bridge will support four ambient properties that get translated to the bean properties if the bean component implements these properties. These ambient properties will be read and set on the bean component when the component is initialized and each time a change notification for the ambient properties is received.

> `DISPID_BACKCOLOR
> DISPID_FORECOLOR
> DISPID_FONT
> DISPID_ENABLED`

The bridge will forward ActiveX container ambient property changes to the bean via setting properties.

### Events

All source interfaces that are declared as default in the `EventSetDescriptor` array returned by the `BeanInfo` will be merged into one interface which is declared as being the ActiveX default source interface. It is an ActiveX requirement that at least the default source interface is accessible by ActiveX containers.

Each method returned by the `getListenerMethodDescriptors` API of the `EventSetDescriptor` is mapped to an ActiveX event. The event name is the method name. Since all default interfaces of beans are merged to a unique interface, interfaces that contain the same method name are not allowed.

Consider, for example the `java.awt.event.ActionListener` source interface:

> `public interface ActionListener extends EventListener {`

> `public void actionPerformed(ActionEvent e);`

> `}`

The ActiveX event name generated from this interface definition is `actionPerformed`. For example, in case of Visual Basic the event signature looks like this:

> `Private Sub Button_actionPerformed (ByVal evt As Object)`

> `MsgBox evt.toString`

> `End-Sub`

The `evt` provided to the container is an automation object, which represents the `java.awt.AWTEvent` `Object`. Containers could access the information on the event by invoking the methods supported by the `AWTEvent` class.

### Security

The bean packaged as an ActiveX control will be part of a stand-alone application. Hence it will be executed outside the applet sand box security model.

In Internet Explorer scripting of the bean is not safe, as it has been granted the `AllPermission` permission.

### JVM Configuration

Note that you can configure the JVM through the Java Plug-in Control Panel. The following tabs are relevant to the ActiveX Bridge:

- Basic
- Advanced
- Proxies

You can use the Java Console for debugging beans.