FileDocCategorySizeDatePackage
Subject.javaAPI DocAndroid 1.5 API27003Wed May 06 22:41:02 BST 2009javax.security.auth

Subject

public final class Subject extends Object implements Serializable
The central class of the {@code javax.security.auth} package representing an authenticated user or entity (both referred to as "subject"). IT defines also the static methods that allow code to be run, and do modifications according to the subject's permissions.

A subject has the following features:

  • A set of {@code Principal} objects specifying the identities bound to a {@code Subject} that distinguish it.
  • Credentials (public and private) such as certificates, keys, or authentication proofs such as tickets

since
Android 1.0

Fields Summary
private static final long
serialVersionUID
private static final AuthPermission
_AS
private static final AuthPermission
_AS_PRIVILEGED
private static final AuthPermission
_SUBJECT
private static final AuthPermission
_PRINCIPALS
private static final AuthPermission
_PRIVATE_CREDENTIALS
private static final AuthPermission
_PUBLIC_CREDENTIALS
private static final AuthPermission
_READ_ONLY
private final Set
principals
private boolean
readOnly
private transient SecureSet
privateCredentials
private transient SecureSet
publicCredentials
Constructors Summary
public Subject()
The default constructor initializing the sets of public and private credentials and principals with the empty set.

    
                          
      
        super();
        principals = new SecureSet<Principal>(_PRINCIPALS);
        publicCredentials = new SecureSet<Object>(_PUBLIC_CREDENTIALS);
        privateCredentials = new SecureSet<Object>(_PRIVATE_CREDENTIALS);

        readOnly = false;
    
public Subject(boolean readOnly, Set subjPrincipals, Set pubCredentials, Set privCredentials)
The constructor for the subject, setting its public and private credentials and principals according to the arguments.

param
readOnly {@code true} if this {@code Subject} is read-only, thus preventing any modifications to be done.
param
subjPrincipals the set of Principals that are attributed to this {@code Subject}.
param
pubCredentials the set of public credentials that distinguish this {@code Subject}.
param
privCredentials the set of private credentials that distinguish this {@code Subject}.


        if (subjPrincipals == null || pubCredentials == null || privCredentials == null) {
            throw new NullPointerException();
        }

        principals = new SecureSet<Principal>(_PRINCIPALS, subjPrincipals);
        publicCredentials = new SecureSet<Object>(_PUBLIC_CREDENTIALS, pubCredentials);
        privateCredentials = new SecureSet<Object>(_PRIVATE_CREDENTIALS, privCredentials);

        this.readOnly = readOnly;
    
Methods Summary
private static voidcheckPermission(java.security.Permission p)

        SecurityManager sm = System.getSecurityManager();
        if (sm != null) {
            sm.checkPermission(p);
        }
    
private voidcheckState()

        if (readOnly) {
            throw new IllegalStateException(Messages.getString("auth.0A")); //$NON-NLS-1$
        }
    
public static java.lang.ObjectdoAs(javax.security.auth.Subject subject, java.security.PrivilegedAction action)
Runs the code defined by {@code action} using the permissions granted to the {@code Subject} itself and to the code as well.

param
subject the distinguished {@code Subject}.
param
action the code to be run.
return
the {@code Object} returned when running the {@code action}.


        checkPermission(_AS);

        return doAs_PrivilegedAction(subject, action, AccessController.getContext());
    
public static java.lang.ObjectdoAs(javax.security.auth.Subject subject, java.security.PrivilegedExceptionAction action)
Runs the code defined by {@code action} using the permissions granted to the subject and to the code itself.

param
subject the distinguished {@code Subject}.
param
action the code to be run.
return
the {@code Object} returned when running the {@code action}.
throws
PrivilegedActionException if running the {@code action} throws an exception.


        checkPermission(_AS);

        return doAs_PrivilegedExceptionAction(subject, action, AccessController.getContext());
    
public static java.lang.ObjectdoAsPrivileged(javax.security.auth.Subject subject, java.security.PrivilegedAction action, java.security.AccessControlContext context)
Run the code defined by {@code action} using the permissions granted to the {@code Subject} and to the code itself, additionally providing a more specific context.

param
subject the distinguished {@code Subject}.
param
action the code to be run.
param
context the specific context in which the {@code action} is invoked. if {@code null} a new {@link AccessControlContext} is instantiated.
return
the {@code Object} returned when running the {@code action}.


        checkPermission(_AS_PRIVILEGED);

        if (context == null) {
            return doAs_PrivilegedAction(subject, action, new AccessControlContext(
                    new ProtectionDomain[0]));
        }
        return doAs_PrivilegedAction(subject, action, context);
    
public static java.lang.ObjectdoAsPrivileged(javax.security.auth.Subject subject, java.security.PrivilegedExceptionAction action, java.security.AccessControlContext context)
Runs the code defined by {@code action} using the permissions granted to the subject and to the code itself, additionally providing a more specific context.

param
subject the distinguished {@code Subject}.
param
action the code to be run.
param
context the specific context in which the {@code action} is invoked. if {@code null} a new {@link AccessControlContext} is instantiated.
return
the {@code Object} returned when running the {@code action}.
throws
PrivilegedActionException if running the {@code action} throws an exception.


        checkPermission(_AS_PRIVILEGED);

        if (context == null) {
            return doAs_PrivilegedExceptionAction(subject, action,
                    new AccessControlContext(new ProtectionDomain[0]));
        }
        return doAs_PrivilegedExceptionAction(subject, action, context);
    
private static java.lang.ObjectdoAs_PrivilegedAction(javax.security.auth.Subject subject, java.security.PrivilegedAction action, java.security.AccessControlContext context)


        AccessControlContext newContext;

        final SubjectDomainCombiner combiner;
        if (subject == null) {
            // performance optimization
            // if subject is null there is nothing to combine
            combiner = null;
        } else {
            combiner = new SubjectDomainCombiner(subject);
        }

        PrivilegedAction dccAction = new PrivilegedAction() {
            public Object run() {

                return new AccessControlContext(context, combiner);
            }
        };

        newContext = (AccessControlContext) AccessController.doPrivileged(dccAction);

        return AccessController.doPrivileged(action, newContext);
    
private static java.lang.ObjectdoAs_PrivilegedExceptionAction(javax.security.auth.Subject subject, java.security.PrivilegedExceptionAction action, java.security.AccessControlContext context)


        AccessControlContext newContext;

        final SubjectDomainCombiner combiner;
        if (subject == null) {
            // performance optimization
            // if subject is null there is nothing to combine
            combiner = null;
        } else {
            combiner = new SubjectDomainCombiner(subject);
        }

        PrivilegedAction<AccessControlContext> dccAction = new PrivilegedAction<AccessControlContext>() {
            public AccessControlContext run() {
                return new AccessControlContext(context, combiner);
            }
        };

        newContext = AccessController.doPrivileged(dccAction);

        return AccessController.doPrivileged(action, newContext);
    
public booleanequals(java.lang.Object obj)
Checks two Subjects for equality. More specifically if the principals, public and private credentials are equal, equality for two {@code Subjects} is implied.

param
obj the {@code Object} checked for equality with this {@code Subject}.
return
{@code true} if the specified {@code Subject} is equal to this one.


        if (this == obj) {
            return true;
        }

        if (obj == null || this.getClass() != obj.getClass()) {
            return false;
        }

        Subject that = (Subject) obj;

        if (principals.equals(that.principals)
                && publicCredentials.equals(that.publicCredentials)
                && privateCredentials.equals(that.privateCredentials)) {
            return true;
        }
        return false;
    
public java.util.SetgetPrincipals()
Returns this {@code Subject}'s {@link Principal}.

return
this {@code Subject}'s {@link Principal}.

        return principals;
    
public java.util.SetgetPrincipals(java.lang.Class c)
Returns this {@code Subject}'s {@link Principal} which is a subclass of the {@code Class} provided.

param
c the {@code Class} as a criteria which the {@code Principal} returned must satisfy.
return
this {@code Subject}'s {@link Principal}. Modifications to the returned set of {@code Principal}s do not affect this {@code Subject}'s set.

        return ((SecureSet<Principal>) principals).get(c);
    
public java.util.SetgetPrivateCredentials()
Returns the private credentials associated with this {@code Subject}.

return
the private credentials associated with this {@code Subject}.

        return privateCredentials;
    
public java.util.SetgetPrivateCredentials(java.lang.Class c)
Returns this {@code Subject}'s private credentials which are a subclass of the {@code Class} provided.

param
c the {@code Class} as a criteria which the private credentials returned must satisfy.
return
this {@code Subject}'s private credentials. Modifications to the returned set of credentials do not affect this {@code Subject}'s credentials.

        return privateCredentials.get(c);
    
public java.util.SetgetPublicCredentials()
Returns the public credentials associated with this {@code Subject}.

return
the public credentials associated with this {@code Subject}.

        return publicCredentials;
    
public java.util.SetgetPublicCredentials(java.lang.Class c)
Returns this {@code Subject}'s public credentials which are a subclass of the {@code Class} provided.

param
c the {@code Class} as a criteria which the public credentials returned must satisfy.
return
this {@code Subject}'s public credentials. Modifications to the returned set of credentials do not affect this {@code Subject}'s credentials.

        return publicCredentials.get(c);
    
public static javax.security.auth.SubjectgetSubject(java.security.AccessControlContext context)
Returns the {@code Subject} that was last associated with the {@code context} provided as argument.

param
context the {@code context} that was associated with the {@code Subject}.
return
the {@code Subject} that was last associated with the {@code context} provided as argument.

        checkPermission(_SUBJECT);
        if (context == null) {
            throw new NullPointerException(Messages.getString("auth.09")); //$NON-NLS-1$
        }
        PrivilegedAction<DomainCombiner> action = new PrivilegedAction<DomainCombiner>() {
            public DomainCombiner run() {
                return context.getDomainCombiner();
            }
        };
        DomainCombiner combiner = AccessController.doPrivileged(action);

        if ((combiner == null) || !(combiner instanceof SubjectDomainCombiner)) {
            return null;
        }
        return ((SubjectDomainCombiner) combiner).getSubject();
    
public inthashCode()
Returns a hash code of this {@code Subject}.

return
a hash code of this {@code Subject}.

        return principals.hashCode() + privateCredentials.hashCode()
                + publicCredentials.hashCode();
    
public booleanisReadOnly()
Returns whether this {@code Subject} is read-only or not.

return
whether this {@code Subject} is read-only or not.

        return readOnly;
    
private voidreadObject(java.io.ObjectInputStream in)


        in.defaultReadObject();

        publicCredentials = new SecureSet<Object>(_PUBLIC_CREDENTIALS);
        privateCredentials = new SecureSet<Object>(_PRIVATE_CREDENTIALS);
    
public voidsetReadOnly()
Prevents from modifications being done to the credentials and {@link Principal} sets. After setting it to read-only this {@code Subject} can not be made writable again. The destroy method on the credentials still works though.

        checkPermission(_READ_ONLY);

        readOnly = true;
    
public java.lang.StringtoString()
Returns a {@code String} representation of this {@code Subject}.

return
a {@code String} representation of this {@code Subject}.


        StringBuffer buf = new StringBuffer("Subject:\n"); //$NON-NLS-1$

        Iterator<?> it = principals.iterator();
        while (it.hasNext()) {
            buf.append("\tPrincipal: "); //$NON-NLS-1$
            buf.append(it.next());
            buf.append('\n");
        }

        it = publicCredentials.iterator();
        while (it.hasNext()) {
            buf.append("\tPublic Credential: "); //$NON-NLS-1$
            buf.append(it.next());
            buf.append('\n");
        }

        int offset = buf.length() - 1;
        it = privateCredentials.iterator();
        try {
            while (it.hasNext()) {
                buf.append("\tPrivate Credential: "); //$NON-NLS-1$
                buf.append(it.next());
                buf.append('\n");
            }
        } catch (SecurityException e) {
            buf.delete(offset, buf.length());
            buf.append("\tPrivate Credentials: no accessible information\n"); //$NON-NLS-1$
        }
        return buf.toString();
    
private voidwriteObject(java.io.ObjectOutputStream out)

        out.defaultWriteObject();