This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Building Apprenda Applications that Connect to Oracle

There are numerous driver options for building .NET or Java applications that connect to Oracle. 

For .NET, Oracle supplies Oracle Data Provider for .NET (ODP.NET); there are also numerous third party options. Although developers are free to determine which drivers work best for their applications, we have tested the following drivers in .NET guest applications that connect to the indicated version of Oracle RDBMS:

  • the 64-bit version of ODP.NET Managed Driver (available for Oracle 12c only) has been tested on applications that use Oracle 12c
  • ​the 64-bit version of ODP.NET Oracle Data Access Components (ODAC) has been tested on applications that use Oracle 11g and is expected to work with applications that use Oracle 12c
  • dotConnect for Oracle driver provided by devArt has been tested on applications that use Oracle 11g and is expected to work with applications that use Oracle 12c

For Java, Oracle Thin driver has been tested on applications that use Oracle 11g and is expected to work with applications that use Oracle 12c.

ODP.NET Manager Driver (available for Oracle 12c only)

As per the details below, using ODP.NET Managed Driver requires developers to include driver files in their archive. 

The latest release of 64-bit ODP.NET Managed Driver is recommended; in the file names below, please replace {latestRelease} with the numbers that correspond to the latest Managed Driver release. It should be noted that support for encryption was introduced in the Managed Driver for 64-bit ODAC 12c Release 4 (12.1.0.2.4).

Required Files

From ODP.NET_Managed_ODAC12c{latestRelease}.zip
http://www.oracle.com/technetwork/database/windows/downloads/index-090165.html

  • Oracle.ManagedDataAccess.dll

Visual Studio Project Setup

In the project that uses ODP.NET:

  • Add a reference to Oracle.ManagedDataAccess.dll

    • Make sure to set Copy Local = true for this reference
    • Build Action = Content
    • Copy to Output Directory = Copy if newer

NOTE: If ODP.NET managed data access is isolated in a class library, then every executable (ASP.NET website, console app, WCF service, etc) that references this class library will also need an explicit reference to Oracle.ManagedDataAccess.dll with Copy Local = true.

Config File Modifications

For every executable project that uses ODP.NET directly or through a class library, the following section needs to be added to the app/web.config:

<system.data>
    <DbProviderFactories>
      <remove invariant="Oracle.DataAccess.Client" />
      <add name="Oracle Data Provider for .NET" invariant="Oracle.DataAccess.Client" description="Oracle Data Provider for .NET" type="Oracle.ManagedDataAccess.Client.OracleClientFactory, Oracle.ManagedDataAccess, Version=4.112.3.0, Culture=neutral, PublicKeyToken=89b483f429c47342" />
    </DbProviderFactories>
</system.data>

Take special note of the "Version" of Oracle.ManagedDataAccess, as it must match the file version of the Oracle.ManagedDataAccess.dll. File version can be found in the "Details" section of the properties of the Oracle.ManagedDataAccess.dll file.

ODP.NET ODAC

There are two options for using ODAC:

  • Your Platform Operator may install ODAC on Apprenda Servers. This options is viable if disk space is a concern and if there is no expectation that the affected servers will not also host guest application databases that use different drivers, such as ODP.NET Managed Driver (as installing ODAC will prevent applications that use other drivers from functioning correctly).
  • Developers may include ODAC in their guest application archive. This will result in larger archives, but will allow much more flexibility in terms of using applications that leverage other drivers.

The latest version of 64-bit ODAC is recommended; in the file names below, please replace {latestVersion} with the numbers that correspond to the latest ODAC version.

Install ODAC on Apprenda Servers

ODAC can be downloaded at
http://www.oracle.com/technetwork/database/windows/downloads/index-090165.html

If ODAC is installed on all Oracle servers that may run an application that leverages Oracle, no further setup is needed. The required assemblies will be installed in the GAC, and the machine.config will be updated to include the correct DbProviderFactory.

Your Platform Operator may also choose to install ODAC only on specific Apprenda servers and use Custom Properties and Deployment Policies to make sure that your application's components that require ODAC are placed on the servers that have it installed.

Include ODAC in the Application Archive

This approach allows developers to package ODAC with an application rather than installing it on each server.  While this eases the burden of server configuration, it dramatically increases the size of an application archive and the disk space required by an application. 

Required Files

From Oracle Instant Client (instantclient-basiclite-windows.x64-{latestVersion}.zip)
http://www.oracle.com/technetwork/topics/winx64soft-089540.html

  • oci.dll
  • ociw32.dll
  • orannzsbb11.dll
  • oraocci11.dll
  • oraociicus11.dll

From ODAC XCopy (ODAC{latestVersion}Xcopy_x64.zip)
http://www.oracle.com/technetwork/database/windows/downloads/index-090165.html

  • \odp.net4\bin\OraOps11w.dll
  • \odp.net4\odp.net\bin\4\Oracle.DataAccess.dll

Visual Studio Project Setup

In the project that uses ODP.NET:

  • Add a reference to Oracle.DataAccess.dll

    • Make sure to set Copy Local = true for this reference
  • Add the other 6 dlls to the root of your project.
    • Build Action = Content
    • Copy to Output Directory = Copy if newer

NOTE: If ODP.NET data access is isolated in a class library, then every executable (ASP.NET website, console app, WCF service, etc) that references this class library will also need an explicit reference to Oracle.DataAccess.dll with Copy Local = true.

Config File Modifications

For every executable project that uses ODP.NET directly or through a class library the following section needs to be added to the app/web.config.

<system.data>
    <DbProviderFactories>
      <remove invariant="Oracle.DataAccess.Client" />
      <add name="Oracle Data Provider for .NET" invariant="Oracle.DataAccess.Client" description="Oracle Data Provider for .NET" type="Oracle.DataAccess.Client.OracleClientFactory, Oracle.DataAccess, Version=4.112.3.0, Culture=neutral, PublicKeyToken=89b483f429c47342" />
    </DbProviderFactories>
</system.data>

Take special note of the "Version" of Oracle.DataAccess, as it must match the file version of the Oracle.DataAccess.dll. File version can be found in the "Details" section of the properties of the Oracle.DataAccess.dll file.

dotConnect for Oracle

When your application uses dotConnect for Oracle you will need to include all required dotConnect dlls in your archive, as well as embed your dotConnect license in your assemblies.  

The latest version of dotConnect for Oracle is recommended. It should be noted that limitations of dotConnect for Oracle include 1) no inherent support for Oracle RAC and 2) no encryption options.

The remainder of this section assumes that you have dotConnect for Oracle installed on the developer machine(s) used to create the application.

Project References

All dotConnect references should set Copy Local = true.

Also, if you use dotConnect from a separate class library all top-level executable projects (ASP.NET, WCF service, console app, etc) that reference this library will also need to explicitly reference all required dotCOnnect dlls and set Copy Local = true.

License Management

The project(s) that use dotConnect will need an embedded license file, as well as a config file telling dotConnect which executables are allowed to accept the license.  This can all be done automatically through the Visual Studio integration that is included with dotConnect.

  • Open your application's solution in Visual Studio
  • From the Tools menu choose Oracle -> License Information
  • Click the "Fix" button next to any project that needs an embedded dotConnect license
  • This will launch a wizard where most of the default options work fine.  However, if your application uses dotConnect from a WCF service that will run on Apprenda one additional step is need:
    • On the screen that says "Specify which executables are allowed to use the class library" add "SaaSGrid.SMART.ServiceBootstrap.exe"
    • This is the name of the executable that will be running your service once it is deployed on Apprenda

Oracle Thin driver

Get the latest version of the driver:

http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html

Add the driver to the project:

This can be done directly, by adding it as a library, or indirectly through maven:

  • Add it to your maven repository
  • Run this from the location of the file (version=the version from the download page)
mvn install:install-file -DgroupId=com.oracle -DartifactId=ojdbc6 -Dversion=11.2.0.4.0 -Dpackaging=jar -Dfile=ojdbc6.jar -DgeneratePom=true
  • Add the reference to your pom.xml:
<dependency>
    <groupId>com.oracle</groupId>
    <artifactId>ojdbc6</artifactId>
    <version>11.2.0.4.0</version>
</dependency>

It should be noted that "version" and "-Dversion" in the examples above should be updated to match the version of the driver you are using.