You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2020/09/15 15:04:34 UTC
[tomcat] branch 9.0.x updated (49aa2b3 -> b2a97a8)
This is an automated email from the ASF dual-hosted git repository.
markt pushed a change to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git.
from 49aa2b3 Fix typos
new a0f8a6a Documentation improvements in preparation for deprecating JDBCRealm
new b2a97a8 Deprecate JDBCRealm
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
java/org/apache/catalina/mbeans/MBeanFactory.java | 7 +-
.../apache/catalina/mbeans/mbeans-descriptors.xml | 2 +-
.../org/apache/catalina/realm/DataSourceRealm.java | 2 +-
java/org/apache/catalina/realm/JDBCRealm.java | 4 +
webapps/docs/appdev/deployment.xml | 2 +-
webapps/docs/changelog.xml | 3 +
webapps/docs/config/realm.xml | 247 +++++++++++----------
webapps/docs/host-manager-howto.xml | 7 +-
webapps/docs/html-host-manager-howto.xml | 7 +-
webapps/docs/realm-howto.xml | 220 +++++++++---------
10 files changed, 258 insertions(+), 243 deletions(-)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[tomcat] 01/02: Documentation improvements in preparation for
deprecating JDBCRealm
Posted by ma...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit a0f8a6a97cda296c18be3b4ad434551102c77d11
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Sep 15 14:32:23 2020 +0100
Documentation improvements in preparation for deprecating JDBCRealm
---
webapps/docs/appdev/deployment.xml | 2 +-
webapps/docs/config/realm.xml | 244 ++++++++++++++++---------------
webapps/docs/host-manager-howto.xml | 7 +-
webapps/docs/html-host-manager-howto.xml | 7 +-
webapps/docs/realm-howto.xml | 217 ++++++++++++++-------------
5 files changed, 238 insertions(+), 239 deletions(-)
diff --git a/webapps/docs/appdev/deployment.xml b/webapps/docs/appdev/deployment.xml
index f479f97..77395a4 100644
--- a/webapps/docs/appdev/deployment.xml
+++ b/webapps/docs/appdev/deployment.xml
@@ -131,7 +131,7 @@ The location commonly used within a Tomcat installation for shared code is
<strong>$CATALINA_HOME/lib</strong>. JAR files placed here are visible both to
web applications and internal Tomcat code. This is a good place to put JDBC
drivers that are required for both your application or internal Tomcat use
-(such as for a JDBCRealm).</p>
+(such as for a DataSourceRealm).</p>
<p>Out of the box, a standard Tomcat installation includes a variety
of pre-installed shared library files, including:</p>
diff --git a/webapps/docs/config/realm.xml b/webapps/docs/config/realm.xml
index 974e54e..44fbd2d 100644
--- a/webapps/docs/config/realm.xml
+++ b/webapps/docs/config/realm.xml
@@ -92,126 +92,6 @@
</subsection>
- <subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm">
-
- <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
- a relational database, accessed through an appropriate JDBC driver,
- to perform lookups of usernames, passwords, and their associated
- roles. Because the lookup is done each time that it is required,
- changes to the database will be immediately reflected in the
- information used to authenticate new logins.</p>
-
- <p>A rich set of additional attributes lets you configure the required
- connection to the underlying database, as well as the table and
- column names used to retrieve the required information:</p>
-
- <attributes>
-
- <attribute name="allRolesMode" required="false">
- <p>This attribute controls how the special role name <code>*</code> is
- handled when processing authorization constraints in web.xml. By
- default, the specification compliant value of <code>strict</code> is
- used which means that the user must be assigned one of the roles defined
- in web.xml. The alternative values are <code>authOnly</code> which means
- that the user must be authenticated but no check is made for assigned
- roles and <code>strictAuthOnly</code> which means that the user must be
- authenticated and no check will be made for assigned roles unless roles
- are defined in web.xml in which case the user must be assigned at least
- one of those roles.</p>
- <p>When this attribute has the value of <code>authOnly</code> or
- <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
- <strong>userRoleTable</strong> attributes become optional. If those two
- attributes are omitted, the user's roles will not be loaded by this
- Realm.</p>
- </attribute>
-
- <attribute name="connectionName" required="true">
- <p>The database username to use when establishing the JDBC
- connection.</p>
- </attribute>
-
- <attribute name="connectionPassword" required="true">
- <p>The database password to use when establishing the JDBC
- connection.</p>
- </attribute>
-
- <attribute name="connectionURL" required="true">
- <p>The connection URL to be passed to the JDBC driver when
- establishing a database connection.</p>
- </attribute>
-
- <attribute name="driverName" required="true">
- <p>Fully qualified Java class name of the JDBC driver to be
- used to connect to the authentication database.</p>
- </attribute>
-
- <attribute name="roleNameCol" required="false">
- <p>Name of the column, in the "user roles" table, which contains
- a role name assigned to the corresponding user.</p>
- <p>This attribute is <strong>required</strong> in majority of
- configurations. See <strong>allRolesMode</strong> attribute for
- a rare case when it can be omitted.</p>
- </attribute>
-
- <attribute name="stripRealmForGss" required="false">
- <p>When processing users authenticated via the GSS-API, this attribute
- controls if any "@..." is removed from the end of the user
- name. If not specified, the default is <code>true</code>.</p>
- </attribute>
-
- <attribute name="transportGuaranteeRedirectStatus" required="false">
- <p>The HTTP status code to use when the container needs to issue an HTTP
- redirect to meet the requirements of a configured transport
- guarantee. The provided status code is not validated. If not
- specified, the default value of <code>302</code> is used.</p>
- </attribute>
-
- <attribute name="userCredCol" required="true">
- <p>Name of the column, in the "users" table, which contains
- the user's credentials (i.e. password). If a
- <code>CredentialHandler</code> is specified, this component
- will assume that the passwords have been encoded with the
- specified algorithm. Otherwise, they will be assumed to be
- in clear text.</p>
- </attribute>
-
- <attribute name="userNameCol" required="true">
- <p>Name of the column, in the "users" and "user roles" table,
- that contains the user's username.</p>
- </attribute>
-
- <attribute name="userRoleTable" required="false">
- <p>Name of the "user roles" table, which must contain columns
- named by the <code>userNameCol</code> and <code>roleNameCol</code>
- attributes.</p>
- <p>This attribute is <strong>required</strong> in majority of
- configurations. See <strong>allRolesMode</strong> attribute for
- a rare case when it can be omitted.</p>
- </attribute>
-
- <attribute name="userTable" required="true">
- <p>Name of the "users" table, which must contain columns named
- by the <code>userNameCol</code> and <code>userCredCol</code>
- attributes.</p>
- </attribute>
-
- <attribute name="X509UsernameRetrieverClassName" required="false">
- <p>When using X509 client certificates, this specifies the class name
- that will be used to retrieve the user name from the certificate.
- The class must implement the
- <code>org.apache.catalina.realm.X509UsernameRetriever</code>
- interface. The default is to use the certificate's SubjectDN
- as the username.</p>
- </attribute>
- </attributes>
-
- <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
- information on setting up container managed security using the
- JDBC Database Realm component.</p>
-
- </subsection>
-
-
<subsection name="DataSource Database Realm - org.apache.catalina.realm.DataSourceRealm">
<p>The <strong>DataSource Database Realm</strong> connects Tomcat to
@@ -340,7 +220,6 @@
roles. Changes to the directory are immediately reflected in the
information used to authenticate new logins.</p>
-
<p>The directory realm supports a variety of approaches to using
LDAP for authentication:</p>
@@ -1169,6 +1048,129 @@
</subsection>
+ <subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm">
+
+ <p>The <strong>JDBC Database Realm</strong> connects Tomcat to
+ a relational database, accessed through an appropriate JDBC driver,
+ to perform lookups of usernames, passwords, and their associated
+ roles. Because the lookup is done each time that it is required,
+ changes to the database will be immediately reflected in the
+ information used to authenticate new logins.</p>
+
+ <p>Note: The <strong>JDBC Database Realm</strong> uses a single connection
+ to the database with synchronisation to prevenbt concurrent usage. It is not
+ recommended for production usage. Use the DataSource Realm instaead.</p>
+
+ <p>A rich set of additional attributes lets you configure the required
+ connection to the underlying database, as well as the table and
+ column names used to retrieve the required information:</p>
+
+ <attributes>
+
+ <attribute name="allRolesMode" required="false">
+ <p>This attribute controls how the special role name <code>*</code> is
+ handled when processing authorization constraints in web.xml. By
+ default, the specification compliant value of <code>strict</code> is
+ used which means that the user must be assigned one of the roles defined
+ in web.xml. The alternative values are <code>authOnly</code> which means
+ that the user must be authenticated but no check is made for assigned
+ roles and <code>strictAuthOnly</code> which means that the user must be
+ authenticated and no check will be made for assigned roles unless roles
+ are defined in web.xml in which case the user must be assigned at least
+ one of those roles.</p>
+ <p>When this attribute has the value of <code>authOnly</code> or
+ <code>strictAuthOnly</code>, the <strong>roleNameCol</strong> and
+ <strong>userRoleTable</strong> attributes become optional. If those two
+ attributes are omitted, the user's roles will not be loaded by this
+ Realm.</p>
+ </attribute>
+
+ <attribute name="connectionName" required="true">
+ <p>The database username to use when establishing the JDBC
+ connection.</p>
+ </attribute>
+
+ <attribute name="connectionPassword" required="true">
+ <p>The database password to use when establishing the JDBC
+ connection.</p>
+ </attribute>
+
+ <attribute name="connectionURL" required="true">
+ <p>The connection URL to be passed to the JDBC driver when
+ establishing a database connection.</p>
+ </attribute>
+
+ <attribute name="driverName" required="true">
+ <p>Fully qualified Java class name of the JDBC driver to be
+ used to connect to the authentication database.</p>
+ </attribute>
+
+ <attribute name="roleNameCol" required="false">
+ <p>Name of the column, in the "user roles" table, which contains
+ a role name assigned to the corresponding user.</p>
+ <p>This attribute is <strong>required</strong> in majority of
+ configurations. See <strong>allRolesMode</strong> attribute for
+ a rare case when it can be omitted.</p>
+ </attribute>
+
+ <attribute name="stripRealmForGss" required="false">
+ <p>When processing users authenticated via the GSS-API, this attribute
+ controls if any "@..." is removed from the end of the user
+ name. If not specified, the default is <code>true</code>.</p>
+ </attribute>
+
+ <attribute name="transportGuaranteeRedirectStatus" required="false">
+ <p>The HTTP status code to use when the container needs to issue an HTTP
+ redirect to meet the requirements of a configured transport
+ guarantee. The provided status code is not validated. If not
+ specified, the default value of <code>302</code> is used.</p>
+ </attribute>
+
+ <attribute name="userCredCol" required="true">
+ <p>Name of the column, in the "users" table, which contains
+ the user's credentials (i.e. password). If a
+ <code>CredentialHandler</code> is specified, this component
+ will assume that the passwords have been encoded with the
+ specified algorithm. Otherwise, they will be assumed to be
+ in clear text.</p>
+ </attribute>
+
+ <attribute name="userNameCol" required="true">
+ <p>Name of the column, in the "users" and "user roles" table,
+ that contains the user's username.</p>
+ </attribute>
+
+ <attribute name="userRoleTable" required="false">
+ <p>Name of the "user roles" table, which must contain columns
+ named by the <code>userNameCol</code> and <code>roleNameCol</code>
+ attributes.</p>
+ <p>This attribute is <strong>required</strong> in majority of
+ configurations. See <strong>allRolesMode</strong> attribute for
+ a rare case when it can be omitted.</p>
+ </attribute>
+
+ <attribute name="userTable" required="true">
+ <p>Name of the "users" table, which must contain columns named
+ by the <code>userNameCol</code> and <code>userCredCol</code>
+ attributes.</p>
+ </attribute>
+
+ <attribute name="X509UsernameRetrieverClassName" required="false">
+ <p>When using X509 client certificates, this specifies the class name
+ that will be used to retrieve the user name from the certificate.
+ The class must implement the
+ <code>org.apache.catalina.realm.X509UsernameRetriever</code>
+ interface. The default is to use the certificate's SubjectDN
+ as the username.</p>
+ </attribute>
+ </attributes>
+
+ <p>See the <a href="../realm-howto.html">Container-Managed Security Guide</a> for more
+ information on setting up container managed security using the
+ JDBC Database Realm component.</p>
+
+ </subsection>
+
</section>
diff --git a/webapps/docs/host-manager-howto.xml b/webapps/docs/host-manager-howto.xml
index fb1ccfd..1530bc1 100644
--- a/webapps/docs/host-manager-howto.xml
+++ b/webapps/docs/host-manager-howto.xml
@@ -111,10 +111,9 @@ OK - Listed hosts
localhost:</source>
</p>
<p>
- Note that in case you retrieve your users using the
- <code>DataSourceRealm</code>, <code>JDBCRealm</code>, or
- <code>JNDIRealm</code> mechanism, add the appropriate role in the database
- or the directory server respectively.
+ If you are using a different realm you will need to add the necessary role
+ to the appropriate user(s) using the standard user management tools for that
+ realm.
</p>
</section>
<section name="List of Commands">
diff --git a/webapps/docs/html-host-manager-howto.xml b/webapps/docs/html-host-manager-howto.xml
index 59ea49c..6a9d464 100644
--- a/webapps/docs/html-host-manager-howto.xml
+++ b/webapps/docs/html-host-manager-howto.xml
@@ -111,10 +111,9 @@
log in with the created credentials.
</p>
<p>
- Note that in case you retrieve your users using the
- <code>DataSourceRealm</code>, <code>JDBCRealm</code>, or
- <code>JNDIRealm</code> mechanism, add the appropriate role in the database
- or the directory server respectively.
+ If you are using a different realm you will need to add the necessary role
+ to the appropriate user(s) using the standard user management tools for
+ that realm.
</p>
</section>
diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml
index aa6fe88..c70fc92 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -300,115 +300,6 @@ users.</p>
<section name="Standard Realm Implementations">
-<subsection name="JDBCRealm">
-
-<h5>Introduction</h5>
-
-<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
-<code>Realm</code> interface that looks up users in a relational database
-accessed via a JDBC driver. There is substantial configuration flexibility
-that lets you adapt to existing table and column names, as long as your
-database structure conforms to the following requirements:</p>
-<ul>
-<li>There must be a table, referenced below as the <em>users</em> table,
- that contains one row for every valid user that this <code>Realm</code>
- should recognize.</li>
-<li>The <em>users</em> table must contain at least two columns (it may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by Tomcat when the user logs in.</li>
- <li>Password to be recognized by Tomcat when the user logs in.
- This value may in cleartext or digested - see below for more
- information.</li>
- </ul></li>
-<li>There must be a table, referenced below as the <em>user roles</em> table,
- that contains one row for every valid role that is assigned to a
- particular user. It is legal for a user to have zero, one, or more than
- one valid role.</li>
-<li>The <em>user roles</em> table must contain at least two columns (it may
- contain more if your existing applications required it):
- <ul>
- <li>Username to be recognized by Tomcat (same value as is specified
- in the <em>users</em> table).</li>
- <li>Role name of a valid role associated with this user.</li>
- </ul></li>
-</ul>
-
-<h5>Quick Start</h5>
-
-<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
-<ol>
-<li>If you have not yet done so, create tables and columns in your database
- that conform to the requirements described above.</li>
-<li>Configure a database username and password for use by Tomcat, that has
- at least read only access to the tables described above. (Tomcat will
- never attempt to write to these tables.)</li>
-<li>Place a copy of the JDBC driver you will be using inside the
- <code>$CATALINA_HOME/lib</code> directory.
- Note that <strong>only</strong> JAR files are recognized!</li>
-<li>Set up a <code><Realm></code> element, as described below, in your
- <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
-<li>Restart Tomcat if it is already running.</li>
-</ol>
-
-<h5>Realm Element Attributes</h5>
-
-<p>To configure JDBCRealm, you will create a <code><Realm></code>
-element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
-as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
-JDBCRealm are defined in the <a href="config/realm.html">Realm</a> configuration
-documentation.</p>
-
-<h5>Example</h5>
-
-<p>An example SQL script to create the needed tables might look something
-like this (adapt the syntax as required for your particular database):</p>
-<source>create table users (
- user_name varchar(15) not null primary key,
- user_pass varchar(15) not null
-);
-
-create table user_roles (
- user_name varchar(15) not null,
- role_name varchar(15) not null,
- primary key (user_name, role_name)
-);</source>
-
-<p>Example <code>Realm</code> elements are included (commented out) in the
-default <code>$CATALINA_BASE/conf/server.xml</code> file. Here's an example
-for using a MySQL database called "authority", configured with the tables
-described above, and accessed with username "dbuser" and password "dbpass":</p>
-<source><![CDATA[<Realm className="org.apache.catalina.realm.JDBCRealm"
- driverName="org.gjt.mm.mysql.Driver"
- connectionURL="jdbc:mysql://localhost/authority?user=dbuser&password=dbpass"
- userTable="users" userNameCol="user_name" userCredCol="user_pass"
- userRoleTable="user_roles" roleNameCol="role_name"/>]]></source>
-
-<h5>Additional Notes</h5>
-
-<p>JDBCRealm operates according to the following rules:</p>
-<ul>
-<li>When a user attempts to access a protected resource for the first time,
- Tomcat will call the <code>authenticate()</code> method of this
- <code>Realm</code>. Thus, any changes you have made to the database
- directly (new users, changed passwords or roles, etc.) will be immediately
- reflected.</li>
-<li>Once a user has been authenticated, the user (and his or her associated
- roles) are cached within Tomcat for the duration of the user's login.
- (For FORM-based authentication, that means until the session times out or
- is invalidated; for BASIC authentication, that means until the user
- closes their browser). The cached user is <strong>not</strong> saved and
- restored across sessions serialisations. Any changes to the database
- information for an already authenticated user will <strong>not</strong> be
- reflected until the next time that user logs on again.</li>
-<li>Administering the information in the <em>users</em> and <em>user roles</em>
- table is the responsibility of your own applications. Tomcat does not
- provide any built-in capabilities to maintain users and roles.</li>
-</ul>
-
-</subsection>
-
-
<subsection name="DataSourceRealm">
<h5>Introduction</h5>
@@ -1220,6 +1111,114 @@ functionality to a UserDatabase Realm.</p>
</subsection>
+<subsection name="JDBCRealm">
+
+<h5>Introduction</h5>
+
+<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
+<code>Realm</code> interface that looks up users in a relational database
+accessed via a JDBC driver. There is substantial configuration flexibility
+that lets you adapt to existing table and column names, as long as your
+database structure conforms to the following requirements:</p>
+<ul>
+<li>There must be a table, referenced below as the <em>users</em> table,
+ that contains one row for every valid user that this <code>Realm</code>
+ should recognize.</li>
+<li>The <em>users</em> table must contain at least two columns (it may
+ contain more if your existing applications required it):
+ <ul>
+ <li>Username to be recognized by Tomcat when the user logs in.</li>
+ <li>Password to be recognized by Tomcat when the user logs in.
+ This value may in cleartext or digested - see below for more
+ information.</li>
+ </ul></li>
+<li>There must be a table, referenced below as the <em>user roles</em> table,
+ that contains one row for every valid role that is assigned to a
+ particular user. It is legal for a user to have zero, one, or more than
+ one valid role.</li>
+<li>The <em>user roles</em> table must contain at least two columns (it may
+ contain more if your existing applications required it):
+ <ul>
+ <li>Username to be recognized by Tomcat (same value as is specified
+ in the <em>users</em> table).</li>
+ <li>Role name of a valid role associated with this user.</li>
+ </ul></li>
+</ul>
+
+<h5>Quick Start</h5>
+
+<p>To set up Tomcat to use JDBCRealm, you will need to follow these steps:</p>
+<ol>
+<li>If you have not yet done so, create tables and columns in your database
+ that conform to the requirements described above.</li>
+<li>Configure a database username and password for use by Tomcat, that has
+ at least read only access to the tables described above. (Tomcat will
+ never attempt to write to these tables.)</li>
+<li>Place a copy of the JDBC driver you will be using inside the
+ <code>$CATALINA_HOME/lib</code> directory.
+ Note that <strong>only</strong> JAR files are recognized!</li>
+<li>Set up a <code><Realm></code> element, as described below, in your
+ <code>$CATALINA_BASE/conf/server.xml</code> file.</li>
+<li>Restart Tomcat if it is already running.</li>
+</ol>
+
+<h5>Realm Element Attributes</h5>
+
+<p>To configure JDBCRealm, you will create a <code><Realm></code>
+element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> file,
+as described <a href="#Configuring_a_Realm">above</a>. The attributes for the
+JDBCRealm are defined in the <a href="config/realm.html">Realm</a> configuration
+documentation.</p>
+
+<h5>Example</h5>
+
+<p>An example SQL script to create the needed tables might look something
+like this (adapt the syntax as required for your particular database):</p>
+<source>create table users (
+ user_name varchar(15) not null primary key,
+ user_pass varchar(15) not null
+);
+
+create table user_roles (
+ user_name varchar(15) not null,
+ role_name varchar(15) not null,
+ primary key (user_name, role_name)
+);</source>
+
+<p>Example <code>Realm</code> elements are included (commented out) in the
+default <code>$CATALINA_BASE/conf/server.xml</code> file. Here's an example
+for using a MySQL database called "authority", configured with the tables
+described above, and accessed with username "dbuser" and password "dbpass":</p>
+<source><![CDATA[<Realm className="org.apache.catalina.realm.JDBCRealm"
+ driverName="org.gjt.mm.mysql.Driver"
+ connectionURL="jdbc:mysql://localhost/authority?user=dbuser&password=dbpass"
+ userTable="users" userNameCol="user_name" userCredCol="user_pass"
+ userRoleTable="user_roles" roleNameCol="role_name"/>]]></source>
+
+<h5>Additional Notes</h5>
+
+<p>JDBCRealm operates according to the following rules:</p>
+<ul>
+<li>When a user attempts to access a protected resource for the first time,
+ Tomcat will call the <code>authenticate()</code> method of this
+ <code>Realm</code>. Thus, any changes you have made to the database
+ directly (new users, changed passwords or roles, etc.) will be immediately
+ reflected.</li>
+<li>Once a user has been authenticated, the user (and his or her associated
+ roles) are cached within Tomcat for the duration of the user's login.
+ (For FORM-based authentication, that means until the session times out or
+ is invalidated; for BASIC authentication, that means until the user
+ closes their browser). The cached user is <strong>not</strong> saved and
+ restored across sessions serialisations. Any changes to the database
+ information for an already authenticated user will <strong>not</strong> be
+ reflected until the next time that user logs on again.</li>
+<li>Administering the information in the <em>users</em> and <em>user roles</em>
+ table is the responsibility of your own applications. Tomcat does not
+ provide any built-in capabilities to maintain users and roles.</li>
+</ul>
+
+</subsection>
+
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org
[tomcat] 02/02: Deprecate JDBCRealm
Posted by ma...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 9.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
commit b2a97a84eab79cef12ef24b3e320a528e5d75631
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Tue Sep 15 14:44:40 2020 +0100
Deprecate JDBCRealm
---
java/org/apache/catalina/mbeans/MBeanFactory.java | 7 +++++--
java/org/apache/catalina/mbeans/mbeans-descriptors.xml | 2 +-
java/org/apache/catalina/realm/DataSourceRealm.java | 2 +-
java/org/apache/catalina/realm/JDBCRealm.java | 4 ++++
webapps/docs/changelog.xml | 3 +++
webapps/docs/config/realm.xml | 3 +++
webapps/docs/realm-howto.xml | 3 +++
7 files changed, 20 insertions(+), 4 deletions(-)
diff --git a/java/org/apache/catalina/mbeans/MBeanFactory.java b/java/org/apache/catalina/mbeans/MBeanFactory.java
index 050031b..bf2970e 100644
--- a/java/org/apache/catalina/mbeans/MBeanFactory.java
+++ b/java/org/apache/catalina/mbeans/MBeanFactory.java
@@ -38,7 +38,6 @@ import org.apache.catalina.core.StandardHost;
import org.apache.catalina.core.StandardService;
import org.apache.catalina.loader.WebappLoader;
import org.apache.catalina.realm.DataSourceRealm;
-import org.apache.catalina.realm.JDBCRealm;
import org.apache.catalina.realm.JNDIRealm;
import org.apache.catalina.realm.MemoryRealm;
import org.apache.catalina.realm.UserDatabaseRealm;
@@ -334,13 +333,17 @@ public class MBeanFactory {
* @return the object name of the created realm
*
* @exception Exception if an MBean cannot be created or registered
+ *
+ * @deprecated This method will be removed in Tomcat 10. Use a
+ * DataSourceRealm instead.
*/
+ @Deprecated
public String createJDBCRealm(String parent, String driverName,
String connectionName, String connectionPassword, String connectionURL)
throws Exception {
// Create a new JDBCRealm instance
- JDBCRealm realm = new JDBCRealm();
+ org.apache.catalina.realm.JDBCRealm realm = new org.apache.catalina.realm.JDBCRealm();
realm.setDriverName(driverName);
realm.setConnectionName(connectionName);
realm.setConnectionPassword(connectionPassword);
diff --git a/java/org/apache/catalina/mbeans/mbeans-descriptors.xml b/java/org/apache/catalina/mbeans/mbeans-descriptors.xml
index 8af469b..913830f 100644
--- a/java/org/apache/catalina/mbeans/mbeans-descriptors.xml
+++ b/java/org/apache/catalina/mbeans/mbeans-descriptors.xml
@@ -106,7 +106,7 @@
</operation>
<operation name="createJDBCRealm"
- description="Create a new JDBC Realm"
+ description="Create a new JDBC Realm (deprecated - will be removed in Tomcat 10)"
impact="ACTION"
returnType="java.lang.String">
<parameter name="parent"
diff --git a/java/org/apache/catalina/realm/DataSourceRealm.java b/java/org/apache/catalina/realm/DataSourceRealm.java
index c638967..8765a85 100644
--- a/java/org/apache/catalina/realm/DataSourceRealm.java
+++ b/java/org/apache/catalina/realm/DataSourceRealm.java
@@ -33,7 +33,7 @@ import org.apache.naming.ContextBindings;
/**
*
* Implementation of <b>Realm</b> that works with any JDBC JNDI DataSource.
-* See the JDBCRealm.howto for more details on how to set up the database and
+* See the Realm How-To for more details on how to set up the database and
* for configuration options.
*
* @author Glenn L. Nielsen
diff --git a/java/org/apache/catalina/realm/JDBCRealm.java b/java/org/apache/catalina/realm/JDBCRealm.java
index f27d9ac..01cd54f 100644
--- a/java/org/apache/catalina/realm/JDBCRealm.java
+++ b/java/org/apache/catalina/realm/JDBCRealm.java
@@ -47,7 +47,11 @@ import org.apache.tomcat.util.ExceptionUtils;
* @author Craig R. McClanahan
* @author Carson McDonald
* @author Ignacio Ortega
+*
+* @deprecated Will be removed in Tomcat 10 onwards. Use the DataSourceRealm
+* instead.
*/
+@Deprecated
public class JDBCRealm
extends RealmBase {
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 9a6e52c..9151610 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -55,6 +55,9 @@
Fix race condition when saving and recycling session in
<code>PersistentValve</code>. (kfujino)
</fix>
+ <update>
+ Deprecate the JDBCRealm. (markt)
+ </update>
</changelog>
</subsection>
<subsection name="Coyote">
diff --git a/webapps/docs/config/realm.xml b/webapps/docs/config/realm.xml
index 44fbd2d..247ea64 100644
--- a/webapps/docs/config/realm.xml
+++ b/webapps/docs/config/realm.xml
@@ -1050,6 +1050,9 @@
<subsection name="JDBC Database Realm - org.apache.catalina.realm.JDBCRealm">
+ <p><strong>The JDBC Database Realm has been deprecated and will be removed
+ in Tomcat 10 onwards. Use the DataSourceRealm instead.</strong></p>
+
<p>The <strong>JDBC Database Realm</strong> connects Tomcat to
a relational database, accessed through an appropriate JDBC driver,
to perform lookups of usernames, passwords, and their associated
diff --git a/webapps/docs/realm-howto.xml b/webapps/docs/realm-howto.xml
index c70fc92..adad6aa 100644
--- a/webapps/docs/realm-howto.xml
+++ b/webapps/docs/realm-howto.xml
@@ -1115,6 +1115,9 @@ functionality to a UserDatabase Realm.</p>
<h5>Introduction</h5>
+<p><strong>The JDBC Database Realm has been deprecated and will be removed
+in Tomcat 10 onwards. Use the DataSourceRealm instead.</strong></p>
+
<p><strong>JDBCRealm</strong> is an implementation of the Tomcat
<code>Realm</code> interface that looks up users in a relational database
accessed via a JDBC driver. There is substantial configuration flexibility
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org