loading table of contents...
2.7.1.2.3. Database product configuration
To use external database storage, select the storage-type "External Database (JDBC)". For the connection to the external database, JDBC connection properties have to provided as described below. All other settings are identical to filesystem-storage (see Section 2.7.1.2.1, “Filesystem product configuration”).
The checkbox "Store publication exports in database" defines whether exported publications will be stored inside or outside of the database. In the later case, the publication files are stored in the product directory (see Section 2.7.1.1, “Storage types” for details on the filesystem structure).
Connection properties
If the storage type "External Database (JDBC)" has been selected, then following connection properties have to be set:
  • Connection URL
    Enter the JDBC connection URL or the JNDI URL of the database instance. Following an example of a JDBC connection URL to a MySQL database instance:
  jdbc:mysql://localhost:3306/docmentadb
For production use it is however recommended to configure a datasource within the application server and to enter the datasource JNDI name. Following an example of a JNDI connection URL:
  java:/comp/env/jdbc/docmentadb
Note that a JNDI connection URL has to start with "java:". See also the following section on connection pooling for further information on configuring database connections.
  • SQL Dialect
    Select the database system to be used. Note that all databases that are supported by Hibernate 3.6 are listed (however, not all of the listed databases have been tested to work with Docmenta). If the version number of your  database system is not listed, then select the version that is nearest to your used database version. For example, if you use Oracle 12, then select Oracle 10g (if 10g is the highest listed Oracle version).
  • JDBC Driver Class
    Enter the JDBC driver classname. For example, the MySQL driver is named "com.mysql.jdbc.Driver". Consult the documentation of your database supplier, if you do not know the driver classname. Note that the JDBC driver has to be available in the Java classpath of the Docmenta web-application (e.g. add the JDBC driver libraries to the WEB-INF/lib directory of the Docmenta installation and restart the web-server).
  • User ID
    Enter the ID of the database user that Docmenta shall use for connections to the database.
  • User Password
    Enter the password of the database user.
 Following a JDBC connection example:

Figure 2.7.12. JDBC connection (example)

MySQL max_allowed_packet
MySQL restricts the packet size transferred via JDBC by the value given in the variable max_allowed_packet. Therefore, this variable has to be set to more than the maximum file-size that shall be storable in the product database. For example, if the publication archive is stored in the database, and the exported publications have a size of up to 10 MB, then the variable max_allowed_packet should be set to 11 MB or more. Note that the MySQL variables can be set in the configuration file my.ini in the MySQL bin directory.
Connection pooling
As creating a connection to an external database is time-consuming, it is recommended to enable connection pooling for external database storage. This is especially true, if the database is located on a different host than the web-server.
Note that even with connection pooling it is recommended to place the web-server and the database-server on the same host, as fine-grained communication is taking place between the web-application and the database.
Hibernate is shipped with a rudimentary connection pool  which is by default enabled for external database-storage. For embedded database-storage the connection pool is disabled by default, as it does not give any notable performance gain.
The settings of the Hibernate connection pool can be changed by editing the files WEB-INF/db_config.properties (used for external databases) and WEB-INF/db_config_embedded.properties (used for embedded databases). Both files are located in the web-application directory. If the files do not exist, just create them to change the default settings. Following an example configuration that sets the maximum number of pooled connection to 30:
hibernate.connection.pool_size=30
For more information on configuring database connection pooling see the Hibernate documentation (http://www.hibernate.org). Note however, that the default Hibernate connection pool is not intended for use in a production system.
In a production system it is recommended to configure the application server to provide a pooled datasource. See the Tomcat JNDI Datasource HOW-TO for more information on configuring JDBC datasources. If Docmenta is deployed in an Apache Tomcat 7 container, then also the built-in Tomcat JDBC Connection Pool can be used. For example, a pooled JNDI datasource can be configured by adding following resource definition to the META-INF/context.xml file in the web-application directory (the example shows the connection to a MySQL database):
<?xml version="1.0" encoding="UTF-8"?>
<Context>

 <Resource name="jdbc/docmentadb"
           auth="Container"
           type="javax.sql.DataSource"
           factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
           testWhileIdle="true"
           testOnBorrow="true"
           testOnReturn="false"
           validationQuery="SELECT 1"
           validationInterval="30000"
           timeBetweenEvictionRunsMillis="30000"
           maxActive="100"
           minIdle="10"
           maxWait="20000"
           initialSize="10"
           removeAbandonedTimeout="1800"
           removeAbandoned="true"
           logAbandoned="true"
           minEvictableIdleTimeMillis="60000"
           jmxEnabled="true"
           jdbcInterceptors=
            "org.apache.tomcat.jdbc.pool.interceptor.ConnectionState;
            org.apache.tomcat.jdbc.pool.interceptor.StatementFinalizer"
           username="root"
           password="password"
           driverClassName="com.mysql.jdbc.Driver"
           url="jdbc:mysql://localhost:3306/docdb" />
</Context>
Note that if removeAbandoned is set to "true", then the value removeAbandonedTimeout should be set to at least 1800 (30 minutes).
The JNDI datasource can then be addressed in the product configuration as shown in the following example:

Figure 2.7.13. JNDI connection (example)

As can be seen in the example above, a JNDI connection URL has to start with "java:/comp/env/" followed by the JNDI resource name. In case of a JNDI connection, the Driver-Class, User-ID and Password are optional, because these values are normally given in the JNDI resource configuration.