7:53 a.m.
Author: sergiykarpenko
Date: 2010-03-22 08:53:09 -0400 (Mon, 22 Mar 2010)
New Revision: 2093
Modified:
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml
Log:
EXOJCR-598: documentation about Query hints parameter added
Modified:
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml
===================================================================
---
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml 2010-03-22
12:17:37 UTC (rev 2092)
+++
jcr/trunk/docs/reference/en/src/main/docbook/en-US/modules/jcr/jdbc-data-container-config.xml 2010-03-22
12:53:09 UTC (rev 2093)
@@ -1,533 +1,592 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
-<chapter id="ch_jdbc_data_container">
- <?dbhtml filename="ch-jdbc-data-container-config.html"?>
-
- <title>JDBC Data Container Config</title>
-
- <section>
- <title>Introduction</title>
-
- <para>eXo JCR persistent data container can work in two configuration
- modes:<itemizedlist>
- <listitem>
- <para><phrase>Multi-database</phrase>: one database for each
- workspace (used in standalone eXo JCR service mode)</para>
- </listitem>
-
- <listitem>
- <para><phrase>Single-database</phrase>: all workspaces
persisted in
- one database (used in embedded eXo JCR service mode, e.g. in eXo
- portal)</para>
- </listitem>
- </itemizedlist></para>
-
- <para>The data container uses the JDBC driver to communicate with the
- actual database software, i.e. any JDBC-enabled data storage can be used
- with eXo JCR implementation.</para>
-
- <para>Currently the data container is tested with the following
- RDBMS:<itemizedlist>
- <listitem>
- <para>MySQL (5.x including UTF8 support)</para>
- </listitem>
-
- <listitem>
- <para>PostgreSQL (8.x)</para>
- </listitem>
-
- <listitem>
- <para>Oracle Database (9i, 10g)</para>
- </listitem>
-
- <listitem>
- <para>Microsoft SQL Server (2005)</para>
- </listitem>
-
- <listitem>
- <para>Sybase ASE (15.0)</para>
- </listitem>
-
- <listitem>
- <para>Apache Derby/Java DB (10.1.x, 10.2.x)</para>
- </listitem>
-
- <listitem>
- <para>IBM DB2 (8.x, 9.x)</para>
- </listitem>
-
- <listitem>
- <para>HSQLDB (1.8.0.7)</para>
- </listitem>
- </itemizedlist></para>
-
- <para>Each database software supports ANSI SQL standards but has its own
- specifics too. So, each database has its own configuration in eXo JCR as a
- database dialect parameter. If you need a more detailed configuration of
- the database it's possible to do that by editing the metadata SQL-script
- files.</para>
-
- <para>In case the non-ANSI node name is used it's necessary to use a
- database with MultiLanguage support[TODO link to MultiLanguage]. Some JDBC
- drivers need additional parameters for establishing a Unicode friendly
- connection. E.g. under mysql it's necessary to add an additional parameter
- for the JDBC driver at the end of JDBC URL. For instance:
-
<code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8<...
-
- <para>There are preconfigured configuration files for HSQLDB. Look for
- these files in /conf/portal and /conf/standalone folders of the jar-file
- <package>exo.jcr.component.core-XXX.XXX.jar</package> or
- source-distribution of eXo JCR implementation.</para>
-
- <para>By default the configuration files are located in service jars
- <filename>/conf/portal/configuration.xml</filename> (eXo services
- including JCR Repository Service) and
- <filename>exo-jcr-config.xml</filename> (repositories configuration). In
- eXo portal product JCR is configured in portal web application
- <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR
- Repository Service and related serivces) and repository-configuration.xml
- (repositories configuration).</para>
-
- <para>Read more about <link
linkend="ch_configuration">Repository
- configuration</link>.</para>
- </section>
-
- <section>
- <title>Multi-database Configuration</title>
-
- <para>You need to configure each workspace in a repository. You may have
- each one on different remote servers as far as you need.</para>
-
- <para>First of all configure the data containers in the
-
<classname>org.exoplatform.services.naming.InitialContextInitializer</classname>
- service. It's the JNDI context initializer which registers (binds) naming
- resources (DataSources) for data containers.</para>
-
- <para>Example (standalone mode, two data containers
- <parameter>jdbcjcr</parameter> - local HSQLDB,
- <parameter>jdbcjcr1</parameter> - remote
MySQL):<programlisting><component>
-
<key>org.exoplatform.services.naming.InitialContextInitializer</key>
-
<type>org.exoplatform.services.naming.InitialContextInitializer</type>
- <component-plugins>
- <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>jdbcjcr</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:target/temp/data/portal"/>
- <property name="username" value="sa"/>
- <property name="password" value=""/>
- </properties-param>
- </init-params>
- </component-plugin>
- <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>jdbcjcr1</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="com.mysql.jdbc.Driver"/>
- <property name="url"
value="jdbc:mysql://exoua.dnsalias.net/jcr"/>
- <property name="username"
value="exoadmin"/>
- <property name="password"
value="exo12321"/>
- <property name="maxActive" value="50"/>
- <property name="maxIdle" value="5"/>
- <property name="initialSize" value="5"/>
- </properties-param>
- </init-params>
- </component-plugin>
- <component-plugins>
- <init-params>
- <value-param>
- <name>default-context-factory</name>
-
<value>org.exoplatform.services.naming.SimpleContextFactory</value>
- </value-param>
- </init-params>
- </component></programlisting></para>
-
- <para>We configure the database connection parameters:<itemizedlist>
- <listitem>
- <para><parameter>driverClassName</parameter>, e.g.
- "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver",
- "org.postgresql.Driver"</para>
- </listitem>
-
- <listitem>
- <para><parameter>url</parameter>, e.g.
- "jdbc:hsqldb:file:target/temp/data/portal",
- "jdbc:mysql://exoua.dnsalias.net/jcr"</para>
- </listitem>
-
- <listitem>
- <para><parameter>username</parameter>, e.g. "sa",
"exoadmin"</para>
- </listitem>
-
- <listitem>
- <para><parameter>password</parameter>, e.g. "",
"exo12321"</para>
- </listitem>
- </itemizedlist></para>
-
- <para>There can be connection pool configuration parameters
- (org.apache.commons.dbcp.BasicDataSourceFactory):<itemizedlist>
- <listitem>
- <para><parameter>maxActive</parameter>, e.g. 50</para>
- </listitem>
-
- <listitem>
- <para><parameter>maxIdle</parameter>, e.g. 5</para>
- </listitem>
-
- <listitem>
- <para><parameter>initialSize</parameter>, e.g.
5</para>
- </listitem>
-
- <listitem>
- <para>and other according to <ulink
-
url="http://jakarta.apache.org/commons/dbcp/configuration.html"...
- DBCP configuration</ulink></para>
- </listitem>
- </itemizedlist></para>
-
- <para>When the data container configuration is done we can configure the
- repository service. Each workspace will be configured for its own data
- container.</para>
-
- <para>Example (two workspaces <parameter>ws</parameter> - jdbcjcr,
- <parameter>ws1</parameter> -
jdbcjcr1):<programlisting><workspaces>
- <workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="source-name" value="jdbcjcr"/>
- <property name="dialect" value="hsqldb"/>
- <property name="multi-db" value="true"/>
- <property name="max-buffer-size" value="200K"/>
- <property name="swap-directory"
value="target/temp/swap/ws"/>
- </properties>
- </container>
- <cache enabled="true">
- <properties>
- <property name="max-size"
value="10K"/><!-- 10Kbytes -->
- <property name="live-time"
value="30m"/><!-- 30 min -->
- </properties>
- </cache>
- <query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
- <properties>
- <property name="index-dir"
value="target/temp/index"/>
- </properties>
- </query-handler>
- <lock-manager>
- <time-out>15m</time-out><!-- 15 min -->
- <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
- <properties>
- <property name="path"
value="target/temp/lock/ws"/>
- </properties>
- </persister>
- </lock-manager>
- </workspace>
- <workspace name="ws1"
auto-init-root-nodetype="nt:unstructured">
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="source-name" value="jdbcjcr1"/>
- <property name="dialect" value="mysql"/>
- <property name="multi-db" value="true"/>
- <property name="max-buffer-size" value="200K"/>
- <property name="swap-directory"
value="target/temp/swap/ws1"/>
- </properties>
- </container>
- <cache enabled="true">
- <properties>
- <property name="max-size" value="10K"/>
- <property name="live-time" value="5m"/>
- </properties>
- </cache>
- <query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
- <properties>
- <property name="index-dir"
value="target/temp/index"/>
- </properties>
- </query-handler>
- <lock-manager>
- <time-out>15m</time-out><!-- 15 min -->
- <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
- <properties>
- <property name="path"
value="target/temp/lock/ws1"/>
- </properties>
- </persister>
- </lock-manager>
- </workspace>
-</workspaces></programlisting><itemizedlist>
- <listitem>
- <para><parameter>source-name</parameter> - a
javax.sql.DataSource
- name configured in InitialContextInitializer component (was
- <parameter>sourceName</parameter> prior JCR 1.9);</para>
- </listitem>
-
- <listitem>
- <para><parameter>dialect</parameter> - a database dialect,
one of
- "hsqldb", "mysql", "mysql-utf8",
"pgsql", "oracle", "oracle-oci",
- "mssql", "sybase", "derby", "db2",
"db2v8".</para>
- </listitem>
-
- <listitem>
- <para><parameter>multi-db</parameter> - enable
multi-database
- container with this parameter (set value "true");</para>
- </listitem>
-
- <listitem>
- <para><parameter>max-buffer-size</parameter> - a threshold
(in
- bytes) after which a javax.jcr.Value content will be swapped to a
- file in a temporary storage. I.e. swap for pending changes.</para>
- </listitem>
-
- <listitem>
- <para><parameter>swap-directory</parameter> - a path in the
file
- system used to swap the pending changes.</para>
- </listitem>
- </itemizedlist></para>
-
- <para>In this way we have configured two workspace which will be persisted
- in two different databases (ws in HSQLDB, ws1 in MySQL).</para>
-
- <note>
- <para> Starting from v.1.9 <link
linkend="ch_configuration">repository
- configuration</link> parameters supports human-readable formats of
- values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc)</para>
- </note>
- </section>
-
- <section>
- <title>Single-database configuration</title>
-
- <para>It's more simple to configure a single-database data container. We
- have to configure one naming resource.</para>
-
- <para>Example (embedded mode for <parameter>jdbcjcr</parameter>
data
- container):<programlisting><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>jdbcjcr</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.postgresql.Driver"/>
- <property name="url"
value="jdbc:postgresql://exoua.dnsalias.net/portal"/>
- <property name="username"
value="exoadmin"/>
- <property name="password"
value="exo12321"/>
- <property name="maxActive" value="50"/>
- <property name="maxIdle" value="5"/>
- <property name="initialSize" value="5"/>
- </properties-param>
- </init-params>
- </component-plugin>
- </external-component-plugins></programlisting></para>
-
- <para>And configure repository workspaces in repositories configuration
- with this one database. Parameter "multi-db" must be switched off (set
- value "false").</para>
-
- <para>Example (two workspaces <parameter>ws</parameter> - jdbcjcr,
- <parameter>ws1</parameter> -
jdbcjcr):<programlisting><workspaces>
- <workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="source-name" value="jdbcjcr"/>
- <property name="dialect" value="pgsql"/>
- <property name="multi-db" value="false"/>
- <property name="max-buffer-size" value="200K"/>
- <property name="swap-directory"
value="target/temp/swap/ws"/>
- </properties>
- </container>
- <cache enabled="true">
- <properties>
- <property name="max-size" value="10K"/>
- <property name="live-time" value="30m"/>
- </properties>
- </cache>
- <query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
- <properties>
- <property name="index-dir"
value="../temp/index"/>
- </properties>
- </query-handler>
- <lock-manager>
- <time-out>15m</time-out>
- <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
- <properties>
- <property name="path"
value="target/temp/lock/ws"/>
- </properties>
- </persister>
- </lock-manager>
- </workspace>
- <workspace name="ws1"
auto-init-root-nodetype="nt:unstructured">
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="source-name" value="jdbcjcr"/>
- <property name="dialect" value="pgsql"/>
- <property name="multi-db" value="false"/>
- <property name="max-buffer-size" value="200K"/>
- <property name="swap-directory"
value="target/temp/swap/ws1"/>
- </properties>
- </container>
- <cache enabled="true">
- <properties>
- <property name="max-size" value="10K"/>
- <property name="live-time" value="5m"/>
- </properties>
- </cache>
- <lock-manager>
- <time-out>15m</time-out>
- <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
- <properties>
- <property name="path"
value="target/temp/lock/ws1"/>
- </properties>
- </persister>
- </lock-manager>
- </workspace>
-</workspaces></programlisting></para>
-
- <para>In this way we have configured two workspaces which will be
- persisted in one database (PostgreSQL).</para>
-
- <section>
- <title>Configuration without DataSource</title>
-
- <para>Repository configuration without using of the
- <classname>javax.sql.DataSource</classname> bounded in
JNDI.</para>
-
- <para>This case may be usable if you have a dedicated JDBC driver
- implementation with special features like XA transactions,
- statements/connections pooling etc:<itemizedlist>
- <listitem>
- <para>You have to remove the configuration in
- <classname>InitialContextInitializer</classname> for your
database
- and configure a new one directly in the workspace
- container.</para>
- </listitem>
-
- <listitem>
- <para>Remove parameter "source-name" and add next lines
instead.
- Describe your values for a JDBC driver, database url and
- username.</para>
- </listitem>
- </itemizedlist></para>
-
- <note>
- <para>But be careful in this case JDBC driver should implement and
- provide connection pooling. Connection pooling is very recommended for
- use with JCR to prevent a database overload.</para>
- </note>
-
- <programlisting><workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
- <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
- <properties>
- <property name="dialect" value="hsqldb"/>
- <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
- <property name="url"
value="jdbc:hsqldb:file:target/temp/data/portal"/>
- <property name="username" value="su"/>
- <property name="password" value=""/>
- ......</programlisting>
- </section>
-
- <section>
- <title>Dynamic Workspace Creation</title>
-
- <para>Workspaces can be added dynamically during runtime.</para>
-
- <para>This can be performed in two steps:<itemizedlist>
- <listitem>
- <para>Firstly,
- <classname>ManageableRepository.configWorkspace(WorkspaceEntry
- wsConfig)</classname> - register a new configuration in
- RepositoryContainer and create a WorkspaceContainer.</para>
- </listitem>
-
- <listitem>
- <para>Secondly, the main step,
- <classname>ManageableRepository.createWorkspace(String
- workspaceName)</classname> - creation of a new workspace.</para>
- </listitem>
- </itemizedlist></para>
- </section>
- </section>
-
- <section>
- <title>Notes for Microsoft Windows users</title>
-
- <para>The current configuration of eXo JCR uses Apache DBCP connection
- pool
- (<classname>org.apache.commons.dbcp.BasicDataSourceFactory</classname>).
- It's possible to set a big value for maxActive parameter in
- <filename>configuration.xml</filename>. That means usage of lots of
TCP/IP
- ports from a client machine inside the pool (i.e. JDBC driver). As a
- result the data container can throw exceptions like "Address already in
- use". To solve this problem you have to configure the client's machine
- networking software for the usage of shorter timeouts for opened TCP/IP
- ports.</para>
-
- <para>Microsoft Windows has <parameter>MaxUserPort</parameter>,
- <parameter>TcpTimedWaitDelay</parameter> registry keys in the node
-
<parameter>HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTcpipParameters</parameter>,
- by default these keys are unset, set each one with values like
- these:<itemizedlist>
- <listitem>
- <para>"TcpTimedWaitDelay"=dword:0000001e, sets TIME_WAIT
parameter
- to 30 seconds, default is 240.</para>
- </listitem>
-
- <listitem>
- <para>"MaxUserPort"=dword:00001b58, sets the maximum of open
ports
- to 7000 or higher, default is 5000.</para>
- </listitem>
- </itemizedlist></para>
-
- <para>A sample registry file is below:<programlisting>Windows Registry
Editor Version 5.00
-
-[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters]
-"MaxUserPort"=dword:00001b58
-"TcpTimedWaitDelay"=dword:0000001e</programlisting></para>
- </section>
-</chapter>
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<chapter id="ch_jdbc_data_container">
+ <?dbhtml filename="ch-jdbc-data-container-config.html"?>
+
+ <title>JDBC Data Container Config</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>eXo JCR persistent data container can work in two configuration
+ modes:<itemizedlist>
+ <listitem>
+ <para><phrase>Multi-database</phrase>: one database for each
+ workspace (used in standalone eXo JCR service mode)</para>
+ </listitem>
+
+ <listitem>
+ <para><phrase>Single-database</phrase>: all workspaces
persisted in
+ one database (used in embedded eXo JCR service mode, e.g. in eXo
+ portal)</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The data container uses the JDBC driver to communicate with the
+ actual database software, i.e. any JDBC-enabled data storage can be used
+ with eXo JCR implementation.</para>
+
+ <para>Currently the data container is tested with the following
+ RDBMS:<itemizedlist>
+ <listitem>
+ <para>MySQL (5.x including UTF8 support)</para>
+ </listitem>
+
+ <listitem>
+ <para>PostgreSQL (8.x)</para>
+ </listitem>
+
+ <listitem>
+ <para>Oracle Database (9i, 10g)</para>
+ </listitem>
+
+ <listitem>
+ <para>Microsoft SQL Server (2005)</para>
+ </listitem>
+
+ <listitem>
+ <para>Sybase ASE (15.0)</para>
+ </listitem>
+
+ <listitem>
+ <para>Apache Derby/Java DB (10.1.x, 10.2.x)</para>
+ </listitem>
+
+ <listitem>
+ <para>IBM DB2 (8.x, 9.x)</para>
+ </listitem>
+
+ <listitem>
+ <para>HSQLDB (1.8.0.7)</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>Each database software supports ANSI SQL standards but has its own
+ specifics too. So, each database has its own configuration in eXo JCR as a
+ database dialect parameter. If you need a more detailed configuration of
+ the database it's possible to do that by editing the metadata SQL-script
+ files.</para>
+
+ <para>In case the non-ANSI node name is used it's necessary to use a
+ database with MultiLanguage support[TODO link to MultiLanguage]. Some JDBC
+ drivers need additional parameters for establishing a Unicode friendly
+ connection. E.g. under mysql it's necessary to add an additional parameter
+ for the JDBC driver at the end of JDBC URL. For instance:
+
<code>jdbc:mysql://exoua.dnsalias.net/portal?characterEncoding=utf8<...
+
+ <para>There are preconfigured configuration files for HSQLDB. Look for
+ these files in /conf/portal and /conf/standalone folders of the jar-file
+ <package>exo.jcr.component.core-XXX.XXX.jar</package> or
+ source-distribution of eXo JCR implementation.</para>
+
+ <para>By default the configuration files are located in service jars
+ <filename>/conf/portal/configuration.xml</filename> (eXo services
+ including JCR Repository Service) and
+ <filename>exo-jcr-config.xml</filename> (repositories configuration). In
+ eXo portal product JCR is configured in portal web application
+ <filename>portal/WEB-INF/conf/jcr/jcr-configuration.xml</filename> (JCR
+ Repository Service and related serivces) and repository-configuration.xml
+ (repositories configuration).</para>
+
+ <para>Read more about <link
linkend="ch_configuration">Repository
+ configuration</link>.</para>
+ </section>
+
+ <section>
+ <title>Multi-database Configuration</title>
+
+ <para>You need to configure each workspace in a repository. You may have
+ each one on different remote servers as far as you need.</para>
+
+ <para>First of all configure the data containers in the
+
<classname>org.exoplatform.services.naming.InitialContextInitializer</classname>
+ service. It's the JNDI context initializer which registers (binds) naming
+ resources (DataSources) for data containers.</para>
+
+ <para>Example (standalone mode, two data containers
+ <parameter>jdbcjcr</parameter> - local HSQLDB,
+ <parameter>jdbcjcr1</parameter> - remote
MySQL):<programlisting><component>
+
<key>org.exoplatform.services.naming.InitialContextInitializer</key>
+
<type>org.exoplatform.services.naming.InitialContextInitializer</type>
+ <component-plugins>
+ <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>jdbcjcr</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:target/temp/data/portal"/>
+ <property name="username" value="sa"/>
+ <property name="password" value=""/>
+ </properties-param>
+ </init-params>
+ </component-plugin>
+ <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>jdbcjcr1</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="com.mysql.jdbc.Driver"/>
+ <property name="url"
value="jdbc:mysql://exoua.dnsalias.net/jcr"/>
+ <property name="username"
value="exoadmin"/>
+ <property name="password"
value="exo12321"/>
+ <property name="maxActive" value="50"/>
+ <property name="maxIdle" value="5"/>
+ <property name="initialSize" value="5"/>
+ </properties-param>
+ </init-params>
+ </component-plugin>
+ <component-plugins>
+ <init-params>
+ <value-param>
+ <name>default-context-factory</name>
+
<value>org.exoplatform.services.naming.SimpleContextFactory</value>
+ </value-param>
+ </init-params>
+ </component></programlisting></para>
+
+ <para>We configure the database connection parameters:<itemizedlist>
+ <listitem>
+ <para><parameter>driverClassName</parameter>, e.g.
+ "org.hsqldb.jdbcDriver", "com.mysql.jdbc.Driver",
+ "org.postgresql.Driver"</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>url</parameter>, e.g.
+ "jdbc:hsqldb:file:target/temp/data/portal",
+ "jdbc:mysql://exoua.dnsalias.net/jcr"</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>username</parameter>, e.g. "sa",
"exoadmin"</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>password</parameter>, e.g. "",
"exo12321"</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>There can be connection pool configuration parameters
+ (org.apache.commons.dbcp.BasicDataSourceFactory):<itemizedlist>
+ <listitem>
+ <para><parameter>maxActive</parameter>, e.g. 50</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>maxIdle</parameter>, e.g. 5</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>initialSize</parameter>, e.g.
5</para>
+ </listitem>
+
+ <listitem>
+ <para>and other according to <ulink
+
url="http://jakarta.apache.org/commons/dbcp/configuration.html"...
+ DBCP configuration</ulink></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>When the data container configuration is done we can configure the
+ repository service. Each workspace will be configured for its own data
+ container.</para>
+
+ <para>Example (two workspaces <parameter>ws</parameter> - jdbcjcr,
+ <parameter>ws1</parameter> -
jdbcjcr1):<programlisting><workspaces>
+ <workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr"/>
+ <property name="dialect" value="hsqldb"/>
+ <property name="multi-db" value="true"/>
+ <property name="max-buffer-size" value="200K"/>
+ <property name="swap-directory"
value="target/temp/swap/ws"/>
+ </properties>
+ </container>
+ <cache enabled="true">
+ <properties>
+ <property name="max-size"
value="10K"/><!-- 10Kbytes -->
+ <property name="live-time"
value="30m"/><!-- 30 min -->
+ </properties>
+ </cache>
+ <query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ <property name="index-dir"
value="target/temp/index"/>
+ </properties>
+ </query-handler>
+ <lock-manager>
+ <time-out>15m</time-out><!-- 15 min -->
+ <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
+ <properties>
+ <property name="path"
value="target/temp/lock/ws"/>
+ </properties>
+ </persister>
+ </lock-manager>
+ </workspace>
+ <workspace name="ws1"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr1"/>
+ <property name="dialect" value="mysql"/>
+ <property name="multi-db" value="true"/>
+ <property name="max-buffer-size" value="200K"/>
+ <property name="swap-directory"
value="target/temp/swap/ws1"/>
+ </properties>
+ </container>
+ <cache enabled="true">
+ <properties>
+ <property name="max-size" value="10K"/>
+ <property name="live-time" value="5m"/>
+ </properties>
+ </cache>
+ <query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ <property name="index-dir"
value="target/temp/index"/>
+ </properties>
+ </query-handler>
+ <lock-manager>
+ <time-out>15m</time-out><!-- 15 min -->
+ <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
+ <properties>
+ <property name="path"
value="target/temp/lock/ws1"/>
+ </properties>
+ </persister>
+ </lock-manager>
+ </workspace>
+</workspaces></programlisting><itemizedlist>
+ <listitem>
+ <para><parameter>source-name</parameter> - a
javax.sql.DataSource
+ name configured in InitialContextInitializer component (was
+ <parameter>sourceName</parameter> prior JCR 1.9);</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>dialect</parameter> - a database dialect,
one of
+ "hsqldb", "mysql", "mysql-utf8",
"pgsql", "oracle", "oracle-oci",
+ "mssql", "sybase", "derby", "db2",
"db2v8" or "auto" for dialect
+ autodetection;</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>multi-db</parameter> - enable
multi-database
+ container with this parameter (set value "true");</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>max-buffer-size</parameter> - a threshold
(in
+ bytes) after which a javax.jcr.Value content will be swapped to a
+ file in a temporary storage. I.e. swap for pending changes.</para>
+ </listitem>
+
+ <listitem>
+ <para><parameter>swap-directory</parameter> - a path in the
file
+ system used to swap the pending changes.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>In this way we have configured two workspace which will be persisted
+ in two different databases (ws in HSQLDB, ws1 in MySQL).</para>
+
+ <note>
+ <para>Starting from v.1.9 <link
linkend="ch_configuration">repository
+ configuration</link> parameters supports human-readable formats of
+ values (e.g. 200K - 200 Kbytes, 30m - 30 minutes etc)</para>
+ </note>
+ </section>
+
+ <section>
+ <title>Single-database configuration</title>
+
+ <para>It's more simple to configure a single-database data container. We
+ have to configure one naming resource.</para>
+
+ <para>Example (embedded mode for <parameter>jdbcjcr</parameter>
data
+ container):<programlisting><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>jdbcjcr</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.postgresql.Driver"/>
+ <property name="url"
value="jdbc:postgresql://exoua.dnsalias.net/portal"/>
+ <property name="username"
value="exoadmin"/>
+ <property name="password"
value="exo12321"/>
+ <property name="maxActive" value="50"/>
+ <property name="maxIdle" value="5"/>
+ <property name="initialSize" value="5"/>
+ </properties-param>
+ </init-params>
+ </component-plugin>
+ </external-component-plugins></programlisting></para>
+
+ <para>And configure repository workspaces in repositories configuration
+ with this one database. Parameter "multi-db" must be switched off (set
+ value "false").</para>
+
+ <para>Example (two workspaces <parameter>ws</parameter> - jdbcjcr,
+ <parameter>ws1</parameter> -
jdbcjcr):<programlisting><workspaces>
+ <workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr"/>
+ <property name="dialect" value="pgsql"/>
+ <property name="multi-db" value="false"/>
+ <property name="max-buffer-size" value="200K"/>
+ <property name="swap-directory"
value="target/temp/swap/ws"/>
+ </properties>
+ </container>
+ <cache enabled="true">
+ <properties>
+ <property name="max-size" value="10K"/>
+ <property name="live-time" value="30m"/>
+ </properties>
+ </cache>
+ <query-handler
class="org.exoplatform.services.jcr.impl.core.query.lucene.SearchIndex">
+ <properties>
+ <property name="index-dir"
value="../temp/index"/>
+ </properties>
+ </query-handler>
+ <lock-manager>
+ <time-out>15m</time-out>
+ <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
+ <properties>
+ <property name="path"
value="target/temp/lock/ws"/>
+ </properties>
+ </persister>
+ </lock-manager>
+ </workspace>
+ <workspace name="ws1"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="source-name" value="jdbcjcr"/>
+ <property name="dialect" value="pgsql"/>
+ <property name="multi-db" value="false"/>
+ <property name="max-buffer-size" value="200K"/>
+ <property name="swap-directory"
value="target/temp/swap/ws1"/>
+ </properties>
+ </container>
+ <cache enabled="true">
+ <properties>
+ <property name="max-size" value="10K"/>
+ <property name="live-time" value="5m"/>
+ </properties>
+ </cache>
+ <lock-manager>
+ <time-out>15m</time-out>
+ <persister
class="org.exoplatform.services.jcr.impl.core.lock.FileSystemLockPersister">
+ <properties>
+ <property name="path"
value="target/temp/lock/ws1"/>
+ </properties>
+ </persister>
+ </lock-manager>
+ </workspace>
+</workspaces></programlisting></para>
+
+ <para>In this way we have configured two workspaces which will be
+ persisted in one database (PostgreSQL).</para>
+
+ <section>
+ <title>Configuration without DataSource</title>
+
+ <para>Repository configuration without using of the
+ <classname>javax.sql.DataSource</classname> bounded in
JNDI.</para>
+
+ <para>This case may be usable if you have a dedicated JDBC driver
+ implementation with special features like XA transactions,
+ statements/connections pooling etc:<itemizedlist>
+ <listitem>
+ <para>You have to remove the configuration in
+ <classname>InitialContextInitializer</classname> for your
database
+ and configure a new one directly in the workspace
+ container.</para>
+ </listitem>
+
+ <listitem>
+ <para>Remove parameter "source-name" and add next lines
instead.
+ Describe your values for a JDBC driver, database url and
+ username.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <note>
+ <para>But be careful in this case JDBC driver should implement and
+ provide connection pooling. Connection pooling is very recommended for
+ use with JCR to prevent a database overload.</para>
+ </note>
+
+ <programlisting><workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="dialect" value="hsqldb"/>
+ <property name="driverClassName"
value="org.hsqldb.jdbcDriver"/>
+ <property name="url"
value="jdbc:hsqldb:file:target/temp/data/portal"/>
+ <property name="username" value="su"/>
+ <property name="password" value=""/>
+ ......</programlisting>
+ </section>
+
+ <section>
+ <title>Dynamic Workspace Creation</title>
+
+ <para>Workspaces can be added dynamically during runtime.</para>
+
+ <para>This can be performed in two steps:<itemizedlist>
+ <listitem>
+ <para>Firstly,
+ <classname>ManageableRepository.configWorkspace(WorkspaceEntry
+ wsConfig)</classname> - register a new configuration in
+ RepositoryContainer and create a WorkspaceContainer.</para>
+ </listitem>
+
+ <listitem>
+ <para>Secondly, the main step,
+ <classname>ManageableRepository.createWorkspace(String
+ workspaceName)</classname> - creation of a new workspace.</para>
+ </listitem>
+ </itemizedlist></para>
+ </section>
+ </section>
+
+ <section>
+ <title>Simple and Complex queries</title>
+
+ <para>eXo JCR provides two ways for interact with Database -
+ <classname>JDBCStorageConnection</classname> that uses simple queries
and
+ <classname>CQJDBCStorageConection</classname> that uses complex queries
+ for reducing amount of database callings.</para>
+
+ <para>Simple queries will be used if you chose
+
<classname>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</classname>:<programlisting><workspaces>
+ <workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ ...
+ </workspace>
+</worksapces></programlisting></para>
+
+ <para>Complex queries will be used if you chose
+
<classname>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</classname>:<programlisting><workspaces>
+ <workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer">
+ ...
+ </workspace>
+</worksapces></programlisting></para>
+
+ <para>Why we should use a Complex Queries?<simplelist>
+ <member>They are optimised to reduce amount of requests to
+ database.</member>
+ </simplelist>Why we should use a Simple Queries?<simplelist>
+ <member>Simple queries implemented in way to support as many database
+ dialects as possible.</member>
+
+ <member>Simple queries do not use sub queries, left or right
+ joins.</member>
+ </simplelist></para>
+ </section>
+
+ <section>
+ <title>Forse Query Hints</title>
+
+ <para>Some databases supports hints to increase query performance (like
+ Oracle, MySQL, etc). eXo JCR have separate Complex Query implementation
+ for Orcale dialect, that uses query hints to increase performance for few
+ important queries. </para>
+
+ <para>To enable this option put next configuration
+ property:<programlisting><workspace name="ws"
auto-init-root-nodetype="nt:unstructured">
+ <container
class="org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer">
+ <properties>
+ <property name="dialect" value="oracle"/>
+ <property name="force.query.hints" value="true"
/>
+ ......</programlisting></para>
+
+ <para>Query hints enabled by default. </para>
+
+ <para>eXo JCR uses query hints only for Complex Query Oracle dialect. For
+ all other dialects this parameter is ignored.</para>
+ </section>
+
+ <section>
+ <title>Notes for Microsoft Windows users</title>
+
+ <para>The current configuration of eXo JCR uses Apache DBCP connection
+ pool
+ (<classname>org.apache.commons.dbcp.BasicDataSourceFactory</classname>).
+ It's possible to set a big value for maxActive parameter in
+ <filename>configuration.xml</filename>. That means usage of lots of
TCP/IP
+ ports from a client machine inside the pool (i.e. JDBC driver). As a
+ result the data container can throw exceptions like "Address already in
+ use". To solve this problem you have to configure the client's machine
+ networking software for the usage of shorter timeouts for opened TCP/IP
+ ports.</para>
+
+ <para>Microsoft Windows has <parameter>MaxUserPort</parameter>,
+ <parameter>TcpTimedWaitDelay</parameter> registry keys in the node
+
<parameter>HKEY_LOCAL_MACHINESYSTEMCurrentControlSetServicesTcpipParameters</parameter>,
+ by default these keys are unset, set each one with values like
+ these:<itemizedlist>
+ <listitem>
+ <para>"TcpTimedWaitDelay"=dword:0000001e, sets TIME_WAIT
parameter
+ to 30 seconds, default is 240.</para>
+ </listitem>
+
+ <listitem>
+ <para>"MaxUserPort"=dword:00001b58, sets the maximum of open
ports
+ to 7000 or higher, default is 5000.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>A sample registry file is below:<programlisting>Windows Registry
Editor Version 5.00
+
+[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters]
+"MaxUserPort"=dword:00001b58
+"TcpTimedWaitDelay"=dword:0000001e</programlisting></para>
+ </section>
+</chapter>
5897
days inactive
5897
days old
exo-jcr-commits@lists.jboss.org
0 comments
1 participants
participants (1)
-
do-not-reply＠jboss.org