Skip to content

Commit

Permalink
Merge pull request #1677 from lat-lon/improveDocForDBCP
Browse files Browse the repository at this point in the history 
Enhanced documention with examples how to configure different connection pool provider
  • Loading branch information
@stephanr
stephanr authored Apr 24, 2024
2 parents 1b6b793 + f08a0bd commit 55e6484
Show file tree
Hide file tree
Showing 2 changed files with 105 additions and 43 deletions.
9 changes: 5 additions & 4 deletions deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ class files)
* Global directories for all web applications running in the container
(depends on the actual web container)

When you add files to the web application claspath, you have to restart
When you add files to the web application classpath, you have to restart
the web application or the web application container to make the new
code available to deegree webservices.

Expand All @@ -60,7 +60,7 @@ When deegree webservices initializes the workspace, it scans directory
_modules/_ of the active deegree workspace for files ending with
_.jar_ and adds them to the classpath. This can be very handy, as it
allows to create self-contained workspaces (no fiddling with other
directories required) and also has the benefit the you can reload the
directories required) and also has the benefit that you can reload the
deegree workspace only after adding your libraries (instead of
restarting the deegree webapp or the whole web application container).

Expand Down Expand Up @@ -92,7 +92,7 @@ workspace classpath.
By default, deegree webservices includes everything that is needed for
connecting to PostgreSQL/PostGIS and Derby databases. If you want to
connect to an Oracle Spatial or Microsoft SQL Server instance, you need
to add additional Java libraries manually, as the required JDBC
to add additional libraries manually, as the required JDBC
libraries are not included in the deegree webservices download (for
license reasons).

Expand Down Expand Up @@ -140,6 +140,7 @@ not available the _xmlparserv2_ can be used instead. (In rare
conditions this could set the oracle library as default XML parser,
which could lead to unexpected behavior).

[[anchor-sqlserverjars]]
==== Adding Microsoft SQL server support

The following deegree resources support Microsoft SQL Server:
Expand All @@ -150,5 +151,5 @@ The following deegree resources support Microsoft SQL Server:

In order to enable Microsoft SQL Server connectivity for these
resources, you need to add a compatible Microsoft JDBC driver (e.g.
_sqljdbc4.jar_)footnote:[https://learn.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server]
_mssql-jdbc-12.6.1.jre11.jar_)footnote:[https://learn.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server]
(see <<anchor-adding-jars>>).
139 changes: 100 additions & 39 deletions ...-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ to add additional modules first. This is described in
NOTE: By default, deegree webservices includes a JDBC driver for connecting to
PostgreSQL. If you want to make a connection to other SQL databases
(e.g. Oracle), you will need to add a compatible JDBC driver manually.
This is described in <<anchor-oraclejars>>.
This is described in <<anchor-oraclejars>> and <<anchor-sqlserverjars>>.


==== Minimal configuration example (PostgreSQL)
Expand All @@ -56,30 +56,27 @@ database:
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="org.apache.commons.dbcp2.BasicDataSource" destroyMethod="close" />
<!-- Configuration of DataSource properties -->
<Property name="driverClassName" value="org.postgresql.Driver" />
<Property name="url" value="jdbc:postgresql://localhost/deegree-db" />
<Property name="username" value="kelvin" />
<Property name="password" value="s3cr3t" />
<Property name="maxTotal" value="10" />
</DataSourceConnectionProvider>
----

* The DataSource object uses Java class
_org.apache.commons.dbcp2.BasicDataSource_ (a connection pool class
provided by
https://commons.apache.org/proper/commons-dbcp/index.html[Apache Commons
DBCP].). If you don't know what this means, then this is most likely
DBCP] project). If you don't know what this means, then this is most likely
what you want to use.
* The JDBC driver class is _org.postgresql.Driver_ (this is the Java
class name to use for PostgreSQL/PostGIS databases).
class name to use when connecting to PostgreSQL/PostGIS databases).
* The JDBC URL is _jdbc:postgresql://localhost:5432/deegree-db_. This
means that PostgreSQL is running on the same machine, port 5432
means that PostgreSQL is running on the same host, port 5432
(default). The database identifier is _deegree-db_. Adapt these values
to match to your setup.
* The database username is _kelvin_, password is _s3cr3t_. Adapt
Expand All @@ -103,10 +100,8 @@ This example defines a connection pool for an Oracle database:
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="org.apache.commons.dbcp2.BasicDataSource" destroyMethod="close" />
<!-- Configuration of DataSource properties -->
<Property name="driverClassName" value="oracle.jdbc.OracleDriver" />
<Property name="url" value="jdbc:oracle:thin:@localhost:1521:deegree" />
Expand All @@ -115,19 +110,20 @@ This example defines a connection pool for an Oracle database:
<Property name="poolPreparedStatements" value="true" />
<Property name="maxTotal" value="10" />
<Property name="maxIdle" value="10" />
</DataSourceConnectionProvider>
----

This defines a database connection with the following properties:

* The DataSource object uses the Java class
_org.apache.commons.dbcp2.BasicDataSource_ (a connection pool class
provided by Apache DBCP). If you are not familiar with J2EE containers,
this is most likely what you want to use.
provided by
https://commons.apache.org/proper/commons-dbcp/index.html[Apache Commons
DBCP] project). If you don't know what this means, then this is most likely
what you want to use.
* The JDBC driver class is _oracle.jdbc.OracleDriver_. This is the
Java class name to use for Oracle.
* The so-called JDBC URL is
Java class name to use when connecting to Oracle databases.
* The JDBC URL is
_jdbc:oracle:thin:@localhost:1521:deegree_. This means that Oracle is
running on the local machine, port 1521 (adapt host name and port as
required). The database identifier is _deegree_.
Expand All @@ -139,7 +135,7 @@ required). The database identifier is _deegree_.
NOTE: By default, deegree webservices includes JDBC drivers for connecting to
PostgreSQL and Derby databases. In order to connect to Microsoft SQL
Server, you need to add a compatible JDBC driver manually. This is
described in <<anchor-oraclejars>>.
described in <<anchor-sqlserverjars>>.

This example defines a connection pool for a Microsoft SQL Server:

Expand All @@ -148,33 +144,30 @@ This example defines a connection pool for a Microsoft SQL Server:
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="org.apache.commons.dbcp2.BasicDataSource" destroyMethod="close" />
<!-- Configuration of DataSource properties -->
<Property name="driverClassName" value="org.postgresql.Driver" />
<Property name="url" value="jdbc:postgresql://localhost/deegree-db" />
<Property name="driverClassName" value="com.microsoft.sqlserver.jdbc.SQLServerDriver" />
<Property name="url" value="jdbc:sqlserver://localhost:1433;databaseName=deegree-db" />
<Property name="username" value="kelvin" />
<Property name="password" value="s3cr3t" />
<Property name="poolPreparedStatements" value="true" />
<Property name="maxTotal" value="10" />
<Property name="maxIdle" value="10" />
</DataSourceConnectionProvider>
----

This defines a database connection with the following properties:

* The DataSource object uses the Java class
_org.apache.commons.dbcp2.BasicDataSource_ (a connection pool class
provided by Apache DBCP). If you are not familiar with J2EE containers,
this is most likely what you want to use.
* The JDBC driver class is _org.postgresql.Driver_. This is the Java
class name to use for PostgreSQL/PostGIS.
* The so-called JDBC URL is
_jdbc:postgresql://localhost:5432/deegree-db_. This means that
PostgreSQL is running on the local machine, port 5432 (adapt host name
provided by
https://commons.apache.org/proper/commons-dbcp/index.html[Apache Commons
DBCP] project). If you don't know what this means, then this is most likely
what you want to use.
* The JDBC driver class is _com.microsoft.sqlserver.jdbc.SQLServerDriver_. This is the Java
class name to use when connecting to Microsoft SQL Server databases.
* The JDBC URL is
_jdbc:sqlserver://localhost:1433;databaseName=deegree-db_. This means that
SQL Server is running on the local machine, port 1433 (adapt host name
and port as required). The database identifier is _deegree-db_.
* The database username is _kelvin_, password is _s3cr3t_.
* The maximum number of simultaneous connections is 10.
Expand All @@ -189,12 +182,10 @@ servlet container that runs deegree webservices (e.g. Apache Tomcat):
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Lookup of javax.sql.DataSource instance via JNDI -->
<DataSource javaClass="org.deegree.db.datasource.JndiLookup" factoryMethod="lookup">
<Argument value="java:comp/env/jdbc/DatabaseName" javaClass="java.lang.String" />
</DataSource>
</DataSourceConnectionProvider>
----

Expand All @@ -219,10 +210,8 @@ Connection Pool):
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation / lookup of javax.sql.DataSource instance -->
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="oracle.ucp.jdbc.PoolDataSourceFactory" factoryMethod="getPoolDataSource" />
<!-- Configuration of DataSource properties -->
<Property name="connectionFactoryClassName" value="oracle.jdbc.pool.OracleDataSource" />
<Property name="URL" value="jdbc:oracle:thin:@//localhost:1521/XE" />
Expand All @@ -232,7 +221,6 @@ Connection Pool):
<Property name="minPoolSize" value="5" />
<Property name="maxPoolSize" value="10" />
<Property name="maxStatements" value="50" />
</DataSourceConnectionProvider>
----

Expand All @@ -248,7 +236,7 @@ The database connection config file format is defined by schema file
https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd. The
root element is _DataSourceConnectionProvider_ and the optional
attribute `config` can be set to _3.5.0_. The following table lists the available
configuration options. When specifiying them, their order must be
configuration options. When specifying them, their order must be
respected.

[width="100%",cols="17%,15%,11%,57%",options="header",]
Expand Down Expand Up @@ -350,7 +338,7 @@ The properties available for configuration depend on the implementation
of _javax.sql.DataSource_:

* Apache Commons DBCP: See
https://commons.apache.org/proper/commons-dbcp/api-2.7.0/org/apache/commons/dbcp2/BasicDataSource.html
https://commons.apache.org/proper/commons-dbcp/apidocs/org/apache/commons/dbcp2/BasicDataSource.html
* Oracle UCP:
https://docs.oracle.com/cd/E11882_01/java.112/e12826/oracle/ucp/jdbc/PoolDataSource.html

Expand All @@ -374,6 +362,79 @@ the element _DialectProvider_:
org.deegree.sqldialect.postgis.PostGISDialectProvider)
|===

[[anchor-configuration-jdbc-cp]]
==== JDBC connection pools

By default, the https://commons.apache.org/proper/commons-dbcp/[Apache Commons DBCP connection pool library] is provided with deegree webservices WAR file. In some cases you may consider another implementation as more appropriate to use. The following examples show how to use other connection pool provider. Keep in mind to add the mentioned libraries to the same classpath as the JDBC driver.

==== PostgreSQL JDBC

The PostgreSQL JDBC driver provides two DataSource implementations which support, among other things, the configuration for multiple hosts. Read further in the https://jdbc.postgresql.org/documentation/datasource/[PostgreSQL JDBC driver documentation].
This DataSource implementation requires the official PostgreSQL JDBC driver on the classpath.
Download the driver from: https://jdbc.postgresql.org/download/

.Configuration example using `PGSimpleDataSource`
[source,xml]
----
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="org.postgresql.ds.PGSimpleDataSource"/>
<!-- Configuration of DataSource properties -->
<Property name="serverName" value="localhost"/>
<Property name="databaseName" value="deegree-db"/>
<Property name="portNumber" value="5432"/>
<Property name="user" value="kelvin"/>
<Property name="password" value="s3cr3t"/>
</DataSourceConnectionProvider>
----

==== HikariCP

The HikariCP project states that the implementation is a "zero-overhead" production ready JDBC connection pool and very lightweight.

This DataSource implementation requires the `com.zaxxer:HikariCP` library on the classpath.
Download the connection pool from: https://github.com/brettwooldridge/HikariCP

.Configuration example using `HikariDataSource`
[source,xml]
----
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="com.zaxxer.hikari.HikariDataSource" />
<!-- Configuration of DataSource properties -->
<Property name="jdbcUrl" value="jdbc:postgresql://localhost:5432/deegree-db" />
<Property name="username" value="kelvin" />
<Property name="password" value="s3cr3t" />
</DataSourceConnectionProvider>
----

===== c3p0

The c3p0 project states that the implementation is an easy-to-use library for making traditional JDBC drivers "enterprise-ready" by augmenting them with functionality defined by the JDBC 3 and 4 specs and the optional extensions to JDBC 2.

This DataSource implementation requires the `com.mchange:c3p0` library on the classpath.
Download the connection pool from: https://www.mchange.com/projects/c3p0/

.Configuration example using `ComboPooledDataSource`
[source,xml]
----
<DataSourceConnectionProvider
xmlns="http://www.deegree.org/connectionprovider/datasource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.deegree.org/connectionprovider/datasource https://schemas.deegree.org/core/3.5/connectionprovider/datasource/datasource.xsd">
<!-- Creation of javax.sql.DataSource instance -->
<DataSource javaClass="com.mchange.v2.c3p0.ComboPooledDataSource" />
<!-- Configuration of DataSource properties -->
<Property name="driverClass" value="org.postgresql.Driver" />
<Property name="jdbcUrl" value="jdbc:postgresql://localhost:5432/deegree-db" />
<Property name="user" value="kelvin" />
<Property name="password" value="s3cr3t" />
</DataSourceConnectionProvider>
----

==== Legacy configuration format

Prior to deegree webservices release 3.4, a simpler (but limited)
Expand All @@ -394,9 +455,9 @@ is called 'inspire', the database user is 'postgres' and password is

The legacy connection config file format is defined by schema file
https://schemas.deegree.org/core/3.5/jdbc/jdbc.xsd. The root element is
_JDBCConnection_ and the config attribute must be _3.0.0_. The
_JDBCConnection_. The
following table lists the available configuration options. When
specifiying them, their order must be respected.
specifying them, their order must be respected.

[width="100%",cols="16%,18%,12%,54%",options="header",]
|===
Expand Down

0 comments on commit 55e6484

Please sign in to comment.