- java.lang.Object
- 
- javax.security.auth.Subject
 
- 
- All Implemented Interfaces:
- Serializable
 
 public final class Subject extends Object implements Serializable A Subjectrepresents a grouping of related information for a single entity, such as a person. Such information includes the Subject's identities as well as its security-related attributes (passwords and cryptographic keys, for example).Subjects may potentially have multiple identities. Each identity is represented as a Principalwithin theSubject. Principals simply bind names to aSubject. For example, aSubjectthat happens to be a person, Alice, might have two Principals: one which binds "Alice Bar", the name on her driver license, to theSubject, and another which binds, "999-99-9999", the number on her student identification card, to theSubject. Both Principals refer to the sameSubjecteven though each has a different name.A Subjectmay also own security-related attributes, which are referred to as credentials. Sensitive credentials that require special protection, such as private cryptographic keys, are stored within a private credentialSet. Credentials intended to be shared, such as public key certificates or Kerberos server tickets are stored within a public credentialSet. Different permissions are required to access and modify the different credential Sets.To retrieve all the Principals associated with a Subject, invoke thegetPrincipalsmethod. To retrieve all the public or private credentials belonging to aSubject, invoke thegetPublicCredentialsmethod orgetPrivateCredentialsmethod, respectively. To modify the returnedSetof Principals and credentials, use the methods defined in theSetclass. For example:Subject subject; Principal principal; Object credential; // add a Principal and credential to the Subject subject.getPrincipals().add(principal); subject.getPublicCredentials().add(credential);This Subjectclass implementsSerializable. While the Principals associated with theSubjectare serialized, the credentials associated with theSubjectare not. Note that thejava.security.Principalclass does not implementSerializable. Therefore all concretePrincipalimplementations associated with Subjects must implementSerializable.- Since:
- 1.4
- See Also:
- Principal,- DomainCombiner, Serialized Form
 
- 
- 
Constructor SummaryConstructors Constructor Description Subject()Create an instance of aSubjectwith an emptySetof Principals and empty Sets of public and private credentials.Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)Create an instance of aSubjectwith Principals and credentials.
 - 
Method SummaryAll Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static <T> TdoAs(Subject subject, PrivilegedAction<T> action)Perform work as a particularSubject.static <T> TdoAs(Subject subject, PrivilegedExceptionAction<T> action)Perform work as a particularSubject.static <T> TdoAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc)Perform privileged work as a particularSubject.static <T> TdoAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc)Perform privileged work as a particularSubject.booleanequals(Object o)Compares the specified Object with thisSubjectfor equality.Set<Principal>getPrincipals()Return theSetof Principals associated with thisSubject.<T extends Principal>
 Set<T>getPrincipals(Class<T> c)Return aSetof Principals associated with thisSubjectthat are instances or subclasses of the specifiedClass.Set<Object>getPrivateCredentials()Return theSetof private credentials held by thisSubject.<T> Set<T>getPrivateCredentials(Class<T> c)Return aSetof private credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.Set<Object>getPublicCredentials()Return theSetof public credentials held by thisSubject.<T> Set<T>getPublicCredentials(Class<T> c)Return aSetof public credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.static SubjectgetSubject(AccessControlContext acc)Get theSubjectassociated with the providedAccessControlContext.inthashCode()Returns a hashcode for thisSubject.booleanisReadOnly()Query whether thisSubjectis read-only.voidsetReadOnly()Set thisSubjectto be read-only.StringtoString()Return the String representation of thisSubject.
 
- 
- 
- 
Constructor Detail- 
Subjectpublic Subject() Create an instance of aSubjectwith an emptySetof Principals and empty Sets of public and private credentials.The newly constructed Sets check whether this Subjecthas been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions. These Sets also prohibit null elements, and attempts to add, query, or remove a null element will result in aNullPointerException.To modify the Principals Set, the caller must have AuthPermission("modifyPrincipals"). To modify the public credential Set, the caller must haveAuthPermission("modifyPublicCredentials"). To modify the private credential Set, the caller must haveAuthPermission("modifyPrivateCredentials").
 - 
Subjectpublic Subject(boolean readOnly, Set<? extends Principal> principals, Set<?> pubCredentials, Set<?> privCredentials)Create an instance of aSubjectwith Principals and credentials.The Principals and credentials from the specified Sets are copied into newly constructed Sets. These newly created Sets check whether this Subjecthas been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions. These Sets also prohibit null elements, and attempts to add, query, or remove a null element will result in aNullPointerException.To modify the Principals Set, the caller must have AuthPermission("modifyPrincipals"). To modify the public credential Set, the caller must haveAuthPermission("modifyPublicCredentials"). To modify the private credential Set, the caller must haveAuthPermission("modifyPrivateCredentials").- Parameters:
- readOnly- true if the- Subjectis to be read-only, and false otherwise.
- principals- the- Setof Principals to be associated with this- Subject.
- pubCredentials- the- Setof public credentials to be associated with this- Subject.
- privCredentials- the- Setof private credentials to be associated with this- Subject.
- Throws:
- NullPointerException- if the specified- principals,- pubCredentials, or- privCredentialsare- null, or a null value exists within any of these three Sets.
 
 
- 
 - 
Method Detail- 
setReadOnlypublic void setReadOnly() Set thisSubjectto be read-only.Modifications (additions and removals) to this Subject's PrincipalSetand credential Sets will be disallowed. Thedestroyoperation on this Subject's credentials will still be permitted.Subsequent attempts to modify the Subject's Principaland credential Sets will result in anIllegalStateExceptionbeing thrown. Also, once aSubjectis read-only, it can not be reset to being writable again.- Throws:
- SecurityException- if a security manager is installed and the caller does not have an- AuthPermission("setReadOnly")permission to set this- Subjectto be read-only.
 
 - 
isReadOnlypublic boolean isReadOnly() Query whether thisSubjectis read-only.- Returns:
- true if this Subjectis read-only, false otherwise.
 
 - 
getSubjectpublic static Subject getSubject(AccessControlContext acc) Get theSubjectassociated with the providedAccessControlContext.The AccessControlContextmay contain many Subjects (from nesteddoAscalls). In this situation, the most recentSubjectassociated with theAccessControlContextis returned.- Parameters:
- acc- the- AccessControlContextfrom which to retrieve the- Subject.
- Returns:
- the Subjectassociated with the providedAccessControlContext, ornullif noSubjectis associated with the providedAccessControlContext.
- Throws:
- SecurityException- if a security manager is installed and the caller does not have an- AuthPermission("getSubject")permission to get the- Subject.
- NullPointerException- if the provided- AccessControlContextis- null.
 
 - 
doAspublic static <T> T doAs(Subject subject, PrivilegedAction<T> action) Perform work as a particularSubject.This method first retrieves the current Thread's AccessControlContextviaAccessController.getContext, and then instantiates a newAccessControlContextusing the retrieved context along with a newSubjectDomainCombiner(constructed using the providedSubject). Finally, this method invokesAccessController.doPrivileged, passing it the providedPrivilegedAction, as well as the newly constructedAccessControlContext.- Type Parameters:
- T- the type of the value returned by the PrivilegedAction's- runmethod.
- Parameters:
- subject- the- Subjectthat the specified- actionwill run as. This parameter may be- null.
- action- the code to be run as the specified- Subject.
- Returns:
- the value returned by the PrivilegedAction's
                  runmethod.
- Throws:
- NullPointerException- if the- PrivilegedActionis- null.
- SecurityException- if a security manager is installed and the caller does not have an- AuthPermission("doAs")permission to invoke this method.
 
 - 
doAspublic static <T> T doAs(Subject subject, PrivilegedExceptionAction<T> action) throws PrivilegedActionException Perform work as a particularSubject.This method first retrieves the current Thread's AccessControlContextviaAccessController.getContext, and then instantiates a newAccessControlContextusing the retrieved context along with a newSubjectDomainCombiner(constructed using the providedSubject). Finally, this method invokesAccessController.doPrivileged, passing it the providedPrivilegedExceptionAction, as well as the newly constructedAccessControlContext.- Type Parameters:
- T- the type of the value returned by the PrivilegedExceptionAction's- runmethod.
- Parameters:
- subject- the- Subjectthat the specified- actionwill run as. This parameter may be- null.
- action- the code to be run as the specified- Subject.
- Returns:
- the value returned by the
                  PrivilegedExceptionAction's runmethod.
- Throws:
- PrivilegedActionException- if the- PrivilegedExceptionAction.runmethod throws a checked exception.
- NullPointerException- if the specified- PrivilegedExceptionActionis- null.
- SecurityException- if a security manager is installed and the caller does not have an- AuthPermission("doAs")permission to invoke this method.
 
 - 
doAsPrivilegedpublic static <T> T doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc) Perform privileged work as a particularSubject.This method behaves exactly as Subject.doAs, except that instead of retrieving the current Thread'sAccessControlContext, it uses the providedAccessControlContext. If the providedAccessControlContextisnull, this method instantiates a newAccessControlContextwith an empty collection of ProtectionDomains.- Type Parameters:
- T- the type of the value returned by the PrivilegedAction's- runmethod.
- Parameters:
- subject- the- Subjectthat the specified- actionwill run as. This parameter may be- null.
- action- the code to be run as the specified- Subject.
- acc- the- AccessControlContextto be tied to the specified subject and action.
- Returns:
- the value returned by the PrivilegedAction's
                  runmethod.
- Throws:
- NullPointerException- if the- PrivilegedActionis- null.
- SecurityException- if a security manager is installed and the caller does not have a- AuthPermission("doAsPrivileged")permission to invoke this method.
 
 - 
doAsPrivilegedpublic static <T> T doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc) throws PrivilegedActionException Perform privileged work as a particularSubject.This method behaves exactly as Subject.doAs, except that instead of retrieving the current Thread'sAccessControlContext, it uses the providedAccessControlContext. If the providedAccessControlContextisnull, this method instantiates a newAccessControlContextwith an empty collection of ProtectionDomains.- Type Parameters:
- T- the type of the value returned by the PrivilegedExceptionAction's- runmethod.
- Parameters:
- subject- the- Subjectthat the specified- actionwill run as. This parameter may be- null.
- action- the code to be run as the specified- Subject.
- acc- the- AccessControlContextto be tied to the specified subject and action.
- Returns:
- the value returned by the
                  PrivilegedExceptionAction's runmethod.
- Throws:
- PrivilegedActionException- if the- PrivilegedExceptionAction.runmethod throws a checked exception.
- NullPointerException- if the specified- PrivilegedExceptionActionis- null.
- SecurityException- if a security manager is installed and the caller does not have a- AuthPermission("doAsPrivileged")permission to invoke this method.
 
 - 
getPrincipalspublic Set<Principal> getPrincipals() Return theSetof Principals associated with thisSubject. EachPrincipalrepresents an identity for thisSubject.The returned Setis backed by this Subject's internalPrincipalSet. Any modification to the returnedSetaffects the internalPrincipalSetas well.If a security manager is installed, the caller must have a AuthPermission("modifyPrincipals")permission to modify the returned set, or aSecurityExceptionwill be thrown.- Returns:
- the Setof Principals associated with thisSubject.
 
 - 
getPrincipalspublic <T extends Principal> Set<T> getPrincipals(Class<T> c) Return aSetof Principals associated with thisSubjectthat are instances or subclasses of the specifiedClass.The returned Setis not backed by this Subject's internalPrincipalSet. A newSetis created and returned for each method invocation. Modifications to the returnedSetwill not affect the internalPrincipalSet.- Type Parameters:
- T- the type of the class modeled by- c
- Parameters:
- c- the returned- Setof Principals will all be instances of this class.
- Returns:
- a Setof Principals that are instances of the specifiedClass.
- Throws:
- NullPointerException- if the specified- Classis- null.
 
 - 
getPublicCredentialspublic Set<Object> getPublicCredentials() Return theSetof public credentials held by thisSubject.The returned Setis backed by this Subject's internal public CredentialSet. Any modification to the returnedSetaffects the internal public CredentialSetas well.If a security manager is installed, the caller must have a AuthPermission("modifyPublicCredentials")permission to modify the returned set, or aSecurityExceptionwill be thrown.- Returns:
- a Setof public credentials held by thisSubject.
 
 - 
getPrivateCredentialspublic Set<Object> getPrivateCredentials() Return theSetof private credentials held by thisSubject.The returned Setis backed by this Subject's internal private CredentialSet. Any modification to the returnedSetaffects the internal private CredentialSetas well.If a security manager is installed, the caller must have a AuthPermission("modifyPrivateCredentials")permission to modify the returned set, or aSecurityExceptionwill be thrown.While iterating through the Set, aSecurityExceptionis thrown if a security manager is installed and the caller does not have aPrivateCredentialPermissionto access a particular Credential. TheIteratoris nevertheless advanced to the next element in theSet.- Returns:
- a Setof private credentials held by thisSubject.
 
 - 
getPublicCredentialspublic <T> Set<T> getPublicCredentials(Class<T> c) Return aSetof public credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.The returned Setis not backed by this Subject's internal public CredentialSet. A newSetis created and returned for each method invocation. Modifications to the returnedSetwill not affect the internal public CredentialSet.- Type Parameters:
- T- the type of the class modeled by- c
- Parameters:
- c- the returned- Setof public credentials will all be instances of this class.
- Returns:
- a Setof public credentials that are instances of the specifiedClass.
- Throws:
- NullPointerException- if the specified- Classis- null.
 
 - 
getPrivateCredentialspublic <T> Set<T> getPrivateCredentials(Class<T> c) Return aSetof private credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.If a security manager is installed, the caller must have a PrivateCredentialPermissionto access all of the requested Credentials, or aSecurityExceptionwill be thrown.The returned Setis not backed by this Subject's internal private CredentialSet. A newSetis created and returned for each method invocation. Modifications to the returnedSetwill not affect the internal private CredentialSet.- Type Parameters:
- T- the type of the class modeled by- c
- Parameters:
- c- the returned- Setof private credentials will all be instances of this class.
- Returns:
- a Setof private credentials that are instances of the specifiedClass.
- Throws:
- NullPointerException- if the specified- Classis- null.
 
 - 
equalspublic boolean equals(Object o) Compares the specified Object with thisSubjectfor equality. Returns true if the given object is also a Subject and the twoSubjectinstances are equivalent. More formally, twoSubjectinstances are equal if theirPrincipalandCredentialSets are equal.- Overrides:
- equalsin class- Object
- Parameters:
- o- Object to be compared for equality with this- Subject.
- Returns:
- true if the specified Object is equal to this
          Subject.
- Throws:
- SecurityException- if a security manager is installed and the caller does not have a- PrivateCredentialPermissionpermission to access the private credentials for this- Subjector the provided- Subject.
- See Also:
- Object.hashCode(),- HashMap
 
 - 
toStringpublic String toString() Return the String representation of thisSubject.
 - 
hashCodepublic int hashCode() Returns a hashcode for thisSubject.- Overrides:
- hashCodein class- Object
- Returns:
- a hashcode for this Subject.
- Throws:
- SecurityException- if a security manager is installed and the caller does not have a- PrivateCredentialPermissionpermission to access this Subject's private credentials.
- See Also:
- Object.equals(java.lang.Object),- System.identityHashCode(java.lang.Object)
 
 
- 
 
-