5:02 a.m.
Author: thomas.heute(a)jboss.com
Date: 2010-02-16 06:02:56 -0500 (Tue, 16 Feb 2010)
New Revision: 1733
Modified:
portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml
Log:
Updated documentation on how to change the database
Modified:
portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml
===================================================================
---
portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml 2010-02-16
09:57:13 UTC (rev 1732)
+++
portal/trunk/docs/reference-guide/en/modules/configuration/Database_Configuration.xml 2010-02-16
11:02:56 UTC (rev 1733)
@@ -1,182 +1,109 @@
-<?xml version='1.0' encoding='utf-8' ?>
-<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+<!ENTITY % BOOK_ENTITIES SYSTEM "../../Reference_Guide.ent">
+%BOOK_ENTITIES;
]>
<section id="sect-Reference_Guide-Database_Configuration">
- <title>Database Configuration</title>
- <section id="sect-Reference_Guide-Database_Configuration-Overview">
- <title>Overview</title>
- <para>
- &PRODUCT; has two different database dependencies. One is the Hibernate service
configuration, which depends on the the Hibernate and c3p0 projects. The other database
dependency is Java content repository (JCR) service, which depends on the native JDBC API
and it can integrate with any existing datasource implementation.
- </para>
- <para>
- When you change the database configuration for the first time, GateIn will
automatically generate the proper schema (assuming that the database user has the
appropriate permissions).
- </para>
- <para>
- GateIn assumes the default encoding for your database is
<literal>latin1</literal> . You will need to change this parameter for your
database in order to work properly.
- </para>
- </section>
-
- <section
id="sect-Reference_Guide-Database_Configuration-DB_and_datasource_configuration">
- <title>DB and datasource configuration</title>
- <para>
- You can find the database configuration in the
portal/WEB-INF/conf/database/database-configuration.xml file (located in your application
server's web application directory).
- </para>
-
-<programlisting role="XML"><?xml version="1.0"
encoding="ISO-8859-1"?>
-<configuration>
- [...]
- <component>
-
<key>org.exoplatform.services.database.HibernateService</key>
- <jmx-name>database:type=HibernateService</jmx-name>
-
<type>org.exoplatform.services.database.impl.HibernateServiceImpl</type>
- <init-params>
- <properties-param>
- <name>hibernate.properties</name>
- <description>Default Hibernate
Service</description>
- <property name="hibernate.show_sql"
value="false"/>
- <property name="hibernate.cglib.use_reflection_optimizer"
value="true"/>
- <property name="hibernate.connection.url"
value="jdbc:hsqldb:file:../temp/data/exodb"/>
- <property name="hibernate.connection.driver_class"
value="org.hsqldb.jdbcDriver"/>
- <property name="hibernate.connection.autocommit"
value="true"/>
- <property name="hibernate.connection.username"
value="sa"/>
- <property name="hibernate.connection.password"
value=""/>
- <property name="hibernate.dialect"
value="org.hibernate.dialect.HSQLDialect"/>
- <property name="hibernate.c3p0.min_size"
value="5"/>
- <property name="hibernate.c3p0.max_size"
value="20"/>
- <property name="hibernate.c3p0.timeout"
value="1800"/>
- <property name="hibernate.c3p0.max_statements"
value="50"/>
- </properties-param>
- </init-params>
- </component>
- <external-component-plugins>
-
<target-component>org.exoplatform.services.naming.InitialContextInitializer</target-component>
- <component-plugin>
- <name>bind.datasource</name>
- <set-method>addPlugin</set-method>
-
<type>org.exoplatform.services.naming.BindReferencePlugin</type>
- <init-params>
- <value-param>
- <name>bind-name</name>
- <value>jdbcexo</value>
- </value-param>
- <value-param>
- <name>class-name</name>
- <value>javax.sql.DataSource</value>
- </value-param>
- <value-param>
- <name>factory</name>
-
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
- </value-param>
- <properties-param>
- <name>ref-addresses</name>
- <description>ref-addresses</description>
- <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
- <property name="url"
value="jdbc:hsqldb:file:../temp/data/exodb"/>
- <property name="username"
value="sa"/>
- <property name="password"
value=""/>
- </properties-param>
- </init-params>
- </component-plugin>
- </external-component-plugins>
- [...]
-</configuration>
+ <title>Database Configuration</title>
+
+ <section id="sect-Reference_Guide-Database_Configuration-Overview">
+ <title>Overview</title>
+
+ <para>&PRODUCT; has two different database dependencies. One is the
+ identity service configuration, which depends on the Hibernate. The other
+ database dependency is Java content repository (JCR) service, which
+ depends on the native JDBC API and it can integrate with any existing
+ datasource implementation.</para>
+
+ <para>When you change the database configuration for the first time,
+ GateIn will automatically generate the proper schema (assuming that the
+ database user has the appropriate permissions).</para>
+
+ <para>GateIn assumes the default encoding for your database is
+ <literal>latin1</literal> . You will need to change this parameter for
+ your database in order to work properly.</para>
+ </section>
+
+ <section
id="sect-Reference_Guide-Database_Configuration-JCR_database_configuration">
+ <title>Configuring the database for JCR</title>
+
+ <para>To configure the databaseused by JCR you will need to edit the
+
file:<programlisting>gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration.xml</programlisting></para>
+
+ <para>And edit the values of driverClassName, url, username and password
+ with the values for your JDBC connection (Please refer to your database
+ JDBC driver documentation).</para>
+
+ <programlisting role="XML"><properties-param>
+ <name>ref-addresses</name>
+ <description>ref-addresses</description>
+ <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
+ <property name="url"
value="jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcjcr${container.name.suffix}"/>
+ property name="username" value="sa"/>
+ <property name="password" value=""/>
+</properties-param>
</programlisting>
- <para>
- The first component configuration is for the Hibernate service. You can enter any
additional properties in a <literal>hibernate.properties</literal> file, but
&PRODUCT; will override <literal>hibernate.properties</literal> with
values read in from this configuration file.
- </para>
- <para>
- The second component configuration is for the JCR datasource. The
<literal>InitialContextInitializer</literal> component will load the factory
class, use the factory object to create a datasource, and bind that datasource in the JNDI
tree with the value of the "bind-name" parameter. If you want to change
the bind-name, for example "<parameter>jdbcexo</parameter>" to
"<parameter>myjdbc</parameter>", you also need to change JCR
repository configuration in order that the service picks up the right datasource.
- </para>
- <para>
- Make sure you update the database connection properties and dialect for both of these
component configurations.
- </para>
- </section>
-
- <section
id="sect-Reference_Guide-Database_Configuration-JCR_database_configuration">
- <title>JCR database configuration</title>
- <para>
- There are two JCR configuration files that must be changed to support a different
database. In both files, <emphasis>edit the dialect (and the data source name if
necessary)</emphasis> .
- </para>
- <para>
- The first file is
<filename>02portal.war:/WEB-INF/conf/jcr/jcr-configuration.xml</filename> :
- </para>
-
-<programlisting>[...]
- <component>
-
<key>org.exoplatform.services.jcr.config.RepositoryServiceConfiguration</key>
-
<type>org.exoplatform.services.jcr.impl.config.RepositoryServiceConfigurationImpl</type>
- <init-params>
- <value-param>
- <name>conf-path</name>
- <description>JCR configuration file</description>
-
<value>war:/conf/jcr/repository-configuration.xml</value>
- </value-param>
- <properties-param>
- <name>working-conf</name>
- <description>working-conf</description>
- <property name="persisterClassName"
value="org.exoplatform.services.jcr.impl.config.JDBCConfigurationPersister"/>
- <property name="sourceName"
value="jdbcexo"/>
- <property name="dialect"
value="hsqldb"/>
- </properties-param>
- </init-params>
- </component>
-[...]
-</programlisting>
- <para>
- The second file is
<filename>02portal.war:/WEB-INF/conf/jcr/repository-configuration.xml</filename>
:
- </para>
-
-<programlisting role="XML"> ...]
- <workspaces>
- <workspace name="system"
auto-init-root-nodetype="nt:unstructured"
- auto-init-permissions="*:/platform/administrators
read;*:/platform/administrators add_node;*:/platform/administrators
set_property;*:/platform/administrators remove" >
- <!-- for system storage -->
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="sourceName"
value="jdbcexo"/>
- <property name="dialect"
value="hsql"/>
- <!-- property name="db-type"
value="mysql"/ -->
- <property name="multi-db"
value="false"/>
- <property name="update-storage"
value="true"/>
- <property name="max-buffer-size"
value="204800"/>
- <property name="swap-directory"
value="../temp/swap/system"/>
- </properties>
-[...]
- </workspace>
- <workspace name="collaboration"
auto-init-root-nodetype="nt:unstructured"
- auto-init-permissions="any read;*:/platform/administrators
read;*:/platform/administrators add_node;*:/platform/administrators
set_property;*:/platform/administrators remove" >
- <!-- for system storage -->
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="sourceName"
value="jdbcexo"/>
- <property name="dialect"
value="hsqldb"/>
- <property name="multi-db"
value="false"/>
- <property name="update-storage"
value="true"/>
- <property name="max-buffer-size"
value="204800"/>
- <property name="swap-directory"
value="../temp/swap/collaboration"/>
- </properties>
-[...]
- </workspace>
- <workspace name="backup"
auto-init-root-nodetype="nt:unstructured"
- auto-init-permissions="any read;*:/platform/administrators
read;*:/platform/administrators add_node;*:/platform/administrators
set_property;*:/platform/administrators remove" >
- <!-- for system storage -->
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="sourceName"
value="jdbcexo"/>
- <property name="dialect"
value="mysql"/>
- <!-- property name="db-type"
value="mysql"/ -->
- <property name="multi-db"
value="false"/>
- <property name="update-storage"
value="true"/>
- <property name="max-buffer-size"
value="204800"/>
- <property name="swap-directory"
value="../temp/swap/backup"/>
- </properties>
- </workspace>
-[...]
- </workspaces>
-[...]
-</programlisting>
- </section>
-</section>
+ <para>In that case, the name of the database is
+ "jdbcjcr${container.name.suffix}", ${container.name.suffix} should be part
+ of the database name, as it is dynamically replaced by the name of the
+ portal extension (for instance gatein-sample-portal.ear defines
+ "sample-portal" as container name and the default portal defines
"portal"
+ as container name). </para>
+ <para>In the case of HSQL the databases are created automatically, for any
+ other database you will need to create a database named jdbcjcr_portal
+ (and "jdbcjcr_sample-portal" if you kept gatein-sample-portal.ear in
+ $JBOSS_HOME/server/default/deploy. Note that some database wont accept '-'
+ in a database name and you will have to delete
+ $JBOSS_HOME/server/default/deploy/gatein-sample-portal.ear)</para>
+ <para>Make sure the user has rights to create tables on jdbcjcr_portal and
+ to update them as during the first startup they will be automatically
+ created.</para>
+
+ <para>Also add the JDBC driver into the classpath, for instance in
+ $JBOSS_HOME/server/default/lib (or $TOMCAT_HOME/lib if you are running on
+ Tomcat)</para>
+
+ <para>MySQL example:</para>
+
+ <para>Let's configure our JCR to store data in MySQL, let's pretend we
+ have a user named "gateinuser" with a password "gateinpassword".
We would
+ create a database "mygateindb_portal" (Remember that _portal is required)
+ and assign him the rights to create tables.</para>
+
+ <para>Then we need to add the MySQL JDBC connector in the classpath and
+ finally edit gatein.ear/02portal.war/WEB-INF/conf/jcr/jcr-configuration
+ with:<programlisting><properties-param>
+ <name>ref-addresses</name>
+ <description>ref-addresses</description>
+ <property name="driverClassName"
value="com.mysql.jdbc.Driver"/>
+ <property name="url"
value="jdbc:mysql://localhost:3306/mygateindb${container.name.suffix}"/>
+ <property name="username" value="gateinuser"/>
+ <property name="password" value="gateinpassword"/>
+</properties-param></programlisting></para>
+ </section>
+
+ <section>
+ <title>Configuring the database for the default identity store</title>
+
+ <para>By default users are stored in database. To change the database to
+ store users, you will need to edit the file:</para>
+
+
<para><programlisting>gatein.ear/02portal.war/WEB-INF/conf/organization/idm-configuration.xml</programlisting>You
+ will find the same configuration as in
+ jcr-configuration.xml:<programlisting><properties-param>
+ <name>ref-addresses</name>
+ <description>ref-addresses</description>
+ <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
+ <property name="url"
value="jdbc:hsqldb:file:${gatein.db.data.dir}/data/jdbcidm${container.name.suffix}"/>
+ property name="username" value="sa"/>
+ <property name="password" value=""/>
+</properties-param></programlisting></para>
+
+ <para>It is recommended to use a different database than the one used by
+ JCR.</para>
+ </section>
+</section>