updated JavaDoc
git-svn-id: https://svn.apache.org/repos/asf/incubator/jsecurity/trunk@738006 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/core/src/org/jsecurity/subject/PrincipalCollection.java b/core/src/org/jsecurity/subject/PrincipalCollection.java
index e5d5d16..d5c4bc5 100644
--- a/core/src/org/jsecurity/subject/PrincipalCollection.java
+++ b/core/src/org/jsecurity/subject/PrincipalCollection.java
@@ -24,7 +24,21 @@
import java.util.Set;
/**
- * A collection of all principals associated with a corresponding {@link Subject Subject}.
+ * A collection of all principals associated with a corresponding {@link Subject Subject}. A <em>principal</em> is
+ * just a security term for an identifying attribute, such as a username or user id or social security number or
+ * anything else that can be considered an 'identifying' attribute for a {@code Subject}.
+ * <p/>
+ * Note that by convention however, the 'first' principal returned from this collection is considered to be the
+ * Subject's <em>primary</em> principal used by the application, usually a user ID or username, based on the
+ * {@code Realm} implementation. The 'first' principal is that which is returned by
+ * {@link #asList() asList()}{@code .iterator().next()}.
+ * <p/>
+ * A PrincipalCollection orgainizes its internal principals based on the {@code Realm} where they came from when the
+ * Subject was first created. To obtain the principal(s) for a specific Realm, see the {@link #fromRealm} method. You
+ * can also see which realms contributed to this collection via the {@link #getRealmNames() getRealmNames()} method.
+ *
+ * @see #fromRealm(String realmName)
+ * @see #getRealmNames()
*
* @author Les Hazlewood
* @since 0.9
@@ -35,7 +49,8 @@
* Returns a single principal assignable from the specified type, or <tt>null</tt> if there are none of the
* specified type.
*
- * <p>Note that this would return <code>null</code> List always if the corresponding subject has not logged in.</p>
+ * <p>Note that this would return <code>null</code> List always if the corresponding subject has not yet
+ * logged in.</p>
*
* @param type the type of the principal that should be returned.
* @return a principal of the specified type or <tt>null</tt> if there isn't one of the specified type.
@@ -46,7 +61,8 @@
* Returns all principals assignable from the specified type, or an empty Collection if no principals of that
* type are contained.
*
- * <p>Note that this would return an empty Collection always if the corresponding subject has not logged in.</p>
+ * <p>Note that this would return an empty Collection always if the corresponding subject has not yet
+ * logged in.</p>
*
* @param type the type of the principals that should be returned.
* @return a Collection of principals that are assignable from the specified type, or
@@ -58,7 +74,7 @@
* Returns a single Subject's principals retrieved from all configured Realms as a List, or an empty List if
* there are not any principals.
*
- * <p>Note that this would return an empty List always if the corresponding subject has not logged in.</p>
+ * <p>Note that this would return an empty List always if the corresponding subject has not yet logged in.</p>
*
* @return a single Subject's principals retrieved from all configured Realms as a List.
*/
@@ -68,7 +84,7 @@
* Returns a single Subject's principals retrieved from all configured Realms as a Set, or an empty Set if there
* are not any principals.
*
- * <p>Note that this would return an empty Set always if the corresponding subject has not logged in.</p>
+ * <p>Note that this would return an empty Set always if the corresponding subject has not yet logged in.</p>
*
* @return a single Subject's principals retrieved from all configured Realms as a Set.
*/
@@ -78,7 +94,7 @@
* Returns a single Subject's principals retrieved from the specified Realm <em>only</em> as a Collection, or an empty
* Collection if there are not any principals from that realm.
*
- * <p>Note that this would return an empty Collection always if the corresponding subject has not logged in.</p>
+ * <p>Note that this would return an empty Collection always if the corresponding subject has not yet logged in.</p>
*
* @param realmName the name of the Realm from which the principals were retrieved.
* @return the Subject's principals from the specified Realm only as a Collection or an empty Collection if there
diff --git a/core/src/org/jsecurity/subject/Subject.java b/core/src/org/jsecurity/subject/Subject.java
index 834a804..1d5f4fc 100644
--- a/core/src/org/jsecurity/subject/Subject.java
+++ b/core/src/org/jsecurity/subject/Subject.java
@@ -357,7 +357,8 @@
/**
* Logs out this Subject and invalidates and/or removes any associated entities
- * (such as a {@link Session Session} and authorization data.
+ * (such as a {@link Session Session} and authorization data. After this method is called, the Subject is
+ * considered 'anonymous' and may continue to be used for another log-in if desired.
*/
void logout();
diff --git a/core/test/org/jsecurity/mgt/DefaultSecurityManagerTest.java b/core/test/org/jsecurity/mgt/DefaultSecurityManagerTest.java
index 701ad31..1d1f850 100644
--- a/core/test/org/jsecurity/mgt/DefaultSecurityManagerTest.java
+++ b/core/test/org/jsecurity/mgt/DefaultSecurityManagerTest.java
@@ -111,6 +111,7 @@
* Test that validates functionality for issue
* <a href="https://issues.apache.org/jira/browse/JSEC-22">JSEC-22</a>
*/
+ @Test
public void testSubjectReuseAfterLogout() {
Subject subject = SecurityUtils.getSubject();