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