Merge pull request #2193 from HorizonNet/TACHYON-935

[TACHYON-935] Added the usage of links in the documentation in the tachyon.security packages

common/src/main/java/tachyon/security/LoginUser.java

@@ -94,7 +94,8 @@ private static User login(TachyonConf conf) throws IOException {
   }
 
   /**
-   * Checks whether Tachyon is running in secure mode, such as SIMPLE, KERBEROS, CUSTOM.
+   * Checks whether Tachyon is running in secure mode, such as {@link AuthType#SIMPLE},
+   * {@link AuthType#KERBEROS}, {@link AuthType#CUSTOM}.
    *
    * @param authType the authentication type in configuration
    */

common/src/main/java/tachyon/security/authentication/AuthenticationProvider.java

@@ -41,9 +41,10 @@ public static AuthenticationProvider getAuthenticationProvider(AuthType authType
   }
 
   /**
-   * The authenticate method is called by the PlainServerCallbackHandler in the PlainSaslServer
-   * layer to authenticate users for their requests. If a user is to be granted, return
-   * nothing/throw nothing. When a user is to be disallowed, throw an appropriate
+   * The authenticate method is called by the
+   * {@link tachyon.security.authentication.PlainSaslServer.PlainServerCallbackHandler} in the
+   * {@link PlainSaslServer} layer to authenticate users for their requests. If a user is to be
+   * granted, return nothing/throw nothing. When a user is to be disallowed, throw an appropriate
    * {@link AuthenticationException}.
    *
    * @param user The username received over the connection request

common/src/main/java/tachyon/security/authentication/AuthenticationUtils.java

@@ -37,9 +37,9 @@
  */
 public final class AuthenticationUtils {
   /**
-   * For server side, this method returns a TTransportFactory based on the auth type. It is used as
-   * one argument to build a Thrift TServer. If the auth type is not supported or recognized, an
-   * UnsupportedOperationException is thrown.
+   * For server side, this method returns a {@link TTransportFactory} based on the auth type. It is
+   * used as one argument to build a Thrift {@link org.apache.thrift.server.TServer}. If the auth
+   * type is not supported or recognized, an {@link UnsupportedOperationException} is thrown.
    *
    * @param tachyonConf Tachyon Configuration
    * @return a corresponding TTransportFactory
@@ -64,11 +64,12 @@ public static TTransportFactory getServerTransportFactory(TachyonConf tachyonCon
   }
 
   /**
-   * Creates a transport per the connection options. Supported transport options are: NOSASL,
-   * SIMPLE, CUSTOM, KERBEROS. With NOSASL as input, an unmodified TTransport is returned; with
+   * Creates a transport per the connection options. Supported transport options are:
+   * {@link AuthType#NOSASL}, {@link AuthType#SIMPLE}, {link@ AuthType#CUSTOM},
+   * {@link AuthType#KERBEROS}. With NOSASL as input, an unmodified TTransport is returned; with
    * SIMPLE/CUSTOM as input, a PlainClientTransport is returned; KERBEROS is not supported
-   * currently. If the auth type is not supported or recognized, an UnsupportedOperationException is
-   * thrown.
+   * currently. If the auth type is not supported or recognized, an
+   * {@link UnsupportedOperationException} is thrown.
    *
    * @param tachyonConf Tachyon Configuration
    * @param serverAddress the server address which clients will connect to

common/src/main/java/tachyon/security/authentication/CustomAuthenticationProviderImpl.java

@@ -23,7 +23,7 @@
 /**
  * An authentication provider implementation that allows {@link AuthenticationProvider} to be
  * customized at configuration time. This authentication provider is created if authentication type
- * specified in {@link TachyonConf} is {@link AuthType#CUSTOM CUSTOM}. It requires the property
+ * specified in {@link TachyonConf} is {@link AuthType#CUSTOM}. It requires the property
  * {@code tachyon.security.authentication.custom.provider} to be set in {@link TachyonConf
  * Configuration} to determine which provider to load.
  */

common/src/main/java/tachyon/security/authentication/PlainSaslServer.java

@@ -38,14 +38,14 @@
  * provider needed to register to support server-side PLAIN mechanism. This class completes three
  * basic steps to implement a SASL security provider:
  * <ol>
- * <li>Write a class that implements the SaslServer interface</li>
- * <li>Write a factory class implements the SaslServerFactory</li>
+ * <li>Write a class that implements the {@link SaslServer} interface</li>
+ * <li>Write a factory class implements the {@link javax.security.sasl.SaslServerFactory}</li>
  * <li>Write a JCA provider that registers the factory</li>
  * </ol>
  *
- * NOTE: When this SaslServer works on authentication (i.e., in the method evaluateResponse()), it
- * always assigns authentication ID to authorization ID currently.
- *
+ * NOTE: When this SaslServer works on authentication (i.e., in the method
+ * {@link #evaluateResponse(byte[])}, it always assigns authentication ID to authorization ID
+ * currently.
  */
 // TODO(dong): Authorization ID and authentication ID could be different after supporting
 // impersonation.
@@ -168,7 +168,7 @@ private void checkNotComplete() {
   }
 
   /**
-   * PlainServerCallbackHandler is used by the SASL mechanisms to get further information to
+   * {@link PlainServerCallbackHandler} is used by the SASL mechanisms to get further information to
    * complete the authentication. For example, a SASL mechanism might use this callback handler to
    * do verification operation.
    */
@@ -213,7 +213,7 @@ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallback
   /**
    * An instance of this class represents a client user connecting to Tachyon service.
    *
-   * It is maintained in a ThreadLocal variable based on the Thrift RPC mechanism.
+   * It is maintained in a {@link ThreadLocal} variable based on the Thrift RPC mechanism.
    * {@link org.apache.thrift.server.TThreadPoolServer} allocates a thread to serve a connection
    * from client side and take back it when connection is closed. During the thread alive cycle,
    * all the RPC happens in this thread. These RPC methods implemented in server side could
@@ -222,12 +222,12 @@ public void handle(Callback[] callbacks) throws IOException, UnsupportedCallback
   public static final class AuthorizedClientUser {
 
     /**
-     * A ThreadLocal variable to maintain the client user along with a specific thread.
+     * A {@link ThreadLocal} variable to maintain the client user along with a specific thread.
      */
     private static ThreadLocal<User> sUserThreadLocal = new ThreadLocal<User>();
 
     /**
-     * Creates a {@link User} and sets it to the ThreadLocal variable.
+     * Creates a {@link User} and sets it to the {@link ThreadLocal} variable.
      *
      * @param userName the name of the client user
      */
@@ -236,7 +236,7 @@ public static void set(String userName) {
     }
 
     /**
-     * Gets the {@link User} from the ThreadLocal variable.
+     * Gets the {@link User} from the {@link ThreadLocal} variable.
      *
      * @return the client user
      */
@@ -245,7 +245,7 @@ public static User get() {
     }
 
     /**
-     * Removes the {@link User} from the ThreadLocal variable.
+     * Removes the {@link User} from the {@link ThreadLocal} variable.
      */
     public static void remove() {
       sUserThreadLocal.remove();

common/src/main/java/tachyon/security/authentication/PlainSaslServerProvider.java

@@ -46,9 +46,9 @@ public PlainSaslServerProvider() {
    */
   public static class PlainSaslServerFactory implements SaslServerFactory {
     /**
-     * Creates a SaslServer using the parameters supplied. It returns null if no SaslServer can be
-     * created using the parameters supplied. Throws SaslException if it cannot create a SaslServer
-     * because of an error.
+     * Creates a {@link SaslServer} using the parameters supplied. It returns null if no SaslServer
+     * can be created using the parameters supplied. Throws {@link SaslException} if it cannot
+     * create a SaslServer because of an error.
      *
      * @param mechanism the name of a SASL mechanism. (e.g. "PLAIN")
      * @param protocol the non-null string name of the protocol for which the authentication is

common/src/main/java/tachyon/security/authentication/PlainSaslUtils.java

@@ -52,13 +52,13 @@ public static boolean isPlainSaslProviderAdded() {
   }
 
   /**
-   * For server side, get a PLAIN mechanism TTransportFactory. A callback handler is hooked for
-   * specific authentication methods.
+   * For server side, get a PLAIN mechanism {@link TTransportFactory}. A callback handler is hooked
+   * for specific authentication methods.
    *
    * @param authType the authentication type
-   * @param conf TachyonConf
+   * @param conf {@link TachyonConf}
    * @return a corresponding TTransportFactory, which is PLAIN mechanism
-   * @throws SaslException if an AuthenticationProvider is not found
+   * @throws SaslException if an {@link AuthenticationProvider} is not found
    */
   public static TTransportFactory getPlainServerTransportFactory(AuthType authType,
       TachyonConf conf) throws SaslException {

common/src/main/java/tachyon/security/authorization/PermissionStatus.java

@@ -90,7 +90,8 @@ public PermissionStatus applyUMask(FileSystemPermission umask) {
   }
 
   /**
-   * Gets the Directory default PermissionStatus. Currently the default dir permission is 0777.
+   * Gets the Directory default {@link PermissionStatus}. Currently the default dir permission is
+   * 0777.
    *
    * @return the default {@link PermissionStatus} for directories
    */

common/src/main/java/tachyon/security/login/AppLoginModule.java

@@ -43,7 +43,7 @@ public void initialize(Subject subject, CallbackHandler callbackHandler,
   }
 
   /**
-   * Retrieves the user name by querying the property of Constants.SECURITY_LOGIN_USERNAME.
+   * Retrieves the user name by querying the property of {@link Constants#SECURITY_LOGIN_USERNAME}.
    *
    * @return true if user name provided by application is set and not empty
    * @throws javax.security.auth.login.LoginException

common/src/main/java/tachyon/security/login/TachyonJaasConfiguration.java

@@ -54,11 +54,12 @@ public final class TachyonJaasConfiguration extends Configuration {
   // private static final AppConfigurationEntry KERBEROS_LOGIN = ...
 
   /**
-   * In SIMPLE mode, JAAS first tries to retrieve the user name set by the application with
-   * {@link tachyon.security.login.AppLoginModule}. Upon failure, it uses the OS specific login
-   * module to fetch the OS user, and then uses the
+   * In {@link AuthType#SIMPLE} mode, JAAS first tries to retrieve the user name set by the
+   * application with {@link tachyon.security.login.AppLoginModule}. Upon failure, it uses the OS
+   * specific login module to fetch the OS user, and then uses the
    * {@link tachyon.security.login .TachyonLoginModule} to convert it to a Tachyon user represented
-   * by {@link tachyon.security.User}. In CUSTOM mode, we also use this configuration.
+   * by {@link tachyon.security.User}. In {@link AuthType#CUSTOM} mode, we also use this
+   * configuration.
    */
   private static final AppConfigurationEntry[] SIMPLE = new AppConfigurationEntry[] {APP_LOGIN,
       OS_SPECIFIC_LOGIN, TACHYON_LOGIN};