模块 java.base

软件包 javax.security.auth

Class Subject

java.lang.Object

javax.security.auth.Subject

实现的所有接口

Serializable

public final class Subject
extends Object
implements Serializable

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

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

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

要检索与Subject关联的所有主体，请调用getPrincipals方法。 要检索属于Subject所有公用或专用凭据，请分别调用getPublicCredentials方法或getPrivateCredentials方法。 要修改Principals和凭证的返回Set ，请使用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是序列化的，但与Subject相关的Subject却没有。 请注意， java.security.Principal类未实现Serializable 。 因此，与Subjects相关的所有具体Principal实现必须实现Serializable 。

从以下版本开始：

1.4

另请参见：

Principal ， DomainCombiner ， Serialized Form

构造方法摘要

构造方法

构造器	描述
Subject()	创建一个 Subject的实例， Subject包含一个空的 Set的Principals和空的公共和私有凭证集。
Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)	使用Principals和凭据创建 Subject的实例。

方法摘要

变量和类型	方法	描述
static <T> T	doAs(Subject subject, PrivilegedAction<T> action)	作为特定的 Subject执行工作。
static <T> T	doAs(Subject subject, PrivilegedExceptionAction<T> action)	作为特定的 Subject执行工作。
static <T> T	doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)	作为特定的 Subject执行特权工作。
static <T> T	doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)	作为特定的 Subject执行特权工作。
boolean	equals(Object o)	比较指定的Object与此 Subject是否相等。
Set<Principal>	getPrincipals()	返回 Set与此 Subject相关的Principals。
<T extends Principal> Set<T>	getPrincipals(类<T> c)	返回与此 Subject相关的 Set个Principals，它们是指定 类实例或子类。
Set<Object>	getPrivateCredentials()	返回此 Set持有的 Subject凭据。
<T> Set<T>	getPrivateCredentials(类<T> c)	返回与此 Subject关联的 Set有凭据，它们是指定的 类实例或子类。
Set<Object>	getPublicCredentials()	返回 Set本公开证书 Subject 。
<T> Set<T>	getPublicCredentials(类<T> c)	返回与此 Subject相关的 Set个公共凭证，它们是指定 类实例或子类。
static Subject	getSubject(AccessControlContext acc)	得到 Subject与所提供的相关 AccessControlContext 。
int	hashCode()	返回此 Subject的哈希 Subject 。
boolean	isReadOnly()	查询此 Subject是否为只读。
void	setReadOnly()	将此 Subject设置为只读。
String	toString()	返回此 Subject的String表示 Subject 。

声明方法的类 java.lang.Object

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

构造方法详细信息

Subject

public Subject()

创建一个Subject的实例， Subject包含一个空的Set的Principals和空的公共和私有凭证集。

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

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

Subject

public Subject(boolean readOnly,
               Set<? extends Principal> principals,
               Set<?> pubCredentials,
               Set<?> privCredentials)

使用Principals和凭据创建Subject的实例。

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

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

参数

readOnly - 如果 Subject是只读的， readOnly true， Subject为false。

principals - 与 Set相关联的校长 Subject 。

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为只读， Subject true，否则为false。

getSubject

public static Subject getSubject(AccessControlContext acc)

得到Subject与所提供的相关AccessControlContext 。

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

参数

acc - 从 AccessControlContext中检索 Subject 。

结果

所述 Subject与所提供的相关联的 AccessControlContext ，或 null如果没有 Subject与提供相关联 AccessControlContext 。

异常

SecurityException - 如果安装了安全管理器且调用者没有获得 Subject的 AuthPermission("getSubject")权限。

NullPointerException - 如果提供的 AccessControlContext是 null 。

doAs

public static <T> T doAs(Subject subject,
                         PrivilegedAction<T> action)

作为特定的Subject执行工作。

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

参数类型

T - PrivilegedAction的 run方法返回的值的类型。

参数

subject -该Subject指定的action会运行。 此参数可能是null 。

action - 要作为指定的 Subject运行的代码。

结果

PrivilegedAction的 run方法返回的值。

异常

NullPointerException - 如果 PrivilegedAction是 null 。

SecurityException - 如果安装了安全管理器且调用者没有调用此方法的权限，则该调用方具有 AuthPermission("doAs")权限。

doAs

public static <T> T doAs(Subject subject,
                         PrivilegedExceptionAction<T> action)
                  throws PrivilegedActionException

作为特定的Subject执行工作。

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

参数类型

T - PrivilegedExceptionAction的 run方法返回的值的类型。

参数

subject -该Subject指定的action会运行。 此参数可能是null 。

action - 要作为指定的 Subject运行的代码。

结果

PrivilegedExceptionAction的 run方法返回的值。

异常

PrivilegedActionException - 如果 PrivilegedExceptionAction.run方法抛出已检查的异常。

NullPointerException - 如果指定的 PrivilegedExceptionAction是 null 。

SecurityException - 如果安装了安全管理器且调用者没有调用此方法的 AuthPermission("doAs")权限。

doAsPrivileged

public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedAction<T> action,
                                   AccessControlContext acc)

作为特定的Subject执行特权工作。

此方法的行为完全一样Subject.doAs ，但不是获取当前Thread的的AccessControlContext ，它使用提供AccessControlContext 。 如果提供的AccessControlContext是null ，则此方法将实例化具有空集合ProtectionDomains的新AccessControlContext 。

参数类型

T - PrivilegedAction的 run方法返回的值的类型。

参数

subject -该Subject指定的action会运行。 此参数可能是null 。

action - 要作为指定的 Subject运行的代码。

acc - 将 AccessControlContext绑定到指定的 主题和 操作 。

结果

PrivilegedAction的 run方法返回的值。

异常

NullPointerException - 如果 PrivilegedAction是 null 。

SecurityException - 如果安装了安全管理器且调用者没有调用此方法的权限，则该调用方具有 AuthPermission("doAsPrivileged")的权限。

doAsPrivileged

public static <T> T doAsPrivileged(Subject subject,
                                   PrivilegedExceptionAction<T> action,
                                   AccessControlContext acc)
                            throws PrivilegedActionException

作为特定的Subject执行特权工作。

此方法的行为完全一样Subject.doAs ，但不是获取当前Thread的的AccessControlContext ，它使用提供AccessControlContext 。 如果提供的AccessControlContext是null ，则此方法将实例化具有空集合ProtectionDomains的新AccessControlContext 。

参数类型

T - PrivilegedExceptionAction的 run方法返回的值的类型。

参数

subject -该Subject指定的action会运行。 此参数可能是null 。

action - 要作为指定的 Subject运行的代码。

acc - 要与指定 主题和 操作绑定的 AccessControlContext 。

结果

PrivilegedExceptionAction的 run方法返回的值。

异常

PrivilegedActionException - 如果 PrivilegedExceptionAction.run方法抛出已检查的异常。

NullPointerException - 如果指定的 PrivilegedExceptionAction是 null 。

SecurityException - 如果安装了安全管理器且调用者没有调用此方法的 AuthPermission("doAsPrivileged")权限。

getPrincipals

public Set<Principal> getPrincipals()

返回Set与此Subject相关的Principals。 每个Principal代表此Subject的标识。

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

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

结果

Set of Principals与此 Subject相关联。

getPrincipals

public <T extends Principal> Set<T> getPrincipals(类<T> c)

返回Set与此Subject相关的Principals，它们是指定类实例或子类。

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

参数类型

T - 由 c建模的类的类型

参数

c - 已返回的校长 Set将全部为此课程的实例。

结果

a Set作为指定 类实例的 类 。

异常

NullPointerException - 如果指定的 类是 null 。

getPublicCredentials

public Set<Object> getPublicCredentials()

返回Set本公开证书Subject 。

返回的Set由此Subject的内部公共证书Set 。 对返回的Set任何修改Set影响内部公共证书Set 。

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

结果

一个 Set本公开证书 Subject 。

getPrivateCredentials

public Set<Object> getPrivateCredentials()

返回此Set所持有的Subject凭据。

返回的Set由此Subject的内部私有凭证Set 。 对返回的Set任何修改Set影响内部私有凭证Set 。

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

在迭代Set ，如果安装了安全管理器并且调用者没有访问特定凭据的Set ， SecurityException引发SecurityException 。 该Iterator是先进还是在接下来的元素Set 。

结果

此 Subject持有的 Set个私人证书。

getPublicCredentials

public <T> Set<T> getPublicCredentials(类<T> c)

返回与此Subject相关的Set公共凭证，它们是指定类实例或子类。

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

参数类型

T - 由 c建模的类的类型

参数

c - 返回的 Set公共凭据都将是此类的实例。

结果

一个 Set的公共凭据，是指定的 类实例。

异常

NullPointerException - 如果指定的 类是 null 。

getPrivateCredentials

public <T> Set<T> getPrivateCredentials(类<T> c)

返回与此Subject关联的Set有凭据，它们是指定类实例或子类。

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

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

参数类型

T - 由 c建模的类的类型

参数

c - 返回的 Set私有凭证都将是此类的实例。

结果

一个 Set的私有凭据，是指定的 类实例。

异常

NullPointerException - 如果指定的 类是 null 。

equals

public boolean equals(Object o)

比较指定的Object与此Subject是否相等。 如果给定对象也是Subject并且两个Subject实例是等效的，则返回true。 更正式地说，如果Principal和Credential集相等，则两个Subject实例相等。

重写：

equals ，类 Object

参数

o - 要与此 Subject进行相等性比较的对象。

结果

如果指定的Object等于此 Subject 。

异常

SecurityException - 如果安装了安全管理器且调用者没有访问此Subject或提供的Subject的私有凭据的PrivateCredentialPermission权限。

另请参见：

Object.hashCode() ， HashMap

toString

public String toString()

返回此 Subject的String表示 Subject 。

重写：

toString在类 Object

结果

此 Subject的字符串表示 Subject 。

hashCode

public int hashCode()

返回此 Subject的哈希 Subject 。

重写：

hashCode类 Object

结果

此 Subject的哈希 Subject 。

异常

SecurityException - 如果安装了安全管理器且调用者没有访问此主题的私有凭据的PrivateCredentialPermission权限。

另请参见：

Object.equals(java.lang.Object) ， System.identityHashCode(java.lang.Object)