This document describes version 6 of Unblu. If you’re using the latest major version of Unblu, go to the documentation of the latest version.

The support period for version 6 ended on 29 August 2023. We no longer provide support or updates for this version. You should upgrade to the latest version of Unblu.

Java Naming and Directory Interface (JNDI) Datasource

The Java Naming and Directory Service (JNDI) can be used to manage connections to the database server. See Oracle’s JNDI overview for more on the JNDI architecture.

Using JNDI-datasource does not require the WAR file to be modified. We recommend you define JNDI environment vars or datasources in the 'context' file of your applications server. For example, in Tomcat this file is called context.xml.

Advantages of using JNDI

You can derive most power from JNDI if your deployment is complex. Abstracting the lookup of resources means not having to, for example, change and deploy properties/configuration files for each environment separately. The more varying deployment stages, such as test, production, etc., the more benefit you would accrue from using JNDI.

Migrating an application between environments (such as Integration > Test > Production) becomes much simpler. You can have multiple databases in each new environment without changing the Unblu deployment package.

As long as each app server uses the same JNDI name you can drop the WAR file into any environment. Using JNDI datasource does not require the Unblu WAR file to be modified.

Standardizes the configuration of database connections.
Enables the use of password encryption (passwords are currently stored as clear text strings). See Encrypting Passwords in Tomcat for more on encrypting your database passwords.
Allows more fine grained control over database connection pooling settings

Disadvantages of using JNDI

Configuration split into two pieces. Unblu configuration only points to separate configuration of the app server. Forgetting to setup the app server’s configuration properly lets Unblu fail at times.

Implementing JNDI Datasource

To implement JNDI Datasource you must enable four configuration items. Two for the main configuration and two for the Admin connection (the Admin connection is used with administration credentials to set up the table structures).

com.unblu.storage.database.datasourceFactory

com.unblu.storage.database.datasourceName

com.unblu.storage.database.adminDatasourceFactory

com.unblu.storage.database.adminDatasourceName

Main configuration items

Key = com.unblu.storage.database.datasourceFactory

Values = INTERNAL | USE_PROVIDED (default: INTERNAL)

The com.unblu.storage.database.datasourceFactory item defines whether to look for db credentials in Unblu properties or to expect a datasource to be provided via JNDI.

Key = com.unblu.storage.database.datasourceName

Values = [name of JNDI data source] (default: jdbc/unblu)

The com.unblu.storage.database.datasourceName item provides the JNDI name of the datasource to use, and is only effective when com.unblu.storage.database.datasourceFactory=USE_PROVIDED is configured.

JNDI names are usually defined like so: java:comp/env/jdbc/unblu - in the datasource name here we only need the jdbc/unblu part).

Admin configuration items

Two properties (as above) must also be enabled for the 'Admin' connection.

Key = com.unblu.storage.database.adminDatasourceFactory

Values = INTERNAL | USE_PROVIDED (default: INTERNAL)

Key = com.unblu.storage.database.adminDatasourceName

Values = +[name of JNDI data source] (default: derived from …datasourceName) +

Configuring a JNDI Datasource

For a comprehensive look at how to configure a JNDI Datasource see The JNDI Resources HOW-TO and JNDI-Datasource Examples.

As Unblu does not support customization within the web.xml of a WAR file we recommend you define JNDI environment vars or datasources in, for example, the context.xml file of Tomcat.

Adapt the context.xml file.
Copy the required JDBC driver to the lib directory of Tomcat. (This is so that the driver can be accessed automatically at runtime.)

The context.xml file (Tomcat)

<Context>
<!-- ... -->
  <Resource name="jdbc/unblu"
            auth="Container"
            type="javax.sql.DataSource"
            maxActive="100"
            maxIdle="100"
            minIdle="20"
            maxWait="30000"
            validationQuery="select 1 from dual"
            timeBetweenEvictionRunsMillis="34000"
            minEvictableIdleTimeMillis="60000"
            validationQueryTimeout="3"
            testWhileIdle="true"
            testOnBorrow="false"
            removeAbandoned="true"
            removeAbandonedTimeout="120"
            factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
            username="username"
            password="password"
            driverClassName="oracle.jdbc.driver.OracleDriver"
            url="jdbc:oracle:thin:@//fqdn-of-ths-host:port/db"
<!-- ... -->
</Context>

In the example context.xml file above a Datasource connection is defined using a username, password, JDBC driver, a JDBC URL (where the driver should connect to), and database connection pool settings.

Password encryption in Tomcat

The example context.xml file shown here uses a clear text password. In order to encrypt the password you must use the features of the underlying application server (in this example: Tomcat). See Encrypting Passwords In Tomcat.

Storage overrides

For each of the specific Unblu storage parts, there are specific overrides possible.

# Main
com.unblu.storage.database.main.datasourceFactory
com.unblu.storage.database.main.datasourceName
com.unblu.storage.database.main.adminDatasourceFactory
com.unblu.storage.database.main.adminDatasourceName

# Stats
com.unblu.storage.database.stats.datasourceFactory
com.unblu.storage.database.stats.datasourceName
com.unblu.storage.database.stats.adminDatasourceFactory
com.unblu.storage.database.stats.adminDatasourceName

# Webhooks
com.unblu.storage.database.weho.datasourceFactory
com.unblu.storage.database.weho.datasourceName
com.unblu.storage.database.weho.adminDatasourceFactory
com.unblu.storage.database.weho.adminDatasourceName

# etc.

Fallback chain

The fallback chain makes it possible to selectively specify what is required (i.e., have specific INTERNAL or PROVIDED connections depending on the purpose, or whether it is an admin connection or not).

However, the fallback chain also makes it possible to define one (simple) DB connection and have all of the specific parts derive from it (i.e., use the same connection definition).

For a specific Unblu storage type:

Is the storage-type-specific datasourceXXX defined? If yes: use it.
If not: Is the storage-type-unspecific datasourceXXX defined? If yes: use it.
If not: use the default (i.e. INTERNAL for datasourceFactory).

For the Admin connections:

Is the storage-type-specific-adminDatasourceXXX defined? If yes: use it.
If not: Is the storage-type-unspecific adminDatasourceXXX defined? If yes: use it.
If not: Is the storage-type-specific datasourceXXX defined? If yes: use it.
If not: Is the storage-type-unspecific datasourceXXX defined? If yes: use it.
If not: use the default (i.e. INTERNAL for adminDatasourceFactory)

Extended environment variable definitions

It is now possible to:

Define different variable types other than just String (although eventually these variables are converted back to a string within Unblu).
Hierarchically structure Unblu environment properties as outlined below:

<Environment name="com.unblu.core.server.livetracking.agent.unavailablesessionlimit" value="3" type="java.lang.Integer" /> # an Integer type property
<Environment name="com.unblu.visual.resourcehistory.enabled" value="true" type="java.lang.Boolean"/> # a Boolean type property
<Environment name="com.unblu.chat.videochat.proxyAuthScheme" value="BASIC" type="java.lang.String"/> # a String type property
<Environment name="unblu/com.unblu.storage.database.poolMax" value="32" type="java.lang.Integer"/> # a hierarchically nested property under the tree entry "unblu"

Type information helps during configuration validation. Type-incompatible values will result in an error at startup.

Hierarchical structuring helps to keep the overview; especially in situations where many configuration parameters for various applications are stored using JNDI. Be aware that whatever structure you use, Unblu will only pick up the last part of it. In the above example unblu/com.unblu.storage.database.poolMax is interpreted as com.unblu.storage.database.poolMax within Unblu.

Other changes

The meaning of setting com.unblu.storage.database.platform has changed slightly. While it previously defaulted to org.eclipse.persistence.platform.database.H2Platform, which is the qualified name of an internal implementation class, it is now possible to use the following properties to define the type of database to connect to:

Auto: new default. (Advises Unblu to detect the used database automatically.)
Oracle
MySQL
PostgreSQL
SQLServer

Unblu still supports the ability to define the (internal) class name of the Platform (like the previous default, above, with the H2Platform).