4.2. Configuring eXo Platform

eXo Platform relies on the application server (Tomcat/JBoss) to access databases. It uses two JNDI datasources:

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.

For Tomcat

  1. 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&amp;characterEncoding=utf8"
  2. 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

    If you have not created exo.properties yet, see Configuration overview.

  3. Download the JDBC driver for Java and install it to $PLATFORM_TOMCAT_HOME/lib.

    Tip

    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.

For JBoss

  1. 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&amp;characterEncoding=utf8</connection-url>
  2. 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.

  3. Download the JDBC driver for Java and install it to $PLATFORM_JBOSS_HOME/standalone/deployments.

    Tip

    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.

    Note

    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.

Then you should remove the jar from $PLATFORM_JBOSS_HOME/standalone/deployments/ and install it to JBoss modules as follows:

  1. Create a new folder: $PLATFORM_JBOSS_HOME/modules/com/mysql/main/.

  2. Place the driver (.jar) in the created folder.

  3. 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>
  4. 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>
Copyright ©. All rights reserved. eXo Platform SAS
blog comments powered byDisqus