TomcatPrincipal (Apache Tomcat 9.0.111 API Documentation)
Description: declaration: package: org.apache.catalina, interface: TomcatPrincipal

# Interface TomcatPrincipal

All Superinterfaces:
  `Principal`

All Known Implementing Classes:
  `GenericPrincipal, UserDatabaseRealm.UserDatabasePrincipal`

public interface TomcatPrincipal extends Principal
Defines additional methods implemented by `Principal`s created by Tomcat's standard `Realm` implementations.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default Object`
  `getAttribute(String name)`
  Returns the value of the named attribute as an `Object`, or `null` if no attribute of the given name exists, or if `null` has been specified as the attribute's name.
  `default Enumeration<String>`
  `getAttributeNames()`
  Returns an `Enumeration` containing the names of the attributes available to this Principal.
  `GSSCredential`
  `getGssCredential()`
  `Principal`
  `getUserPrincipal()`
  `void`
  `logout()`
  Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext.

  ### Methods inherited from interface Principal

  `equals, getName, hashCode, implies, toString`

- ## Method Details

  - ### getUserPrincipal

    Principal getUserPrincipal()
    Returns:
      The authenticated Principal to be exposed to applications.

  - ### getGssCredential

    GSSCredential getGssCredential()
    Returns:
      The user's delegated credentials.

  - ### logout

    void logout() throws Exception
    Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext. May in the future be extended to cover other logout requirements.
    Throws:
      `Exception` - If something goes wrong with the logout. Uses Exception to allow for future expansion of this method to cover other logout mechanisms that might throw a different exception to LoginContext

  - ### getAttribute

    default Object getAttribute(String name)
    Returns the value of the named attribute as an `Object`, or `null` if no attribute of the given name exists, or if `null` has been specified as the attribute's name.

    Only the servlet container may set attributes to make available custom information about a Principal or the user it represents.

    The purpose of the method is to implement read only access to attributes which may be stored in the `Realm` implementation's backend due to its inherent design.

    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 `Principal`, 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 `Principal`.

    `Realm` implementations that are provided by Tomcat will not provide complex type mapping, but will in most cases always return a result as a `String` object which may need custom decoding.

    `Realm` implementations that are provided by Tomcat will not provide an implementation for this facility unless it is inherent to the storage backend of the `Realm` itself and metadata is available without additional user intervention or configuration.

    Parameters:
      `name` - a `String` specifying the name of the attribute
    Returns:
      an `Object` containing the value of the attribute, or `null` if the attribute does not exist, or if `null` has been specified as the attribute's name

  - ### getAttributeNames

    default Enumeration<String> getAttributeNames()
    Returns an `Enumeration` containing the names of the attributes available to this Principal. This method returns an empty `Enumeration` if the Principal has no attributes available to it.
    Returns:
      an `Enumeration` of strings containing the names of the Principal's attributes