Difference between revisions of "Database/Drivers/New Driver Tutorial"

From Apache OpenOffice Wiki
Jump to: navigation, search
m
(No difference)

Revision as of 20:25, 16 October 2006

Preface

This small How To contains simple step-by-step introduction how to put your driver inside connectivity module. Second part of this document covers differences between driver in connectivity module and driver in an UNO package. This document is not manual how to write driver, but how to put it in OpenOffice.org connectivity module.

Parts of our driver

Lets say, that our driver implements following services:

   sdbc.Driver - org.openoffice.comp.connectivity.6sql.Driver
   sdbc.Connection – org.openoffice.comp.connectivity.6sql.Connection

For more complicated example, lets assume that our driver depends on two external libraries. Because we are covering Windows platform only, these libraries are in DLL files. Name of these libraries are lib6sql.dll and lib6sql-security.dll. These libraries must be installed inside OpenOffice.org/program directory otherwise our driver will not work.

External libraries

External module and deliver script

Put your external libraries in external/6sql directory and add following lines in external/prj/d.lst file:

   ..\6sql\lib6sql.dll %_DEST%\bin%_EXT%\lib6sql.dll
   ..\6sql\lib6sql-security.dll %_DEST%\bin%_EXT%\lib6sql-security.dll

This makes deliver happy and your DLL libraries will be deliver to solver directory.

Installation

You have to look at scp2 module. Define gid's for your libraries in scp2/source/ooo/file_library_ooo.scp:

   #ifdef WNT
   
   File gid_File_Lib_6sql
       BIN_FILE_BODY;
       Styles = (PACKED);
       Dir = gid_Dir_Program;
       Name = "lib6sql.dll";
   End
   
   File gid_File_Lib_6sql_security
       BIN_FILE_BODY;
       Styles = (PACKED);
       Dir = gid_Dir_Program;
       Name = "lib6sql-security.dll";
   End
   
   #endif

Do not forget to put your gid's in scp2/source/ooo/module_hidden_ooo.scp to install your DLL libraries within hidden module.

Driver

Connectivity module

We put our driver in connectivity/source/drivers/6sql directory. To build and deliver it properly, we need to modify build.lst and d.lst files. Add following line in connectivity/prj/build.lst file:

   cn connectivity\source\drivers\6sql nmake - all cn_6sql cn_dbtools NULL

And add following line in connectivity/prj/d.lst file:

   ..\source\drivers\6sql\*.xml %_DEST%\xml%_EXT%\*.xml

This makes build and deliver happy when build process reaches connectivity module.

Driver service

Let's assume that our sdbc.Driver service is implemented and compiled into 6sql-driver.dll library. We have to create 6sql-driver.xml file with following content:

   <?xml version='1.0' encoding="UTF-8"?>
   <!DOCTYPE COMPONENTDESCRIPTION PUBLIC "-//W3C//DTD HTML 3.2//EN" "module-description.dtd">
   <module-description xmlns:xlink="http://www.w3.org/1999/xlink">
       <module-name> 6sql-driver </module-name>
       <component-description>
           <Author>Your Name</Author>
           <Name>org.openoffice.comp.connectivity.6sql.Driver</Name>
           <Description>
               This is the implementation of the 6SQL bridge.
           </Description>
           <loader-name>com.sun.star.loader.SharedLibrary</loader-name>
           <language>c++</language>
           <status value="final"/>
           <supported-service>	com.sun.star.sdbc.Driver	</supported-service>
           <service-dependency>	...	</service-dependency>
       </component-description>
   </module-description>

Do not forget to put your build and run dependencies in this file. Search for xml files inside source/drivers directory to get more examples.

Connection service

Let's assume that our sdbc.Connection service is implemented and compiled into 6sql-connection.dll library. We have to create 6sql-connection.xml file with following content:

   <?xml version='1.0' encoding="UTF-8"?>
   <!DOCTYPE COMPONENTDESCRIPTION PUBLIC "-//W3C//DTD HTML 3.2//EN" "module-description.dtd">
   <module-description xmlns:xlink="http://www.w3.org/1999/xlink">
       <module-name> 6sql-connection </module-name>
       <component-description>
           <Author>Your Name</Author>
           <Name>org.openoffice.comp.connectivity.6sql.Connection</Name>
           <Description>
               This is the implementation of the 6SQL connection.
           </Description>
           <loader-name>com.sun.star.loader.SharedLibrary</loader-name>
           <language>c++</language>
           <status value="final"/>
           <supported-service>	com.sun.star.sdbc.Connection	</supported-service>
           <service-dependency>	...	</service-dependency>
       </component-description>
   </module-description>

Again, do not forget to put some build and run dependencies in this file. Now, you should have idea why we put *.xml in project deliver file.

Installation

We have to install our driver libraries in similiar way as external libraries. Our driver implements services, it's an UNO compoment, we have to modify our gid's definitions. So, put following lines in scp2/source/ooo/file_library_ooo.scp file:

   #ifdef WNT
   
   File gid_File_Lib_6sql_driver
       TXT_FILE_BODY;
       Styles = (PACKED,UNO_COMPONENT,PATCH);
       RegistryId = gid_Starregistry_Services_Rdb;
       Dir = gid_Dir_Program;
       Name = "6sql-driver.dll";
   End
   
   File gid_File_Lib_6sql_connection
       TXT_FILE_BODY;
       Styles = (PACKED,UNO_COMPONENT,PATCH);
       RegistryId = gid_Starregistry_Services_Rdb;
       Dir = gid_Dir_Program;
       Name = "6sql-connection.dll";
   End
   
   #endif

And do not forget to put our gid's in module_hidden_ooo.scp file.

Configuration

Last step is to make our driver visible to OpenOffice.org. Everything is inside officecfg/registry/data/org/openoffice/Office/DataAccess.xcu file. Following node should be placed there as a root node:

   <node oor:name="UserDefinedDriverSettings">
       <node oor:name="6SQL Driver" oor:op="replace">
           <prop oor:name="DriverTypeDisplayName">
               <value>6SQL</value>
           </prop>
           <prop oor:name="DriverPageDisplayName">
               <value>6SQL</value>
           </prop>
           <prop oor:name="DriverDsnPrefix">
               <value>sdbc:6sql:</value>
           </prop>
       </node>	
   </node>

This makes your driver visible in available drivers list. Now, make this driver visible to OpenOffice.org with following lines:

   <node oor:name="org.openoffice.comp.connectivity.6sql.Driver" oor:op="replace">
       <prop oor:name="DriverName">
           <value>org.openoffice.comp.connectivity.6sql.Driver</value>
       </prop>
       <prop oor:name="Enable">
           <value>false</value>
       </prop>
       <prop oor:name="Timeout">
           <value>60</value>
       </prop>
   </node>

This node should be placed in ConnectionPool/DriverSettings node.

Driver as UNO package

If you want to publish your driver as an UNO package, you have to build your driver libraries, put them inside UNO package with DataAccess.xcu file only. Content of this file should be:

   <node oor:name="UserDefinedDriverSettings">
       <node oor:name="6SQL Driver" oor:op="replace">
           <prop oor:name="DriverTypeDisplayName">
               <value>6SQL</value>
           </prop>
           <prop oor:name="DriverPageDisplayName">
               <value>6SQL</value>
           </prop>
           <prop oor:name="DriverDsnPrefix">
               <value>sdbc:6sql:</value>
           </prop>
       </node>	
   </node>

Easy? Yes, it is. Be modular and use UNO packages ;-) Easier way and you can update your driver more frequently.

Summary

You can use this How To for other platforms too. You have to use #ifdef, .so instead of .dll, etc. Search for more examples in all mentioned files. This just works. I'm not sure if everything is OK or not. If you find mistakes, just let me know.

Personal tools