After the database is ready, you need to configure eXo Platform to connect to it. The configuration steps may be different, depending on the application server. Here are instructions for Tomcat and JBoss.
Step 1: Defining datasource name
The default datasource name is exo-idm_portal (for IDM) and exo-jcr_portal (for JCR). You can optionally change it by following steps:
Edit
$PLATFORM_TOMCAT_HOME/gatein/conf/configuration.propertiesfile to change "exo-idm" and "exo-jcr" part to the names you want:# JNDI Name of the IDM datasource gatein.idm.datasource.name=java:/comp/env/exo-idm ... # name of the datasource that will be used by eXo JCR gatein.jcr.datasource.name=java:/comp/env/exo-jcr
Note
eXo Platform automatically appends the portal container name ("_portal" by default) to these values before performing a JNDI lookup. This means, if you use exo-jcr in this step, you will use exo-jcr_portal in Step 3, Binding.
Edit the resource names in
$PLATFORM_TOMCAT_HOME/conf/Catalina/localhost/context.xml.default. Notice the suffix "_portal" needs to be added to the names:<ResourceLink name="exo-jcr_portal" global="exo-jcr_portal" type="javax.sql.DataSource"/>
<ResourceLink name="exo-idm_portal" global="exo-idm_portal" type="javax.sql.DataSource"/>
Step 2: Defining Hibernate SQL Dialect for Database configuration
Normally, the eXo Platform server automatically detects Hibernate SQL dialect for almost database servers listed in Hibernate Reference Documentation. Otherwise, you need to declare explicitly the value of hibernate.dialect parameter. For example, use org.hibernate.dialect.PostgresPlusDialect when you configure eXo Platform with Postgres Plus Advanced Server 9.2. See Customizing environment variables to know how to set environment variables.
Step 3: Binding a database schema to the datasource
Open the
$PLATFORM_TOMCAT_HOME/conf/server.xmlfile.Here is an explanation of default (HSQL) configurations:
<!-- eXo JCR Datasource for portal -->
<Resource name="exo-jcr_portal" auth="Container" type="javax.sql.DataSource"
initialSize="5" maxActive="20" minIdle="5" maxIdle="15" maxWait="10000"
validationQuery="SELECT 1 FROM INFORMATION_SCHEMA.SYSTEM_USERS" validationQueryTimeout="5"
testWhileIdle="true" testOnBorrow="true" testOnReturn="false"
timeBetweenEvictionRunsMillis="30000" minEvictableIdleTimeMillis="60000"
removeAbandoned="true" removeAbandonedTimeout="300" logAbandoned="false"
poolPreparedStatements="true"
username="sa" password=""
driverClassName="org.hsqldb.jdbcDriver" url="jdbc:hsqldb:file:${gatein.data.dir}/hsql/exo-plf;shutdown=true;hsqldb.write_delay=false;"/>
The default datasource name is exo-jcr_portal for JCR and exo-idm_portal for IDM. You do not need to change this value unless you change it in the previous step.
The username and password to connect to your database.
The driver class name and URL. The default values here are for HSQL.
Change above configurations to your database system, with some notes:
To ease configurations, eXo Platform provides samples for some databases in files:
$PLATFORM_TOMCAT_HOME/conf/server-mssql.xml$PLATFORM_TOMCAT_HOME/conf/server-hsqldb.xml$PLATFORM_TOMCAT_HOME/conf/server-mysql.xml$PLATFORM_TOMCAT_HOME/conf/server-postgres.xml$PLATFORM_TOMCAT_HOME/conf/server-postgresplus.xml$PLATFORM_TOMCAT_HOME/conf/server-oracle.xml$PLATFORM_TOMCAT_HOME/conf/server-sybase.xml$PLATFORM_TOMCAT_HOME/conf/server-db2.xml
In case your database character set is
utf8, you should append this character encoding to the url. For example, in MySQL:url="jdbc:mysql://localhost:3306/plf?autoReconnect=true&characterEncoding=utf8"
Particularly to Microsoft SQL, ensure that you have the sendStringParametersAsUnicode=false parameter in the JDBC connection URL as in the example below:
<Resource name="exo-idm_portal" auth="Container" type="javax.sql.DataSource"
initialSize="5" maxActive="20" minIdle="5" maxIdle="15" maxWait="10000"
validationQuery="SELECT 1" validationQueryTimeout="5"
testWhileIdle="true" testOnBorrow="true" testOnReturn="false"
timeBetweenEvictionRunsMillis="30000" minEvictableIdleTimeMillis="60000"
removeAbandoned="true" removeAbandonedTimeout="300" logAbandoned="false"
poolPreparedStatements="true"
username="plf" password="plf" driverClassName="com.microsoft.sqlserver.jdbc.SQLServerDriver"
url="jdbc:sqlserver://localhost:1433;databaseName=plf;sendStringParametersAsUnicode=false" />
This parameter is necessary to avoid any possible performance problem. MS SQL Server differentiates Unicode data types (such as nchar) from ASCII data types (such as char). By default, (without this parameter) all the JDBC drivers send strings in Unicode format to SQL Server. When, for example, doing a comparison on a non-Unicode column, SQL Server tries to convert data in the table into Unicode first. This conversion might cause the serious performance issue.
The parameter is a bit different between JDBC Drivers. See more details here.
Install your database's JDBC driver into
$PLATFORM_TOMCAT_HOME/lib.
Step 1: Defining the datasource name
The default datasource name is exo-idm_portal (for IDM) and exo-jcr_portal (for JCR). You can optionally change it by following steps:
Open the
$PLATFORM_JBOSS_HOME/standalone/configuration/gatein/configuration.propertiesfile.Edit the following properties to change "exo-idm" and "exo-jcr" part to the names you want:
# JNDI Name of the IDM datasource gatein.idm.datasource.name=java:/comp/env/exo-idm ... # name of the datasource that will be used by eXo JCR gatein.jcr.datasource.name=java:/comp/env/exo-jcr
Note
eXo Platform automatically appends the portal container name ("_portal" by default) to these values before performing a JNDI lookup. It means, if you use exo-jcr in this step, you will use exo-jcr_portal in Step 3.
Step 2: Defining Hibernate SQL Dialect for Database configuration
Normally, the eXo Platform server automatically detects Hibernate SQL dialect for almost database servers listed in Hibernate Reference Documentation. Otherwise, you need to declare explicitly the value of hibernate.dialect parameter. For example, use org.hibernate.dialect.PostgresPlusDialect when you configure eXo Platform with Postgres Plus Advanced Server 9.2. See Customizing environment variables to know how to set environment variables.
Step 3: Binding a database schema to the datasource
Open the
$PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xmlfile.Here is an explanation of default (HSQL) configurations:
<!-- eXo JCR Datasource for PLF -->
<datasource enabled="true" jndi-name="java:/comp/env/exo-jcr_portal" jta="true" pool-name="exo-jcr_portal" spy="false" use-ccm="true" use-java-context="true">
<driver>hsqldb-driver.jar</driver>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<connection-url>jdbc:hsqldb:file:${gatein.data.dir}/hsql/exo-plf;shutdown=true;hsqldb.write_delay=false;</connection-url>
...
<security>
<user-name>sa</user-name>
<password/>
</security>
...
</datasource>
The default datasource name is exo-jcr_portal for JCR and exo-idm_portal for IDM. You do not need to change this value unless you changed it in previous step.
The driver class and connection URL. The default values here are for HSQL.
The username and password to connect to your database.
Change above configurations to your database system, with some notes:
To ease the configuration, eXo Platform presets the
$PLATFORM_JBOSS_HOME/standalone/configuration/standalone-exo.xmlfile with configurations for:MSSQL
MySQL
PostgreSQL
Postgres Plus Advanced Server
Oracle
Sybase
DB2
In case your database character set is
utf8, you should append this character encoding to the url. For example, in MySQL:url="jdbc:mysql://localhost:3306/plf?autoReconnect=true&characterEncoding=utf8"
Particularly to Microsoft SQL, you need to add the sendStringParametersAsUnicode=false parameter to the connection string as in the example below:
<datasource enabled="true" jndi-name="java:/comp/env/exo-idm_portal" jta="false" pool-name="exo-idm_portal" spy="false" use-ccm="true" use-java-context="true">
...
<!-- Microsoft SQLServer -->
<driver>XXXX.jar</driver>
<driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>
<connection-url>jdbc:sqlserver://localhost:1433;databaseName=plf;sendStringParametersAsUnicode=false</connection-url>
...
</datasource>
This parameter is necessary to avoid any possible performance problem. MS SQL Server differentiates Unicode data types (such as nchar) from ASCII data types (such as char). By default, (without this parameter) all the JDBC drivers send strings in Unicode format to SQL Server. When, for example, doing a comparison on a non-Unicode column, SQL Server tries to convert data in the table into Unicode first. This conversion might cause the serious performance issue.
The parameter is a bit different between JDBC Drivers. See more details here.
Install your database's JDBC driver into
$PLATFORM_JBOSS_HOME/standalone/deployments.