[tomcat] branch main updated: Add agreed upon javadoc

[re...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

remm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tomcat.git


The following commit(s) were added to refs/heads/main by this push:
     new 2d076f5  Add agreed upon javadoc
2d076f5 is described below

commit 2d076f5136097f710e6e8dc80816c6841333e897
Author: remm <re...@apache.org>
AuthorDate: Mon Feb 14 00:01:29 2022 +0100

    Add agreed upon javadoc
---
 java/org/apache/catalina/TomcatPrincipal.java | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/java/org/apache/catalina/TomcatPrincipal.java b/java/org/apache/catalina/TomcatPrincipal.java
index 515576a..3d69f0b 100644
--- a/java/org/apache/catalina/TomcatPrincipal.java
+++ b/java/org/apache/catalina/TomcatPrincipal.java
@@ -56,6 +56,27 @@ public interface TomcatPrincipal extends Principal {
      * <p>
      * Only the servlet container may set attributes to make available custom
      * information about a Principal or the user it represents.
+     * <p>
+     * The purpose of the method is to implement read only access to attributes
+     * which may be stored in the <code>Realm</code> implementation's backend
+     * due to its inherent design.
+     * <p>
+     * As using this method from application code will make it non portable to
+     * other EE compliant containers, it is advised this should never be used
+     * as an object storage facility tied to the <code>Principal</code>, but
+     * rather as simple extra additional metadata. It is recommended that a
+     * container level object is used to further process the attributes that
+     * may be associated with the <code>Principal</code>.
+     * <p>
+     * <code>Realm</code> implementations that are provided by Tomcat will
+     * not provide complex type mapping, but will in most cases always
+     * return a result as a <code>String</code> object which may need custom
+     * decoding.
+     * <p>
+     * <code>Realm</code> implementations that are provided by Tomcat will
+     * not provide an implementation for this facility unless it is inherent
+     * to the storage backend of the <code>Realm</code> itself and metadata
+     * is available without additional user intervention or configuration.
      *
      * @param name a <code>String</code> specifying the name of the attribute
      * @return an <code>Object</code> containing the value of the attribute, or

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org