Module java.base

软件包 javax.security.auth

Class Subject

java.lang.Object

javax.security.auth.Subject

All Implemented Interfaces:

Serializable

public final class Subject
extends Object
implements Serializable

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

受试者可能具有多个身份。 每个身份在Principal内表示为Subject 。 校长只需将名称绑定到一个Subject 。 例如，一个Subject恰好是一个人，爱丽丝可能有两个校长：一个将“爱丽丝酒吧”（她的驾驶执照上的名称）绑定到Subject ，另一个绑定“999-99-9999” ，她的学生身份证号码，到Subject 。 即使每个人都有不同的名称，两位校长也参考同一个Subject 。

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

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

从以下版本开始：

1.4

另请参见：

Principal ， DomainCombiner ， Serialized Form

构造方法摘要

构造方法

Constructor	描述
Subject()	创建一个 Subject的实例，一个空的 Set的主体和空的公共和私有凭据集。
Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)	使用主体和凭据创建一个 Subject的实例。

方法摘要

Modifier and Type	方法	描述
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()	返回 Set与此相关的校长 Subject 。
<T extends Principal> Set<T>	getPrincipals(Class<T> c)	返回 Set与此关联的Principal Subject是实例或指定的子类 Class 。
Set<Object>	getPrivateCredentials()	返回此 Set所持有的私有证书的 Subject 。
<T> Set<T>	getPrivateCredentials(Class<T> c)	返回一个 Set与此相关的私有证书 Subject是实例或指定的子类 Class 。
Set<Object>	getPublicCredentials()	返回这个 Set所持有的公共证书的 Subject 。
<T> Set<T>	getPublicCredentials(Class<T> c)	返回一个 Set与此相关的公开证书 Subject是实例或指定的子类 Class 。
static Subject	getSubject(AccessControlContext acc)	得到 Subject与所提供的相关 AccessControlContext 。
int	hashCode()	返回此 Subject的哈希 Subject 。
boolean	isReadOnly()	查询 Subject是否为只读。
void	setReadOnly()	将此 Subject设置为只读。
String	toString()	返回此 Subject的String表示 Subject 。

Methods inherited from class java.lang.Object

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

构造方法详细信息

Subject

public Subject()

创建一个Subject的实例，一个空的Set的主体和空的公共和私人凭据集。

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

要修改Principals Set，主叫方必须具有AuthPermission("modifyPrincipals") 。 要修改公用证书集，主叫方必须具有AuthPermission("modifyPublicCredentials") 。 要修改私人凭证集，主叫方必须具有AuthPermission("modifyPrivateCredentials") 。

Subject

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

使用主体和凭据创建一个Subject的实例。

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

要修改Principals Set，调用者必须具有AuthPermission("modifyPrincipals") 。 要修改公用证书集，呼叫者必须具有AuthPermission("modifyPublicCredentials") 。 要修改私人凭证集，主叫方必须具有AuthPermission("modifyPrivateCredentials") 。

参数

readOnly - 如果 Subject为只读， Subject true，否则为false。

principals -在 Set校长与此相关 Subject 。

pubCredentials -在 Set公开证书与此相关 Subject 。

privCredentials -在 Set私有证书与此相关 Subject 。

异常

NullPointerException -如果指定 principals ， pubCredentials ，或 privCredentials是 null ，或在任何这三组存在空值。

方法详细信息

setReadOnly

public void setReadOnly()

将此Subject设置为只读。

此主题的修改（添加和删除） Principal Set和凭证集将被禁止。 此主题凭据的destroy操作仍将被允许。

随后尝试修改Subject的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 - 如果安装了一个安全管理器，并且主叫方没有 AuthPermission("getSubject")权限获取 Subject 。

NullPointerException - 如果提供的 AccessControlContext是 null 。

doAs

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

执行工作作为一个特定的Subject 。

此方法首先通过AccessController.getContext检索当前线程的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检索当前线程的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完全相同，不同之处在于，它不是检索当前线程的AccessControlContext ，而是使用提供的AccessControlContext 。 如果提供的AccessControlContext是null ，则此方法将实例化一个新的AccessControlContext其中包含一个空集合ProtectionDomains。

参数类型

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完全相同，不同之处在于，它不是检索当前线程的AccessControlContext ，而是使用提供的AccessControlContext 。 如果提供的AccessControlContext是null ，则此方法将实例化一个新的AccessControlContext其中包含一个空集合ProtectionDomains。

参数类型

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 。 每个Principal代表这个Subject的身份。

返回的Set由本主题的内部Principal Set 。 对所返回的Set任何修改Set影响内部Principal Set 。

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

结果

在 Set与此相关的Principal Subject 。

getPrincipals

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

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

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

参数类型

T - 类型由 c建模

参数

c - 返回的 Set的校长都将是这个类的实例。

结果

一个 Set的主体是指定的 Class实例。

异常

NullPointerException - 如果指定的 Class是 null 。

getPublicCredentials

public Set<Object> getPublicCredentials()

返回Set本公开证书Subject 。

返回的Set由本主题的内部公开凭证Set 。 对所返回的Set任何修改Set影响内部公共证书Set 。

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

结果

一个由这个 Subject持有的 Set的公共证书。

getPrivateCredentials

public Set<Object> getPrivateCredentials()

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

返回的Set由本主题的内部私人凭证Set 。 对所返回的Set任何修改Set影响内部私人凭据Set 。

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

在遍历的Set ，一个SecurityException如果安装了安全管理器抛出调用者不具有PrivateCredentialPermission访问特定凭证。 该Iterator是先进还是在接下来的元素Set 。

结果

一个 Set这个私有证书 Subject 。

getPublicCredentials

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

返回一个Set与此相关的公开证书Subject是实例或指定的子类Class 。

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

参数类型

T - 由 c建模的类的类型

参数

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

结果

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

异常

NullPointerException - 如果指定的 Class是 null 。

getPrivateCredentials

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

返回一个Set与此相关的私有证书Subject是实例或指定的子类Class 。

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

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

参数类型

T - 类型由 c建模

参数

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

结果

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

异常

NullPointerException - 如果指定的 Class是 null 。

equals

public boolean equals(Object o)

将指定的对象与此Subject进行比较以获得相等性。 如果给定对象也是主题，并且两个Subject实例是等效的，则返回true。 更正式地，如果Principal和Credential集合相等，则两个Subject实例相等。

重写：

equals在 Object

参数

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

结果

如果指定的对象等于此 Subject 。

异常

SecurityException - 如果安装了一个安全管理器，并且主叫方没有PrivateCredentialPermission权限访问该Subject或所提供的Subject的私有凭据。

另请参见：

Object.hashCode() ， HashMap

toString

public String toString()

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

重写：

toString在 Object

结果

这个 Subject的String表示。

hashCode

public int hashCode()

返回此 Subject的哈希 Subject 。

重写：

hashCode在 Object

结果

这个 Subject的哈希 Subject 。

异常

SecurityException - 如果安装了一个安全管理器，并且调用者没有访问该主体的私有凭据的权限， 则为PrivateCredentialPermission 。

另请参见：

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