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..ecb1f0f662 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. @@ -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). @@ -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). @@ -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: @@ -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 <>). 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..2bd401f645 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) @@ -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_. @@ -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 <>. +described in <>. This example defines a connection pool for a Microsoft SQL Server: @@ -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 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] +---- + + + + + + + + + + +---- + +==== 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] +---- + + + + + + + + +---- + +===== 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] +---- + + + + + + + + + +---- + ==== 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",] |===