Class Subject
- All Implemented Interfaces:
- Serializable
 A Subject represents 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 Principal
 within the Subject.  Principals simply bind names to a
 Subject.  For example, a Subject that happens
 to be a person, Alice, might have two Principals:
 one which binds "Alice Bar", the name on her driver license,
 to the Subject, and another which binds,
 "999-99-9999", the number on her student identification card,
 to the Subject.  Both Principals refer to the same
 Subject even though each has a different name.
 
 A Subject may 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 credential
 Set.  Credentials intended to be shared, such as
 public key certificates or Kerberos server tickets are stored
 within a public credential Set.
 
 To retrieve all the Principals associated with a Subject,
 invoke the getPrincipals method.  To retrieve
 all the public or private credentials belonging to a Subject,
 invoke the getPublicCredentials method or
 getPrivateCredentials method, respectively.
 To modify the returned Set of Principals and credentials,
 use the methods defined in the Set class.
 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 Subject class implements Serializable.
 While the Principals associated with the Subject are serialized,
 the credentials associated with the Subject are not.
 Note that the java.security.Principal class
 does not implement Serializable.  Therefore, all concrete
 Principal implementations associated with Subjects
 must implement Serializable.
 
Deprecated Methods and Replacements
The following methods in this class for user-based authorization that are dependent on Security Manager APIs are deprecated for removal:
- getSubject(AccessControlContext)
- doAs(Subject, PrivilegedAction)
- doAs(Subject, PrivilegedExceptionAction)
- doAsPrivileged(Subject, PrivilegedAction, AccessControlContext)
- doAsPrivileged(Subject, PrivilegedExceptionAction, AccessControlContext)
current() and callAs(Subject, Callable)
 are replacements for these methods, where current is equivalent to
 getSubject(AccessController.getContext()) (as originally specified)
 and callAs is similar to doAs except that the
 input type and exceptions thrown are slightly different.
  A doAs or callAs call
 binds a Subject object to the period of execution of an action,
 and the subject can be retrieved using the current method inside
 the action. This subject can be inherited by child threads if they are
 started and terminate within the execution of its parent thread using
 structured concurrency.
- Since:
- 1.4
- See Also:
- 
Constructor SummaryConstructorsConstructorDescriptionSubject()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 SummaryModifier and TypeMethodDescriptionstatic <T> TExecutes aCallablewithsubjectas the current subject.static Subjectcurrent()Returns the current subject.static <T> TdoAs(Subject subject, PrivilegedAction<T> action) Deprecated, for removal: This API element is subject to removal in a future version.static <T> TdoAs(Subject subject, PrivilegedExceptionAction<T> action) Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedExceptionActionwith privileges enabled.static <T> TdoAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc) Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedActionwith privileges enabled and restricted by the specifiedAccessControlContext.static <T> TdoAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc) Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedExceptionActionwith privileges enabled and restricted by the specifiedAccessControlContext.booleanCompares the specified Object with thisSubjectfor equality.Return theSetof Principals associated with thisSubject.getPrincipals(Class<T> c) Return aSetof Principals associated with thisSubjectthat are instances or subclasses of the specifiedClass.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.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 SubjectDeprecated, for removal: This API element is subject to removal in a future version.This method used to get the subject associated with the providedAccessControlContext, which was only useful in conjunction with the Security Manager, which is no longer supported.inthashCode()Returns a hashcode for thisSubject.booleanQuery whether thisSubjectis read-only.voidSet thisSubjectto be read-only.toString()Return the String representation of thisSubject.
- 
Constructor Details- 
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. These Sets also prohibit null elements, and attempts to add, query, or remove a null element will result in aNullPointerException.
- 
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. These Sets also prohibit null elements, and attempts to add, query, or remove a null element will result in aNullPointerException.- 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 Details- 
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.
- 
isReadOnlypublic boolean isReadOnly()Query whether thisSubjectis read-only.- Returns:
- true if this Subjectis read-only, false otherwise.
 
- 
getSubjectDeprecated, for removal: This API element is subject to removal in a future version.This method used to get the subject associated with the providedAccessControlContext, which was only useful in conjunction with the Security Manager, which is no longer supported. This method has been changed to always throwUnsupportedOperationException. A replacement API namedcurrent()has been added which can be used to obtain the current subject. There is no replacement for the Security Manager.ThrowsUnsupportedOperationException. A replacement API namedcurrent()has been added which can be used to obtain the current subject.- Parameters:
- acc- ignored
- Returns:
- n/a
- Throws:
- UnsupportedOperationException- always
- See Also:
 
- 
currentReturns the current subject.The current subject is installed by the callAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>)method. WhencallAs(subject, action)is called,actionis executed withsubjectas its current subject which can be retrieved by this method. Afteractionis finished, the current subject is reset to its previous value. The current subject isnullbefore the first call ofcallAs().This method returns the Subjectbound to the period of the execution of the current thread.- Returns:
- the current subject, or nullif a current subject is not installed or the current subject is set tonull.
- Since:
- 18
- See Also:
 
- 
callAsExecutes aCallablewithsubjectas the current subject.This method launches actionand bindssubjectto the period of its execution.- Type Parameters:
- T- the type of value returned by the- callmethod of- action
- Parameters:
- subject- the- Subjectthat the specified- actionwill run as. This parameter may be- null.
- action- the code to be run with- subjectas its current subject. Must not be- null.
- Returns:
- the value returned by the callmethod ofaction
- Throws:
- NullPointerException- if- actionis- null
- CompletionException- if- action.call()throws an exception. The cause of the- CompletionExceptionis set to the exception thrown by- action.call().
- Since:
- 18
- See Also:
 
- 
doAs@Deprecated(since="18", forRemoval=true) public static <T> T doAs(Subject subject, PrivilegedAction<T> action) Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedActionwith privileges enabled. Running the action with privileges enabled was only useful in conjunction with the Security Manager, which is no longer supported. This method has been changed to launch the action as is and bind the subject to the period of its execution. A replacement API namedcallAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>)has been added which can be used to perform the same work. There is no replacement for the Security Manager.Perform work as a particularSubject.This method launches actionand bindssubjectto the period of its execution.- 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.
- See Also:
 
- 
doAs@Deprecated(since="18", forRemoval=true) public static <T> T doAs(Subject subject, PrivilegedExceptionAction<T> action) throws PrivilegedActionException Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedExceptionActionwith privileges enabled. Running the action with privileges enabled was only useful in conjunction with the Security Manager, which is no longer supported. This method has been changed to launch the action as is and bind the subject to the period of its execution. A replacement API namedcallAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>)has been added which can be used to perform the same work. There is no replacement for the Security Manager.Perform work as a particularSubject.This method launches actionand bindssubjectto the period of its execution.- 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.
- See Also:
 
- 
doAsPrivileged@Deprecated(since="17", forRemoval=true) public static <T> T doAsPrivileged(Subject subject, PrivilegedAction<T> action, AccessControlContext acc) Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedActionwith privileges enabled and restricted by the specifiedAccessControlContext. Running the action with privileges enabled was only useful in conjunction with the Security Manager, which is no longer supported. This method has been changed to ignore theAccessControlContextand launch the action as is and bind the subject to the period of its execution. A replacement API namedcallAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>)has been added which can be used to perform the same work. There is no replacement for the Security Manager.Perform work as a particularSubject.This method launches actionand bindssubjectto the period of its execution.- 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- ignored
- Returns:
- the value returned by the PrivilegedAction's
                  runmethod.
- Throws:
- NullPointerException- if the- PrivilegedActionis- null.
- See Also:
 
- 
doAsPrivileged@Deprecated(since="17", forRemoval=true) public static <T> T doAsPrivileged(Subject subject, PrivilegedExceptionAction<T> action, AccessControlContext acc) throws PrivilegedActionException Deprecated, for removal: This API element is subject to removal in a future version.This method originally performed the specifiedPrivilegedExceptionActionwith privileges enabled and restricted by the specifiedAccessControlContext. Running the action with privileges enabled was only useful in conjunction with the Security Manager, which is no longer supported. This method has been changed to ignore theAccessControlContextand launch the action as is and bind the subject to the period of its execution. A replacement API namedcallAs(javax.security.auth.Subject, java.util.concurrent.Callable<T>)has been added which can be used to perform the same work. There is no replacement for the Security Manager.Perform work as a particularSubject.This method launches actionand bindssubjectto the period of its execution.- 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- ignored
- 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.
- See Also:
 
- 
getPrincipalsReturn 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.- Returns:
- the Setof Principals associated with thisSubject.
 
- 
getPrincipalsReturn 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.
 
- 
getPublicCredentialsReturn 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.- Returns:
- a Setof public credentials held by thisSubject.
 
- 
getPrivateCredentialsReturn 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.- Returns:
- a Setof private credentials held by thisSubject.
 
- 
getPublicCredentialsReturn 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.
 
- 
getPrivateCredentialsReturn aSetof private credentials associated with thisSubjectthat are instances or subclasses of the specifiedClass.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.
 
- 
equalsCompares 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.
- 
toString
- 
hashCode
 
- 
PrivilegedActionwith privileges enabled.