⁠Chapter 7. Platform-specific Configuration

Procedure 7.5. Install a JDBC Driver as a Core Module

1. Create a file path structure under the JPP_HOME/modules/system/layers/base directory. For example, for a MySQL JDBC driver, create JPP_HOME/modules/system/layers/base/com/mysql/main/.
2. Copy the JDBC driver JAR into the main/ subdirectory.
3. In the main/ subdirectory, create a module.xml file. The following is an example of a module.xml file:

   ​<?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.15.jar"/>
   ​  </resources>
   ​  <dependencies>
   ​    <module name="javax.api"/>
   ​    <module name="javax.transaction.api"/>
   ​  </dependencies>
   ​</module>

4. Start the Server.
5. Start the Management CLI.
6. Run the CLI command to add the JDBC driver module to the server configuration.
   The command you choose depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. For example, the /META-INF/services/java.sql.Driver file in the MySQL 5.1.20 JDBC JAR lists two classes:

   • com.mysql.jdbc.Driver
   • com.mysql.fabric.jdbc.FabricMySQLDriver

   When there is more than one entry, you must also specify the name of the driver class. Failure to do so results in an error similar to the following:

   ⁠

   Example 7.1. Driver class error

   JBAS014749: Operation handler failed: Service jboss.jdbc-driver.mysql is already registered

   Note

   The value for DRIVER_NAME depends on the number of classes listed in the /META-INF/services/java.sql.Driver file located in the JDBC driver JAR. If there is only one class, the value is the name of the JAR. If there are multiple classes, the value is the name of the JAR + driverClassName + "_" + majorVersion +"_" + minorVersion. Failure to do so will result in the following error being logged:

   JBAS014775:    New missing/unsatisfied dependencies

   For example, the DRIVER_NAME value required for the MySQL 5.1.31 driver, is mysql-connector-java-5.1.31-bin.jarcom.mysql.jdbc.Driver_5_1.
   • Run the CLI command for JDBC JARs containing one class entry.

     /subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME)

     ⁠

     Example 7.2. CLI Command for Standalone Mode for JDBC JARs with one driver class

     /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)

     ⁠

     Example 7.3. CLI Command for Domain Mode for JDBC JARs with one driver class

     /profile=ha/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource)

   • Run the CLI command for JDBC JARs containing multiple class entries.

     /subsystem=datasources/jdbc-driver=DRIVER_NAME:add(driver-name=DRIVER_NAME,driver-module-name=MODULE_NAME,driver-xa-datasource-class-name=XA_DATASOURCE_CLASS_NAME, driver-class-name=DRIVER_CLASS_NAME)

     ⁠

     Example 7.4. CLI Command for Standalone Mode for JDBC JARs with multiple driver class entries

     /subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource, driver-class-name=com.mysql.jdbc.Driver)

     ⁠

     Example 7.5. CLI Command for Domain Mode for JDBC JARs with multiple driver class entries

     /profile=ha/subsystem=datasources/jdbc-driver=mysql:add(driver-name=mysql,driver-module-name=com.mysql,driver-xa-datasource-class-name=com.mysql.jdbc.jdbc2.optional.MysqlXADataSource, driver-class-name=com.mysql.jdbc.Driver)

Procedure 7.6. Shared Datasource Configuration

1. Open JPP_HOME/standalone/configuration/standalone.xml.
2. Comment the jdbcjcr_portal <datasource> directive to disable the JCR datasource.

   ​<datasources>
   ​  <!--<datasource jndi-name="java:/jdbcjcr_portal" pool-name="JCRPortalDS" enabled="true" use-java-context="true">
   ​  <connection-url>jdbc:h2:file:${jboss.server.data.dir}/gatein/portal/jdbcjcr_portal;DB_CLOSE_DELAY=-1</connection-url>
   ​  <driver>h2</driver>
   ​  <security>
   ​    <user-name>sa</user-name>
   ​    <password>sa</password>
   ​  </security>
   ​  </datasource>-->
   ​</datasources>

3. Configure jdbcidm_portal <datasource> directive to use the MySQL database.

   ​<datasources>
   ​  <!--<datasource jndi-name="java:/jdbcjcr_portal" pool-name="JCRPortalDS" enabled="true" use-java-context="true">
   ​    <connection-url>jdbc:h2:file:${jboss.server.data.dir}/gatein/portal/jdbcjcr_portal;DB_CLOSE_DELAY=-1</connection-url>
   ​    <driver>h2</driver>
   ​    <security>
   ​      <user-name>sa</user-name>
   ​      <password>sa</password>
   ​    </security>
   ​  </datasource>-->
   ​  <datasource jndi-name="java:/jdbcidm_portal" pool-name="IDMPortalDS" enabled="true" use-java-context="true">
   ​    <connection-url>jdbc:mysql://localhost/portal</connection-url>
   ​    <driver>mysql</driver>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​    <pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </pool>
   ​  </datasource>
   ​</datasources>

4. Add the MySQL module into the list of <drivers>.

   ​<datasources>
   ​  <!--<datasource jndi-name="java:/jdbcjcr_portal" pool-name="JCRPortalDS" enabled="true" use-java-context="true">
   ​    <connection-url>jdbc:h2:file:${jboss.server.data.dir}/gatein/portal/jdbcjcr_portal;DB_CLOSE_DELAY=-1</connection-url>
   ​    <driver>h2</driver>
   ​    <security>
   ​      <user-name>sa</user-name>
   ​      <password>sa</password>
   ​    </security>
   ​  </datasource>-->
   ​  <datasource jndi-name="java:/jdbcidm_portal" pool-name="IDMPortalDS" enabled="true" use-java-context="true">
   ​    <connection-url>jdbc:mysql://localhost/portal</connection-url>
   ​    <driver>mysql</driver>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​    <pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </pool>
   ​  </datasource>
   ​  <drivers>
   ​    <driver name="mysql" module="com.mysql">
   ​      <xa-datasource-class>com.mysql.jdbc.Driver</xa-datasource-class>
   ​    </driver>
   ​  </drivers>
   ​</datasources>

5. Open JPP_HOME/standalone/configuration/gatein/configuration.properties, and verify the gatein.jcr.datasource.name property has the value java:/jdbcidm. This value ensures the JCR database uses the IDM database as the datasource.

   gatein.jcr.datasource.name=java:/jdbcidm
   gatein.idm.datasource.name=java:/jdbcidm
   			

Procedure 7.7. XA Datasource Configuration

1. Open JPP_HOME/standalone/configuration/standalone.xml.
2. Configure jdbcidm_portal <xa-datasource> directive to use the MySQL database.

   ​<datasources>
   ​  <xa-datasource jndi-name="java:/jdbcidm_portal" pool-name="IDMPortalDS" enabled="true" use-java-context="true">
   ​    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
   ​    <xa-datasource-property name="DatabaseName">portalidm</xa-datasource-property>
   ​    <driver>mysql</driver>
   ​    <xa-pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </xa-pool>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​  </xa-datasource>
   ​</datasources>

3. Configure jdbcjcr_portal <xa-datasource> directive to use the MySQL database.

   ​<datasources>
   ​  <xa-datasource jndi-name="java:/jdbcidm_portal" pool-name="IDMPortalDS" enabled="true" use-java-context="true">
   ​    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
   ​    <xa-datasource-property name="DatabaseName">portalidm</xa-datasource-property>
   ​    <driver>mysql</driver>
   ​    <xa-pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </xa-pool>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​  </xa-datasource>
   ​  <xa-datasource jndi-name="java:/jdbcjcr_portal" pool-name="JCRPortalDS" enabled="true" use-java-context="true">
   ​    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
   ​    <xa-datasource-property name="DatabaseName">portaljcr</xa-datasource-property>
   ​    <driver>mysql</driver>
   ​    <xa-pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </xa-pool>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​  </xa-datasource>
   ​</datasources>

4. Add the MySQL module into the list of <drivers>.

   ​<datasources>
   ​  <xa-datasource jndi-name="java:/jdbcidm_portal" pool-name="IDMPortalDS" enabled="true" use-java-context="true">
   ​    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
   ​    <xa-datasource-property name="DatabaseName">portalidm</xa-datasource-property>
   ​    <driver>mysql</driver>
   ​    <xa-pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </xa-pool>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​  </xa-datasource>
   ​  <xa-datasource jndi-name="java:/jdbcjcr_portal" pool-name="JCRPortalDS" enabled="true" use-java-context="true">
   ​    <xa-datasource-property name="ServerName">localhost</xa-datasource-property>
   ​    <xa-datasource-property name="DatabaseName">portaljcr</xa-datasource-property>
   ​    <driver>mysql</driver>
   ​    <xa-pool>
   ​      <min-pool-size>10</min-pool-size>
   ​      <max-pool-size>100</max-pool-size>
   ​      <prefill>true</prefill>
   ​    </xa-pool>
   ​    <security>
   ​      <user-name>portal</user-name>
   ​      <password>portal</password>
   ​    </security>
   ​  </xa-datasource>
   ​  <drivers>
   ​    <driver name="mysql" module="com.mysql">
   ​      <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
   ​  </driver>
   ​  </drivers>
   ​</datasources>

5. Open JPP_HOME/standalone/configuration/gatein/configuration.properties, and verify the gatein.jcr.datasource.name property has the value java:/jdbcidm. This value ensures the JCR database uses the IDM database as the datasource.

   gatein.jcr.datasource.name=java:/jdbcjcr
   gatein.idm.datasource.name=java:/jdbcidm
   			

Procedure 7.8. Configuring Hibernate and Picketlink for JTA

1. Open JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/idm-configuration.xml
2. In the hibernate.properties <init-params> group, comment the Non-JTA Setup directives, and uncomment the JTA Setup directives:

   ​<init-params>
   ​  <properties-param>
   ​    <name>hibernate.properties</name>
   ​    <description>Default Hibernate Service</description>
   ​    <property name="hibernate.hbm2ddl.auto" value="update"/>
   ​    <property name="hibernate.show_sql" value="false"/>
   ​    <property name="hibernate.connection.datasource" value="${gatein.idm.datasource.name}${container.name.suffix}"/>
   ​    <property name="hibernate.connection.autocommit" value="false"/>
   ​    <!--  Non-JTA setup  -->
   ​    <!--<property name="hibernate.current_session_context_class" value="thread"/>-->
   ​    <!--  JTA setup  -->
   ​    <property name="hibernate.current_session_context_class" value="jta"/>
   ​    <property name="hibernate.transaction.factory_class" value="org.hibernate.transaction.JTATransactionFactory" />
   ​    <property name="hibernate.transaction.jta.platform" value="org.exoplatform.services.organization.idm.UserTransactionJtaPlatform" />
   ​
   ​<!-- Remaining code removed for readability-->
   ​
   

3. In the org.exoplatform.services.organization.idm.Config <init-params> group, change useJTA <field> value to true.

   ​<field name="useJTA">
   ​  <boolean>true</boolean>
   ​</field>

   This setting forces PicketlinkIDMOrganizationServiceImpl to encapsulate each HTTP request within the JTA transaction, instead of the Hibernate transaction API. The bounds of the transaction are startRequest and endRequest.

   Important

   If managed transactions are used in portlet applications (for example, using EJB with Container-Managed transactions), be aware that some changes to transaction behavior may occur in the application.

   Ensure that portlet applications do not attempt to start or commit JTA transactions from the application.
4. Open JPP_HOME/gatein/gatein.ear/portal.war/WEB-INF/conf/organization/picketlink-idm/picketlink-idm-config.xml
5. In the <stores> directives, change the lazyStartOfHibernateTransaction option to false to switch transaction management from PicketLink to JTA.