Module java.base
Package javax.security.auth

Class Subject

java.lang.Object
javax.security.auth.Subject
所有已实现的接口:
Serializable
public final class Subject extends Object implements Serializable

Subject表示单个实体（例如人员）的相关信息分组。这些信息包括主体的身份以及其与安全相关的属性（例如密码和加密密钥）。

主体可能具有多个身份。每个身份在Subject内表示为Principal。Principal简单地将名称绑定到Subject。例如，一个作为人员Alice的Subject可能有两个Principal：一个将她驾驶执照上的名称“Alice Bar”绑定到Subject，另一个将她学生证件上的号码“999-99-9999”绑定到Subject。尽管每个Principal具有不同的名称，但两个Principal都指向同一个Subject。

Subject还可以拥有与安全相关的属性，称为凭据。需要特殊保护的敏感凭据，例如私有加密密钥，存储在私有凭据Set中。用于共享的凭据，例如公钥证书或Kerberos服务器票证，存储在公共凭据Set中。访问和修改不同凭据集合需要不同的权限。

要检索与Subject关联的所有Principal，调用getPrincipals方法。要检索属于Subject的所有公共或私有凭据，分别调用getPublicCredentials方法或getPrivateCredentials方法。要修改返回的Principal和凭据Set，请使用Set类中定义的方法。例如：

      Subject subject;
      Principal principal;
      Object credential;

      // 向Subject添加Principal和凭据
      subject.getPrincipals().add(principal);
      subject.getPublicCredentials().add(credential);

这个Subject类实现了Serializable。虽然与Subject关联的Principal被序列化，但与Subject关联的凭据没有被序列化。请注意，java.security.Principal类没有实现Serializable。因此，与Subjects关联的所有具体Principal实现都必须实现Serializable。

自从:
1.4
参见:

  • Constructor Summary

    Constructors
    Constructor
    Description
    Subject()
    创建一个具有空的Principal集合和空的公共和私有凭据集合的Subject实例。
    Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)
    创建一个具有Principal和凭据的Subject实例。

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> T
    callAs(Subject subject, Callable<T> action)
    使用subject作为当前主体执行Callable。
    static Subject
    current()
    返回当前主体。
    static <T> T
    doAs(Subject subject, PrivilegedAction<T> action)
    已弃用，将来会移除: 此API元素可能在将来的版本中被移除。
    此方法依赖于AccessControlContext，与Security Manager一起，已被弃用并可能在将来的版本中被移除。
    static <T> T
    doAs(Subject subject, PrivilegedExceptionAction<T> action)
    已弃用，将来会移除: 此API元素可能在将来的版本中被移除。
    此方法依赖于AccessControlContext，与Security Manager一起，已被弃用并可能在将来的版本中被移除。
    static <T> T
    doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
    已弃用，将来会移除: 此API元素可能在将来的版本中被移除。
    此方法仅在与Security Manager一起使用时有用，Security Manager已被弃用并可能在将来的版本中被移除。
    static <T> T
    doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)
    已弃用，将来会移除: 此API元素可能在将来的版本中被移除。
    此方法仅在与Security Manager一起使用时有用，Security Manager已被弃用并可能在将来的版本中被移除。
    boolean
    equals(Object o)
    将指定的对象与此Subject进行比较以确定是否相等。
    Set<Principal>
    getPrincipals()
    返回与此Subject关联的Principal集合。
    <T extends Principal>
    Set<T>
    getPrincipals(Class<T> c)
    返回与此Subject关联的是指定Class的实例或子类的Principal集合。
    Set<Object>
    getPrivateCredentials()
    返回此Subject持有的私有凭据集合。
    <T> Set<T>
    getPrivateCredentials(Class<T> c)
    返回与此Subject关联的是指定Class的实例或子类的私有凭据集合。
    Set<Object>
    getPublicCredentials()
    返回此Subject持有的公共凭据集合。
    <T> Set<T>
    getPublicCredentials(Class<T> c)
    返回与此Subject关联的是指定Class的实例或子类的公共凭据集合。
    static Subject
    getSubject(AccessControlContext acc)
    已弃用，将来会移除: 此API元素可能在将来的版本中被移除。
    此方法依赖于AccessControlContext，与Security Manager一起，已被弃用并可能在将来的版本中被移除。
    int
    hashCode()
    返回此Subject的哈希码。
    boolean
    isReadOnly()
    查询此Subject是否为只读。
    void
    setReadOnly()
    将此Subject设置为只读。
    String
    toString()
    返回此Subject的字符串表示形式。

    Methods declared in class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Subject

      public Subject()
      创建一个具有空的Principal集合和空的公共和私有凭据集合的Subject实例。

      新构建的集合在允许后续修改之前会检查此Subject是否已设置为只读。新创建的集合还通过确保调用者具有足够的权限来防止非法修改。这些集合还禁止空元素，尝试添加、查询或删除空元素将导致NullPointerException。

      要修改Principal集合，调用者必须具有AuthPermission("modifyPrincipals")。要修改公共凭据集合，调用者必须具有AuthPermission("modifyPublicCredentials")。要修改私有凭据集合，调用者必须具有AuthPermission("modifyPrivateCredentials")。

    • Subject

      public Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)
      创建一个具有Principal和凭据的Subject实例。

      从指定的集合中的Principal和凭据被复制到新构建的集合中。这些新创建的集合在允许后续修改之前会检查此Subject是否已设置为只读。新创建的集合还通过确保调用者具有足够的权限来防止非法修改。这些集合还禁止空元素，尝试添加、查询或删除空元素将导致NullPointerException。

      要修改Principal集合，调用者必须具有AuthPermission("modifyPrincipals")。要修改公共凭据集合，调用者必须具有AuthPermission("modifyPublicCredentials")。要修改私有凭据集合，调用者必须具有AuthPermission("modifyPrivateCredentials")。

      参数:
      readOnly - 如果Subject应为只读，则为true；否则为false。
      principals - 要与此Subject关联的Principal集合。
      pubCredentials - 要与此Subject关联的公共凭据集合。
      privCredentials - 要与此Subject关联的私有凭据集合。
      抛出:
      NullPointerException - 如果指定的principals、pubCredentials或privCredentials为null，或这三个集合中存在空值。

  • Method Details

    • setReadOnly

      public void setReadOnly()
      将此Subject设置为只读。

      对此主体的Principal集合和凭据集合的修改（添加和删除）将被禁止。仍然允许对此主体凭据的destroy操作。

      后续尝试修改主体的Principal和凭据集合将导致抛出IllegalStateException。此外，一旦Subject为只读，就无法将其重新设置为可写。

      抛出:
      SecurityException - 如果安装了安全管理器并且调用者没有AuthPermission("setReadOnly")权限将此Subject设置为只读。

    • isReadOnly

      public boolean isReadOnly()
      查询此Subject是否为只读。
      返回:
      如果此Subject为只读，则为true；否则为false。

    • getSubject

      @Deprecated(since="17", forRemoval=true) public static Subject getSubject(AccessControlContext acc)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method depends on AccessControlContext which, in conjunction with the Security Manager, is deprecated and subject to removal in a future release. However, obtaining a Subject is useful independent of the Security Manager. Thus, a replacement API named current() has been added which can be used to obtain the current subject.
      获取与提供的AccessControlContext关联的Subject。

      AccessControlContext可能包含许多主体（来自嵌套的doAs调用）。在这种情况下，将返回与AccessControlContext最近关联的Subject。

      参数:
      acc - 从中检索Subject的AccessControlContext。
      返回:
      与提供的AccessControlContext关联的Subject，如果没有与提供的AccessControlContext关联的Subject，则返回null。
      抛出:
      SecurityException - 如果安装了安全管理器并且调用者没有AuthPermission("getSubject")权限来获取Subject。
      NullPointerException - 如果提供的AccessControlContext为null。

    • current

      public static Subject current()
      返回当前主体。

      当前主体由callAs(subject, action)方法安装。当调用callAs(subject, action)时，action将以subject作为其当前主体执行，可以通过此方法检索。在action完成后，当前主体将重置为其先前的值。在第一次调用callAs()之前，当前主体为null。

      实现注意:
      此方法返回与Subject.getSubject(AccessController.getContext())相同的值。这保留了仍可能调用doAs的代码的兼容性，该代码将主体安装在AccessControlContext中。此行为可能会在将来的版本中更改。
      返回:
      当前主体，如果未安装当前主体或当前主体设置为null，则返回null。
      自版本:
      18
      参见:

    • callAs

      public static <T> T callAs(Subject subject, Callable<T> action) throws CompletionException
      以特定Subject执行Callable。
      实现注意:
      此方法调用Subject.doAs(subject, altAction)，该方法将主体存储在新的AccessControlContext中，其中altAction.run()等同于action.call()，并且抛出的异常已修改以匹配此方法的规范。这保留了仍可能调用getSubject(AccessControlContext)的代码的兼容性，该代码从AccessControlContext中检索主体。此行为可能会在将来的版本中更改。
      类型参数:
      T - action的call方法返回的值的类型
      参数:
      subject - 指定action将作为其运行的Subject。此参数可能为null。
      action - 作为其当前主体运行的代码。不得为null。
      返回:
      action的call方法返回的值
      抛出:
      NullPointerException - 如果action为null
      CompletionException - 如果action.call()抛出异常。 CompletionException的原因设置为action.call()抛出的异常。
      自版本:
      18
      参见:

    • doAs

      @Deprecated(since="18", forRemoval=true) public static <T> T doAs(Subject subject, PrivilegedAction<T> action)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method depends on AccessControlContext which, in conjunction with the Security Manager, is deprecated and subject to removal in a future release. However, performing work as a Subject is useful independent of the Security Manager. Thus, a replacement API named callAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>) has been added which can be used to perform the same work.
      作为特定Subject执行工作。

      此方法首先通过AccessController.getContext检索当前线程的AccessControlContext，然后使用检索到的上下文以及使用提供的Subject构造的新SubjectDomainCombiner实例化一个新的AccessControlContext。最后，此方法调用AccessController.doPrivileged，将提供的PrivilegedAction以及新构造的AccessControlContext传递给它。

      类型参数:
      T - PrivilegedAction的run方法返回的值的类型。
      参数:
      subject - 指定action将作为其运行的Subject。此参数可能为null。
      action - 作为指定Subject运行的代码。
      返回:
      PrivilegedAction的run方法返回的值。
      抛出:
      NullPointerException - 如果PrivilegedAction为null。
      SecurityException - 如果安装了安全管理器并且调用者没有AuthPermission("doAs")权限来调用此方法。

    • doAs

      @Deprecated(since="18", forRemoval=true) public static <T> T doAs(Subject subject, PrivilegedExceptionAction<T> action) throws PrivilegedActionException
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method depends on AccessControlContext which, in conjunction with the Security Manager, is deprecated and subject to removal in a future release. However, performing work as a Subject is useful independent of the Security Manager. Thus, a replacement API named callAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>) has been added which can be used to perform the same work.
      作为特定Subject执行工作。

      此方法首先通过AccessController.getContext检索当前线程的AccessControlContext，然后使用检索到的上下文以及使用提供的Subject构造的新SubjectDomainCombiner实例化一个新的AccessControlContext。最后，此方法调用AccessController.doPrivileged，将提供的PrivilegedExceptionAction以及新构造的AccessControlContext传递给它。

      类型参数:
      T - PrivilegedExceptionAction的run方法返回的值的类型。
      参数:
      subject - 指定action将作为其运行的Subject。此参数可能为null。
      action - 作为指定Subject运行的代码。
      返回:
      PrivilegedExceptionAction的run方法返回的值。
      抛出:
      PrivilegedActionException - 如果PrivilegedExceptionAction.run方法抛出已检查异常。
      NullPointerException - 如果指定的PrivilegedExceptionAction为null。
      SecurityException - 如果安装了安全管理器并且调用者没有AuthPermission("doAs")权限来调用此方法。

    • doAsPrivileged

      @Deprecated(since="17", forRemoval=true) public static <T> T doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method is only useful in conjunction with the Security Manager, which is deprecated and subject to removal in a future release. Consequently, this method is also deprecated and subject to removal. There is no replacement for the Security Manager or this method.
      作为特定Subject执行特权工作。

      此方法与Subject.doAs完全相同，只是不是检索当前线程的AccessControlContext，而是使用提供的AccessControlContext。如果提供的AccessControlContext为null，则此方法将实例化一个具有一组空的ProtectionDomains的新AccessControlContext。

      类型参数:
      T - PrivilegedAction的run方法返回的值的类型。
      参数:
      subject - 指定action将作为其运行的Subject。此参数可能为null。
      action - 作为指定Subject运行的代码。
      acc - 与指定的subject和action绑定的AccessControlContext。
      返回:
      PrivilegedAction的run方法返回的值。
      抛出:
      NullPointerException - 如果PrivilegedAction为null。
      SecurityException - 如果安装了安全管理器并且调用者没有AuthPermission("doAsPrivileged")权限来调用此方法。

    • doAsPrivileged

      @Deprecated(since="17", forRemoval=true) public static <T> T doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc) throws PrivilegedActionException
      Deprecated, for removal: This API element is subject to removal in a future version.
      This method is only useful in conjunction with the Security Manager, which is deprecated and subject to removal in a future release. Consequently, this method is also deprecated and subject to removal. There is no replacement for the Security Manager or this method.
      作为特定Subject执行特权工作。

      此方法与Subject.doAs完全相同，只是不是检索当前线程的AccessControlContext，而是使用提供的AccessControlContext。如果提供的AccessControlContext为null，则此方法将实例化一个具有一组空的ProtectionDomains的新AccessControlContext。

      类型参数:
      T - 由PrivilegedExceptionAction的run方法返回的值的类型。
      参数:
      subject - 指定的action将作为其运行的Subject。此参数可以为null。
      action - 要作为指定的Subject运行的代码。
      acc - 与指定的subject和action绑定的AccessControlContext。
      返回:
      由PrivilegedExceptionAction的run方法返回的值。
      抛出:
      PrivilegedActionException - 如果PrivilegedExceptionAction.run方法抛出已检查异常。
      NullPointerException - 如果指定的PrivilegedExceptionAction为null。
      SecurityException - 如果安装了安全管理器且调用者没有AuthPermission("doAsPrivileged")权限来调用此方法。

    • getPrincipals

      public Set<Principal> getPrincipals()
      返回与此Subject关联的Principal集合。每个Principal代表此Subject的身份。

      返回的Set由此Subject的内部Principal Set支持。对返回的Set的任何修改也会影响内部Principal Set。

      如果安装了安全管理器，则调用者必须具有AuthPermission("modifyPrincipals")权限来修改返回的集合，否则将抛出SecurityException。

      返回:
      与此Subject关联的Principal集合。

    • getPrincipals

      public <T extends Principal> Set<T> getPrincipals(Class<T> c)
      返回与此Subject关联且是指定Class的实例或子类的Principal集合。

      返回的Set不由此Subject的内部Principal Set支持。每次方法调用都会创建并返回一个新的Set。对返回的Set的修改不会影响内部Principal Set。

      类型参数:
      T - 由c建模的类的类型
      参数:
      c - 所有返回的Principal都将是此类的实例。
      返回:
      是指定Class的实例的Principal集合。
      抛出:
      NullPointerException - 如果指定的Class为null。

    • getPublicCredentials

      public Set<Object> getPublicCredentials()
      返回此Subject持有的公共凭据的Set。

      返回的Set由此Subject的内部公共凭据Set支持。对返回的Set的任何修改也会影响内部公共凭据Set。

      如果安装了安全管理器，则调用者必须具有AuthPermission("modifyPublicCredentials")权限来修改返回的集合，否则将抛出SecurityException。

      返回:
      此Subject持有的公共凭据的Set。

    • getPrivateCredentials

      public Set<Object> getPrivateCredentials()
      返回此Subject持有的私有凭据的Set。

      返回的Set由此Subject的内部私有凭据Set支持。对返回的Set的任何修改也会影响内部私有凭据Set。

      如果安装了安全管理器，则调用者必须具有AuthPermission("modifyPrivateCredentials")权限来修改返回的集合，否则将抛出SecurityException。

      在遍历Set时，如果安装了安全管理器且调用者没有PrivateCredentialPermission来访问特定凭据，则会抛出SecurityException。尽管如此，Iterator仍会前进到Set中的下一个元素。

      返回:
      此Subject持有的私有凭据的Set。

    • getPublicCredentials

      public <T> Set<T> getPublicCredentials(Class<T> c)
      返回与此Subject关联且是指定Class的实例或子类的公共凭据的Set。

      返回的Set不由此Subject的内部公共凭据Set支持。每次方法调用都会创建并返回一个新的Set。对返回的Set的修改不会影响内部公共凭据Set。

      类型参数:
      T - 由c建模的类的类型
      参数:
      c - 所有返回的公共凭据都将是此类的实例。
      返回:
      是指定Class的实例的公共凭据的Set。
      抛出:
      NullPointerException - 如果指定的Class为null。

    • getPrivateCredentials

      public <T> Set<T> getPrivateCredentials(Class<T> c)
      返回与此Subject关联且是指定Class的实例或子类的私有凭据的Set。

      如果安装了安全管理器，则调用者必须具有PrivateCredentialPermission来访问所有请求的凭据，否则将抛出SecurityException。

      返回的Set不由此Subject的内部私有凭据Set支持。每次方法调用都会创建并返回一个新的Set。对返回的Set的修改不会影响内部私有凭据Set。

      类型参数:
      T - 由c建模的类的类型
      参数:
      c - 所有返回的私有凭据都将是此类的实例。
      返回:
      是指定Class的实例的私有凭据的Set。
      抛出:
      NullPointerException - 如果指定的Class为null。

    • equals

      public boolean equals(Object o)
      将指定的对象与此Subject进行比较以确定是否相等。如果给定对象也是一个Subject且两个Subject实例是等价的，则返回true。更正式地说，如果它们的Principal和Credential集合相等，则两个Subject实例是相等的。
      覆盖:
      equals 在类 Object中
      参数:
      o - 用于与此Subject比较是否相等的对象。
      返回:
      如果指定的对象等于此Subject，则返回true。
      抛出:
      SecurityException - 如果安装了安全管理器且调用者没有PrivateCredentialPermission权限来访问此Subject或提供的私有凭据。
      参见:

    • toString

      public String toString()
      返回此Subject的字符串表示形式。
      覆盖:
      toString 在类 Object中
      返回:
      此Subject的字符串表示形式。

    • hashCode

      public int hashCode()
      返回此Subject的哈希码。
      覆盖:
      hashCode 在类 Object中
      返回:
      此Subject的哈希码。
      抛出:
      SecurityException - 如果安装了安全管理器且调用者没有PrivateCredentialPermission权限来访问此Subject的私有凭据。
      参见: