Javadoc fixes.

2026-08-31 22:46:02 +00:00 · 2010-02-14 23:27:09 +00:00
parent 36612377e2
commit c12c43da9e
42 changed files with 106 additions and 139 deletions
@@ -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;
    }

-}
+}
@@ -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
- * in conjunction with an {@link org.springframework.security.acl.AclManager} to
- * obtain the access control list applicable for the domain object instance.
- * </p>
- *
+ * authorised bean properties or <code>Collection</code> elements.
 * <p>
 * Special consideration should be given to using an
 * <code>AfterInvocationManager</code> on bean methods that modify a database.
@@ -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,
- * List<ConfigAttribute>, Object)} method is called. The <code>Object</code> returned from each provider will be
- * presented to the successive provider for processing. This means each provider <b>must</b> ensure they return the
- * <code>Object</code>, even if they are not interested in the "after invocation" decision (perhaps as the secure
- * object invocation did not include a configuration attribute a given provider is configured to respond to).
+ * Every <code>AfterInvocationProvider</code> will be polled when the
+ * {@link #decide(Authentication, Object, Collection, Object)} method is called. The <code>Object</code> returned
+ * from each provider will be presented to the successive provider for processing. This means each provider
+ * <b>must</b> ensure they return the <code>Object</code>, even if they are not interested in the "after invocation"
+ * decision (perhaps as the secure object invocation did not include a configuration attribute a given provider is
+ * configured to respond to).
 *
 * @author Ben Alex
 */
@@ -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
- * {@link org.springframework.aop.framework.autoproxy.DefaultAdvisorAutoProxyCreator}, which makes
+ * This class also allows the use of Spring's {@code 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
-     * class should extend in future. The original hierarchy and constructor have been retained for backwards
+     * This is essentially the approach taken by subclasses of Spring's {@code AbstractBeanFactoryPointcutAdvisor},
+     * 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
@@ -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) {}

@@ -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
- * the <code>AuthenticationEntryPoint</code> to be called, allowing the principal to authenticate with a stronger
- * level of authentication.</p>
+ * anonymously. The commonly used {@link org.springframework.security.web.access.ExceptionTranslationFilter
+ * ExceptionTranslationFilter} will thus cause the <code>AuthenticationEntryPoint</code> to be called, allowing
+ * the principal to authenticate with a stronger level of authentication.
 *
 * @author Ben Alex
 */
@@ -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 ase The {@link SpringSecurityException} that caused the failure
+     * @param token The authentication token being processed
+     * @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) {
@@ -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.
@@ -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);
@@ -19,8 +19,9 @@ import org.springframework.security.core.Authentication;


 /**
- * Base implementation of {@link SecurityContext}.<p>Used by default by {@link SecurityContextHolder} and {@link
- * HttpSessionContextIntegrationFilter}.</p>
+ * Base implementation of {@link SecurityContext}.
+ * <p>
+ * Used by default by {@link SecurityContextHolder} strategies.
 *
 * @author Ben Alex
 */
@@ -24,8 +24,7 @@ public abstract class SessionDestroyedEvent extends ApplicationEvent {
    public abstract SecurityContext getSecurityContext();

    /**
-     * The identifier associated with the destroyed session.
-     * @return
+     * @return the identifier associated with the destroyed session.
     */
    public abstract String getId();
 }
@@ -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
- * 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>
+ * Used to extract the session ID from an <code>Authentication</code> object.
 *
 * @author Ben Alex
 */
@@ -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();

@@ -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);

@@ -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
 */
@@ -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>)
     *