HDFS-5578. [JDK8] Fix Javadoc errors caused by incorrect or illegal tags in doc comments. Contributed by Andrew Purtell.

This commit is contained in:
Haohui Mai 2014-12-10 14:54:08 -08:00
parent 84d50003f6
commit 92916ae487
19 changed files with 81 additions and 79 deletions

View File

@ -78,7 +78,7 @@
/**
* HttpFSServer implementation of the FileSystemAccess FileSystem.
* <p/>
* <p>
* This implementation allows a user to access HDFS over HTTP via a HttpFSServer server.
*/
@InterfaceAudience.Private
@ -223,7 +223,7 @@ public String getMethod() {
/**
* Convenience method that creates a <code>HttpURLConnection</code> for the
* HttpFSServer file system operations.
* <p/>
* <p>
* This methods performs and injects any needed authentication credentials
* via the {@link #getConnection(URL, String)} method
*
@ -289,7 +289,7 @@ public HttpURLConnection run() throws Exception {
/**
* Convenience method that creates a <code>HttpURLConnection</code> for the specified URL.
* <p/>
* <p>
* This methods performs and injects any needed authentication credentials.
*
* @param url url to connect to.
@ -371,7 +371,7 @@ protected int getDefaultPort() {
/**
* HttpFSServer subclass of the <code>FSDataInputStream</code>.
* <p/>
* <p>
* This implementation does not support the
* <code>PositionReadable</code> and <code>Seekable</code> methods.
*/
@ -414,8 +414,8 @@ public boolean seekToNewSource(long targetPos) throws IOException {
/**
* Opens an FSDataInputStream at the indicated Path.
* </p>
* IMPORTANT: the returned <code><FSDataInputStream/code> does not support the
* <p>
* IMPORTANT: the returned <code>FSDataInputStream</code> does not support the
* <code>PositionReadable</code> and <code>Seekable</code> methods.
*
* @param f the file name to open
@ -434,7 +434,7 @@ public FSDataInputStream open(Path f, int bufferSize) throws IOException {
/**
* HttpFSServer subclass of the <code>FSDataOutputStream</code>.
* <p/>
* <p>
* This implementation closes the underlying HTTP connection validating the Http connection status
* at closing time.
*/
@ -516,7 +516,7 @@ private FSDataOutputStream uploadData(String method, Path f, Map<String, String>
/**
* Opens an FSDataOutputStream at the indicated Path with write-progress
* reporting.
* <p/>
* <p>
* IMPORTANT: The <code>Progressable</code> parameter is not used.
*
* @param f the file name to open.
@ -549,7 +549,7 @@ public FSDataOutputStream create(Path f, FsPermission permission,
/**
* Append to an existing file (optional operation).
* <p/>
* <p>
* IMPORTANT: The <code>Progressable</code> parameter is not used.
*
* @param f the existing file to be appended.
@ -838,7 +838,7 @@ public boolean setReplication(Path src, short replication)
* Modify the ACL entries for a file.
*
* @param path Path to modify
* @param aclSpec List<AclEntry> describing modifications
* @param aclSpec describing modifications
* @throws IOException
*/
@Override
@ -855,7 +855,7 @@ public void modifyAclEntries(Path path, List<AclEntry> aclSpec)
/**
* Remove the specified ACL entries from a file
* @param path Path to modify
* @param aclSpec List<AclEntry> describing entries to remove
* @param aclSpec describing entries to remove
* @throws IOException
*/
@Override
@ -900,7 +900,7 @@ public void removeAcl(Path path) throws IOException {
/**
* Set the ACLs for the given file
* @param path Path to modify
* @param aclSpec List<AclEntry> describing modifications, must include
* @param aclSpec describing modifications, must include
* entries for user, group, and others for compatibility
* with permission bits.
* @throws IOException

View File

@ -18,10 +18,10 @@
package org.apache.hadoop.fs.http.client;
/**
* HttpFSServer implementation of the FileSystemAccess FileSystem for SSL.
* <p/>
* This implementation allows a user to access HDFS over HTTPS via a
* HttpFSServer server.
* <p>HttpFSServer implementation of the FileSystemAccess FileSystem for SSL.
* </p>
* <p>This implementation allows a user to access HDFS over HTTPS via a
* HttpFSServer server.</p>
*/
public class HttpsFSFileSystem extends HttpFSFileSystem {

View File

@ -50,7 +50,7 @@ public class CheckUploadContentTypeFilter implements Filter {
/**
* Initializes the filter.
* <p/>
* <p>
* This implementation is a NOP.
*
* @param config filter configuration.
@ -103,7 +103,7 @@ public void doFilter(ServletRequest request, ServletResponse response,
/**
* Destroys the filter.
* <p/>
* <p>
* This implementation is a NOP.
*/
@Override

View File

@ -44,7 +44,7 @@ public class HttpFSAuthenticationFilter
/**
* Returns the hadoop-auth configuration from HttpFSServer's configuration.
* <p/>
* <p>
* It returns all HttpFSServer's configuration properties prefixed with
* <code>httpfs.authentication</code>. The <code>httpfs.authentication</code>
* prefix is removed from the returned property names.

View File

@ -43,7 +43,6 @@ public class HttpFSExceptionProvider extends ExceptionProvider {
/**
* Maps different exceptions thrown by HttpFSServer to HTTP status codes.
* <p/>
* <ul>
* <li>SecurityException : HTTP UNAUTHORIZED</li>
* <li>FileNotFoundException : HTTP NOT_FOUND</li>

View File

@ -85,7 +85,7 @@
/**
* Main class of HttpFSServer server.
* <p/>
* <p>
* The <code>HttpFSServer</code> class uses Jersey JAX-RS to binds HTTP requests to the
* different operations.
*/
@ -117,7 +117,7 @@ private <T> T fsExecute(UserGroupInformation ugi, FileSystemAccess.FileSystemExe
/**
* Returns a filesystem instance. The fileystem instance is wired for release at the completion of
* the current Servlet request via the {@link FileSystemReleaseFilter}.
* <p/>
* <p>
* If a do-as user is specified, the current user must be a valid proxyuser, otherwise an
* <code>AccessControlException</code> will be thrown.
*

View File

@ -34,9 +34,9 @@
* HttpFSServer server, it is a <code>javax.servlet.ServletContextListener
* </code> implementation that is wired in HttpFSServer's WAR
* <code>WEB-INF/web.xml</code>.
* <p/>
* <p>
* It provides acces to the server context via the singleton {@link #get}.
* <p/>
* <p>
* All the configuration is loaded from configuration properties prefixed
* with <code>httpfs.</code>.
*/

View File

@ -61,7 +61,7 @@ private XException(ERROR error, String message, Throwable cause) {
/**
* Creates an XException using another XException as cause.
* <p/>
* <p>
* The error code and error message are extracted from the cause.
*
* @param cause exception cause.
@ -95,7 +95,7 @@ public ERROR getError() {
/**
* Creates a message using a error message template and arguments.
* <p/>
* <p>
* The template must be in JDK <code>MessageFormat</code> syntax
* (using {#} positional parameters).
*

View File

@ -44,11 +44,11 @@ public BaseService(String prefix) {
/**
* Initializes the service.
* <p/>
* <p>
* It collects all service properties (properties having the
* <code>#SERVER#.#SERVICE#.</code> prefix). The property names are then
* trimmed from the <code>#SERVER#.#SERVICE#.</code> prefix.
* <p/>
* <p>
* After collecting the service properties it delegates to the
* {@link #init()} method.
*
@ -75,7 +75,7 @@ public final void init(Server server) throws ServiceException {
/**
* Post initializes the service. This method is called by the
* {@link Server} after all services of the server have been initialized.
* <p/>
* <p>
* This method does a NOP.
*
* @throws ServiceException thrown if the service could not be
@ -88,7 +88,7 @@ public void postInit() throws ServiceException {
/**
* Destroy the services. This method is called once, when the
* {@link Server} owning the service is being destroyed.
* <p/>
* <p>
* This method does a NOP.
*/
@Override
@ -98,7 +98,7 @@ public void destroy() {
/**
* Returns the service dependencies of this service. The service will be
* instantiated only if all the service dependencies are already initialized.
* <p/>
* <p>
* This method returns an empty array (size 0)
*
* @return an empty array (size 0).
@ -110,7 +110,7 @@ public Class[] getServiceDependencies() {
/**
* Notification callback when the server changes its status.
* <p/>
* <p>
* This method returns an empty array (size 0)
*
* @param oldStatus old server status.
@ -154,7 +154,7 @@ protected String getPrefixedName(String name) {
/**
* Returns the service configuration properties. Property
* names are trimmed off from its prefix.
* <p/>
* <p>
* The sevice configuration properties are all properties
* with names starting with <code>#SERVER#.#SERVICE#.</code>
* in the server configuration.
@ -169,7 +169,7 @@ protected Configuration getServiceConfig() {
/**
* Initializes the server.
* <p/>
* <p>
* This method is called by {@link #init(Server)} after all service properties
* (properties prefixed with
*

View File

@ -42,40 +42,39 @@
/**
* A Server class provides standard configuration, logging and {@link Service}
* lifecyle management.
* <p/>
* <p>
* A Server normally has a home directory, a configuration directory, a temp
* directory and logs directory.
* <p/>
* <p>
* The Server configuration is loaded from 2 overlapped files,
* <code>#SERVER#-default.xml</code> and <code>#SERVER#-site.xml</code>. The
* default file is loaded from the classpath, the site file is laoded from the
* configuration directory.
* <p/>
* <p>
* The Server collects all configuration properties prefixed with
* <code>#SERVER#</code>. The property names are then trimmed from the
* <code>#SERVER#</code> prefix.
* <p/>
* <p>
* The Server log configuration is loaded from the
* <code>#SERVICE#-log4j.properties</code> file in the configuration directory.
* <p/>
* <p>
* The lifecycle of server is defined in by {@link Server.Status} enum.
* When a server is create, its status is UNDEF, when being initialized it is
* BOOTING, once initialization is complete by default transitions to NORMAL.
* The <code>#SERVER#.startup.status</code> configuration property can be used
* to specify a different startup status (NORMAL, ADMIN or HALTED).
* <p/>
* <p>
* Services classes are defined in the <code>#SERVER#.services</code> and
* <code>#SERVER#.services.ext</code> properties. They are loaded in order
* (services first, then services.ext).
* <p/>
* <p>
* Before initializing the services, they are traversed and duplicate service
* interface are removed from the service list. The last service using a given
* interface wins (this enables a simple override mechanism).
* <p/>
* <p>
* After the services have been resoloved by interface de-duplication they are
* initialized in order. Once all services are initialized they are
* post-initialized (this enables late/conditional service bindings).
* <p/>
*/
@InterfaceAudience.Private
public class Server {
@ -152,7 +151,7 @@ public boolean isOperational() {
/**
* Creates a server instance.
* <p/>
* <p>
* The config, log and temp directories are all under the specified home directory.
*
* @param name server name.
@ -177,9 +176,9 @@ public Server(String name, String homeDir, String configDir, String logDir, Stri
/**
* Creates a server instance.
* <p/>
* <p>
* The config, log and temp directories are all under the specified home directory.
* <p/>
* <p>
* It uses the provided configuration instead loading it from the config dir.
*
* @param name server name.
@ -192,7 +191,7 @@ public Server(String name, String homeDir, Configuration config) {
/**
* Creates a server instance.
* <p/>
* <p>
* It uses the provided configuration instead loading it from the config dir.
*
* @param name server name.
@ -250,9 +249,9 @@ public Status getStatus() {
/**
* Sets a new server status.
* <p/>
* <p>
* The status must be settable.
* <p/>
* <p>
* All services will be notified o the status change via the
* {@link Service#serverStatusChange(Server.Status, Server.Status)} method. If a service
* throws an exception during the notification, the server will be destroyed.
@ -299,7 +298,7 @@ protected void ensureOperational() {
/**
* Convenience method that returns a resource as inputstream from the
* classpath.
* <p/>
* <p>
* It first attempts to use the Thread's context classloader and if not
* set it uses the <code>ClassUtils</code> classloader.
*
@ -319,7 +318,7 @@ static InputStream getResource(String name) {
/**
* Initializes the Server.
* <p/>
* <p>
* The initialization steps are:
* <ul>
* <li>It verifies the service home and temp directories exist</li>
@ -335,6 +334,7 @@ static InputStream getResource(String name) {
* <li>Initializes the services</li>
* <li>Post-initializes the services</li>
* <li>Sets the server startup status</li>
* </ul>
*
* @throws ServerException thrown if the server could not be initialized.
*/
@ -625,7 +625,7 @@ protected void destroyServices() {
/**
* Destroys the server.
* <p/>
* <p>
* All services are destroyed in reverse order of initialization, then the
* Log4j framework is shutdown.
*/
@ -651,7 +651,7 @@ public String getName() {
/**
* Returns the server prefix for server configuration properties.
* <p/>
* <p>
* By default it is the server name.
*
* @return the prefix for server configuration properties.
@ -733,10 +733,10 @@ public <T> T get(Class<T> serviceKlass) {
/**
* Adds a service programmatically.
* <p/>
* <p>
* If a service with the same interface exists, it will be destroyed and
* removed before the given one is initialized and added.
* <p/>
* <p>
* If an exception is thrown the server is destroyed.
*
* @param klass service class to add.

View File

@ -33,7 +33,7 @@
/**
* The <code>FileSystemReleaseFilter</code> releases back to the
* {@link FileSystemAccess} service a <code>FileSystem</code> instance.
* <p/>
* <p>
* This filter is useful in situations where a servlet request
* is streaming out HDFS data and the corresponding filesystem
* instance have to be closed after the streaming completes.
@ -44,7 +44,7 @@ public abstract class FileSystemReleaseFilter implements Filter {
/**
* Initializes the filter.
* <p/>
* <p>
* This implementation is a NOP.
*
* @param filterConfig filter configuration.
@ -83,7 +83,7 @@ public void doFilter(ServletRequest servletRequest, ServletResponse servletRespo
/**
* Destroys the filter.
* <p/>
* <p>
* This implementation is a NOP.
*/
@Override

View File

@ -43,7 +43,7 @@ public class HostnameFilter implements Filter {
/**
* Initializes the filter.
* <p/>
* <p>
* This implementation is a NOP.
*
* @param config filter configuration.
@ -56,7 +56,7 @@ public void init(FilterConfig config) throws ServletException {
/**
* Resolves the requester hostname and delegates the request to the chain.
* <p/>
* <p>
* The requester hostname is available via the {@link #get} method.
*
* @param request servlet request.
@ -101,7 +101,7 @@ public static String get() {
/**
* Destroys the filter.
* <p/>
* <p>
* This implementation is a NOP.
*/
@Override

View File

@ -33,7 +33,7 @@
/**
* Filter that sets request contextual information for the slf4j MDC.
* <p/>
* <p>
* It sets the following values:
* <ul>
* <li>hostname: if the {@link HostnameFilter} is present and configured
@ -48,7 +48,7 @@ public class MDCFilter implements Filter {
/**
* Initializes the filter.
* <p/>
* <p>
* This implementation is a NOP.
*
* @param config filter configuration.
@ -93,7 +93,7 @@ public void doFilter(ServletRequest request, ServletResponse response, FilterCha
/**
* Destroys the filter.
* <p/>
* <p>
* This implementation is a NOP.
*/
@Override

View File

@ -75,21 +75,21 @@ protected ServerWebApp(String name, String homeDir, Configuration config) {
/**
* Constructor. Subclasses must have a default constructor specifying
* the server name.
* <p/>
* <p>
* The server name is used to resolve the Java System properties that define
* the server home, config, log and temp directories.
* <p/>
* <p>
* The home directory is looked in the Java System property
* <code>#SERVER_NAME#.home.dir</code>.
* <p/>
* <p>
* The config directory is looked in the Java System property
* <code>#SERVER_NAME#.config.dir</code>, if not defined it resolves to
* the <code>#SERVER_HOME_DIR#/conf</code> directory.
* <p/>
* <p>
* The log directory is looked in the Java System property
* <code>#SERVER_NAME#.log.dir</code>, if not defined it resolves to
* the <code>#SERVER_HOME_DIR#/log</code> directory.
* <p/>
* <p>
* The temp directory is looked in the Java System property
* <code>#SERVER_NAME#.temp.dir</code>, if not defined it resolves to
* the <code>#SERVER_HOME_DIR#/temp</code> directory.
@ -105,7 +105,7 @@ public ServerWebApp(String name) {
/**
* Returns the server home directory.
* <p/>
* <p>
* It is looked up in the Java System property
* <code>#SERVER_NAME#.home.dir</code>.
*
@ -159,15 +159,15 @@ public void contextInitialized(ServletContextEvent event) {
}
/**
* Resolves the host & port InetSocketAddress the web server is listening to.
* <p/>
* Resolves the host and port InetSocketAddress the web server is listening to.
* <p>
* This implementation looks for the following 2 properties:
* <ul>
* <li>#SERVER_NAME#.http.hostname</li>
* <li>#SERVER_NAME#.http.port</li>
* </ul>
*
* @return the host & port InetSocketAddress the web server is listening to.
* @return the host and port InetSocketAddress the web server is listening to.
* @throws ServerException thrown if any of the above 2 properties is not defined.
*/
protected InetSocketAddress resolveAuthority() throws ServerException {
@ -217,7 +217,7 @@ public InetSocketAddress getAuthority() throws ServerException {
/**
* Sets an alternate hostname:port InetSocketAddress to use.
* <p/>
* <p>
* For testing purposes.
*
* @param authority alterante authority.

View File

@ -26,7 +26,7 @@
/**
* Utility methods to check preconditions.
* <p/>
* <p>
* Commonly used for method arguments preconditions.
*/
@InterfaceAudience.Private

View File

@ -90,7 +90,7 @@ public static Configuration resolve(Configuration conf) {
/**
* Create a configuration from an InputStream.
* <p/>
* <p>
* ERROR canibalized from <code>Configuration.loadResource()</code>.
*
* @param is inputstream to read the configuration from.

View File

@ -26,7 +26,7 @@
/**
* Class that contains all parsed JAX-RS parameters.
* <p/>
* <p>
* Instances are created by the {@link ParametersProvider} class.
*/
@InterfaceAudience.Private
@ -63,7 +63,7 @@ public <V, T extends Param<V>> V get(String name, Class<T> klass) {
*
* @param name parameter name.
* @param klass class of the parameter, used for value casting.
* @return List<V> the values of the parameter.
* @return the values of the parameter.
*/
@SuppressWarnings("unchecked")
public <V, T extends Param<V>> List<V> getValues(String name, Class<T> klass) {

View File

@ -26,7 +26,7 @@
/**
* This class is used to allow the initial registration of the NFS gateway with
* the system portmap daemon to come from a privileged (< 1024) port. This is
* the system portmap daemon to come from a privileged (&lt; 1024) port. This is
* necessary on certain operating systems to work around this bug in rpcbind:
*
* Red Hat: https://bugzilla.redhat.com/show_bug.cgi?id=731542

View File

@ -564,6 +564,9 @@ Release 2.7.0 - UNRELEASED
HDFS-7502. Fix findbugs warning in hdfs-nfs project.
(Brandon Li via wheat9)
HDFS-5578. [JDK8] Fix Javadoc errors caused by incorrect or illegal tags
in doc comments. (Andrew Purtell via wheat9)
Release 2.6.1 - UNRELEASED
INCOMPATIBLE CHANGES