A DESCRIPTION OF THE PROBLEM :
I came across the below potential inconsistency while reading Sun's JAAS documentation regarding method commit of the LoginModule.

The JavaDoc API [1] states: "If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved." (Statement 1)

A similar statement can be found in the SampleLoginModule.java [2] class provided with the JAAS Authentication Tutorial [3]: "If this LoginModule's own authentication attempted failed, then this method removes any state that was originally saved." (Statement 2)

However, the Login Module Developer's Guide [4] states: "If the authentication result denotes that the login method failed, then this commit method should remove/destroy any corresponding state that was originally saved...After adding Principals and credentials, dispensable state fields should be destroyed expeditiously. Likely fields to destroy would be user names and passwords stored during the authentication process." (Statement 3)

This indicates that, even upon a successful commit, there should be a clean out of state fields set during phase 1 authentication. This is confirmed in the code itself [2], where within method commit() the following is found (*):
// in any case, clean out state
<state clean up code>

(*) Actually, the commit method in SampleLoginModule is not cleaning out state fields if phase 1 authentication failed, as it should

[1] JavaDoc of method commit, class LoginModule: http://java.sun.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html#commit()
[2] SampleLoginModule.java, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/SampleLoginModule.java
[3] JAAS Authentication Tutorial, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/GeneralAcnOnly.html
[4] Java Authentication and Authorization Service (JAAS), LoginModule Developer's Guide, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
"If the authentication result denotes that the login method failed, then this commit method should remove/destroy any corresponding state that was originally saved...After adding Principals and credentials, dispensable state fields should be destroyed expeditiously. Likely fields to destroy would be user names and passwords stored during the authentication process." (Statement 3)

My suggestion would be to update [1] and [2] so they become consistent with [4]. This would make clear that phase 1 authentication state must always be cleaned out during commit. Therefore:
- Statement 1 should be replaced by Statement 3
- Statement 2 should be replaced by Statement 3

[1] JavaDoc of method commit, class LoginModule: http://java.sun.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html#commit()
[2] SampleLoginModule.java, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/SampleLoginModule.java
[4] Java Authentication and Authorization Service (JAAS), LoginModule Developer's Guide, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/JAASLMDevGuide.html
ACTUAL -
The JavaDoc API [1] states: "If this LoginModule's own authentication attempted failed, then this method removes/destroys any state that was originally saved." (Statement 1)

The SampleLoginModule.java [2] class provided with the JAAS Authentication Tutorial [3] states: "If this LoginModule's own authentication attempted failed, then this method removes any state that was originally saved." (Statement 2)

[1] JavaDoc of method commit, class LoginModule: http://java.sun.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html#commit()
[2] SampleLoginModule.java, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/SampleLoginModule.java
[3] JAAS Authentication Tutorial, http://java.sun.com/javase/6/docs/technotes/guides/security/jaas/tutorials/GeneralAcnOnly.html

URL OF FAULTY DOCUMENTATION :
http://java.sun.com/javase/6/docs/api/javax/security/auth/spi/LoginModule.html#commit()