Connecting to custom data sources
iHub runs designs using third-party software to connect to data sources. The following sections describe how to install custom data source connection software:
Installing a custom open data access (ODA) driver
iHub supports open data access (ODA) drivers that a design uses to retrieve data from a data source. To install an ODA driver, place the ODA driver files in the AC_SERVER_HOME/oda directory. AC_SERVER_HOME refers to the folder that the iHub installer chose as the location for binary files during the iHub installation. By default, this location is /Program Files (x86)/Actuate/iHub2 in a Windows environment, and <installation directory>/AcServer in a Linux environment.
Each ODA driver must be in a separate directory. For example, if you have two ODA drivers, the installation directories would be similar to the following directories:
AC_SERVER_HOME/oda/oda-driver1
AC_SERVER_HOME/oda/oda-driver2
iHub does not support installing ODA drivers in a directory below the oda directory. For example, if you have two ODA drivers, Driver1 and Driver2, iHub does not support the following ODA directory structure for the two drivers:
AC_SERVER_HOME/oda/CustomDrivers/Driver1
AC_SERVER_HOME/oda/CustomDrivers/Driver2
The directory name for an ODA driver in the AC_SERVER_HOME/oda directory must match the driver name specified in an Actuate Basic information object (.dox).
When installing an ODA driver, you must also install and configure any software the ODA driver requires to access a data source. For example, you must install and configure any database connection software the ODA driver uses to connect to a database. You must also ensure the ODA driver can access the required software.
Install the configuration file and files required for the ODA driver on the machine that runs the design. Each ODA driver requires a run-time configuration file, odaconfig.xml. The configuration file must be in the ODA driver directory. You can locate the ODA library files outside of the Actuate installation directory. Specify the location in odaconfig.xml.
The iHub installation process puts the Actuate Data Integration service driver in the AC_SERVER_HOME/oda directory. The installation also provides an example of an ODA flat file driver that operates with iHub in ACTUATE_HOME/oda/examples/FlatFileExample.
Installing a custom Eclipse DTP ODA driver plug‑in
A design can use a custom Eclipse Data Tools Platform (DTP) open data access (ODA) driver to retrieve data from a data source. The DTP ODA API supports building a custom Eclipse plug-in that accesses data from standard and custom data sources.
Install a plug‑in in the AC_SERVER_HOME/MyClasses/eclipse/plugins directory. You may need to manually create the eclipse/plugins subdirectory if it does not already exist in MyClasses. In the Linux installation of iHub, there is a common folder, acshared/MyClasses, for installing a customized DTP ODA driver.
Do not place a custom ODA plug-in in the AC_SERVER_HOME/oda/eclipse/plugins directory. This directory is reserved only for plug-ins provided by the Actuate product installation. Installing a plug-in in the AC_SERVER_HOME/MyClasses/eclipse/plugins directory ensures that the Actuate install and uninstall processes do not remove the custom plug-in.
About using an ODA driver
When running a design using an ODA driver, the Factory process loads the driver during the document generation. If the Factory process cannot load the specified driver, iHub logs an error message and document generation terminates.
An ODA driver cannot share a library file with another ODA driver or data source connection software. Each ODA driver must have a separate copy of the library file for dedicated use. For example, on a Windows system, if a database library uses a DLL to connect to a data source, and an ODA driver uses the same DLL, you create a copy of the DLL file and use the copy with the ODA driver.
If you change an ODA driver’s configuration such as a setting in the configuration file or an ODA driver library, the Factory process uses the updated configuration information and the updated library during the next document generation.
iHub can cache an ODA driver. If a Factory process uses a cached ODA driver, the Factory process checks the last modified time of the configuration file and the cached driver’s run-time libraries before document generation. If you modify the configuration file or the driver since last loading the driver, the Factory process releases the cached driver and reloads it.
Using custom Java-based data source connections
To connect BIRT designs to JDBC data sources, place the .jar files for the custom database driver in:
AC_SERVER_HOME\Jar\birt\platform\plugins\ org.eclipse.birt.report.data.oda.jdbc<version>\drivers
The iHub Integration service also looks in this location for drivers to access JDBC data sources.
Using custom relational data sources with the Integration service
iHub connects to Actuate information object data sources using the BIRT iHub Integration service (AIS). AIS works with JDBC drivers that are compliant with DataDirect Connect for JDBC version 3.7 Service Pack 1 and later.
AIS uses configuration files that define the data source connections.
AC_SERVER_HOME/etc/data_integration/datasources.xml contains a list of custom relational data sources.
AC_SERVER_HOME/etc/data_integration/<database>/mappings.xml contains the data source mappings for a custom relational data source.
Specifying connection types
iHub installation provides an example of a datasources.xml configuration file that specifies a MySQL Enterprise connection type as an example. The datasources.xml file specifies the JDBC connection type as shown in
Listing 11‑2.
Listing 11‑2 Specifying JDBC connection types in datasources.xml
<DataSourceConfig>
<DataSourceHosts>
</DataSourceHosts>
<ConnectionTypes>
<
-- Example: MySQL Enterprise connection type
(requires MySQL driver) -->
<ConnectionType Name="MySQL_41">
<JDBCDriver DriverName="com.mysql.jdbc.Driver">
<ConnectionString>
jdbc:mysql://%server%:%port%/%database%?
</ConnectionString>
<ConnectionProperties>
<Property Name="user">%username%</Property>
<Property Name="password">%password%</Property>
</ConnectionProperties>
<LibraryPath>
<
-- Fill in JAR location below -->
<Location></Location>
</LibraryPath>
</JDBCDriver>
<ConnectionParams>
<ConnectionParam Name="server"
Display="Server"
Type="string"
ValueIsCaseSensitive="false"/>
<ConnectionParam Name="database"
Display="Database"
Type="string"
ValueIsCaseSensitive="false"/>
<ConnectionParam Name="username"
Display="User name"
Type="string"/>
<ConnectionParam Name="password"
Display="Password"
Type="masked"/>
<ConnectionParam Name="port"
Display="Port"
Type="integer"
Optional="true"
DefaultValue="3306"/>
</ConnectionParams>
</ConnectionType>
</ConnectionTypes>
<DatabaseTypes> <
-- Example: MySQL data base type -->
<
--
<DatabaseType Name="MySQL_41" DisplayName="MySQL 4.1"
ConnectionType="MySQL_41"
DataSourceMapper="BaseMySQLMapper"
DataSourceMapping="MySQL"/>
-->
</DatabaseTypes>
</DataSourceConfig>
Specify the location of the JDBC driver in <Library Path>, as shown in
Listing 11‑2. Place the driver classes or Java archive (.jar) files accessing JDBC data sources in the /drivers directory, as described earlier in this document.