From 87e65ad75da4f5d8964236bc7768fe4e191a1291 Mon Sep 17 00:00:00 2001 From: Torsten Friebe Date: Thu, 11 Apr 2024 19:03:07 +0200 Subject: [PATCH 1/3] added examples how to configure hikari and c3p0 connection pool provider, fixed config example for ms sql server and aligned description of cp properties --- .../src/main/asciidoc/javamodules.adoc | 4 +- .../src/main/asciidoc/serverconnections.adoc | 135 +++++++++++++----- 2 files changed, 100 insertions(+), 39 deletions(-) diff --git a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc index f50bcf4b0f..a9e81d108f 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc +++ b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc @@ -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. @@ -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). diff --git a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc index cb22284e36..65be4460f2 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc +++ b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc @@ -56,17 +56,14 @@ database: - - - ---- @@ -74,12 +71,12 @@ database: _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 @@ -103,10 +100,8 @@ This example defines a connection pool for an Oracle database: - - @@ -115,7 +110,6 @@ This example defines a connection pool for an Oracle database: - ---- @@ -123,11 +117,13 @@ 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_. @@ -148,19 +144,14 @@ This example defines a connection pool for a Microsoft SQL Server: - - - - + + - - - ---- @@ -168,13 +159,15 @@ 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. @@ -189,12 +182,10 @@ servlet container that runs deegree webservices (e.g. Apache Tomcat): - - ---- @@ -219,10 +210,8 @@ Connection Pool): - - + - @@ -232,7 +221,6 @@ Connection Pool): - ---- @@ -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",] @@ -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 @@ -374,6 +362,79 @@ the element _DialectProvider_: org.deegree.sqldialect.postgis.PostGISDialectProvider) |=== +[[anchor-configuration-jdbc-cp]] +==== JDBC connection pools + +By default, the 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 of `PGSimpleDataSource` +[source,xml] +---- + + + + + + + + + + +---- + +==== 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 of `HikariDataSource` +[source,xml] +---- + + + + + + + + +---- + +===== 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 of `ComboPooledDataSource` +[source,xml] +---- + + + + + + + + + +---- + ==== Legacy configuration format Prior to deegree webservices release 3.4, a simpler (but limited) @@ -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",] |=== From 5787b65d1b33f1c3692600866c31f705dd002f32 Mon Sep 17 00:00:00 2001 From: Torsten Friebe Date: Fri, 12 Apr 2024 12:49:45 +0200 Subject: [PATCH 2/3] fixed document reference for sql server jars --- .../src/main/asciidoc/javamodules.adoc | 1 + .../src/main/asciidoc/serverconnections.adoc | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc index a9e81d108f..03f6e6cd34 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc +++ b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc @@ -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: diff --git a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc index 65be4460f2..ae2a971978 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc +++ b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc @@ -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 <>. +This is described in <> and <>. ==== Minimal configuration example (PostgreSQL) @@ -135,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 <>. +described in <>. This example defines a connection pool for a Microsoft SQL Server: @@ -373,7 +373,7 @@ The PostgreSQL JDBC driver provides two DataSource implementations which support This DataSource implementation requires the official PostgreSQL JDBC driver on the classpath. Download the driver from: https://jdbc.postgresql.org/download/ -.Configuration of `PGSimpleDataSource` +.Configuration example using `PGSimpleDataSource` [source,xml] ---- Date: Wed, 24 Apr 2024 11:52:01 +0200 Subject: [PATCH 3/3] Fixed name of MS SQL Server JDBC driver JAR file, and typos fixed --- .../src/main/asciidoc/javamodules.adoc | 4 ++-- .../src/main/asciidoc/serverconnections.adoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc index 03f6e6cd34..ecb1f0f662 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc +++ b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/javamodules.adoc @@ -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). @@ -151,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 <>). diff --git a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc index ae2a971978..2bd401f645 100644 --- a/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc +++ b/deegree-services/deegree-webservices-handbook/src/main/asciidoc/serverconnections.adoc @@ -365,7 +365,7 @@ org.deegree.sqldialect.postgis.PostGISDialectProvider) [[anchor-configuration-jdbc-cp]] ==== JDBC connection pools -By default, the 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. +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