Package org.apache.catalina.realm

## Class GenericPrincipal

- java.lang.Object
- - org.apache.catalina.realm.GenericPrincipal

- All Implemented Interfaces:
    `java.io.Serializable`, `java.security.Principal`, `TomcatPrincipal`
  Direct Known Subclasses:
    `UserDatabaseRealm.UserDatabasePrincipal`

      public class GenericPrincipal
      extends java.lang.Object
      implements TomcatPrincipal, java.io.Serializable

  Generic implementation of java.security.Principal that is available for use by `Realm` implementations.
  Author:
    Craig R. McClanahan
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected java.util.Map<java.lang.String,​java.lang.Object>` | `attributes` | The additional attributes associated with this Principal.
    `protected org.ietf.jgss.GSSCredential` | `gssCredential` | The user's delegated credentials.
    `protected javax.security.auth.login.LoginContext` | `loginContext` | The JAAS LoginContext, if any, used to authenticate this Principal.
    `protected java.lang.String` | `name` | The username of the user represented by this Principal.
    `protected java.lang.String[]` | `roles` | The set of roles associated with this user.
    `protected java.security.Principal` | `userPrincipal` | The authenticated Principal to be exposed to applications.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GenericPrincipal​(java.lang.String name)` | Construct a new Principal, associated with the specified Realm, for the specified username, with no roles.
    `GenericPrincipal​(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles)` | Deprecated. This method will be removed in Tomcat 11 onwards
    `GenericPrincipal​(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal)` | Deprecated. This method will be removed in Tomcat 11 onwards
    `GenericPrincipal​(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal, javax.security.auth.login.LoginContext loginContext)` | Deprecated. This method will be removed in Tomcat 11 onwards
    `GenericPrincipal​(java.lang.String name, java.lang.String password, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal, javax.security.auth.login.LoginContext loginContext, org.ietf.jgss.GSSCredential gssCredential)` | Deprecated. This method will be removed in Tomcat 11 onwards
    `GenericPrincipal​(java.lang.String name, java.util.List<java.lang.String> roles)` | Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
    `GenericPrincipal​(java.lang.String name, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal)` | Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
    `GenericPrincipal​(java.lang.String name, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal, javax.security.auth.login.LoginContext loginContext)` | Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
    `GenericPrincipal​(java.lang.String name, java.util.List<java.lang.String> roles, java.security.Principal userPrincipal, javax.security.auth.login.LoginContext loginContext, org.ietf.jgss.GSSCredential gssCredential, java.util.Map<java.lang.String,​java.lang.Object> attributes)` | Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `java.lang.Object` | `getAttribute​(java.lang.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.
    `java.util.Enumeration<java.lang.String>` | `getAttributeNames()` | Returns an `Enumeration` containing the names of the attributes available to this Principal.
    `org.ietf.jgss.GSSCredential` | `getGssCredential()` |
    `java.lang.String` | `getName()` |
    `java.lang.String[]` | `getRoles()` |
    `java.security.Principal` | `getUserPrincipal()` |
    `boolean` | `hasRole​(java.lang.String role)` | Does the user represented by this Principal possess the specified role?
    `void` | `logout()` | Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext.
    `protected void` | `setGssCredential​(org.ietf.jgss.GSSCredential gssCredential)` |
    `java.lang.String` | `toString()` | Return a String representation of this object, which exposes only information that should be public.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface java.security.Principal

      `equals, hashCode, implies`

- - ### Field Detail

    - #### name

          protected final java.lang.String name

      The username of the user represented by this Principal.

    - #### roles

          protected final java.lang.String[] roles

      The set of roles associated with this user.

    - #### userPrincipal

          protected final java.security.Principal userPrincipal

      The authenticated Principal to be exposed to applications.

    - #### loginContext

          protected final transient javax.security.auth.login.LoginContext loginContext

      The JAAS LoginContext, if any, used to authenticate this Principal. Kept so we can call logout().

    - #### gssCredential

          protected transient org.ietf.jgss.GSSCredential gssCredential

      The user's delegated credentials.

    - #### attributes

          protected final java.util.Map<java.lang.String,​java.lang.Object> attributes

      The additional attributes associated with this Principal.

  - ### Constructor Detail

    - #### GenericPrincipal

          public GenericPrincipal​(java.lang.String name)

      Construct a new Principal, associated with the specified Realm, for the specified username, with no roles.
      Parameters:
        `name` - The username of the user represented by this Principal

    - #### GenericPrincipal

          public GenericPrincipal​(java.lang.String name,
                                  java.util.List<java.lang.String> roles)

      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `roles` - List of roles (must be Strings) possessed by this user

    - #### GenericPrincipal

          @Deprecated
          public GenericPrincipal​(java.lang.String name,
                                  java.lang.String password,
                                  java.util.List<java.lang.String> roles)

      Deprecated.
      This method will be removed in Tomcat 11 onwards
      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `password` - Unused
        `roles` - List of roles (must be Strings) possessed by this user

    - #### GenericPrincipal

          public GenericPrincipal​(java.lang.String name,
                                  java.util.List<java.lang.String> roles,
                                  java.security.Principal userPrincipal)

      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `roles` - List of roles (must be Strings) possessed by this user
        `userPrincipal` - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned

    - #### GenericPrincipal

          @Deprecated
          public GenericPrincipal​(java.lang.String name,
                                  java.lang.String password,
                                  java.util.List<java.lang.String> roles,
                                  java.security.Principal userPrincipal)

      Deprecated.
      This method will be removed in Tomcat 11 onwards
      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `password` - Unused
        `roles` - List of roles (must be Strings) possessed by this user
        `userPrincipal` - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned

    - #### GenericPrincipal

          public GenericPrincipal​(java.lang.String name,
                                  java.util.List<java.lang.String> roles,
                                  java.security.Principal userPrincipal,
                                  javax.security.auth.login.LoginContext loginContext)

      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `roles` - List of roles (must be Strings) possessed by this user
        `userPrincipal` - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned
        `loginContext` - - If provided, this will be used to log out the user at the appropriate time

    - #### GenericPrincipal

          @Deprecated
          public GenericPrincipal​(java.lang.String name,
                                  java.lang.String password,
                                  java.util.List<java.lang.String> roles,
                                  java.security.Principal userPrincipal,
                                  javax.security.auth.login.LoginContext loginContext)

      Deprecated.
      This method will be removed in Tomcat 11 onwards
      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `password` - Unused
        `roles` - List of roles (must be Strings) possessed by this user
        `userPrincipal` - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned
        `loginContext` - - If provided, this will be used to log out the user at the appropriate time

    - #### GenericPrincipal

          public GenericPrincipal​(java.lang.String name,
                                  java.util.List<java.lang.String> roles,
                                  java.security.Principal userPrincipal,
                                  javax.security.auth.login.LoginContext loginContext,
                                  org.ietf.jgss.GSSCredential gssCredential,
                                  java.util.Map<java.lang.String,​java.lang.Object> attributes)

      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `roles` - List of roles (must be Strings) possessed by this user
        `userPrincipal` - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned
        `loginContext` - - If provided, this will be used to log out the user at the appropriate time
        `gssCredential` - - If provided, the user's delegated credentials
        `attributes` - - If provided, additional attributes associated with this Principal

    - #### GenericPrincipal

          @Deprecated
          public GenericPrincipal​(java.lang.String name,
                                  java.lang.String password,
                                  java.util.List<java.lang.String> roles,
                                  java.security.Principal userPrincipal,
                                  javax.security.auth.login.LoginContext loginContext,
                                  org.ietf.jgss.GSSCredential gssCredential)

      Deprecated.
      This method will be removed in Tomcat 11 onwards
      Construct a new Principal, associated with the specified Realm, for the specified username, with the specified role names (as Strings).
      Parameters:
        `name` - The username of the user represented by this Principal
        `password` - Unused
        `roles` - List of roles (must be Strings) possessed by this user
        `userPrincipal` - - the principal to be returned from the request getUserPrincipal call if not null; if null, this will be returned
        `loginContext` - - If provided, this will be used to log out the user at the appropriate time
        `gssCredential` - - If provided, the user's delegated credentials

  - ### Method Detail

    - #### getName

          public java.lang.String getName()

      Specified by:
        `getName` in interface `java.security.Principal`

    - #### getRoles

          public java.lang.String[] getRoles()

    - #### getUserPrincipal

          public java.security.Principal getUserPrincipal()

      Specified by:
        `getUserPrincipal` in interface `TomcatPrincipal`
      Returns:
        The authenticated Principal to be exposed to applications.

    - #### getGssCredential

          public org.ietf.jgss.GSSCredential getGssCredential()

      Specified by:
        `getGssCredential` in interface `TomcatPrincipal`
      Returns:
        The user's delegated credentials.

    - #### setGssCredential

          protected void setGssCredential​(org.ietf.jgss.GSSCredential gssCredential)

    - #### hasRole

          public boolean hasRole​(java.lang.String role)

      Does the user represented by this Principal possess the specified role?
      Parameters:
        `role` - Role to be tested
      Returns:
        `true` if this Principal has been assigned the given role, otherwise `false`

    - #### toString

          public java.lang.String toString()

      Return a String representation of this object, which exposes only information that should be public.
      Specified by:
        `toString` in interface `java.security.Principal`
      Overrides:
        `toString` in class `java.lang.Object`

    - #### logout

          public void logout()
                      throws java.lang.Exception

      Description copied from interface: `TomcatPrincipal`
      Calls logout, if necessary, on any associated JAASLoginContext and/or GSSContext. May in the future be extended to cover other logout requirements.
      Specified by:
        `logout` in interface `TomcatPrincipal`
      Throws:
        `java.lang.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

          public java.lang.Object getAttribute​(java.lang.String name)

      Description copied from interface: `TomcatPrincipal`
      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.

      Specified by:
        `getAttribute` in interface `TomcatPrincipal`
      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

          public java.util.Enumeration<java.lang.String> getAttributeNames()

      Description copied from interface: `TomcatPrincipal`
      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.
      Specified by:
        `getAttributeNames` in interface `TomcatPrincipal`
      Returns:
        an `Enumeration` of strings containing the names of the Principal's attributes