eXo Platform relies on the application server (Tomcat/JBoss) to access databases. It uses two JNDI datasources:
IDM uses exo-idm_portal.
JCR uses exo-jcr_portal.
eXo provides the ready-made and fine-tuned configuration so typically you just need to choose a sample and modify the connection url and the credentials.
Configure the datasources.
i. Edit conf/server.xml to remove the default HSQL configuration:
<!-- eXo IDM Datasource for portal -->
<Resource name="exo-idm_portal" ...
username="sa" password="" driverClassName="org.hsqldb.jdbcDriver" .../>
<!-- eXo JCR Datasource for portal -->
<Resource name="exo-jcr_portal" ...
username="sa" password="" driverClassName="org.hsqldb.jdbcDriver" .../>
ii. Add a new one. For MySQL as an example, you will just need to copy the sample in conf/server-mysql.xml:
<!-- eXo IDM Datasource for portal -->
<Resource name="exo-idm_portal" auth="Container" type="javax.sql.DataSource"
...
username="plf" password="plf" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/plf?autoReconnect=true" />
<!-- eXo JCR Datasource for portal -->
<Resource name="exo-jcr_portal" auth="Container" type="javax.sql.DataSource"
...
username="plf" password="plf" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/plf?autoReconnect=true" />
iii. Edit username, password, url (host, port and database name). Besides MySQL, if you are using Enterprise Edition,
you will find the samples for other RDBMSs in conf/server-*.xml.
iv. Append this character encoding to the url in case your database character set is utf8.
For example, in MySQL (this is different between RDBMSs):
url="jdbc:mysql://localhost:3306/plf?autoReconnect=true&characterEncoding=utf8"
Set the SQL Dialect if necessary. This step is not mandatory because the dialect is auto-detected in most cases. You only need to take care of it for some particular RDBMSs:
i. For JCR, only when you are using MySQL and database character set utf8,
you need to edit gatein/conf/exo.properties file to have:
exo.jcr.datasource.dialect=MySQL-UTF8
ii. For IDM, eXo Platform detects automatically the dialect for RDBMSs listed
here.
Only when your RDBMS is not in the list, for example Postgres Plus Advanced Server 9.2,
you will need to edit gatein/conf/exo.properties file to have:
hibernate.dialect=org.hibernate.dialect.PostgresPlusDialect
Or for Oracle Database 12c:
hibernate.dialect=org.hibernate.dialect.Oracle10gDialect
If you have not created exo.properties yet, see Configuration overview.
Download the JDBC driver for Java and install it to $PLATFORM_TOMCAT_HOME/lib.
Normally you can find out an appropriate driver for your JDK from your database vendor website. For example, for MySQL: http://dev.mysql.com/downloads/connector/j/, and for Oracle: http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html.
Configure the datasources.
i. Edit standalone/configuration/standalone-exo.xml to remove the default HSQL configuration:
<!-- eXo IDM Datasource for PLF -->
<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">
<!-- HSQLDB -->
<driver>hsqldb-driver.jar</driver>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<connection-url>jdbc:hsqldb:file:${exo.data.dir}/hsql/exo-plf;shutdown=true;hsqldb.write_delay=false;</connection-url>
...
<!-- eXo JCR Datasource for PLF -->
<datasource enabled="true" jndi-name="java:/comp/env/exo-jcr_portal" jta="false" pool-name="exo-jcr_portal" spy="false" use-ccm="true" use-java-context="true">
<!-- HSQLDB -->
<driver>hsqldb-driver.jar</driver>
<driver-class>org.hsqldb.jdbcDriver</driver-class>
<connection-url>jdbc:hsqldb:file:${exo.data.dir}/hsql/exo-plf;shutdown=true;hsqldb.write_delay=false;</connection-url>
...
ii. For MySQL as an example, need to uncomment some lines in the file, edit driver, username, password, url:
<!-- MySQL -->
<driver>mysql-connector-java-5.1.6-bin.jar</driver>
<driver-class>com.mysql.jdbc.Driver</driver-class>
<connection-url>jdbc:mysql://localhost:3306/plf?autoReconnect=true</connection-url>
...
<security>
<user-name>root</username>
<password>exoplf</password>
</security>
<validation>
...
<!-- MySQL -->
<exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter" />
<valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker" />
iii. Append this character encoding to the url in case your database character set is utf8.
For example, in MySQL (this is different between RDBMSs):
<connection-url>jdbc:mysql://localhost:3306/plf?autoReconnect=true&characterEncoding=utf8</connection-url>
Set the SQL Dialect if necessary.
This step is not mandatory because the dialect is auto-detected in most cases. You only need to take care of it for some particular RDBMSs:
i. For JCR, only when you are using MySQL and database character set utf8,
you need to edit standalone/configuration/gatein/exo.properties file to have:
exo.jcr.datasource.dialect=MySQL-UTF8
ii. For IDM, eXo Platform detects automatically the dialect for RDBMSs listed
here.
Only when your RDBMS is not in the list, for example Postgres Plus Advanced Server 9.2,
you will need to edit standalone/configuration/gatein/exo.properties file to have:
hibernate.dialect=org.hibernate.dialect.PostgresPlusDialect
If you have not created exo.properties yet, see Configuration overview.
Download the JDBC driver for Java and install it to $PLATFORM_JBOSS_HOME/standalone/deployments.
Normally you can find out an appropriate driver for your JDK from your database vendor website. For example, for MySQL: http://dev.mysql.com/downloads/connector/j/, and for Oracle: http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html.
Particularly to MySQL, this fast install method might not work for some couples of MySQL server and driver versions. If it happens to you, solve it by installing the driver as a module. See details below.
Installing JDBC driver as a JBoss module
This alternative method is applied to solve a deployment problem with some couples of MySQL server and driver versions. There is no statement that indicates exactly the versions, but the problem likely happens with some most recent versions, such as MySQL server 5.6.19 and mysql-connector-java-5.1.35-bin.jar.
When it happens, you will get a JBAS014775 message like the following, and Platform JBoss does not start successfully:
JBAS014775: New missing/unsatisfied dependencies:
service jboss.jdbc-driver.mysql-connector-java-5_1_35-bin_jar (missing) dependents:
[service jboss.data-source.java:/comp/env/exo-idm_portal,
service jboss.driver-demander.java:/comp/env/exo-jcr_portal,
service jboss.driver-demander.java:/comp/env/exo-idm_portal, JBAS014799: ... and 3 more ]
Then you should remove the jar from $PLATFORM_JBOSS_HOME/standalone/deployments/ and install it to JBoss modules as follows:
Create a new folder: $PLATFORM_JBOSS_HOME/modules/com/mysql/main/.
Place the driver (.jar) in the created folder.
Create a module.xml file in the created folder, with the following content:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.mysql">
<resources>
<resource-root path="mysql-connector-java-5.1.35-bin.jar"/> <!--replace this with your jar file-->
</resources>
<dependencies>
<module name="javax.api"/>
</dependencies>
</module>
Modify the datasources configuration in standalone-exo.xml
to declare a driver in drivers tag and reference to it in datasource tag:
<subsystem xmlns="urn:jboss:domain:datasources:1.1">
<datasources>
<!-- eXo IDM Datasource for PLF -->
<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">
<driver>com.mysql</driver>
<connection-url>jdbc:mysql://localhost:3306/plf?autoReconnect=true</connection-url>
<!-- note: don't put driver-class tag here-->
...
</datasource>
<!-- similar to other datasources, JCR (and Quartz in cluster) -->
<drivers>
<driver name="com.mysql" module="com.mysql">
<xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
<driver-class>com.mysql.jdbc.Driver</driver-class>
</driver>
</drivers>
</datasources>
</subsystem>