SEC-3056 - Fix JavaDoc errors.

Fixed JavaDoc errors accross multiple modules in order to make javadoc happy with Java 8.
2026-08-05 09:47:05 +00:00 · 2015-07-30 01:13:33 +02:00
parent 7317c090cc
commit ad1d858e2b
84 changed files with 235 additions and 268 deletions
@@ -59,14 +59,14 @@ import java.util.*;
 * requests which match the pattern. An example configuration might look like this:
 *
 * <pre>
- *  &lt;bean id="myfilterChainProxy" class="org.springframework.security.util.FilterChainProxy">
- *      &lt;constructor-arg>
- *          &lt;util:list>
- *              &lt;security:filter-chain pattern="/do/not/filter*" filters="none"/>
- *              &lt;security:filter-chain pattern="/**" filters="filter1,filter2,filter3"/>
- *          &lt;/util:list>
- *      &lt;/constructor-arg>
- *  &lt;/bean>
+ *  &lt;bean id="myfilterChainProxy" class="org.springframework.security.util.FilterChainProxy"&gt;
+ *      &lt;constructor-arg&gt;
+ *          &lt;util:list&gt;
+ *              &lt;security:filter-chain pattern="/do/not/filter*" filters="none"/&gt;
+ *              &lt;security:filter-chain pattern="/**" filters="filter1,filter2,filter3"/&gt;
+ *          &lt;/util:list&gt;
+ *      &lt;/constructor-arg&gt;
+ *  &lt;/bean&gt;
 * </pre>
 *
 * The names "filter1", "filter2", "filter3" should be the bean names of {@code Filter}
@@ -50,7 +50,7 @@ public class PortMapperImpl implements PortMapper {
 	// ========================================================================================================

 	/**
-	 * Returns the translated (Integer -> Integer) version of the original port mapping
+	 * Returns the translated (Integer -&gt; Integer) version of the original port mapping
 	 * specified via setHttpsPortMapping()
 	 */
 	public Map<Integer, Integer> getTranslatedPortMappings() {
@@ -77,12 +77,12 @@ public class PortMapperImpl implements PortMapper {
 	 * like this:
 	 * 
 	 * <pre>
-	 *  &lt;property name="portMappings">
-	 *      &lt;map>
-	 *          &lt;entry key="80">&lt;value>443&lt;/value>&lt;/entry>
-	 *          &lt;entry key="8080">&lt;value>8443&lt;/value>&lt;/entry>
-	 *      &lt;/map>
-	 * &lt;/property>
+	 *  &lt;property name="portMappings"&gt;
+	 *      &lt;map&gt;
+	 *          &lt;entry key="80"&gt;&lt;value&gt;443&lt;/value&gt;&lt;/entry&gt;
+	 *          &lt;entry key="8080"&gt;&lt;value&gt;8443&lt;/value&gt;&lt;/entry&gt;
+	 *      &lt;/map&gt;
+	 * &lt;/property&gt;
 	 * </pre>
 	 *
 	 * @param newMappings A Map consisting of String keys and String values, where for
@@ -50,30 +50,30 @@ import org.springframework.web.filter.GenericFilterBean;
 * 
 * <pre>
 *
- * &lt;bean id="channelProcessingFilter" class="org.springframework.security.web.access.channel.ChannelProcessingFilter">
- *   &lt;property name="channelDecisionManager" ref="channelDecisionManager"/>
- *   &lt;property name="securityMetadataSource">
- *     &lt;security:filter-security-metadata-source request-matcher="regex">
- *       &lt;security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/>
- *       &lt;security:intercept-url pattern="\A/login.jsp.*\Z" access="REQUIRES_SECURE_CHANNEL"/>
- *       &lt;security:intercept-url pattern="\A/.*\Z" access="ANY_CHANNEL"/>
- *     &lt;/security:filter-security-metadata-source>
- *   &lt;/property>
- * &lt;/bean>
+ * &lt;bean id="channelProcessingFilter" class="org.springframework.security.web.access.channel.ChannelProcessingFilter"&gt;
+ *   &lt;property name="channelDecisionManager" ref="channelDecisionManager"/&gt;
+ *   &lt;property name="securityMetadataSource"&gt;
+ *     &lt;security:filter-security-metadata-source request-matcher="regex"&gt;
+ *       &lt;security:intercept-url pattern="\A/secure/.*\Z" access="REQUIRES_SECURE_CHANNEL"/&gt;
+ *       &lt;security:intercept-url pattern="\A/login.jsp.*\Z" access="REQUIRES_SECURE_CHANNEL"/&gt;
+ *       &lt;security:intercept-url pattern="\A/.*\Z" access="ANY_CHANNEL"/&gt;
+ *     &lt;/security:filter-security-metadata-source&gt;
+ *   &lt;/property&gt;
+ * &lt;/bean&gt;
 * 
- * &lt;bean id="channelDecisionManager" class="org.springframework.security.web.access.channel.ChannelDecisionManagerImpl">
- *   &lt;property name="channelProcessors">
- *     &lt;list>
- *     &lt;ref bean="secureChannelProcessor"/>
- *     &lt;ref bean="insecureChannelProcessor"/>
- *     &lt;/list>
- *   &lt;/property>
- * &lt;/bean>
+ * &lt;bean id="channelDecisionManager" class="org.springframework.security.web.access.channel.ChannelDecisionManagerImpl"&gt;
+ *   &lt;property name="channelProcessors"&gt;
+ *     &lt;list&gt;
+ *     &lt;ref bean="secureChannelProcessor"/&gt;
+ *     &lt;ref bean="insecureChannelProcessor"/&gt;
+ *     &lt;/list&gt;
+ *   &lt;/property&gt;
+ * &lt;/bean&gt;
 * 
 * &lt;bean id="secureChannelProcessor"
- *   class="org.springframework.security.web.access.channel.SecureChannelProcessor"/>
+ *   class="org.springframework.security.web.access.channel.SecureChannelProcessor"/&gt;
 * &lt;bean id="insecureChannelProcessor"
- *   class="org.springframework.security.web.access.channel.InsecureChannelProcessor"/>
+ *   class="org.springframework.security.web.access.channel.InsecureChannelProcessor"/&gt;
 * 
 * </pre>
 * 
@@ -46,8 +46,8 @@ public class DefaultWebSecurityExpressionHandler extends

 	/**
 	 * <p>
-	 * Sets the default prefix to be added to {@link #hasAnyRole(String...)} or
-	 * {@link #hasRole(String)}. For example, if hasRole("ADMIN") or hasRole("ROLE_ADMIN")
+	 * Sets the default prefix to be added to {@link org.springframework.security.access.expression.SecurityExpressionRoot#hasAnyRole(String...)} or
+	 * {@link org.springframework.security.access.expression.SecurityExpressionRoot#hasRole(String)}. For example, if hasRole("ADMIN") or hasRole("ROLE_ADMIN")
 	 * is passed in, then the role ROLE_ADMIN will be used when the defaultRolePrefix is
 	 * "ROLE_" (default).
 	 * </p>
@@ -10,15 +10,14 @@ import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.springframework.security.core.Authentication;
 import org.springframework.security.web.access.ExceptionTranslationFilter;
-import org.springframework.security.web.savedrequest.HttpSessionRequestCache;
-import org.springframework.security.web.savedrequest.RequestCache;
-import org.springframework.security.web.savedrequest.SavedRequest;
-import org.springframework.security.web.savedrequest.DefaultSavedRequest;
 import org.springframework.util.StringUtils;
+import org.springframework.security.web.savedrequest.SavedRequest;
+import org.springframework.security.web.savedrequest.RequestCache;
+import org.springframework.security.web.savedrequest.HttpSessionRequestCache;

 /**
 * An authentication success strategy which can make use of the
- * {@link DefaultSavedRequest} which may have been stored in the session by the
+ * {@link org.springframework.security.web.savedrequest.DefaultSavedRequest} which may have been stored in the session by the
 * {@link ExceptionTranslationFilter}. When such a request is intercepted and requires
 * authentication, the request data is stored to record the original destination before
 * the authentication process commenced, and to allow the request to be reconstructed when
@@ -36,15 +35,15 @@ import org.springframework.util.StringUtils;
 * If the {@code targetUrlParameter} has been set on the request, the value will be used
 * as the destination. Any {@code DefaultSavedRequest} will again be removed.</li>
 * <li>
- * If a {@link SavedRequest} is found in the {@code RequestCache} (as set by the
+ * If a {@link org.springframework.security.web.savedrequest.SavedRequest} is found in the {@code RequestCache} (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 {@code SavedRequest} object will remain cached and be picked
 * up when the redirected request is received (See
- * {@link org.springframework.security.web.savedrequest.SavedRequestAwareWrapper
- * SavedRequestAwareWrapper}).</li>
+ * <a href="{@docRoot}/org/springframework/security/web/savedrequest/SavedRequestAwareWrapper.html">SavedRequestAwareWrapper</a>).
+ * </li>
 * <li>
- * If no {@code SavedRequest} is found, it will delegate to the base class.</li>
+ * If no {@link org.springframework.security.web.savedrequest.SavedRequest} is found, it will delegate to the base class.</li>
 * </ul>
 *
 * @author Luke Taylor
@@ -23,7 +23,7 @@ import javax.servlet.http.HttpSession;
 import org.springframework.util.ReflectionUtils;

 /**
- * Uses {@link HttpServletRequest#changeSessionId()} to protect against session fixation
+ * Uses {@code HttpServletRequest.changeSessionId()} to protect against session fixation
 * attacks. This is the default implementation for Servlet 3.1+.
 *
 * @author Rob Winch
@@ -16,13 +16,12 @@ import org.springframework.util.Assert;
 * {@link RegisterSessionAuthenticationStrategy} is typically used in combination with
 * {@link CompositeSessionAuthenticationStrategy} and
 * {@link ConcurrentSessionControlAuthenticationStrategy}, but can be used on its own if
- * tracking of sessions is desired but no need to control concurrency.</P
+ * tracking of sessions is desired but no need to control concurrency.
 *
 * <p>
 * NOTE: When using a {@link SessionRegistry} it is important that all sessions (including
 * timed out sessions) are removed. This is typically done by adding
 * {@link HttpSessionEventPublisher}.
- * </p>
 *
 * @see CompositeSessionAuthenticationStrategy
 *
@@ -27,7 +27,7 @@ import javax.servlet.http.HttpSession;
 import org.springframework.util.Assert;

 /**
- * The default implementation of {@link SessionAuthenticationStrategy} when using <
+ * The default implementation of {@link SessionAuthenticationStrategy} when using &lt;
 * Servlet 3.1.
 * <p>
 * Creates a new session for the newly authenticated user if they already have a session
@@ -92,12 +92,12 @@ import org.springframework.web.filter.GenericFilterBean;
 * correct constraints to the <tt>switchUserUrl</tt>. Example:
 * 
 * <pre>
- * &lt;bean id="switchUserProcessingFilter" class="org.springframework.security.web.authentication.switchuser.SwitchUserFilter">
- *    &lt;property name="userDetailsService" ref="userDetailsService" />
- *    &lt;property name="switchUserUrl" value="/login/impersonate" />
- *    &lt;property name="exitUserUrl" value="/logout/impersonate" />
- *    &lt;property name="targetUrl" value="/index.jsp" />
- * &lt;/bean>
+ * &lt;bean id="switchUserProcessingFilter" class="org.springframework.security.web.authentication.switchuser.SwitchUserFilter"&gt;
+ *    &lt;property name="userDetailsService" ref="userDetailsService" /&gt;
+ *    &lt;property name="switchUserUrl" value="/login/impersonate" /&gt;
+ *    &lt;property name="exitUserUrl" value="/logout/impersonate" /&gt;
+ *    &lt;property name="targetUrl" value="/index.jsp" /&gt;
+ * &lt;/bean&gt;
 * </pre>
 *
 * @author Mark St.Godard
@@ -34,13 +34,14 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 * {@link Controller}:
 *
 * <pre>
- * @Controller
+ * &#64;Controller
 * public class MyController {
- *     @RequestMapping("/user/current/show")
+ *     &#64;RequestMapping("/user/current/show")
 *     public String show(@AuthenticationPrincipal CustomUser customUser) {
 *         // do something with CustomUser
 *         return "view";
 *     }
+ * }
 * </pre>
 *
 * <p>
@@ -50,11 +51,9 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 * match, null will be returned unless
 * {@link AuthenticationPrincipal#errorOnInvalidType()} is true in which case a
 * {@link ClassCastException} will be thrown.
- * </p>
 *
 * <p>
 * Alternatively, users can create a custom meta annotation as shown below:
- * </p>
 *
 * <pre>
 * &#064;Target({ ElementType.PARAMETER })
@@ -66,16 +65,16 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 *
 * <p>
 * The custom annotation can then be used instead. For example:
- * </p>
 *
 * <pre>
- * @Controller
+ * &#64;Controller
 * public class MyController {
- *     @RequestMapping("/user/current/show")
+ *     &#64;RequestMapping("/user/current/show")
 *     public String show(@CurrentUser CustomUser customUser) {
 *         // do something with CustomUser
 *         return "view";
 *     }
+ * }
 * </pre>
 *
 * @deprecated use org.springframework.security.web.method.annotation.
@@ -267,7 +267,7 @@ public abstract class AbstractSecurityWebApplicationInitializer implements
 	}

 	/**
-	 * Return the <servlet-name> to use the DispatcherServlet's
+	 * Return the &lt;servlet-name&gt; to use the DispatcherServlet's
 	 * {@link WebApplicationContext} to find the {@link DelegatingFilterProxy} or null to
 	 * use the parent {@link ApplicationContext}.
 	 *
@@ -278,7 +278,7 @@ public abstract class AbstractSecurityWebApplicationInitializer implements
 	 * {@link WebApplicationContext}.
 	 * </p>
 	 *
-	 * @return the <servlet-name> of the DispatcherServlet to use its
+	 * @return the &lt;servlet-name&gt; of the DispatcherServlet to use its
 	 * {@link WebApplicationContext} or null (default) to use the parent
 	 * {@link ApplicationContext}.
 	 */
@@ -28,7 +28,8 @@ import javax.servlet.http.HttpServletRequest;
 public class InvalidCsrfTokenException extends CsrfException {

 	/**
-	 * @param msg
+	 * @param expectedAccessToken
+	 * @param actualAccessToken
 	 */
 	public InvalidCsrfTokenException(CsrfToken expectedAccessToken,
 			String actualAccessToken) {
@@ -85,7 +85,7 @@ public final class XXssProtectionHeaderWriter implements HeaderWriter {
 	 * If false, will not specify the mode as blocked. In this instance, any content will
 	 * be attempted to be fixed. If true, the content will be replaced with "#".
 	 *
-	 * @param enabled the new value
+	 * @param block the new value
 	 */
 	public void setBlock(boolean block) {
 		if (!enabled && block) {
@@ -7,7 +7,7 @@ import java.util.regex.Pattern;
 /**
 * Implementation which uses a regular expression to validate the supplied origin. If the
 * value of the HTTP parameter matches the pattern, then the the result will be ALLOW-FROM
- * <paramter-value>.
+ * &lt;paramter-value&gt;.
 *
 * @author Marten Deinum
 * @since 3.2
@@ -50,7 +50,7 @@ public final class XFrameOptionsHeaderWriter implements HeaderWriter {
 	 *
 	 * @param frameOptionsMode the {@link XFrameOptionsMode} to use. If using
 	 * {@link XFrameOptionsMode#ALLOW_FROM}, use
-	 * {@link #FrameOptionsHeaderWriter(AllowFromStrategy)} instead.
+	 * {@link #XFrameOptionsHeaderWriter(AllowFromStrategy)} instead.
 	 */
 	public XFrameOptionsHeaderWriter(XFrameOptionsMode frameOptionsMode) {
 		Assert.notNull(frameOptionsMode, "frameOptionsMode cannot be null");
@@ -34,12 +34,13 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 * {@link Controller}:
 *
 * <pre>
- * @Controller
+ * &#64;Controller
 * public class MyController {
- *     @MessageMapping("/im")
+ *     &#64;MessageMapping("/im")
 *     public void im(@AuthenticationPrincipal CustomUser customUser) {
 *         // do something with CustomUser
 *     }
+ * }
 * </pre>
 *
 * <p>
@@ -49,11 +50,9 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 * match, null will be returned unless
 * {@link AuthenticationPrincipal#errorOnInvalidType()} is true in which case a
 * {@link ClassCastException} will be thrown.
- * </p>
 *
 * <p>
 * Alternatively, users can create a custom meta annotation as shown below:
- * </p>
 *
 * <pre>
 * &#064;Target({ ElementType.PARAMETER })
@@ -65,15 +64,15 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 *
 * <p>
 * The custom annotation can then be used instead. For example:
- * </p>
 *
 * <pre>
- * @Controller
+ * &#64;Controller
 * public class MyController {
- *     @MessageMapping("/im")
+ *     &#64;MessageMapping("/im")
 *     public void im(@CurrentUser CustomUser customUser) {
 *         // do something with CustomUser
 *     }
+ * }
 * </pre>
 *
 * @author Rob Winch
@@ -43,7 +43,6 @@ import org.apache.commons.logging.LogFactory;
 * wrapper. Nevertheless, the important data from the original request is emulated and
 * this should prove adequate for most purposes (in particular standard HTTP GET and POST
 * operations).
- * </p>
 *
 * <p>
 * Added into a request by
@@ -155,7 +155,7 @@ public class SecurityContextHolderAwareRequestFilter extends GenericFilterBean {
 	 * when invoking {@link HttpServletRequest#logout()}.
 	 * </p>
 	 *
-	 * @param logoutHandlers the {@link List<LogoutHandler>}s when invoking
+	 * @param logoutHandlers the {@code List&lt;LogoutHandler&gt;}s when invoking
 	 * {@link HttpServletRequest#logout()}.
 	 *
 	 * @throws IllegalStateException if the Servlet 3 APIs are not found on the classpath
@@ -102,8 +102,11 @@ public class ThrowableAnalyzer {
 	/**
 	 * Initializes associations between <code>Throwable</code>s and
 	 * <code>ThrowableCauseExtractor</code>s. The default implementation performs the
-	 * following registrations: <li>{@link #DEFAULT_EXTRACTOR} for {@link Throwable}</li>
-	 * <li>{@link #INVOCATIONTARGET_EXTRACTOR} for {@link InvocationTargetException}</li> <br>
+	 * following registrations:
+	 * <ul>
+	 * <li>{@link #DEFAULT_EXTRACTOR} for {@link Throwable}</li>
+	 * <li>{@link #INVOCATIONTARGET_EXTRACTOR} for {@link InvocationTargetException}</li>
+	 * </ul><br>
 	 * Subclasses overriding this method are encouraged to invoke the super method to
 	 * perform the default registrations. They can register additional extractors as
 	 * required.