INFO: Using ActiveX Data Objects (ADO) via Visual J++

Last reviewed: April 9, 1998
Article ID: Q183591

The information in this article applies to:

ActiveX Data Objects (ADO), versions 1.0, 1.5

SUMMARY

The Java Typelib Wizard allows you to import OLE Automation servers. When used with ActiveX Data Objects (ADO), it can simplify exposing data to your Java-based application. This article discusses what is necessary to take advantage of ADO from Java via the Typelib Wizard.

MORE INFORMATION

The Java TypeLib Wizard

You can use the Java Typelib Wizard to import the ADO typelib. Typically, you would invoke the wizard on the following string:

   Microsoft ActiveX Data Objects 1.5 Library

You want to distinguish between this and the other option below:

   Microsoft ActiveX Data Objects 1.5 Recordset Library

The first library is the full ADO object model and the second is a subset featuring just the Recordset object and is used in conjunction with the Remote Data Service. If you are not marshalling Recordsets across the web or network, you should choose the Microsoft ActiveX Data Objects 1.5 Library.

The process of importing the Typelib file creates compiled Java classes for both ADO objects as well as enumerated types. You can view the Java definitions to invoke these objects in the Summary.txt file using the following path:

   <windows directory>\java\trustlib\msado15\Summary.txt

After you have imported the ADO typelib, you can then reference it in your code as shown below.

Sample Code

   import msado15.*
   ...
   public  Variant     vtEmpty  = new Variant();
   public  Variant     vtEmpty2 = new Variant();
   public  String      bstrEmpty = new String();
   vtEmpty.noParam();
   vtEmpty2.noParam();
   ...
   msado15._Connection  Conn1  = new msado15.Connection();
   Conn1.putConnectionString ( bstrAccessConnect );
   Conn1.Open( bstrEmpty, bstrEmpty, bstrEmpty, -1 );
   ...
   Rs1 = Cmd1.Execute( vtEmpty, vtEmpty2,
                       msado15.CommandTypeEnum.adCmdText );

Note that the ADO Typelib is specifically referenced both for ADO objects (Msado15.Connection) and for ADO enumerated types (Msado15.CommandTypeEnum). You can remove this through the use of the implements keyword as shown in the code-snippet below:

   class ADOCore implements msado15.CommandTypeEnum {
      public void foo {
         int x = adCmdText;
      }
   }

Default Arguments

Within Java you will be explicitly specifying each argument in a method, whereas in other implementations (such as Visual Basic for Applications [VBA]), you could take advantage of the default values that the ADO Typelib defines. Consider the Connection.Open() method that takes as it's first argument a connection string. However, you could also specify this information in the Connection.ConnectionString property.

Depending on whether the method expects a String or Variant (in C++ this would be a BSTR or VARIANT), you can pass "empty" strings and variants. This is why the code snippet above has the following variables pre-defined and ready for use.

   public  Variant     vtEmpty  = new Variant();
   public  Variant     vtEmpty2 = new Variant();
   public  String      bstrEmpty = new String();
   vtEmpty.noParam();
   vtEmpty2.noParam();

The noParam() method initializes the Variant correctly, and it may be necessary to occasionally call noParam() to clear the variant before use, especially with the Recordset.Open() method.

Default Arguments and adXXXUknown Value in Enumerated Types

ADO typically uses enumerated types for many of its arguments within methods where the argument is not a String (BSTR in the Typelib) or Variant type. Some enumerated types have both an Unknown and an Unspecified value. When in doubt, you can use the adXXXUnknown and ADO attempts to determine the correct value.

Exception Handling

You need to be prepared to catch both the Java Exception class, as well as the com.ms.com.ComFailException class. When ADO encounters an error condition, it uses the ComFailException class to display error information within Java. This is not to be confused with the fact that the exception raised may indicate that an underlying data or service provider has encountered an error, in which case you should examine the ADO Errors Collection. If an exception is raised and the ADO Errors Collection is empty, then it is either an ADO exception or some other exception.

Invoking Get/Put Directly

When using ADO within Java, you will be invoking the get/put methods for a given property directly, as opposed to VBA (or #import with C++) where they are hidden.

   Fields1 = Rs1.getFields();

Default Members of ADO Objects & Unseen Item Method

You will be using the Item property to get and put the values of individual items within a collection. In VBA/VBScript this is invisible, but within Java you would reference, for example, the value of a given field object as shown below:

   Variant              v1      = new Variant();
   v1.putInt( (int) 1 );    // Get the first field.
   ...
   Rs1.getFields().getItem( v1 ).getName()

Note that the Fields Collection does not directly reference objects in the collection, but instead allows you to retrieve a specific item through the Item property.

Keywords          : adovj
Version           : WINDOWS:1.0,1.5
Platform          : WINDOWS
Issue type        : kbinfo

================================================================================

THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY.