Javadoc fixes.

acl/src/main/java/org/springframework/security/acls/afterinvocation/AclEntryAfterInvocationCollectionFilteringProvider.java

@@ -38,8 +38,7 @@ import org.springframework.security.core.Authentication;
  * <p>
  * This after invocation provider will fire if any {@link ConfigAttribute#getAttribute()} matches the {@link
  * #processConfigAttribute}. The provider will then lookup the ACLs from the <code>AclService</code> and ensure the
- * principal is {@link org.springframework.security.acls.Acl#isGranted(List,
+ * principal is {@link org.springframework.security.acls.model.Acl#isGranted(List, List, boolean) Acl.isGranted()}
- * List, boolean) Acl.isGranted(Permission[], Sid[], boolean)}
  * when presenting the {@link #requirePermission} array to that method.
  * <p>
  * If the principal does not have permission, that element will not be included in the returned

acl/src/main/java/org/springframework/security/acls/afterinvocation/AclEntryAfterInvocationProvider.java

@@ -39,11 +39,10 @@ import org.springframework.security.core.SpringSecurityMessageSource;
  * <p>
  * This after invocation provider will fire if any  {@link ConfigAttribute#getAttribute()} matches the {@link
  * #processConfigAttribute}. The provider will then lookup the ACLs from the <tt>AclService</tt> and ensure the
- * principal is {@link org.springframework.security.acls.Acl#isGranted(List,
+ * principal is {@link org.springframework.security.acls.model.Acl#isGranted(List, List, boolean)
-   List, boolean) Acl.isGranted(Permission[], Sid[], boolean)}
+ * Acl.isGranted(List, List, boolean)} when presenting the {@link #requirePermission} array to that method.
- * when presenting the {@link #requirePermission} array to that method.
  * <p>
- * Often users will setup an <code>AclEntryAfterInvocationProvider</code> with a {@link
+ * Often users will set up an <code>AclEntryAfterInvocationProvider</code> with a {@link
  * #processConfigAttribute} of <code>AFTER_ACL_READ</code> and a {@link #requirePermission} of
  * <code>BasePermission.READ</code>. These are also the defaults.
  * <p>

acl/src/main/java/org/springframework/security/acls/jdbc/JdbcMutableAclService.java

@@ -155,10 +155,10 @@ public class JdbcMutableAclService extends JdbcAclService implements MutableAclS
     }
 
     /**
-     * Retrieves the primary key from acl_class, creating a new row if needed and the allowCreate property is
+     * Retrieves the primary key from {@code acl_class}, creating a new row if needed and the
-     * true.
+     * {@code allowCreate} property is {@code true}.
      *
-     * @param clazz to find or create an entry for (this implementation uses the fully-qualified class name String)
+     * @param type to find or create an entry for (often the fully-qualified class name)
      * @param allowCreate true if creation is permitted if not found
      *
      * @return the primary key or null if not found

acl/src/main/java/org/springframework/security/acls/model/AclDataAccessException.java

@@ -13,7 +13,7 @@ public abstract class AclDataAccessException extends RuntimeException {
      * message and root cause.
      *
      * @param msg the detail message
-     * @param t the root cause
+     * @param cause the root cause
      */
     public AclDataAccessException(String msg, Throwable cause) {
         super(msg, cause);

acl/src/main/java/org/springframework/security/acls/model/AclService.java

@@ -37,7 +37,7 @@ public interface AclService {
     List<ObjectIdentity> findChildren(ObjectIdentity parentIdentity);
 
     /**
-     * Same as {@link #readAclsById(Java.util.List<ObjectIdentity>)} except it returns only a single Acl.
+     * Same as {@link #readAclsById(List)} except it returns only a single Acl.
      * <p>
      * This method should not be called as it does not leverage the underlying implementation's potential ability to
      * filter <tt>Acl</tt> entries based on a {@link Sid} parameter.</p>

acl/src/main/java/org/springframework/security/acls/model/ObjectIdentityGenerator.java

@@ -4,7 +4,7 @@ import java.io.Serializable;
 
 
 /**
- * Strategy which creates an <tt>ObjectIdentity</tt> from an object identifier (such as a primary key)
+ * Strategy which creates an {@link ObjectIdentity} from an object identifier (such as a primary key)
  * and type information.
  * <p>
  * Differs from {@link ObjectIdentityRetrievalStrategy} in that it is used in situations when the actual object
@@ -18,8 +18,8 @@ public interface ObjectIdentityGenerator {
     /**
      *
      * @param id the identifier of the domain object, not null
-     * @param type the type of the object (usually a class name), not null
+     * @param type the type of the object (often a class name), not null
-     * @return
+     * @return the identity constructed using the supplied identifier and type information.
      */
     ObjectIdentity createObjectIdentity(Serializable id, String type);
 

build.gradle

@@ -142,6 +142,7 @@ def docsDir = new File(project(':manual').buildDir, 'docs')
 
 task apidocs(type: Javadoc) {
     destinationDir = new File(buildDir, 'apidocs')
+    title = "Spring Security $version API"
     optionsFile = file("$buildDir/tmp/javadoc.options")
 
     source coreModuleProjects().collect { project ->
@@ -240,8 +241,12 @@ def sampleProjects() {
     subprojects.findAll { project -> project.name.startsWith('spring-security-samples') }
 }
 
+def itestProjects() {
+    subprojects.findAll { project -> project.name.startsWith('itest') }
+}
+
 def coreModuleProjects() {
-    javaProjects() - sampleProjects()
+    javaProjects() - sampleProjects() - itestProjects()
 }
 
 def releaseType() {

core/src/main/java/org/springframework/security/access/hierarchicalroles/UserDetailsServiceWrapper.java

@@ -21,11 +21,11 @@ import org.springframework.dao.DataAccessException;
 
 /**
  * This class wraps Spring Security's <tt>UserDetailsService</tt> in a way that its <tt>loadUserByUsername()</tt>
- * method returns wrapped <tt>UserDetails</tt> that return all hierachically reachable authorities
+ * method returns wrapped <tt>UserDetails</tt> that return all hierarchically reachable authorities
  * instead of only the directly assigned authorities.
  *
  * @author Michael Mayr
- * @deprecated use a {@link RoleHierarchyVoter} instead of populating the user Authentication object
+ * @deprecated use a {@code RoleHierarchyVoter} instead of populating the user Authentication object
  * with the additional authorities.
  */
 public class UserDetailsServiceWrapper implements UserDetailsService {
@@ -52,4 +52,4 @@ public class UserDetailsServiceWrapper implements UserDetailsService {
         return userDetailsService;
     }
 
-}
+}

core/src/main/java/org/springframework/security/access/intercept/AfterInvocationManager.java

@@ -25,16 +25,11 @@ import org.springframework.security.core.Authentication;
  * Reviews the <code>Object</code> returned from a secure object invocation,
  * being able to modify the <code>Object</code> or throw an {@link
  * AccessDeniedException}.
- *
  * <p>
  * Typically used to ensure the principal is permitted to access the domain
  * object instance returned by a service layer bean. Can also be used to
  * mutate the domain object instance so the principal is only able to access
- * authorised bean properties or <code>Collection</code> elements. Often used
+ * authorised bean properties or <code>Collection</code> elements.
- * in conjunction with an {@link org.springframework.security.acl.AclManager} to
- * obtain the access control list applicable for the domain object instance.
- * </p>
- *
  * <p>
  * Special consideration should be given to using an
  * <code>AfterInvocationManager</code> on bean methods that modify a database.

core/src/main/java/org/springframework/security/access/intercept/AfterInvocationProviderManager.java

@@ -34,11 +34,12 @@ import org.springframework.util.Assert;
  * <p>
  * Handles configuration of a bean context defined list of  {@link AfterInvocationProvider}s.
  * <p>
- * Every <code>AfterInvocationProvider</code> will be polled when the {@link #decide(Authentication, Object,
+ * Every <code>AfterInvocationProvider</code> will be polled when the
- * List<ConfigAttribute>, Object)} method is called. The <code>Object</code> returned from each provider will be
+ * {@link #decide(Authentication, Object, Collection, Object)} method is called. The <code>Object</code> returned
- * presented to the successive provider for processing. This means each provider <b>must</b> ensure they return the
+ * from each provider will be presented to the successive provider for processing. This means each provider
- * <code>Object</code>, even if they are not interested in the "after invocation" decision (perhaps as the secure
+ * <b>must</b> ensure they return the <code>Object</code>, even if they are not interested in the "after invocation"
- * object invocation did not include a configuration attribute a given provider is configured to respond to).
+ * decision (perhaps as the secure object invocation did not include a configuration attribute a given provider is
+ * configured to respond to).
  *
  * @author Ben Alex
  */

core/src/main/java/org/springframework/security/access/intercept/aopalliance/MethodSecurityMetadataSourceAdvisor.java

@@ -36,8 +36,7 @@ import org.springframework.util.Assert;
  * Because the AOP framework caches advice calculations, this is normally faster than just letting the
  * <code>MethodSecurityInterceptor</code> run and find out itself that it has no work to do.
  * <p>
- * This class also allows the use of Spring's
+ * This class also allows the use of Spring's {@code DefaultAdvisorAutoProxyCreator}, which makes
- * {@link org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator}, which makes
  * configuration easier than setup a <code>ProxyFactoryBean</code> for each object requiring security. Note that
  * autoproxying is not supported for BeanFactory implementations, as post-processing is automatic only for application
  * contexts.
@@ -74,8 +73,8 @@ public class MethodSecurityMetadataSourceAdvisor extends AbstractPointcutAdvisor
      * bean name should be set. This prevents eager instantiation of the interceptor
      * (and hence the AuthenticationManager). See SEC-773, for example.
      * <p>
-     * This is essentially the approach taken by subclasses of {@link AbstractBeanFactoryPointcutAdvisor}, which this
+     * This is essentially the approach taken by subclasses of Spring's {@code AbstractBeanFactoryPointcutAdvisor},
-     * class should extend in future. The original hierarchy and constructor have been retained for backwards
+     * which this class should extend in future. The original hierarchy and constructor have been retained for backwards
      * compatibility.
      *
      * @param adviceBeanName name of the MethodSecurityInterceptor bean

core/src/main/java/org/springframework/security/authentication/AuthenticationDetails.java

@@ -30,7 +30,7 @@ public class AuthenticationDetails implements Serializable {
    /**
     * Provided so that subclasses can populate additional information.
     *
-    * @param request that the authentication request was received from
+    * @param context the existing contextual information
     */
    protected void doPopulateAdditionalInformation(Object context) {}
 

core/src/main/java/org/springframework/security/authentication/InsufficientAuthenticationException.java

@@ -23,9 +23,9 @@ import org.springframework.security.core.AuthenticationException;
  * <p>
  * {@link org.springframework.security.access.AccessDecisionVoter}s will typically throw this exception if
  * they are dissatisfied with the level of the authentication, such as if performed using a remember-me mechanism or
- * anonymously. The commonly used {@link org.springframework.security.web.ExceptionTranslationFilter} will thus cause
+ * anonymously. The commonly used {@link org.springframework.security.web.access.ExceptionTranslationFilter
- * the <code>AuthenticationEntryPoint</code> to be called, allowing the principal to authenticate with a stronger
+ * ExceptionTranslationFilter} will thus cause the <code>AuthenticationEntryPoint</code> to be called, allowing
- * level of authentication.</p>
+ * the principal to authenticate with a stronger level of authentication.
  *
  * @author Ben Alex
  */

core/src/main/java/org/springframework/security/authentication/jaas/JaasAuthenticationProvider.java

@@ -323,8 +323,8 @@ public class JaasAuthenticationProvider implements AuthenticationProvider, Appli
      * Publishes the {@link JaasAuthenticationFailedEvent}. Can be overridden by subclasses for different
      * functionality
      *
-     * @param token The {@link UsernamePasswordAuthenticationToken} being processed
+     * @param token The authentication token being processed
-     * @param ase The {@link SpringSecurityException} that caused the failure
+     * @param ase The excetion that caused the authentication failure
      */
     protected void publishFailureEvent(UsernamePasswordAuthenticationToken token, AuthenticationException ase) {
         applicationEventPublisher.publishEvent(new JaasAuthenticationFailedEvent(token, ase));
@@ -334,7 +334,7 @@ public class JaasAuthenticationProvider implements AuthenticationProvider, Appli
      * Publishes the {@link JaasAuthenticationSuccessEvent}. Can be overridden by subclasses for different
      * functionality.
      *
-     * @param token The {@link UsernamePasswordAuthenticationToken} being processed
+     * @param token The token being processed
      */
     protected void publishSuccessEvent(UsernamePasswordAuthenticationToken token) {
         if (applicationEventPublisher != null) {
@@ -425,11 +425,11 @@ public class JaasAuthenticationProvider implements AuthenticationProvider, Appli
 
     /**
      * If set, a call to {@code Configuration#refresh()} will be made by {@code #configureJaas(Resource) }
-     * method. Defaults to {@literal true}.
+     * method. Defaults to {@code true}.
      *
      * @see <a href="https://jira.springsource.org/browse/SEC-1320">SEC-1230</a>
      *
-     * @param refreshConfigurationOnStartup set to {@literal false} to disable reloading of the configuration.
+     * @param refresh set to {@code false} to disable reloading of the configuration.
      * May be useful in some environments.
      */
     public void setRefreshConfigurationOnStartup(boolean refresh) {

core/src/main/java/org/springframework/security/core/Authentication.java

@@ -31,7 +31,7 @@ import org.springframework.security.core.context.SecurityContextHolder;
  * Once the request has been authenticated, the <tt>Authentication</tt> will usually be stored in a thread-local
  * <tt>SecurityContext</tt> managed by the {@link SecurityContextHolder} by the authentication mechanism which is
  * being used. An explicit authentication can be achieved, without using one of Spring Security's authentication
- * mechanisms,  by creating an <tt>Authentication</tt> instance and using the code:
+ * mechanisms, by creating an <tt>Authentication</tt> instance and using the code:
  *
  * <pre>
  * SecurityContextHolder.getContext().setAuthentication(anAuthentication);
@@ -84,14 +84,14 @@ public interface Authentication extends Principal, Serializable {
      * <p>
      * The <tt>AuthenticationManager</tt> implementation will often return an <tt>Authentication</tt> containing
      * richer information as the principal for use by the application. Many of the authentication providers will
-     * create a {@link UserDetails} object as the principal.
+     * create a {@code UserDetails} object as the principal.
      *
      * @return the <code>Principal</code> being authenticated or the authenticated principal after authentication.
      */
     Object getPrincipal();
 
     /**
-     * Used to indicate to <code>AbstractSecurityInterceptor</code> whether it should present the
+     * Used to indicate to {@code AbstractSecurityInterceptor} whether it should present the
      * authentication token to the <code>AuthenticationManager</code>. Typically an <code>AuthenticationManager</code>
      * (or, more often, one of its <code>AuthenticationProvider</code>s) will return an immutable authentication token
      * after successful authentication, in which case that token can safely return <code>true</code> to this method.

core/src/main/java/org/springframework/security/core/authority/mapping/Attributes2GrantedAuthoritiesMapper.java

@@ -20,7 +20,7 @@ public interface Attributes2GrantedAuthoritiesMapper {
      * GrantedAuthorities, all attributes can be mapped to a single Spring Security
      * GrantedAuthority, some attributes may not be mapped, etc.
      *
-     * @param attribute the attributes to be mapped
+     * @param attributes the attributes to be mapped
      * @return the list of mapped GrantedAuthorities
      */
     public List<GrantedAuthority> getGrantedAuthorities(Collection<String> attributes);

core/src/main/java/org/springframework/security/core/context/SecurityContextImpl.java

@@ -19,8 +19,9 @@ import org.springframework.security.core.Authentication;
 
 
 /**
- * Base implementation of {@link SecurityContext}.<p>Used by default by {@link SecurityContextHolder} and {@link
+ * Base implementation of {@link SecurityContext}.
- * HttpSessionContextIntegrationFilter}.</p>
+ * <p>
+ * Used by default by {@link SecurityContextHolder} strategies.
  *
  * @author Ben Alex
  */

core/src/main/java/org/springframework/security/core/session/SessionDestroyedEvent.java

@@ -24,8 +24,7 @@ public abstract class SessionDestroyedEvent extends ApplicationEvent {
     public abstract SecurityContext getSecurityContext();
 
     /**
-     * The identifier associated with the destroyed session.
+     * @return the identifier associated with the destroyed session.
-     * @return
      */
     public abstract String getId();
 }

core/src/main/java/org/springframework/security/core/session/SessionIdentifierAware.java

@@ -18,16 +18,8 @@ package org.springframework.security.core.session;
 /**
  * Implemented by {@link org.springframework.security.core.Authentication#getDetails()}
  * implementations that are capable of returning a session ID.
- *
  * <p>
- * This interface is used by {@link
+ * Used to extract the session ID from an <code>Authentication</code> object.
- * org.springframework.security.authentication.concurrent.SessionRegistryUtils} to extract the session
- * ID from an <code>Authentication</code> object. In turn,
- * <code>SessionRegistryUtils</code> is used by {@link
- * ConcurrentSessionControllerImpl}. If not using this latter implementation,
- * you do not need the <code>Authentication.getDetails()</code> object to
- * implement <code>SessionIdentifierAware</code>.
- * </p>
  *
  * @author Ben Alex
  */

core/src/main/java/org/springframework/security/core/token/Token.java

@@ -31,7 +31,7 @@ public interface Token {
      * token must never have this creation time changed. If necessary, a new token can be
      * requested from the {@link TokenService} to replace the original token.
      *
-     * @return the time this token key was created, in the same format as specified by {@link Date#getTime()).
+     * @return the time this token key was created, in the same format as specified by {@link java.util.Date#getTime()}.
      */
     long getKeyCreationTime();
 

core/src/main/java/org/springframework/security/core/token/TokenService.java

@@ -29,9 +29,10 @@ public interface TokenService {
     /**
      * Forces the allocation of a new {@link Token}.
      *
-     * @param the extended information desired in the token (cannot be <code>null</code>, but can be empty)
+     * @param extendedInformation the extended information desired in the token
+     *          (cannot be <code>null</code>, but can be empty)
      * @return a new token that has not been issued previously, and is guaranteed to be recognised
-     * by this implementation's {@link #verifyToken(String)} at any future time.
+     *          by this implementation's {@link #verifyToken(String)} at any future time.
      */
     Token allocateToken(String extendedInformation);
 

core/src/main/java/org/springframework/security/core/userdetails/UserCache.java

@@ -15,7 +15,6 @@
 
 package org.springframework.security.core.userdetails;
 
-
 /**
  * Provides a cache of {@link UserDetails} objects.
  *
@@ -30,7 +29,7 @@ package org.springframework.security.core.userdetails;
  * a database or other persistent storage mechanism to validate would be excessive. In this case, you would configure
  * a cache to store the <tt>UserDetails</tt> information rather than loading it each time.
  *
- * @see {@link org.springframework.security.authentication.dao.AbstractUserDetailsAuthenticationProvider}
+ * @see org.springframework.security.authentication.dao.AbstractUserDetailsAuthenticationProvider
  *
  * @author Ben Alex
  */

core/src/main/java/org/springframework/security/core/userdetails/UserDetailsService.java

@@ -41,7 +41,7 @@ public interface UserDetailsService {
      * <code>UserDetails</code> object that comes back may have a username that is of a different case than what was
      * actually requested..
      *
-     * @param username the username presented to the {@link DaoAuthenticationProvider}
+     * @param username the username identifying the user whose data is required.
      *
      * @return a fully populated user record (never <code>null</code>)
      *

ldap/src/main/java/org/springframework/security/ldap/ppolicy/PasswordPolicyControl.java

@@ -22,14 +22,14 @@ import javax.naming.ldap.Control;
  *
  * A Password Policy request control.
  * <p>
- * Based on the information in the corresponding internet draft on LDAP password policy.
+ * Based on the information in the corresponding
+ * <a href="http://tools.ietf.org/draft/draft-behera-ldap-password-policy/draft-behera-ldap-password-policy-09.txt">
+ * internet draft on LDAP password policy</a>
  *
  * @author Stefan Zoerner
  * @author Luke Taylor
  *
  * @see PasswordPolicyResponseControl
- * @see <a href="http://www.ietf.org/internet-drafts/draft-behera-ldap-password-policy-09.txt">Password Policy for LDAP
- *      Directories</a>
  */
 public class PasswordPolicyControl implements Control {
     //~ Static fields/initializers =====================================================================================

ldap/src/main/java/org/springframework/security/ldap/server/ApacheDSContainer.java

@@ -33,7 +33,7 @@ import org.springframework.util.Assert;
 
 /**
  * Provides lifecycle services for the embedded apacheDS server defined by the supplied configuration.
- * Used by {@link LdapServerBeanDefinitionParser}. An instance will be stored in the application context for
+ * Used by {code LdapServerBeanDefinitionParser}. An instance will be stored in the application context for
  * each embedded server instance. It will start the server when the context is initialized and shut it down when
  * it is closed. It is intended for temporary embedded use and will not retain changes across start/stop boundaries. The
  * working directory is deleted on shutdown.

openid/src/main/java/org/springframework/security/openid/OpenIDAuthenticationFilter.java

@@ -273,7 +273,7 @@ public class OpenIDAuthenticationFilter extends AbstractAuthenticationProcessing
 
     /**
      * Specifies any extra parameters submitted along with the identity field which should be appended to the
-     * {@literal return_to} URL which is assembled by {@link #buildReturnToUrl}.
+     * {@code return_to} URL which is assembled by {@link #buildReturnToUrl}.
      *
      * @param returnToUrlParameters
      *      the set of parameter names. If not set, it will default to the parameter name used by the

taglibs/src/main/java/org/springframework/security/taglibs/velocity/Authz.java

@@ -16,19 +16,12 @@
 package org.springframework.security.taglibs.velocity;
 
 
+import org.springframework.context.ApplicationContext;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.userdetails.UserDetails;
-import org.springframework.security.taglibs.authz.AuthenticationTag;
-import org.springframework.security.taglibs.authz.LegacyAuthorizeTag;
-
-
-import org.springframework.context.ApplicationContext;
 
 
 /**
- * Wrapper the implementation of Spring Security JSP tag includes:
- * {@link AuthenticationTag}, {@link AclTag}, {@link LegacyAuthorizeTag}
- *
  * @author Wang Qi
  */
 public interface Authz {

taglibs/src/main/java/org/springframework/security/taglibs/velocity/AuthzImpl.java

@@ -73,13 +73,6 @@ public class AuthzImpl implements Authz {
 
     /**
      * implementation of LegacyAuthorizeTag
-     *
-     * @param roles DOCUMENT ME!
-     * @param grantType DOCUMENT ME!
-     *
-     * @return DOCUMENT ME!
-     *
-     * @throws IllegalArgumentException DOCUMENT ME!
      */
     private boolean ifGranted(String roles, int grantType) {
         LegacyAuthorizeTag authorizeTag = new LegacyAuthorizeTag();

web/src/main/java/org/springframework/security/web/access/channel/AbstractRetryEntryPoint.java

@@ -26,9 +26,9 @@ public abstract class AbstractRetryEntryPoint implements ChannelEntryPoint {
     private PortMapper portMapper = new PortMapperImpl();
     private PortResolver portResolver = new PortResolverImpl();
     /** The scheme ("http://" or "https://") */
-    private String scheme;
+    private final String scheme;
     /** The standard port for the scheme (80 for http, 443 for https) */
-    private int standardPort;
+    private final int standardPort;
 
     //~ Constructors ===================================================================================================
 
@@ -39,9 +39,7 @@ public abstract class AbstractRetryEntryPoint implements ChannelEntryPoint {
 
     //~ Methods ========================================================================================================
 
-    public void commence(HttpServletRequest req, HttpServletResponse res) throws IOException, ServletException {
+    public void commence(HttpServletRequest request, HttpServletResponse res) throws IOException, ServletException {
-        HttpServletRequest request = (HttpServletRequest) req;
-
         String pathInfo = request.getPathInfo();
         String queryString = request.getQueryString();
         String contextPath = request.getContextPath();
@@ -64,7 +62,7 @@ public abstract class AbstractRetryEntryPoint implements ChannelEntryPoint {
             logger.debug("Redirecting to: " + redirectUrl);
         }
 
-        ((HttpServletResponse) res).sendRedirect(((HttpServletResponse) res).encodeRedirectURL(redirectUrl));
+        res.sendRedirect(res.encodeRedirectURL(redirectUrl));
     }
 
     protected abstract Integer getMappedPort(Integer mapFromPort);

web/src/main/java/org/springframework/security/web/access/intercept/DefaultFilterInvocationSecurityMetadataSource.java

@@ -36,15 +36,12 @@ import org.springframework.security.web.util.UrlMatcher;
  * Stores an ordered map of compiled URL paths to <tt>ConfigAttribute</tt> lists and provides URL matching
  * against the items stored in this map using the configured <tt>UrlMatcher</tt>.
  * <p>
- * The order of registering the regular expressions using the
+ * The order of the URL paths in the map is very important.
- * {@link #addSecureUrl(String, List<ConfigAttribute>)} is very important.
+ * The system will identify the <b>first</b>  matching path for a given HTTP URL. It will not proceed to evaluate
- * The system will identify the <b>first</b>  matching regular
+ * later paths if a match has already been found. Accordingly, the most specific matches should be
- * expression for a given HTTP URL. It will not proceed to evaluate later regular expressions if a match has already
+ * registered first, with the most general matches registered last.
- * been found. Accordingly, the most specific regular expressions should be registered first, with the most general
- * regular expressions registered last.
  * <p>
- * If URLs are registered for a particular HTTP method using
+ * If URL paths are registered for a particular HTTP method using, then the method-specific matches will take
- * {@link #addSecureUrl(String, String, List<ConfigAttribute>)}, then the method-specific matches will take
  * precedence over any URLs which are registered without an HTTP method.
  *
  * @author Ben Alex

web/src/main/java/org/springframework/security/web/authentication/AbstractAuthenticationProcessingFilter.java

@@ -166,11 +166,12 @@ public abstract class AbstractAuthenticationProcessingFilter extends GenericFilt
      * to perform the authentication. There are then three possible outcomes:
      * <ol>
      * <li>An <tt>Authentication</tt> object is returned.
-     * The {@link #successfulAuthentication(HttpServletRequest, HttpServletResponse, Authentication)
+     * The configured {link SessionAuthenticationStrategy} will be invoked followed by the
-     * successfulAuthentication} method will be invoked</li>
+     * {@link #successfulAuthentication(HttpServletRequest, HttpServletResponse, Authentication)
+     * successfulAuthentication} method</li>
      * <li>An <tt>AuthenticationException</tt> occurs during authentication.
-     * The {@link #unSuccessfulAuthentication(HttpServletRequest, HttpServletResponse, Authentication)
+     * The {@link #unsuccessfulAuthentication(HttpServletRequest, HttpServletResponse, AuthenticationException)
-     * unSuccessfulAuthentication} method will be invoked</li>
+     * unsuccessfulAuthentication} method will be invoked</li>
      * <li>Null is returned, indicating that the authentication process is incomplete.
      * The method will then return immediately, assuming that the subclass has done any necessary work (such as
      * redirects) to continue the authentication process. The assumption is that a later request will be received

web/src/main/java/org/springframework/security/web/authentication/AuthenticationSuccessHandler.java

@@ -18,7 +18,6 @@ import org.springframework.security.core.Authentication;
  *
  * @author Luke Taylor
  * @since 3.0
- * @see
  */
 public interface AuthenticationSuccessHandler {
 

web/src/main/java/org/springframework/security/web/authentication/RememberMeServices.java

@@ -25,8 +25,11 @@ import org.springframework.security.core.Authentication;
  * Implement by a class that is capable of providing a remember-me service.
  *
  * <p>
- * Spring Security filters (namely {@link org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter} and
+ * Spring Security filters (namely
- * {@link RememberMeAuthenticationFilter} will call the methods provided by an implementation of this interface.
+ * {@link org.springframework.security.web.authentication.AbstractAuthenticationProcessingFilter
+ * AbstractAuthenticationProcessingFilter} and
+ * {@link org.springframework.security.web.authentication.rememberme.RememberMeAuthenticationFilter
+ * RememberMeAuthenticationFilter} will call the methods provided by an implementation of this interface.
  * <p>
  * Implementations may implement any type of remember-me capability they wish.
  * Rolling cookies (as per <a href="http://fishbowl.pastiche.org/2004/01/19/persistent_login_cookie_best_practice">

web/src/main/java/org/springframework/security/web/authentication/SavedRequestAwareAuthenticationSuccessHandler.java

@@ -38,7 +38,8 @@ import org.springframework.util.StringUtils;
  * If a {@link DefaultSavedRequest} is found in the <tt>RequestCache</tt> (as set by the {@link ExceptionTranslationFilter} to
  * record the original destination before the authentication process commenced), a redirect will be performed to the
  * Url of that original destination. The <tt>DefaultSavedRequest</tt> object will remain cached and be picked up
- * when the redirected request is received (See {@link SavedRequestAwareWrapper}).
+ * when the redirected request is received
+ * (See {@link org.springframework.security.web.savedrequest.SavedRequestAwareWrapper SavedRequestAwareWrapper}).
  * </li>
  * <li>
  * If no <tt>DefaultSavedRequest</tt> is found, it will delegate to the base class.

web/src/main/java/org/springframework/security/web/authentication/UsernamePasswordAuthenticationFilter.java

@@ -35,10 +35,10 @@ import org.springframework.util.Assert;
  * Login forms must present two parameters to this filter: a username and
  * password. The default parameter names to use are contained in the
  * static fields {@link #SPRING_SECURITY_FORM_USERNAME_KEY} and {@link #SPRING_SECURITY_FORM_PASSWORD_KEY}.
- * The parameter names can also be changed by setting the {@literal usernameParameter} and {@literal passwordParameter}
+ * The parameter names can also be changed by setting the {@code usernameParameter} and {@code passwordParameter}
  * properties.
  * <p>
- * This filter by default responds to the URL {@literal /j_spring_security_check}.
+ * This filter by default responds to the URL {@code /j_spring_security_check}.
  *
  * @author Ben Alex
  * @author Colin Sampaleanu

web/src/main/java/org/springframework/security/web/authentication/preauth/PreAuthenticatedAuthenticationToken.java

@@ -22,11 +22,6 @@ public class PreAuthenticatedAuthenticationToken extends AbstractAuthenticationT
      * org.springframework.security.core.Authentication#isAuthenticated()} will return
      * <code>false</code>.
      *
-     * @TODO Should we have only a single credentials parameter here? For
-     *       example for X509 the certificate is used as credentials, while
-     *       currently a J2EE username is specified as a principal but could as
-     *       well be set as credentials.
-     *
      * @param aPrincipal
      *            The pre-authenticated principal
      * @param aCredentials

web/src/main/java/org/springframework/security/web/authentication/preauth/PreAuthenticatedGrantedAuthoritiesAuthenticationDetails.java

@@ -25,16 +25,6 @@ public class PreAuthenticatedGrantedAuthoritiesAuthenticationDetails extends Aut
         super(context);
     }
 
-    /**
-     * @return The String representation of this object.
-     */
-    public String toString() {
-        StringBuilder sb = new StringBuilder();
-        sb.append(super.toString() + "; ");
-        sb.append("preAuthenticatedGrantedAuthorities: " + preAuthenticatedGrantedAuthorities);
-        return sb.toString();
-    }
-
     /**
      *
      * @see org.springframework.security.core.authority.GrantedAuthoritiesContainer#getGrantedAuthorities()
@@ -46,9 +36,19 @@ public class PreAuthenticatedGrantedAuthoritiesAuthenticationDetails extends Aut
     }
 
     /**
-     * @see org.springframework.security.core.authority.MutableGrantedAuthoritiesContainer#setGrantedAuthorities()
+     * @see MutableGrantedAuthoritiesContainer#setGrantedAuthorities(List)
      */
     public void setGrantedAuthorities(List<GrantedAuthority> aJ2eeBasedGrantedAuthorities) {
         this.preAuthenticatedGrantedAuthorities = Collections.unmodifiableList(aJ2eeBasedGrantedAuthorities);
     }
+
+    /**
+     * @return The String representation of this object.
+     */
+    public String toString() {
+        StringBuilder sb = new StringBuilder();
+        sb.append(super.toString() + "; ");
+        sb.append("preAuthenticatedGrantedAuthorities: " + preAuthenticatedGrantedAuthorities);
+        return sb.toString();
+    }
 }

web/src/main/java/org/springframework/security/web/authentication/preauth/j2ee/J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource.java

@@ -11,15 +11,15 @@ import javax.servlet.http.HttpServletRequest;
 
 /**
  * Implementation of AuthenticationDetailsSource which converts the user's J2EE roles (as obtained by calling
- * {@link HttpServletRequest#isUserInRole(String)}) into GrantedAuthoritys and stores these in the authentication
+ * {@link HttpServletRequest#isUserInRole(String)}) into {@code GrantedAuthority}s and stores these in the authentication
- * details object (.
+ * details object.
  *
  * @author Ruud Senden
  * @since 2.0
  */
 public class J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource extends AbstractPreAuthenticatedAuthenticationDetailsSource {
     /**
-     * Public constructor which overrides the default AuthenticationDetails
+     * Public constructor which overrides the default {@code WebAuthenticationDetails}
      * class to be used.
      */
     public J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource() {
@@ -30,10 +30,6 @@ public class J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource extends Abs
 
     /**
      * Obtains the list of user roles based on the current user's J2EE roles.
-     *
-     * @param request The request against which <tt>isUserInRole</tt> will be called for each role name
-     *                returned by the MappableAttributesRetriever.
-     * @return GrantedAuthority[] mapped from the user's J2EE roles.
      */
     protected Collection<String> getUserRoles(Object context, Set<String> mappableRoles) {
         ArrayList<String> j2eeUserRolesList = new ArrayList<String>();

web/src/main/java/org/springframework/security/web/authentication/session/ConcurrentSessionControlStrategy.java

@@ -115,7 +115,6 @@ public class ConcurrentSessionControlStrategy extends SessionFixationProtectionS
     /**
      * Allows subclasses to customise behaviour when too many sessions are detected.
      *
-     * @param sessionId the session ID of the present request
      * @param sessions either <code>null</code> or all unexpired sessions associated with the principal
      * @param allowableSessions the number of concurrent sessions the user is allowed to have
      * @param registry an instance of the <code>SessionRegistry</code> for subclass use

web/src/main/java/org/springframework/security/web/context/HttpSessionSecurityContextRepository.java

@@ -42,7 +42,7 @@ import org.springframework.util.ReflectionUtils;
  * ensure that the <tt>allowSessionCreation</tt> property of this class is set to <tt>true</tt> (the default).
  * <p>
  * If for whatever reason no {@code HttpSession} should <b>ever</b> be created (for example, if
- * Basic authentication is being used or similar clients that will never present the same {@literal jsessionid}), then
+ * Basic authentication is being used or similar clients that will never present the same {@code jsessionid}), then
  * {@link #setAllowSessionCreation(boolean) allowSessionCreation} should be set to <code>false</code>.
  * Only do this if you really need to conserve server memory and ensure all classes using the
  * {@code SecurityContextHolder} are designed to have no persistence of the {@code SecurityContext}

web/src/main/java/org/springframework/security/web/savedrequest/RequestCache.java

@@ -22,7 +22,8 @@ public interface RequestCache {
 
     /**
      * Returns the saved request, leaving it cached.
-     * @param currentRequest the current
+     *
+     * @param request the current request
      * @return the saved request which was previously cached, or null if there is none.
      */
     SavedRequest getRequest(HttpServletRequest request, HttpServletResponse response);
@@ -39,8 +40,9 @@ public interface RequestCache {
     HttpServletRequest getMatchingRequest(HttpServletRequest request, HttpServletResponse response);
 
     /**
-     * Removes the cached request
+     * Removes the cached request.
-     * @param currentRequest
+     *
+     * @param request the current request, allowing access to the cache.
      */
     void removeRequest(HttpServletRequest request, HttpServletResponse response);
 

web/src/main/java/org/springframework/security/web/util/TextEscapeUtils.java

@@ -1,11 +1,11 @@
 package org.springframework.security.web.util;
 
 /**
- * Internal utility for escaping characters in HTML strings.
+ * Internal utility for <a href="http://www.owasp.org/index.php/How_to_perform_HTML_entity_encoding_in_Java">escaping
+ * characters in HTML strings</a>.
  *
  * @author Luke Taylor
  *
- * @see http://www.owasp.org/index.php/How_to_perform_HTML_entity_encoding_in_Java
  */
 public abstract class TextEscapeUtils {