<p> A {@code 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).
<p> Subjects may potentially have multiple identities.
Each identity is represented as a {@code Principal}
within the {@code Subject}. Principals simply bind names to a
{@code Subject}. For example, a {@code 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 {@code Subject}, and another which binds,
"999-99-9999", the number on her student identification card,
to the {@code Subject}. Both Principals refer to the same
{@code Subject} even though each has a different name.
<p> A {@code 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
{@code Set}. Credentials intended to be shared, such as
key certificates or Kerberos server tickets are stored
within a credential {@code Set}. Different permissions
are required to access and modify the different credential Sets.
<p> To retrieve all the Principals associated with a {@code Subject},
invoke the {@code getPrincipals} method. To retrieve
all the or private credentials belonging to a {@code Subject},
invoke the {@code getPublicCredentials} method or
{@code getPrivateCredentials} method, respectively.
To modify the returned {@code Set} of Principals and credentials,
use the methods defined in the {@code Set} class.
For example:
<pre>
Subject subject;
Principal principal;
Object credential;
// add a Principal and credential to the Subject
subject.getPrincipals().add(principal);
subject.getPublicCredentials().add(credential);
</pre>
<p> This {@code Subject} class implements {@code Serializable}.
While the Principals associated with the {@code Subject} are serialized,
the credentials associated with the {@code Subject} are not.
Note that the {@code java.security.Principal} class
does not implement {@code Serializable}. Therefore all concrete
{@code Principal} implementations associated with Subjects
must implement {@code Serializable}.
<p> A {@code 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).
<p> Subjects may potentially have multiple identities. Each identity is represented as a {@code Principal} within the {@code Subject}. Principals simply bind names to a {@code Subject}. For example, a {@code 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 {@code Subject}, and another which binds, "999-99-9999", the number on her student identification card, to the {@code Subject}. Both Principals refer to the same {@code Subject} even though each has a different name.
<p> A {@code 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 {@code Set}. Credentials intended to be shared, such as key certificates or Kerberos server tickets are stored within a credential {@code Set}. Different permissions are required to access and modify the different credential Sets.
<p> To retrieve all the Principals associated with a {@code Subject}, invoke the {@code getPrincipals} method. To retrieve all the or private credentials belonging to a {@code Subject}, invoke the {@code getPublicCredentials} method or {@code getPrivateCredentials} method, respectively. To modify the returned {@code Set} of Principals and credentials, use the methods defined in the {@code Set} class. For example: <pre> Subject subject; Principal principal; Object credential;
// add a Principal and credential to the Subject subject.getPrincipals().add(principal); subject.getPublicCredentials().add(credential); </pre>
<p> This {@code Subject} class implements {@code Serializable}. While the Principals associated with the {@code Subject} are serialized, the credentials associated with the {@code Subject} are not. Note that the {@code java.security.Principal} class does not implement {@code Serializable}. Therefore all concrete {@code Principal} implementations associated with Subjects must implement {@code Serializable}.
@see java.security.Principal @see java.security.DomainCombiner