This document includes the following topics:
The Example Applications chapter describes two example applications.
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.
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.
Notes 1. Running the packager (
2. In order for |
Use packager.exe
to generated the .dll
for the bean.
Use of packager.exe
is as follows:
|
.dll
can contain only one packaged bean. Thus, a
separate .jar
file is required for each bean..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
.).-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.-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
.)-out
is not specified, or -out
does not specify <jre_home>\axbridge\bin
, then
the -reg
option should not be used.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:
.dll
file with the bean name
(JellyBean.dll
) and put it in the
j2re\axbridge\bin
directory;j2re1.4.2\axbridge\lib
directory and
place jelly.jar
there;.dll
with the CLSID
D824B185-AE3C-11D6-ABF5-00B0D07B8581
..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:
CLSID
registry entry for
JellyBean.dll
under
HKEY_CLASSES_ROOT
;j2re1.4.2\axbridge\lib
directory and
place jelly.jar
there.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.
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 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
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.
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.
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.
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.
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.
Note that you can configure the JVM through the Java Plug-in Control Panel. The following tabs are relevant to the ActiveX Bridge:
You can use the Java Console for debugging beans.