Start up VisualAge, and create a new project. From the Workbench, use Selected|Add|Project:
Name the project pure:
You may read this example simply to get a feel for how easy it is to use J-Integra® to access COM components from within a GUI development environment such as VisualAge, however we urge you to try out this example. Although it appears that there are a lot of steps, most of them are trivial -- we have included such a lot of detail in order that no matter your experience, you will be able to follow the example. If you have previous experience of using VisualAge, then you will speed through this example. If not, then the detailed steps we provide should ease you through.
Prior to doing this example, please do the Excel example, since we introduce in that example some basic concepts that are assumed here. In addition, this example uses files that were generated as part of that example.
If you do wish to try out this example, you should first download and install the Java Developers Kit.
You should download and install J-Integra®. You must also have installed VisualAge. There is an evaluation version available which you can use to try things out. This example assumes you are using VisualAge version 2.0.
Since J-Integra® can be used to access COM components from any JVM running on any platform, the Applet you create should execute on any platform, using any JVM.
Import the J-Integra® runtime and the pure Java Excel classes that were generated using com2java
Hook up the Visible checkbox to the Excel.Application.visible property
Start up VisualAge, and create a new project. From the Workbench, use Selected|Add|Project:
Name the project pure:
Use File|Import:
Specify that you want to import a Jar file:
Click on Next.
Set the file name to D:\jintegra\lib\jintegra.jar:
Note: The license file for J-Integra® v1.5.0 and upwards is an XML file (jintegra.xml), not a Java class file as used previously. You will probably have to click resource and specify the license file to be imported from jintegra.jar.
Click on Finish.
Use File|Import again, but this time specify that a directory will be imported:
Click on Next.
Set the directory to D:\pure\excel. Make sure that only classes will be imported (this is because if you are using the evaluation version of VisualAge, there is a limit of 500 classes; if you were to include the Java source files, over 900 classes and interfaces would be imported):
Click on Finish.
Select the 'pure' project, and use Selected|Add|Applet...:
Name the applet GUIExcelExample:
VisualAge provides a pallet of GUI elements which can be used to compose a user interface. You will make use of the following:
Create the following user interface. Don't worry about making things
line up! Double click on the labels, buttons and the checkbox to change
the text:
You will now add a bean that will be used to create an instance of com.linar.jintegra.AuthInfo, which can be used to authenticate access to a COM component (it is not required, but if it is not specified, then DCOM authentication must be disabled). You will create a Factory bean which handles the creation of the AuthInfo, and you will then visually hook up the Start button to the new bean, so that when you click on start, it uses the domain, user, and password beans to create an AuthInfo instance.
Select the Other set of items in the composition editor pallet:
Click on the Factory item in the new (Other) pallet:
Click below the dashed line, to create the factory non-GUI item:
Right-click on the Factory object, and select Change Bean Name... from the popup menu:
Set the bean name to authInfo:
Right-click on the Factory object, and select Change Type... from the popup menu:
Set the bean type to AuthInfo:
Right click on the Start button on the form, and select Connect|ActionPerformed:
Move the little spider over to the authInfo bean, and click on it:
Select the first constructor from the list presented:
You must now specify the parameters to be passed to the constructor. Right-click on the domain TextBox, and select Connect|text:
Move the little spider to half way along the connection between Start and authInfo. A small circle will appear. Click on that circle:
The first parameter is the domain. Select arg1 from the list:
In the same way, connect the User Text Box to arg2 and Password Text Box to arg3.
You should now see something like this. You may wish to rearrange things a little:
Summary of what you have just accomplished: When you run the applet, and click on the start button, a new instance of com.linar.jintegra.AuthInfo will be created, using the domain, user, and password specified.
You will now add a bean that will be used to create an instance of excel.Application, which can be used to access to an Excel COM component. You will create a Factory bean which handles the creation of the Excel.Application, and you will then visually hook up the Start button to the new bean, so that when you click on start, it uses the host and authInfo components to create the new instance of Excel.
In the same way as you created the Factory
for the AuthInfo component,
now create a second Factory, positioning it to the right of the authInfo
component, and change its name to excel,
and its type to Application:
Right click on the Start button on the form, and select Connect|ActionPerformed, to create a second action which will be executed after the one you have already created. Move the little spider over to the excel bean, and click on it:
Select the second to last item from the list presented (the constructor which takes the String host and AuthInfo as parameters):
Right-click on the Host Text Box, and select Connect|text, move the little spider to half way along the connection between Start and excel. A small circle will appear. Click on that circle. Select the first item from the list of parameters (arg1):
Right-click on the authInfo bean, and select Connect|this:
Connect the authInfo to arg2:
Summary of what you have just accomplished: When you run the applet, and click on the start button, a new instance of com.linar.jintegra.AuthInfo will be created, using the domain, user, and password specified. A new instance of Excel will be created on the host specified in the host textbox, using the authInfo just created. Unfortunately, you wouldn't be able to see the Excel application, since it is started up invisible by default...
Right click on the Visible checkbox on the form, and select Connect|itemStateChanged:
Move the little spider over to the excel bean, and click on it:
Select Connectable Features... from the popup menu presented:
Select the Property radio-button, and select the visible property:
Right click on the Visible checkbox on the form, and select Connect|state:
Move the little spider to half way along the connection between Visible and excel. A small circle will appear. Click on that circle. Select the item that appears (value):
Summary of what you have just accomplished: When you run the applet, and start Excel, you can make Excel visible/invisible by checking and unchecking the 'Visible?' checkbox.
So far you have seen two of the three elements generally associated with beans. You have seen how to set properties, and invoke methods on COM components. In this step, you will see how to react to events generated by COM components. When the user creates a new Excel workbook, you will display some text in the Text Area component on the form.
Right click on the excel bean on the form, and select Connect|Connectable Features .... Select the Event radio button. Select the newWorkbook event, which is generated when the user creates a new workbook:
Move the little mouse over to the Text Area bean and click on it:
Select the append method:
Double-click the connection between the excel bean and the Text Area bean, and click on Set Parameters ... in the dialog which is displayed:
Set the text to "New Workbook\n":
Summary of what you have just accomplished: When you run the applet, start excel, make it visible, and create a new workbook (File|New|Workbook), then the applet receives an event, and displays a message to that effect.
This final step is slightly complicated, in that several things must be done in order to shut down Excel:
Excel must be made invisible
The excel.Application.quit() method must be invoked
The Excel reference must be set to null
The com.linar.jintegra.cleaner.ReleaseAll() static method must be invoked
Right-click on the Stop button, select Connect|actionPerformed, click on the excel bean, select Connectable Features ..., and select the setVisible method:
The default parameter is false, which will make excel invisible. You may wish to double-click on the connection to verify this.
Right-click on the Stop button, select Connect|actionPerformed, click on the excel bean, select Connectable Features ..., and select the quit method:
Right-click on the Stop button, select Connect|actionPerformed, click on the excel bean, select this. Then double-click on the new connection, click on Set Parameters, and specify null:
You will now create a variable representing the com.linar.jintegra.Cleaner class. Click on the Variable item from the other pallet, and then click to the right of the excel bean, below the dotted line:
Change the variable name to cleaner by right-clicking on the new bean, and selecting Change bean name...:
Change the variable type to Cleaner by right-clicking on the new bean, and selecting Change Type...:
Right-click on the Stop button, select Connect|actionPerformed, click on the cleaner bean, select Connectable Features ..., and select the releaseAll() method:
Right-click on the Stop button, select Connect|actionPerformed, click on the Visible bean, select state:
This will set the state to false, and thus uncheck the checkbox (false is the default).
You may wish to double check the connections from the stop button. Right-click on the stop button, and select Reorder Connections From .... You should see something like this:
Your form should look something like this:
Summary of what you have just accomplished: When you click on the stop button, Excel is made invisible, and quitted. The reference to Excel is set to null (which has the side-effect of unsubscribing from any events that were subscribed-to). All references to remote COM components are released, and the 'Visible' checkbox is unchecked.
Click on the Run button:
VisualAge will generate code, and then start up the applet viewer. Fill in the form with an appropriate domain/user/password, and specify the host on which Excel will be started (probably localhost, meaning the current machine), and click on Start:
Wait ten seconds to allow Excel to start, and then check the Visible checkbox. Excel should appear:
Create a new workbook in Excel. You should see that a NewWorkbook event has been generated:
Finally, click on the Stop button. You may wish to use the NT Task Manager to verify that Excel has indeed been shut down.
In this example, you have seen how the Java classes and interfaces generated by J-Integra®'s com2java tool can be manipulated in a GUI builder environment. You have seen how properties, methods and events from COM components are exposed as their Java counterparts, and recognised as such by VisualAge.
J-Integra® seamlessly presents COM components as Java components, invisibly translating the setting of properties, the invocation of methods, and the subscription/handling of events into their COM counterparts.
As a Java software developer, you wouldn't even know that Excel was anything other than pure Java, and that, in our opinion, is how Java/COM integration should be.
Because J-Integra® requires no native code to integrate Java software with COM components, the Applet generated in this example, combined with J-Integra®'s pure Java runtime (jintegra.jar) should run on any platform that supports a standard JVM.