模块 java.base
包 javax.security.auth

类 Subject

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

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

受试者可能具有多重身份。每个身份都表示为 Subject 中的 Principal。校长只需将名称绑定到 Subject 即可。例如，恰好是一个人 Alice 的 Subject 可能有两个委托人：一个将她驾驶执照上的名字“Alice Bar”绑定到 Subject，另一个绑定“999-99-9999” ，她的学生证上的号码，到Subject。两个 Principal 都引用相同的 Subject，尽管每个 Principal 的名称不同。

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

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

   Subject subject;
   Principal principal;
   Object credential;

   // add a Principal and credential to the Subject
   subject.getPrincipals().add(principal);
   subject.getPublicCredentials().add(credential);

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

自从：
1.4
参见：

  • 构造方法详细信息

    • Subject

      public Subject()
      使用空的 Set Principals 和空的公共和私有凭证集创建 Subject 的实例。

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

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

    • Subject

      public Subject(boolean readOnly, Set <? extends Principal > principals, Set <?> pubCredentials, Set <?> privCredentials)
      使用主体和凭据创建 Subject 的实例。

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

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

      参数：
      readOnly - 如果 Subject 为只读，则为真，否则为假。
      principals - 要与此 Subject 关联的委托人的 Set。
      pubCredentials - 与此 Subject 关联的公共凭证的 Set。
      privCredentials - 与此 Subject 关联的私有凭证的 Set。
      抛出：
      NullPointerException - 如果指定的 principals 、 pubCredentials 或 privCredentials 是 null ，或者在这三个集合中的任何一个中存在空值。

  • 方法详情

    • setReadOnly

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

      不允许对此主题的 Principal Set 和凭证集进行修改（添加和删除）。仍然允许对该主题的凭据进行 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)
      已弃用，将被删除：此 API 元素可能会在未来版本中删除。
      此方法取决于 AccessControlContext ，它与 安全管理器 一起被弃用，并在未来的版本中被删除。但是，独立于安全管理器获取主题是有用的。因此，已添加名为 current() 的替换 API，可用于获取当前主题。
      获取与提供的 AccessControlContext 关联的 Subject。

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

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

    • current

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

      当前主题是通过callAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>) 方法安装的。当调用 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 - 以 subject 作为当前主题运行的代码。不能是 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)
      已弃用，将被删除：此 API 元素可能会在未来版本中删除。
      此方法取决于 AccessControlContext ，它与 安全管理器 一起被弃用，并在未来的版本中被删除。但是，独立于安全管理器，作为主题执行工作是有用的。因此，已添加名为 callAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>) 的替换 API，可用于执行相同的工作。
      作为特定的 Subject 执行工作。

      此方法首先通过 AccessController.getContext 检索当前线程的 AccessControlContext，然后使用检索到的上下文和新的 SubjectDomainCombiner（使用提供的 Subject 构造）实例化一个新的 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
      已弃用，将被删除：此 API 元素可能会在未来版本中删除。
      此方法取决于 AccessControlContext ，它与 安全管理器 一起被弃用，并在未来的版本中被删除。但是，独立于安全管理器，作为主题执行工作是有用的。因此，已添加名为 callAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>) 的替换 API，可用于执行相同的工作。
      作为特定的 Subject 执行工作。

      此方法首先通过 AccessController.getContext 检索当前线程的 AccessControlContext，然后使用检索到的上下文和新的 SubjectDomainCombiner（使用提供的 Subject 构造）实例化一个新的 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)
      已弃用，将被删除：此 API 元素可能会在未来版本中删除。
      此方法仅与 安全管理器 结合使用，后者已弃用并会在未来版本中删除。因此，此方法也已弃用并可能被删除。安全管理器或此方法没有替代品。
      作为特定的 Subject 执行特权工作。

      此方法的行为与 Subject.doAs 完全相同，除了它不是检索当前线程的 AccessControlContext ，而是使用提供的 AccessControlContext 。如果提供的 AccessControlContext 是 null ，此方法将实例化一个新的 AccessControlContext 和一个空的 ProtectionDomains 集合。

      类型参数：
      T - PrivilegedAction 的 run 方法返回值的类型。
      参数：
      subject - 指定的 action 将运行的 Subject。这个参数可能是 null 。
      action - 要作为指定的 Subject 运行的代码。
      acc - 要绑定到指定的 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
      已弃用，将被删除：此 API 元素可能会在未来版本中删除。
      此方法仅与 安全管理器 结合使用，后者已弃用并会在未来版本中删除。因此，此方法也已弃用并可能被删除。安全管理器或此方法没有替代品。
      作为特定的 Subject 执行特权工作。

      此方法的行为与 Subject.doAs 完全相同，除了它不是检索当前线程的 AccessControlContext ，而是使用提供的 AccessControlContext 。如果提供的 AccessControlContext 是 null ，此方法将实例化一个新的 AccessControlContext 和一个空的 ProtectionDomains 集合。

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

    • getPrincipals

      public Set <Principal > getPrincipals()
      返回与此 Subject 关联的委托人的 Set。每个 Principal 代表这个 Subject 的身份。

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

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

      返回：
      与此 Subject 关联的校长的 Set。

    • getPrincipals

      public <T extends Principal > Set <T> getPrincipals(Class <T> c)
      返回与此 Subject 关联的主体的 Set，它们是指定的 Class 的实例或子类。

      返回的 Set 不受此主题的内部 Principal Set 支持。为每个方法调用创建并返回一个新的 Set。对返回的 Set 的修改不会影响内部 Principal Set 。

      类型参数：
      T - 由 c 建模的类的类型
      参数：
      c - Principals 返回的 Set 将全部是此类的实例。
      返回：
      a Set of Principals 是指定 Class 的实例。
      抛出：
      NullPointerException - 如果指定的 Class 是 null 。

    • getPublicCredentials

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

      返回的 Set 由该主题的内部公共凭证 Set 支持。对返回的 Set 的任何修改也会影响内部公共凭证 Set。

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

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

    • getPrivateCredentials

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

      返回的 Set 由该主题的内部私有凭证 Set 支持。对返回的 Set 的任何修改也会影响内部私有凭证 Set。

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

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

      返回：
      此 Subject 持有的 Set 私人凭证。

    • getPublicCredentials

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

      返回的 Set 不受此主题的内部公共凭证 Set 的支持。为每个方法调用创建并返回一个新的 Set。对返回的 Set 的修改不会影响内部公共凭证 Set。

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

    • getPrivateCredentials

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

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

      返回的 Set 不受此主题的内部私有凭证 Set 的支持。为每个方法调用创建并返回一个新的 Set。对返回的 Set 的修改不会影响内部私有凭证 Set 。

      类型参数：
      T - 由 c 建模的类的类型
      参数：
      c - 返回的 Set 私有凭证将全部是此类的实例。
      返回：
      作为指定 Class 实例的私有凭证的 Set。
      抛出：
      NullPointerException - 如果指定的 Class 是 null 。

    • equals

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

    • toString

      public String  toString()
      返回此 Subject 的字符串表示形式。
      重写：
      toString 在类 Object 中
      返回：
      此 Subject 的字符串表示形式。

    • hashCode

      public int hashCode()
      返回此 Subject 的哈希码。
      重写：
      hashCode 在类 Object 中
      返回：
      这个 Subject 的哈希码。
      抛出：
      SecurityException - 如果安装了安全管理器并且调用者没有 PrivateCredentialPermission 权限来访问此主题的私有凭证。
      参见：