/*
 * Copyright 2002 Sun Microsystems, Inc. All rights reserved.
 * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package javax.security.auth;

import java.util.*;
import java.io.*;
import java.lang.reflect.*;
import java.security.AccessController;
import java.security.AccessControlContext;
import java.security.DomainCombiner;
import java.security.Permission;
import java.security.PermissionCollection;
import java.security.Principal;
import java.security.PrivilegedAction;
import java.security.PrivilegedExceptionAction;
import java.security.PrivilegedActionException;
import java.security.ProtectionDomain;

/**
 * <p> A <code>Subject</code> 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</code>
 * within the <code>Subject</code>.  Principals simply bind names to a
 * <code>Subject</code>.  For example, a <code>Subject</code> 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</code>, and another which binds,
 * "999-99-9999", the number on her student identification card,
 * to the <code>Subject</code>.  Both Principals refer to the same
 * <code>Subject</code> even though each has a different name.
 *
 * <p> A <code>Subject</code> 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</code>.  Credentials intended to be shared, such as
 * public key certificates or Kerberos server tickets are stored
 * within a public credential <code>Set</code>.  Different permissions
 * are required to access and modify the different credential Sets.
 *
 * <p> To retrieve all the Principals associated with a <code>Subject</code>,
 * invoke the <code>getPrincipals</code> method.  To retrieve
 * all the public or private credentials belonging to a <code>Subject</code>,
 * invoke the <code>getPublicCredentials</code> method or
 * <code>getPrivateCredentials</code> method, respectively.
 * To modify the returned <code>Set</code> of Principals and credentials,
 * use the methods defined in the <code>Set</code> 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</code> class implements <code>Serializable</code>.
 * While the Principals associated with the <code>Subject</code> are serialized,
 * the credentials associated with the <code>Subject</code> are not.
 * Note that the <code>java.security.Principal</code> class
 * does not implement <code>Serializable</code>.  Therefore all concrete
 * <code>Principal</code> implementations associated with Subjects
 * must implement <code>Serializable</code>.
 *
 * @version 1.105, 01/14/00
 * @see java.security.Principal
 * @see java.security.DomainCombiner
 */
public final class Subject implements java.io.Serializable {

    private static final java.util.ResourceBundle rb =
	java.util.ResourceBundle.getBundle("com.sun.security.auth.Resources");

    /**
     * A <code>Set</code> that provides a view of all of this
     * Subject's Principals
     *
     * @serial
     */
    Set principals;

    /**
     * Sets that provide a view of all of this
     * Subject's Credentials
     */
    transient Set pubCredentials;
    transient Set privCredentials;

    /**
     * Whether this Subject is read-only
     *
     * @serial
     */
    private boolean readOnly = false;

    /**
     * The constructor for the DomainCombiner (for doAs)
     * and the ClassLoader used to load it
     */
    private static Constructor combiner_constructor;
    private static ClassLoader sysClassLoader;

    private static final int PRINCIPAL_SET = 1;
    private static final int PUB_CREDENTIAL_SET = 2;
    private static final int PRIV_CREDENTIAL_SET = 3;

    /**
     * This is undocumented flexibility --
     * Developers can override the default SubjectDomainCombiner implementation
     * by specifying their own DomainCombiner implementation in the
     * combiner.provider Security property.
     *
     * <p> DomainCombiner implementations must have a public constructor
     * that takes a Subject as a single argument.
     *
     * <p> Note that this is protected with a security check.
     */
    static {

	if (sysClassLoader == null) {
	    synchronized(Subject.class) {
		if (sysClassLoader == null) {
		    sysClassLoader =
			(ClassLoader)java.security.AccessController.doPrivileged
			(new java.security.PrivilegedAction() {
			public Object run() {
    			    return ClassLoader.getSystemClassLoader();
			}
		    });

		    Class[] PARAMS = { Subject.class };
		    String combiner_class =
			(String)AccessController.doPrivileged
			(new PrivilegedAction() {
			public Object run() {
			    return java.security.Security.getProperty
					("combiner.provider");
			}
		    });
		    if (combiner_class == null) {
			combiner_class =
			"javax.security.auth.SubjectDomainCombiner";
		    } else {
			// protect this flexibility with a Security check
			java.lang.SecurityManager sm =
				System.getSecurityManager();
			if (sm != null) {
			    sm.checkPermission
				(new AuthPermission("specifyDomainCombiner"));
			}
		    }
		    try {
			Class c = Class.forName(combiner_class,
					true,
					sysClassLoader);
			combiner_constructor = c.getConstructor(PARAMS);
		    } catch (Exception e) {
			throw new SecurityException(e.toString());
		    }
		}
	    }
	}
    }

    /**
     * Create an instance of a <code>Subject</code>
     * with an empty <code>Set</code> of Principals and empty
     * Sets of public and private credentials.
     *
     * <p> The newly constructed Sets check whether this <code>Subject</code>
     * 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 have
     * <code>AuthPermission("modifyPrincipals")</code>, for example).
     */
    public Subject() {

	this.principals = new SecureSet(PRINCIPAL_SET);
	this.pubCredentials = new SecureSet(PUB_CREDENTIAL_SET);
	this.privCredentials = new SecureSet(PRIV_CREDENTIAL_SET);
    }

    /**
     * Create an instance of a <code>Subject</code> with
     * the specified Sets of Principals and credentials.
     *
     * <p> The specified Sets must check whether this <code>Subject</code>
     * has been set read-only before permitting subsequent modifications.
     * The specified Sets must also prevent illegal modifications
     * by ensuring that callers have sufficient permissions.
     *
     * <p>
     *
     * @param readOnly true if the <code>Subject</code> is to be read-only,
     *		and false otherwise. <p>
     *
     * @param principals the <code>Set</code> of Principals
     *		to be associated with this <code>Subject</code>. <p>
     *
     * @param pubCredentials the <code>Set</code> of public credentials
     *		to be associated with this <code>Subject</code>. <p>
     *
     * @param privCredentials the <code>Set</code> of private credentials
     *		to be associated with this <code>Subject</code>.
     *
     * @exception NullPointerException if the specified
     *		<code>principals</code>, <code>pubCredentials</code>,
     *		or <code>privCredentials</code> are <code>null</code>.
     */
    public Subject(boolean readOnly, Set principals,
		Set pubCredentials, Set privCredentials) {

	if (principals == null ||
	    pubCredentials == null ||
	    privCredentials == null)
	    throw new NullPointerException
		(rb.getString("invalid null input(s)"));

	this.principals = new SecureSet(PRINCIPAL_SET,
					principals);
	this.pubCredentials = new SecureSet(PUB_CREDENTIAL_SET,
					pubCredentials);
	this.privCredentials = new SecureSet(PRIV_CREDENTIAL_SET,
					privCredentials);
	this.readOnly = readOnly;
    }

    /**
     * Set this <code>Subject</code> to be read-only.
     *
     * <p> Modifications (additions and removals) to this Subject's
     * <code>Principal</code> <code>Set</code> and
     * credential Sets will be disallowed.
     * The <code>destroy</code> operation on this Subject's credentials will
     * still be permitted.
     *
     * <p> Subsequent attempts to modify the Subject's <code>Principal</code>
     * and credential Sets will result in an
     * <code>IllegalStateException</code> being thrown.
     * Also, once a <code>Subject</code> is read-only,
     * it can not be reset to being writable again.
     *
     * <p>
     *
     * @exception SecurityException if the caller does not have permission
     *		to set this <code>Subject</code> to be read-only.
     */
    public void setReadOnly() {
	java.lang.SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(new AuthPermission("setReadOnly"));
	}

	this.readOnly = true;
    }

    /**
     * Query whether this <code>Subject</code> is read-only.
     *
     * <p>
     *
     * @return true if this <code>Subject</code> is read-only, false otherwise.
     */
    public boolean isReadOnly() {
	return this.readOnly;
    }

    /**
     * Get the <code>Subject</code> associated with the provided
     * <code>AccessControlContext</code>.
     *
     * <p> The <code>AccessControlContext</code> may contain many
     * Subjects (from nested <code>doAs</code> calls).
     * In this situation, the most recent <code>Subject</code> associated
     * with the <code>AccessControlContext</code> is returned.
     *
     * <p>
     *
     * @param  acc the <code>AccessControlContext</code> from which to retrieve
     *		the <code>Subject</code>.
     *
     * @return  the <code>Subject</code> associated with the provided
     *		<code>AccessControlContext</code>, or <code>null</code>
     *		if no <code>Subject</code> is associated
     *		with the provided <code>AccessControlContext</code>.
     *
     * @exception SecurityException if the caller does not have permission
     *		to get the <code>Subject</code>. <p>
     *
     * @exception NullPointerException if the provided
     *		<code>AccessControlContext</code> is <code>null</code>.
     */
    public static Subject getSubject(final AccessControlContext acc) {

	java.lang.SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(new AuthPermission("getSubject"));
	}

	if (acc == null)
	    throw new NullPointerException
		(rb.getString("invalid null AccessControlContext provided"));

	// return the Subject from the DomainCombiner of the provided context
	return (Subject)AccessController.doPrivileged
	    (new java.security.PrivilegedAction() {
	    public Object run() {
		DomainCombiner dc = acc.getDomainCombiner();
		if (!(dc instanceof SubjectDomainCombiner))
		    return null;
		SubjectDomainCombiner sdc = (SubjectDomainCombiner)dc;
		return sdc.getSubject();
	    }
	});
    }

    /**
     * Perform work as a particular <code>Subject</code>.
     *
     * <p> This method first retrieves the current Thread's
     * <code>AccessControlContext</code> via
     * <code>AccessController.getContext</code>,
     * and then instantiates a new <code>AccessControlContext</code>
     * using the retrieved context along with a new
     * <code>SubjectDomainCombiner</code> (constructed using
     * the provided <code>Subject</code>).
     * Finally, this method invokes <code>AccessController.doPrivileged</code>,
     * passing it the provided <code>PrivilegedAction</code>,
     * as well as the newly constructed <code>AccessControlContext</code>.
     *
     * <p>
     *
     * @param subject the <code>Subject</code> that the specified
     *			<code>action</code> will run as.  This parameter
     *			may be <code>null</code>. <p>
     *
     * @param action the code to be run as the specified
     *			<code>Subject</code>. <p>
     *
     * @return the <code>Object</code> returned by the PrivilegedAction's
     *			<code>run</code> method.
     *
     * @exception NullPointerException if the <code>PrivilegedAction</code>
     *			is <code>null</code>. <p>
     *
     * @exception SecurityException if the caller does not have permission
     *			to invoke this method.
     */
    public static Object doAs(final Subject subject,
			final java.security.PrivilegedAction action) {

	java.lang.SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(new AuthPermission("doAs"));
	}
	if (action == null)
	    throw new NullPointerException
		(rb.getString("invalid null action provided"));

	// set up the new Subject-based AccessControlContext
	// for doPrivileged
	final AccessControlContext currentAcc = AccessController.getContext();

	// call doPrivileged and push this new context on the stack
	return java.security.AccessController.doPrivileged
					(action,
					createContext(subject, currentAcc));
    }

    /**
     * Perform work as a particular <code>Subject</code>.
     *
     * <p> This method first retrieves the current Thread's
     * <code>AccessControlContext</code> via
     * <code>AccessController.getContext</code>,
     * and then instantiates a new <code>AccessControlContext</code>
     * using the retrieved context along with a new
     * <code>SubjectDomainCombiner</code> (constructed using
     * the provided <code>Subject</code>).
     * Finally, this method invokes <code>AccessController.doPrivileged</code>,
     * passing it the provided <code>PrivilegedExceptionAction</code>,
     * as well as the newly constructed <code>AccessControlContext</code>.
     *
     * <p>
     *
     * @param subject the <code>Subject</code> that the specified
     *			<code>action</code> will run as.  This parameter
     *			may be <code>null</code>. <p>
     *
     * @param action the code to be run as the specified
     *			<code>Subject</code>. <p>
     *
     * @return the <code>Object</code> returned by the
     *			PrivilegedExceptionAction's <code>run</code> method.
     *
     * @exception PrivilegedActionException if the
     *			<code>PrivilegedExceptionAction.run</code>
     *			method throws a checked exception. <p>
     *
     * @exception NullPointerException if the specified
     *			<code>PrivilegedExceptionAction</code> is
     *			<code>null</code>. <p>
     *
     * @exception SecurityException if the caller does not have permission
     *			to invoke this method.
     */
    public static Object doAs(final Subject subject,
			final java.security.PrivilegedExceptionAction action)
			throws java.security.PrivilegedActionException {

	java.lang.SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(new AuthPermission("doAs"));
	}

	if (action == null)
	    throw new NullPointerException
		(rb.getString("invalid null action provided"));

	// set up the new Subject-based AccessControlContext for doPrivileged
	final AccessControlContext currentAcc = AccessController.getContext();

	// call doPrivileged and push this new context on the stack
	return java.security.AccessController.doPrivileged
					(action,
					createContext(subject, currentAcc));
    }

    /**
     * Perform privileged work as a particular <code>Subject</code>.
     *
     * <p> This method behaves exactly as <code>Subject.doAs</code>,
     * except that instead of retrieving the current Thread's
     * <code>AccessControlContext</code>, it uses the provided
     * <code>AccessControlContext</code>.  If the provided
     * <code>AccessControlContext</code> is <code>null</code>,
     * this method instantiates a new <code>AccessControlContext</code>
     * with an empty collection of ProtectionDomains.
     *
     * <p>
     *
     * @param subject the <code>Subject</code> that the specified
     *			<code>action</code> will run as.  This parameter
     *			may be <code>null</code>. <p>
     *
     * @param action the code to be run as the specified
     *			<code>Subject</code>. <p>
     *
     * @param acc the <code>AccessControlContext</code> to be tied to the
     *			specified <i>subject</i> and <i>action</i>. <p>
     *
     * @return the <code>Object</code> returned by the PrivilegedAction's
     *			<code>run</code> method.
     *
     * @exception NullPointerException if the <code>PrivilegedAction</code>
     *			is <code>null</code>. <p>
     *
     * @exception SecurityException if the caller does not have permission
     *			to invoke this method.
     */
    public static Object doAsPrivileged(final Subject subject,
			final java.security.PrivilegedAction action,
			final java.security.AccessControlContext acc) {

	java.lang.SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(new AuthPermission("doAsPrivileged"));
	}

	if (action == null)
	    throw new NullPointerException
		(rb.getString("invalid null action provided"));

	// set up the new Subject-based AccessControlContext
	// for doPrivileged
	final AccessControlContext callerAcc =
		(acc == null ?
		new AccessControlContext(new ProtectionDomain[0]) :
		acc);

	// call doPrivileged and push this new context on the stack
	return java.security.AccessController.doPrivileged
					(action,
					createContext(subject, callerAcc));
    }

    /**
     * Perform privileged work as a particular <code>Subject</code>.
     *
     * <p> This method behaves exactly as <code>Subject.doAs</code>,
     * except that instead of retrieving the current Thread's
     * <code>AccessControlContext</code>, it uses the provided
     * <code>AccessControlContext</code>.  If the provided
     * <code>AccessControlContext</code> is <code>null</code>,
     * this method instantiates a new <code>AccessControlContext</code>
     * with an empty collection of ProtectionDomains.
     *
     * <p>
     *
     * @param subject the <code>Subject</code> that the specified
     *			<code>action</code> will run as.  This parameter
     *			may be <code>null</code>. <p>
     *
     * @param action the code to be run as the specified
     *			<code>Subject</code>. <p>
     *
     * @param acc the <code>AccessControlContext</code> to be tied to the
     *			specified <i>subject</i> and <i>action</i>. <p>
     *
     * @return the <code>Object</code> returned by the
     *			PrivilegedExceptionAction's <code>run</code> method.
     *
     * @exception PrivilegedActionException if the
     *			<code>PrivilegedExceptionAction.run</code>
     *			method throws a checked exception. <p>
     *
     * @exception NullPointerException if the specified
     *			<code>PrivilegedExceptionAction</code> is
     *			<code>null</code>. <p>
     *
     * @exception SecurityException if the caller does not have permission
     *			to invoke this method.
     */
    public static Object doAsPrivileged(final Subject subject,
			final java.security.PrivilegedExceptionAction action,
			final java.security.AccessControlContext acc)
			throws java.security.PrivilegedActionException {

	java.lang.SecurityManager sm = System.getSecurityManager();
	if (sm != null) {
	    sm.checkPermission(new AuthPermission("doAsPrivileged"));
	}

	if (action == null)
	    throw new NullPointerException
		(rb.getString("invalid null action provided"));

	// set up the new Subject-based AccessControlContext for doPrivileged
	final AccessControlContext callerAcc =
		(acc == null ?
		new AccessControlContext(new ProtectionDomain[0]) :
		acc);

	// call doPrivileged and push this new context on the stack
	return java.security.AccessController.doPrivileged
					(action,
					createContext(subject, callerAcc));
    }

    private static AccessControlContext createContext(final Subject subject,
					final AccessControlContext acc) {
	return (AccessControlContext)
	    java.security.AccessController.doPrivileged
	    (new java.security.PrivilegedAction() {
	    public Object run() {
		if (combiner_constructor == null) {
		    // default to this
		    return new AccessControlContext
					(acc,
					new SubjectDomainCombiner(subject));
		} else {
		    try {
			Object[] args = { subject };
			DomainCombiner dc = (DomainCombiner)
				combiner_constructor.newInstance(args);
			return new AccessControlContext(acc, dc);
		    } catch (Exception e) {
			throw new SecurityException(e.toString());
		    }
		}
	    }
	});
    }

    /**
     * Return the <code>Set</code> of Principals associated with this
     * <code>Subject</code>.  Each <code>Principal</code> represents
     * an identity for this <code>Subject</code>.
     *
     * <p> The returned <code>Set</code> is backed by this Subject's
     * internal <code>Principal</code> <code>Set</code>.  Any modification
     * to the returned <code>Set</code> affects the internal
     * <code>Principal</code> <code>Set</code> as well.
     *
     * <p>
     *
     * @return	The <code>Set</code> of Principals associated with this
     *		<code>Subject</code>.
     */
    public Set getPrincipals() {

	// always return an empty Set instead of null
	// so LoginModules can add to the Set if necessary
	return principals;
    }

    /**
     * Return a <code>Set</code> of Principals associated with this
     * <code>Subject</code> that are instances or subclasses of the specified
     * <code>Class</code>.
     *
     * <p> The returned <code>Set</code> is not backed by this Subject's
     * internal <code>Principal</code> <code>Set</code>.  A new
     * <code>Set</code> is created and returned for each method invocation.
     * Modifications to the returned <code>Set</code>
     * will not affect the internal <code>Principal</code> <code>Set</code>.
     *
     * <p>
     *
     * @param c the returned <code>Set</code> of Principals will all be
     *		instances of this class.
     *
     * @return a <code>Set</code> of Principals that are instances of the
     *		specified <code>Class</code>.
     *
     * @exception NullPointerException if the specified <code>Class</code>
     *			is <code>null</code>.
     */
    public Set getPrincipals(Class c) {

	if (c == null)
	    throw new NullPointerException
		(rb.getString("invalid null Class provided"));

	// always return an empty Set instead of null
	// so LoginModules can add to the Set if necessary
	return new ClassSet(PRINCIPAL_SET, c);
    }

    /**
     * Return the <code>Set</code> of public credentials held by this
     * <code>Subject</code>.
     *
     * <p> The returned <code>Set</code> is backed by this Subject's
     * internal public Credential <code>Set</code>.  Any modification
     * to the returned <code>Set</code> affects the internal public
     * Credential <code>Set</code> as well.
     *
     * <p>
     *
     * @return	A <code>Set</code> of public credentials held by this
     *		<code>Subject</code>.
     */
    public Set getPublicCredentials() {

	// always return an empty Set instead of null
	// so LoginModules can add to the Set if necessary
	return pubCredentials;
    }

    /**
     * Return the <code>Set</code> of private credentials held by this
     * <code>Subject</code>.
     *
     * <p> The returned <code>Set</code> is backed by this Subject's
     * internal private Credential <code>Set</code>.  Any modification
     * to the returned <code>Set</code> affects the internal private
     * Credential <code>Set</code> as well.
     *
     * <p>
     *
     * @return	A <code>Set</code> of private credentials held by this
     *		<code>Subject</code>.
     */
    public Set getPrivateCredentials() {

	// XXX
	// we do not need a security check for
	// AuthPermission(getPrivateCredentials)
	// because we already restrict access to private credentials
	// via the PrivateCredentialPermission.  all the extra AuthPermission
	// would do is protect the set operations themselves
	// (like size()), which don't seem security-sensitive.

	// always return an empty Set instead of null
	// so LoginModules can add to the Set if necessary
	return privCredentials;
    }

    /**
     * Return a <code>Set</code> of public credentials associated with this
     * <code>Subject</code> that are instances or subclasses of the specified
     * <code>Class</code>.
     *
     * <p> The returned <code>Set</code> is not backed by this Subject's
     * internal public Credential <code>Set</code>.  A new
     * <code>Set</code> is created and returned for each method invocation.
     * Modifications to the returned <code>Set</code>
     * will not affect the internal public Credential <code>Set</code>.
     *
     * <p>
     *
     * @param c the returned <code>Set</code> of public credentials will all be
     *		instances of this class.
     *
     * @return a <code>Set</code> of public credentials that are instances
     *		of the	specified <code>Class</code>.
     *
     * @exception NullPointerException if the specified <code>Class</code>
     *		is <code>null</code>.
     */
    public Set getPublicCredentials(Class c) {

	if (c == null)
	    throw new NullPointerException
		(rb.getString("invalid null Class provided"));

	// always return an empty Set instead of null
	// so LoginModules can add to the Set if necessary
	return new ClassSet(PUB_CREDENTIAL_SET, c);
    }

    /**
     * Return a <code>Set</code> of private credentials associated with this
     * <code>Subject</code> that are instances or subclasses of the specified
     * <code>Class</code>.
     *
     * <p> The returned <code>Set</code> is not backed by this Subject's
     * internal private Credential <code>Set</code>.  A new
     * <code>Set</code> is created and returned for each method invocation.
     * Modifications to the returned <code>Set</code>
     * will not affect the internal private Credential <code>Set</code>.
     *
     * <p>
     *
     * @param c the returned <code>Set</code> of private credentials will all be
     *		instances of this class.
     *
     * @return a <code>Set</code> of private credentials that are instances
     *		of the	specified <code>Class</code>.
     *
     * @exception NullPointerException if the specified <code>Class</code>
     *		is <code>null</code>.
     */
    public Set getPrivateCredentials(Class c) {

	// XXX
	// we do not need a security check for
	// AuthPermission(getPrivateCredentials)
	// because we already restrict access to private credentials
	// via the PrivateCredentialPermission.  all the extra AuthPermission
	// would do is protect the set operations themselves
	// (like size()), which don't seem security-sensitive.

	if (c == null)
	    throw new NullPointerException
		(rb.getString("invalid null Class provided"));

	// always return an empty Set instead of null
	// so LoginModules can add to the Set if necessary
	return new ClassSet(PRIV_CREDENTIAL_SET, c);
    }

    /**
     * Compares the specified Object with this <code>Subject</code>
     * for equality.  Returns true if the given object is also a Subject
     * and the two <code>Subject</code> instances are equivalent.
     * More formally, two <code>Subject</code> instances are
     * equal if their <code>Principal</code> and <code>Credential</code>
     * Sets are equal.
     *
     * <p>
     *
     * @param o Object to be compared for equality with this
     *		<code>Subject</code>.
     *
     * @return true if the specified Object is equal to this
     *		<code>Subject</code>.
     *
     * @exception SecurityException if the caller does not have permission
     *		to access the private credentials for this <code>Subject</code>,
     *		or if the caller does not have permission to access the
     *		private credentials for the provided <code>Subject</code>.
     */
    public boolean equals(Object o) {

	if (o == null)
	    return false;

	if (this == o)
	    return true;

	if (o instanceof Subject) {

	    final Subject that = (Subject)o;

	    // check the principal and credential sets
	    if (!getPrincipals().equals(that.getPrincipals()) ||
		!getPublicCredentials().equals(that.getPublicCredentials()) ||
		!getPrivateCredentials().equals(that.getPrivateCredentials())) {
		return false;
	    } else {
		return true;
	    }
	}
	return false;
    }

    /**
     * Return the String representation of this <code>Subject</code>.
     *
     * <p>
     *
     * @return the String representation of this <code>Subject</code>.
     */
    public String toString() {
	return toString(true);
    }

    /**
     * package private convenience method to print out the Subject
     * without firing off a security check when trying to access
     * the Private Credentials
     */
    String toString(boolean includePrivateCredentials) {

	String s = new String(rb.getString("Subject:\n"));

	String suffix = new String();
	Iterator principals = getPrincipals().iterator();
	Iterator pubCreds = getPublicCredentials().iterator();
	Iterator privCreds = null;
		   
	if (includePrivateCredentials) {
	    try {
		privCreds = getPrivateCredentials().iterator();
	    } catch (SecurityException se) {
		// ok
	    }
	}

	while (principals.hasNext()) {
	    Principal p = (Principal)principals.next();
	    suffix = suffix + rb.getString("\tPrincipal: ") +
			p.toString() + rb.getString("\n");
	}

	while (pubCreds.hasNext()) {
	    Object o = pubCreds.next();
	    suffix = suffix + rb.getString("\tPublic Credential: ") +
			o.toString() + rb.getString("\n");
	}

	if (privCreds == null) {
	    suffix = suffix +
		rb.getString("\tPrivate Credentials inaccessible\n");
	} else {
	    while (privCreds.hasNext()) {
		try {
		    Object o = privCreds.next();
		    suffix += rb.getString("\tPrivate Credential: ") +
			o.toString() + rb.getString("\n");
		} catch (SecurityException se) {
		    suffix +=
			rb.getString("\tPrivate Credential inaccessible\n");
		    break;
		}
	    }
	}
	return s + suffix;
    }

    /**
     * Returns a hashcode for this <code>Subject</code>.
     *
     * <p> The hashcode is derived exclusive or-ing the
     * hashcodes of this Subject's Principals and credentials.
     *
     * <p> If a particular credential was destroyed
     * (<code>credential.hashCode()</code> throws an
     * <code>IllegalStateException</code>),
     * the hashcode for that credential is derived via:
     * <code>credential.getClass().toString().hashCode()</code>.
     *
     * <p>
     *
     * @return a hashcode for this <code>Subject</code>.
     *
     * @exception SecurityException if the caller does not have permission
     *		to access this Subject's private credentials.
     */
    public int hashCode() {

	int hashCode = 0;

	Iterator pIterator = getPrincipals().iterator();
	Iterator pubCIterator = getPublicCredentials().iterator();
	Iterator privCIterator = getPrivateCredentials().iterator();

	while (pIterator.hasNext()) {
	    Principal p = (Principal)pIterator.next();
	    hashCode ^= p.hashCode();
	}

	while (pubCIterator.hasNext()) {
	    hashCode ^= getCredHashCode(pubCIterator.next());
	}

	while (privCIterator.hasNext()) {
	    hashCode ^= getCredHashCode(privCIterator.next());
	}

	return hashCode;
    }

    /**
     * get a credential's hashcode
     */
    private int getCredHashCode(Object o) {

	try {
	    return o.hashCode();
	} catch (IllegalStateException ise) {
	    return o.getClass().toString().hashCode();
	}
    }

    private void sort(int[] sortMe) {
 
	// bubble sort :)
 
	int i = 0;
	boolean flipped = true;
	int size = sortMe.length - 1;
 
	while (flipped) {
	    i = 0;
	    flipped = false;
	    while (i < size) {
		if (sortMe[i] < sortMe[i + 1]) {
		    flipped = true;
		    int tmp = sortMe[i];
		    sortMe[i] = sortMe[i + 1];
		    sortMe[i + 1] = tmp;
		}
		i++;
	    }
	    size--;
	}
    }

    /**
     * Writes this object out to a stream (i.e., serializes it).
     */
    private synchronized void writeObject(java.io.ObjectOutputStream oos)
    throws java.io.IOException {
	
	// XXX possibly add security checks in the future

	oos.defaultWriteObject();
    }

    /**
     * Reads this object from a stream (i.e., deserializes it)
     */
    private void readObject(java.io.ObjectInputStream s) throws
					java.io.IOException,
					java.io.NotActiveException,
					ClassNotFoundException {

	s.defaultReadObject();

	// The Credential <code>Set</code> is not serialized, but we do not
	// want the default deserialization routine to set it to null.
	this.pubCredentials = new SecureSet(PUB_CREDENTIAL_SET);
	this.privCredentials = new SecureSet(PRIV_CREDENTIAL_SET);
    }

    /**
     * Prevent modifications unless caller has permission.
     */
    private class SecureSet
	extends AbstractSet
	implements java.io.Serializable {

	/**
	 * @serial
	 */
	LinkedList elements;

	/**
	 * @serial
	 */
	private int which;

	SecureSet(int which) {
	    this.which = which;
	    this.elements = new LinkedList();
	}

	SecureSet(int which, Set set) {
	    this.which = which;
	    this.elements = new LinkedList(set);
	}

	public synchronized int size() {
	    return elements.size();
	}

	public Iterator iterator() {
	    final LinkedList list = elements;
	    return new Iterator() {
		ListIterator i = list.listIterator(0);

		public synchronized boolean hasNext() {return i.hasNext();}

		public synchronized Object next() {
		    if (which != Subject.PRIV_CREDENTIAL_SET) 
			return i.next();

		    // only enforce security on the private credential set
		    java.lang.SecurityManager sm = System.getSecurityManager();
		    if (sm != null) {
			if (Subject.this.getPrincipals() == null ||
			    Subject.this.getPrincipals().size() == 0) {
			    sm.checkPermission(new PrivateCredentialPermission
				(list.get(i.nextIndex()).getClass().getName(),
				new java.util.HashSet()));
			} else {
			    sm.checkPermission(new PrivateCredentialPermission
				(PrivateCredentialPermission.buildTarget
				(list.get(i.nextIndex()).getClass().getName(),
				Subject.this.getPrincipals()), "read"));
			}
		    }
		    return i.next();
		}

		public synchronized void remove() {

		    if (Subject.this.isReadOnly()) {
			throw new IllegalStateException
				(rb.getString("Subject is read-only"));
		    }

		    java.lang.SecurityManager sm = System.getSecurityManager();
		    if (sm != null) {
			switch (which) {
			case Subject.PRINCIPAL_SET:
			    sm.checkPermission(new AuthPermission
					("modifyPrincipals"));
			    break;
			case Subject.PUB_CREDENTIAL_SET:
			    sm.checkPermission(new AuthPermission
					("modifyPublicCredentials"));
			    break;
			default:
			    sm.checkPermission(new AuthPermission
					("modifyPrivateCredentials"));
			    break;
			}
		    }
		    i.remove();
		}
	    };
	}

	public synchronized boolean add(Object o) {

	    if (Subject.this.isReadOnly()) {
		throw new IllegalStateException
			(rb.getString("Subject is read-only"));
	    }

	    java.lang.SecurityManager sm = System.getSecurityManager();
	    if (sm != null) {
		switch (which) {
		case Subject.PRINCIPAL_SET:
		    sm.checkPermission(new AuthPermission("modifyPrincipals"));
		    break;
		case Subject.PUB_CREDENTIAL_SET:
		    sm.checkPermission(new AuthPermission
					("modifyPublicCredentials"));
		    break;
		default:
		    sm.checkPermission(new AuthPermission
					("modifyPrivateCredentials"));
		    break;
		}
	    }

	    switch (which) {
	    case Subject.PRINCIPAL_SET:
		if (!(o instanceof Principal))
		    throw new SecurityException
				(rb.getString("attempting to add an object ") +
				rb.getString("which is not an instance of ") +
				rb.getString("java.security.Principal ") +
				rb.getString("to a Subject's Principal Set"));
		break;
	    default:
		// ok to add Objects of any kind to credential sets
		break;
	    }

	    // check for duplicates
	    if (!elements.contains(o))
		return elements.add(o);
	    else
		return false;
	}
    }

    /**
     * This class implements a <code>Set</code> which returns only 
     * members that are an instance of a specified Class. 
     */
    private class ClassSet extends AbstractSet {

	/**
	 * @serial
	 */
	private int which;

	/**
	 * @serial
	 */
	private Set set;

	/**
	 * @serial
	 */
	private Class c;

	ClassSet(int which, Class c) {

	    synchronized(this) {

		this.which = which;
		this.c = c;

		Iterator iterator = null;
		switch(which) {
		case Subject.PRINCIPAL_SET:
		    iterator = Subject.this.principals.iterator();
		    break;
		case Subject.PUB_CREDENTIAL_SET:
		    iterator = Subject.this.pubCredentials.iterator();
		    break;
		default:
		    iterator = Subject.this.privCredentials.iterator();
		    break;
		}

		HashSet newSet = new HashSet();
		while (iterator.hasNext()) {
		    Object next = iterator.next();
		    if (c.isAssignableFrom(next.getClass())) {
			newSet.add(next);
		    }
		}
		set = new SecureSet(which, newSet);
	    }
	}

	public synchronized int size() {
	    return set.size();
	}

	public Iterator iterator() {
	    return set.iterator();
	}

	public synchronized boolean add(Object o) {

	    if (!o.getClass().isAssignableFrom(c)) {
		throw new SecurityException
			(rb.getString("attempting to add an object ") +
			rb.getString("which is not an instance of ") +
			c.toString());
	    }

	    return set.add(o);
	}
    }
}