java.lang.Object | +--javax.security.auth.Subject
ASubject 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 aPrincipal within theSubject. Principals simply bind names to aSubject. For example, aSubject that 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 sameSubject even though each has a different name.
ASubject 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 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 aSubject, invoke thegetPrincipals method. To retrieve all the public or private credentials belonging to aSubject, invoke thegetPublicCredentials method orgetPrivateCredentials method, respectively. To modify the returnedSet of Principals and credentials, use the methods defined in theSet class. For example:
Subject subject;Principal principal;Object credential;// add a Principal and credential to the Subjectsubject.getPrincipals().add(principal);subject.getPublicCredentials().add(credential);
ThisSubject class implementsSerializable. While the Principals associated with theSubject are serialized, the credentials associated with theSubject are not. Note that thejava.security.Principal class does not implementSerializable. Therefore all concretePrincipal implementations associated with Subjects must implementSerializable.
Principal,DomainCombiner,Serialized FormSubject()Create an instance of a Subject with an emptySet of Principals and empty Sets of public and private credentials. | |
Subject(boolean readOnly, java.util.Set principals, java.util.Set pubCredentials, java.util.Set privCredentials)Create an instance of a Subject with the specified Sets of Principals and credentials. | |
doAs(Subject subject, java.security.PrivilegedAction action)Perform work as a particular Subject. | |
doAs(Subject subject, java.security.PrivilegedExceptionAction action)Perform work as a particular Subject. | |
doAsPrivileged(Subject subject, java.security.PrivilegedAction action, java.security.AccessControlContext acc)Perform privileged work as a particular Subject. | |
doAsPrivileged(Subject subject, java.security.PrivilegedExceptionAction action, java.security.AccessControlContext acc)Perform privileged work as a particular Subject. | |
equals(java.lang.Object o)Compares the specified Object with this Subject for equality. | |
getPrincipals()Return the Set of Principals associated with thisSubject. | |
getPrincipals(java.lang.Class c)Return a Set of Principals associated with thisSubject that are instances or subclasses of the specifiedClass. | |
getPrivateCredentials()Return the Set of private credentials held by thisSubject. | |
getPrivateCredentials(java.lang.Class c)Return a Set of private credentials associated with thisSubject that are instances or subclasses of the specifiedClass. | |
getPublicCredentials()Return the Set of public credentials held by thisSubject. | |
getPublicCredentials(java.lang.Class c)Return a Set of public credentials associated with thisSubject that are instances or subclasses of the specifiedClass. | |
getSubject(java.security.AccessControlContext acc)Get the Subject associated with the providedAccessControlContext. | |
hashCode()Returns a hashcode for this Subject. | |
isReadOnly()Query whether this Subject is read-only. | |
setReadOnly()Set this Subject to be read-only. | |
toString()Return the String representation of this Subject. | |
| Methods inherited from class java.lang.Object |
clone, finalize, getClass, notify, notifyAll, wait, wait, wait |
publicSubject()
Subject with an emptySet of Principals and empty Sets of public and private credentials. The newly constructed Sets check whether thisSubject has been set read-only before permitting subsequent modifications. The newly created Sets also prevent illegal modifications by ensuring that callers have sufficient permissions (to modify the Principals Set, the caller must haveAuthPermission("modifyPrincipals"), for example).
publicSubject(boolean readOnly, java.util.Set principals, java.util.Set pubCredentials, java.util.Set privCredentials)
Subject with the specified Sets of Principals and credentials. The specified Sets must check whether thisSubject has been set read-only before permitting subsequent modifications. The specified Sets must also prevent illegal modifications by ensuring that callers have sufficient permissions.
readOnly - true if theSubject is to be read-only,and false otherwise.principals - theSet of Principalsto be associated with thisSubject.pubCredentials - theSet of public credentialsto be associated with thisSubject.privCredentials - theSet of private credentialsto be associated with thisSubject.java.lang.NullPointerException - if the specifiedprincipals,pubCredentials,orprivCredentials arenull.public voidsetReadOnly()
Subject to be read-only. Modifications (additions and removals) to this Subject'sPrincipalSet and credential Sets will be disallowed. Thedestroy operation on this Subject's credentials will still be permitted.
Subsequent attempts to modify the Subject'sPrincipal and credential Sets will result in anIllegalStateException being thrown. Also, once aSubject is read-only, it can not be reset to being writable again.
java.lang.SecurityException - if the caller does not have permissionto set thisSubject to be read-only.public booleanisReadOnly()
Subject is read-only.Subject is read-only, false otherwise.public staticSubjectgetSubject(java.security.AccessControlContext acc)
Subject associated with the providedAccessControlContext. TheAccessControlContext may contain many Subjects (from nesteddoAs calls). In this situation, the most recentSubject associated with theAccessControlContext is returned.
acc - theAccessControlContext from which to retrievetheSubject.Subject associated with the providedAccessControlContext, ornullif noSubject is associatedwith the providedAccessControlContext.java.lang.SecurityException - if the caller does not have permissionto get theSubject.java.lang.NullPointerException - if the providedAccessControlContext isnull.public static java.lang.ObjectdoAs(Subject subject, java.security.PrivilegedAction action)
Subject. This method first retrieves the current Thread'sAccessControlContext viaAccessController.getContext, and then instantiates a newAccessControlContext using 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.
subject - theSubject that the specifiedaction will run as. This parametermay benull.action - the code to be run as the specifiedSubject.Object returned by the PrivilegedAction'srun method.java.lang.NullPointerException - if thePrivilegedActionisnull.java.lang.SecurityException - if the caller does not have permissionto invoke this method.public static java.lang.ObjectdoAs(Subject subject, java.security.PrivilegedExceptionAction action) throws java.security.PrivilegedActionException
Subject. This method first retrieves the current Thread'sAccessControlContext viaAccessController.getContext, and then instantiates a newAccessControlContext using 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.
subject - theSubject that the specifiedaction will run as. This parametermay benull.action - the code to be run as the specifiedSubject.Object returned by thePrivilegedExceptionAction'srun method.java.security.PrivilegedActionException - if thePrivilegedExceptionAction.runmethod throws a checked exception.java.lang.NullPointerException - if the specifiedPrivilegedExceptionAction isnull.java.lang.SecurityException - if the caller does not have permissionto invoke this method.public static java.lang.ObjectdoAsPrivileged(Subject subject, java.security.PrivilegedAction action, java.security.AccessControlContext acc)
Subject. This method behaves exactly asSubject.doAs, except that instead of retrieving the current Thread'sAccessControlContext, it uses the providedAccessControlContext. If the providedAccessControlContext isnull, this method instantiates a newAccessControlContext with an empty collection of ProtectionDomains.
subject - theSubject that the specifiedaction will run as. This parametermay benull.action - the code to be run as the specifiedSubject.acc - theAccessControlContext to be tied to thespecifiedsubject andaction.Object returned by the PrivilegedAction'srun method.java.lang.NullPointerException - if thePrivilegedActionisnull.java.lang.SecurityException - if the caller does not have permissionto invoke this method.public static java.lang.ObjectdoAsPrivileged(Subject subject, java.security.PrivilegedExceptionAction action, java.security.AccessControlContext acc) throws java.security.PrivilegedActionException
Subject. This method behaves exactly asSubject.doAs, except that instead of retrieving the current Thread'sAccessControlContext, it uses the providedAccessControlContext. If the providedAccessControlContext isnull, this method instantiates a newAccessControlContext with an empty collection of ProtectionDomains.
subject - theSubject that the specifiedaction will run as. This parametermay benull.action - the code to be run as the specifiedSubject.acc - theAccessControlContext to be tied to thespecifiedsubject andaction.Object returned by thePrivilegedExceptionAction'srun method.java.security.PrivilegedActionException - if thePrivilegedExceptionAction.runmethod throws a checked exception.java.lang.NullPointerException - if the specifiedPrivilegedExceptionAction isnull.java.lang.SecurityException - if the caller does not have permissionto invoke this method.public java.util.SetgetPrincipals()
Set of Principals associated with thisSubject. EachPrincipal represents an identity for thisSubject. The returnedSet is backed by this Subject's internalPrincipalSet. Any modification to the returnedSet affects the internalPrincipalSet as well.
Set of Principals associated with thisSubject.public java.util.SetgetPrincipals(java.lang.Class c)
Set of Principals associated with thisSubject that are instances or subclasses of the specifiedClass. The returnedSet is not backed by this Subject's internalPrincipalSet. A newSet is created and returned for each method invocation. Modifications to the returnedSet will not affect the internalPrincipalSet.
c - the returnedSet of Principals will all beinstances of this class.Set of Principals that are instances of thespecifiedClass.java.lang.NullPointerException - if the specifiedClassisnull.public java.util.SetgetPublicCredentials()
Set of public credentials held by thisSubject. The returnedSet is backed by this Subject's internal public CredentialSet. Any modification to the returnedSet affects the internal public CredentialSet as well.
Set of public credentials held by thisSubject.public java.util.SetgetPrivateCredentials()
Set of private credentials held by thisSubject. The returnedSet is backed by this Subject's internal private CredentialSet. Any modification to the returnedSet affects the internal private CredentialSet as well.
Set of private credentials held by thisSubject.public java.util.SetgetPublicCredentials(java.lang.Class c)
Set of public credentials associated with thisSubject that are instances or subclasses of the specifiedClass. The returnedSet is not backed by this Subject's internal public CredentialSet. A newSet is created and returned for each method invocation. Modifications to the returnedSet will not affect the internal public CredentialSet.
c - the returnedSet of public credentials will all beinstances of this class.Set of public credentials that are instancesof thespecifiedClass.java.lang.NullPointerException - if the specifiedClassisnull.public java.util.SetgetPrivateCredentials(java.lang.Class c)
Set of private credentials associated with thisSubject that are instances or subclasses of the specifiedClass. The returnedSet is not backed by this Subject's internal private CredentialSet. A newSet is created and returned for each method invocation. Modifications to the returnedSet will not affect the internal private CredentialSet.
c - the returnedSet of private credentials will all beinstances of this class.Set of private credentials that are instancesof thespecifiedClass.java.lang.NullPointerException - if the specifiedClassisnull.public booleanequals(java.lang.Object o)
Subject for equality. Returns true if the given object is also a Subject and the twoSubject instances are equivalent. More formally, twoSubject instances are equal if theirPrincipal andCredential Sets are equal.equals in classjava.lang.Objecto - Object to be compared for equality with thisSubject.Subject.java.lang.SecurityException - if the caller does not have permissionto access the private credentials for thisSubject,or if the caller does not have permission to access theprivate credentials for the providedSubject.public java.lang.StringtoString()
Subject.toString in classjava.lang.ObjectSubject.public inthashCode()
Subject.The hashcode is derived exclusive or-ing the hashcodes of this Subject's Principals and credentials.
If a particular credential was destroyed (credential.hashCode() throws anIllegalStateException), the hashcode for that credential is derived via:credential.getClass().toString().hashCode().
hashCode in classjava.lang.ObjectSubject.java.lang.SecurityException - if the caller does not have permissionto access this Subject's private credentials.