Javadoc fixes.

2026-05-22 21:33:16 +00:00 · 2010-02-14 23:27:09 +00:00
parent 36612377e2
commit c12c43da9e
42 changed files with 106 additions and 139 deletions
@@ -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 {
-        HttpServletRequest request = (HttpServletRequest) req;
-
+    public void commence(HttpServletRequest request, HttpServletResponse res) throws IOException, ServletException {
        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);
@@ -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
- * {@link #addSecureUrl(String, List<ConfigAttribute>)} is very important.
- * The system will identify the <b>first</b>  matching regular
- * expression for a given HTTP URL. It will not proceed to evaluate later regular expressions if a match has already
- * been found. Accordingly, the most specific regular expressions should be registered first, with the most general
- * regular expressions registered last.
+ * The order of the URL paths in the map is very important.
+ * The system will identify the <b>first</b>  matching path for a given HTTP URL. It will not proceed to evaluate
+ * later paths if a match has already been found. Accordingly, the most specific matches should be
+ * registered first, with the most general matches registered last.
 * <p>
- * If URLs are registered for a particular HTTP method using
- * {@link #addSecureUrl(String, String, List<ConfigAttribute>)}, then the method-specific matches will take
+ * If URL paths are registered for a particular HTTP method using, then the method-specific matches will take
 * precedence over any URLs which are registered without an HTTP method.
 *
 * @author Ben Alex
@@ -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)
-     * successfulAuthentication} method will be invoked</li>
+     * The configured {link SessionAuthenticationStrategy} will be invoked followed by the
+     * {@link #successfulAuthentication(HttpServletRequest, HttpServletResponse, Authentication)
+     * successfulAuthentication} method</li>
     * <li>An <tt>AuthenticationException</tt> occurs during authentication.
-     * The {@link #unSuccessfulAuthentication(HttpServletRequest, HttpServletResponse, Authentication)
-     * unSuccessfulAuthentication} method will be invoked</li>
+     * The {@link #unsuccessfulAuthentication(HttpServletRequest, HttpServletResponse, AuthenticationException)
+     * 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
@@ -18,7 +18,6 @@ import org.springframework.security.core.Authentication;
 *
 * @author Luke Taylor
 * @since 3.0
- * @see
 */
 public interface AuthenticationSuccessHandler {

@@ -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
- * {@link RememberMeAuthenticationFilter} will call the methods provided by an implementation of this interface.
+ * Spring Security filters (namely
+ * {@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">
@@ -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.
@@ -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
@@ -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
@@ -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();
+    }
 }
@@ -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
- * details object (.
+ * {@link HttpServletRequest#isUserInRole(String)}) into {@code GrantedAuthority}s and stores these in the authentication
+ * 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>();
@@ -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
@@ -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}
@@ -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
-     * @param currentRequest
+     * Removes the cached request.
+     *
+     * @param request the current request, allowing access to the cache.
     */
    void removeRequest(HttpServletRequest request, HttpServletResponse response);

@@ -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 {