This is an automated email from the ASF dual-hosted git repository.
remm pushed a commit to branch 10.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/10.0.x by this push:
new 480c548 Add agreed upon javadoc
480c548 is described below
commit 480c5488b3ca1642d06ccd32ac7ff7d82a130e49
Author: remm <r...@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 b74f187..08c766a 100644
--- a/java/org/apache/catalina/TomcatPrincipal.java
+++ b/java/org/apache/catalina/TomcatPrincipal.java
@@ -57,6 +57,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-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
