javax.security.auth
类 Subject

java.lang.Object
  javax.security.auth.Subject

所有已实现的接口：

Serializable

public final class Subject
extends Object
implements Serializable

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

Subject 可以潜在地具有多重身份。每个身份被表示为 Subject 中的一个 Principal。Principal 只是把名称绑定到 Subject。例如，Subject 正好是一个人（Alice）时,它可以有两个主体：一个把她驾驶证上的名称 "Alice Bar" 绑定到 Subject，另一个把学生身份证上的号码 "999-99-9999" 绑定到 Subject。即使每个主体具有不同的名称，它们也都指的是同一个 Subject。

Subject 也可以拥有与安全相关的属性，它们被称为证书。敏感的证书需要特殊的保护，例如私有加密密钥存储在私有的证书 Set 中。将证书设计为共享的，例如公钥证书或 Kerberos 服务票据存储在一个公开证书 Set 中。访问和修改不同的证书 Set 需要不同的权限。

要获取与 Subject 关联的所有 Principal，请调用 getPrincipals 方法。要获取属于一个 Subject 的所有公开的或私有的证书，请分别调用 getPublicCredentials 方法或 getPrivateCredentials 方法。要修改返回的 Principal 和证书的 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 关联的 Principal 是已序列化的，与 Subject 关联的证书不是已序列化的。注意，java.security.Principal 类不会实现 Serializable。因此，与 Subject 关联的所有具体的 Principal 实现必须实现 Serializable。

另请参见：

Principal, DomainCombiner, 序列化表格

构造方法摘要

Subject()
创建一个带有空的 Principal Set 和空的公开或私有证书 Set 的 Subject 的一个实例。

Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)
创建带有 Principal 和证书的 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) 比较指定对象与此 Subject 的相等性。
Set<Principal>	getPrincipals() 返回与此 Subject 关联的 Principal Set。
<T extends Principal> Set<T>	getPrincipals(Class<T> c) 返回与此 Subject 关联的 Principal Set，它是指定的 Class 的实例或子类。
Set<Object>	getPrivateCredentials() 返回此 Subject 中包含的私有证书 Set。
<T> Set<T>	getPrivateCredentials(Class<T> c) 返回与此 Subject关联的私有证书 Set，它是指定的 Class 的实例或子类。
Set<Object>	getPublicCredentials() 返回此 Subject 中包含的公开证书 Set。
<T> Set<T>	getPublicCredentials(Class<T> c) 返回与此 Subject 关联的公开证书 Set，它是指定的 Class 的实例或子类。
static Subject	getSubject(AccessControlContext acc) 获取与提供的 AccessControlContext 关联的 Subject。
int	hashCode() 返回此 Subject 的哈希码。
boolean	isReadOnly() 查询此 Subject 是否为只读的。
void	setReadOnly() 将此 Subject 设置为只读的。
String	toString() 返回此 Subject 的字符串表示形式。

从类 java.lang.Object 继承的方法

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

构造方法详细信息

Subject

public Subject()

创建一个带有空的 Principal Set 和空的公开或私有证书 Set 的 Subject 的一个实例。

在新构建的 Set 允许进行后续修改前检查此 Subject 是否已设置为只读的。新创建的 Set 还通过确保调用者具有足够权限的方式来防止非法修改。

要修改 Principal Set，调用者必须具有 AuthPermission("modifyPrincipals") 权限。要修改公开证书 Set，调用者必须具有 AuthPermission("modifyPublicCredentials") 权限。要修改私有证书 Set，调用者必须具有 AuthPermission("modifyPrivateCredentials") 权限。

Subject

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

创建带有 Principal 和证书的 Subject 的实例。

指定将 Set 中的 Principal 和证书复制到新构建的 Set 中。在新创建的 Set 允许进行后续修改前检查此 Subject 是否已设置为只读的。新创建的 Set 还通过确保调用者具有足够权限的方式来防止非法修改。

要修改 Principal Set，调用者必须具有 AuthPermission("modifyPrincipals") 权限。要修改公开证书 Set，调用者必须具有 AuthPermission("modifyPublicCredentials") 权限。要修改私有证书 Set，调用者必须具有 AuthPermission("modifyPrivateCredentials") 权限。

参数：

readOnly - 如果 Subject 是只读的，则参数为 true，否则为 false。

principals - 要与此 Subject 关联的 Principal Set。

pubCredentials - 要与此 Subject 关联的公开证书 Set。

privCredentials - 要与此 Subject 关联的私有证书 Set。

抛出：

NullPointerException - 如果指定的 principals、pubCredentials 或 privCredentials 为 null。

方法详细信息

setReadOnly

public void setReadOnly()

将此 Subject 设置为只读的。

对此 Subject 的 Principal Set 和证书 Set 的修改（添加和移除）将是不允许的。仍然允许在此 Subject 的证书上进行 destroy 操作。

如果后续企图修改 Subject 的 Principal 和证书 Set，将导致抛出 IllegalStateException。另外，一旦 Subject 是只读的，就不可能再将它重新设置为可写的。

抛出：

SecurityException - 如果调用者不具有将此 Subject 设置为只读的权限。

isReadOnly

public boolean isReadOnly()

查询此 Subject 是否为只读的。

返回：

如果此 Subject 为只读的，则返回 true；否则，返回 false。

getSubject

public static Subject getSubject(AccessControlContext acc)

获取与提供的 AccessControlContext 关联的 Subject。

AccessControlContext 可以包含很多 Subject（从嵌套的 doAs 调用得到）。在这种情况下，返回与 AccessControlContext 关联的最近的 Subject。

参数：

acc - AccessControlContext，从它获取 Subject。

返回：

与所提供的 AccessControlContext 关联的 Subject，如果没有 Subject 与提供的 AccessControlContext 相关联，则返回 null。

抛出：

SecurityException - 如果调用者不具有获取此 Subject 的权限。

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 传递到 AccessController.doPrivileged。

参数：

subject - 指定的 action 将作为该 Subject 运行。此参数可以为 null。

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

返回：

PrivilegedAction 的 run 方法所返回的值。

抛出：

NullPointerException - 如果 PrivilegedAction 为 null。

SecurityException - 如果调用者不具有调用此方法的权限。

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 传递到 AccessController.doPrivileged。

参数：

subject - 指定的 action 将作为该 Subject 运行。此参数可以为 null。

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

返回：

PrivilegedExceptionAction 的 run 方法所返回的值。

抛出：

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

NullPointerException - 如果指定的 PrivilegedExceptionAction 为 null。

SecurityException - 如果调用者不具有调用此方法的权限。

doAsPrivileged

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

作为特定的 Subject 的特权功能。

除了使用提供的 AccessControlContext，而不是获取当前 Thread 的 AccessControlContext 外，此方法的行为与 Subject.doAs 完全一样。如果提供的 AccessControlContext 为 null，则此方法实例化一个新的带有空 ProtectionDomains 集合的 AccessControlContext。

参数：

subject - 指定的 action 将作为该 Subject 运行。此参数可以为 null。

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

acc - 限制为指定 subject 和 action 的 AccessControlContext。

返回：

PrivilegedAction 的 run 方法所返回的值。

抛出：

NullPointerException - 如果 PrivilegedAction 为 null。

SecurityException - 如果调用者不具有调用此方法的权限。

doAsPrivileged

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

作为特定的 Subject 的特权功能。

除了使用提供的 AccessControlContext，而不是获取当前 Thread 的 AccessControlContext 外，此方法的行为与 Subject.doAs 完全一样。如果提供的 AccessControlContext 为 null，则此方法实例化一个新的带有空 ProtectionDomains 集合的 AccessControlContext。

参数：

subject - 指定的 action 将作为该 Subject 运行。此参数可以为 null。

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

acc - 限制为指定 subject 和 action 的 AccessControlContext。

返回：

PrivilegedExceptionAction 的 run 方法所返回的值。

抛出：

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

NullPointerException - 如果指定的 PrivilegedExceptionAction 为 null。

SecurityException - 如果调用者不具有调用此方法的权限。

getPrincipals

public Set<Principal> getPrincipals()

返回与此 Subject 关联的 Principal Set。每个 Principal 表示此 Subject 的一个身份。

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

返回：

与此 Subject 关联的 Principal Set。

getPrincipals

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

返回与此 Subject 关联的 Principal Set，它是指定的 Class 的实例或子类。

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

参数：

c - 返回的 Principal Set 将都是此类的实例。

返回：

是指定的 Class 的实例的 Principal Set。

抛出：

NullPointerException - 如果指定的 Class 为 null。

getPublicCredentials

public Set<Object> getPublicCredentials()

返回此 Subject 中包含的公开证书 Set。

此 Subject 的内部公开证书 Set 支持返回的 Set。对返回的 Set 的任何修改也影响内部公开证书 Set。

返回：

此 Subject 中包含的公开证书 Set。

getPrivateCredentials

public Set<Object> getPrivateCredentials()

返回此 Subject 中包含的私有证书 Set。

此 Subject 的内部私有证书 Set 支持返回的 Set。对返回的 Set 的任何修改也影响内部私有证书 Set。

调用者需要权限来访问返回的 Set 中的证书，或修改 Set 本身。如果调用者不具有正确的权限,则会抛出 SecurityException。

当迭代 Set 时，如果调用者不具有访问特定证书的权限，则抛出 SecurityException。Iterator 仍然是前移到 Set 中的下一个元素。

返回：

此 Subject 中包含的私有证书 Set。

getPublicCredentials

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

返回与此 Subject 关联的公开证书 Set，它是指定的 Class 的实例或子类。

此 Subject 的内部公开证书 Set 不支持返回的 Set。每次方法调用都创建和返回一个新的 Set。对返回的 Set 的修改不影响内部公开证书 Set。

参数：

c - 返回的公开证书 Set 将都是此类的实例。

返回：

是指定的 Class 的实例的公开证书 Set。

抛出：

NullPointerException - 如果指定的 Class 为 null。

getPrivateCredentials

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

返回与此 Subject关联的私有证书 Set，它是指定的 Class 的实例或子类。

调用者必须具有访问所有请求证书的权限，否则将抛出 SecurityException。

此 Subject 的内部私有证书 Set 不支持返回的 Set。每次方法调用都创建和返回一个新的 Set。对返回的 Set 的修改不影响内部私有证书 Set。

参数：

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

返回：

是指定的 Class 的实例的私有证书 Set。

抛出：

NullPointerException - 如果指定的 Class 为 null。

equals

public boolean equals(Object o)

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

覆盖：

类 Object 中的 equals

参数：

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

返回：

如果指定的对象与此 Subject 相等，则返回 true。

抛出：

SecurityException - 如果调用者不具有访问此 Subject 的私有证书的权限，或者如果调用者不具有访问所提供的 Subject 的私有证书的权限。

另请参见：

Object.hashCode(), Hashtable

toString

public String toString()

返回此 Subject 的字符串表示形式。

覆盖：

类 Object 中的 toString

返回：

此 Subject 的字符串表示形式。

hashCode

public int hashCode()

返回此 Subject 的哈希码。

覆盖：

类 Object 中的 hashCode

返回：

此 Subject 的哈希码。

抛出：

SecurityException - 如果调用者不具有访问此 Subject 的私有证书的权限。

另请参见：

Object.equals(java.lang.Object), Hashtable