From e49226340b2b8c9796beea7cfe31830229ec582d Mon Sep 17 00:00:00 2001 From: Charles Oliver Nutter Date: Mon, 10 Jun 2024 16:01:12 -0500 Subject: [PATCH] Fix javadoc lint issues Fixes #251 --- .../java/org/jruby/rack/AbstractFilter.java | 32 ++++--- .../jruby/rack/DefaultRackApplication.java | 8 +- .../rack/DefaultRackApplicationFactory.java | 22 ++--- .../rack/PoolingRackApplicationFactory.java | 4 +- .../java/org/jruby/rack/RackApplication.java | 9 +- .../jruby/rack/RackApplicationFactory.java | 12 ++- .../rack/RackApplicationFactoryDecorator.java | 19 +++-- src/main/java/org/jruby/rack/RackConfig.java | 83 +++++++++++++++---- .../java/org/jruby/rack/RackEnvironment.java | 22 ++++- src/main/java/org/jruby/rack/RackFilter.java | 6 +- .../java/org/jruby/rack/RackResponse.java | 2 +- .../jruby/rack/RackResponseEnvironment.java | 35 +++++--- src/main/java/org/jruby/rack/RackServlet.java | 10 ++- .../SerialPoolingRackApplicationFactory.java | 2 +- .../org/jruby/rack/UnmappedRackFilter.java | 16 ++-- .../java/org/jruby/rack/embed/Context.java | 2 +- src/main/java/org/jruby/rack/ext/Input.java | 16 +++- .../java/org/jruby/rack/ext/Response.java | 43 ++++++---- src/main/java/org/jruby/rack/ext/Servlet.java | 5 ++ .../jruby/rack/servlet/RequestCapture.java | 4 +- .../jruby/rack/servlet/ResponseCapture.java | 5 +- .../rack/servlet/RewindableInputStream.java | 12 +-- .../rack/servlet/ServletRackEnvironment.java | 6 +- .../servlet/ServletRackIncludedResponse.java | 3 +- 24 files changed, 270 insertions(+), 108 deletions(-) diff --git a/src/main/java/org/jruby/rack/AbstractFilter.java b/src/main/java/org/jruby/rack/AbstractFilter.java index 6fd49f62..47c95de1 100644 --- a/src/main/java/org/jruby/rack/AbstractFilter.java +++ b/src/main/java/org/jruby/rack/AbstractFilter.java @@ -42,11 +42,11 @@ public abstract class AbstractFilter implements Filter { /** * @see Filter#doFilter(ServletRequest, ServletResponse, FilterChain) - * @param request - * @param response - * @param chain - * @throws IOException - * @throws ServletException + * @param request the request + * @param response the response + * @param chain the FilterChain + * @throws IOException if there's an IO exception + * @throws ServletException if there's a servlet exception */ public final void doFilter( ServletRequest request, ServletResponse response, @@ -82,11 +82,15 @@ public void destroy() { * requests are given to the {@link RackDispatcher}, but you can extend * this method and return false if you want to signal that you don't want * the {@link RackDispatcher} to see the request. - + * + * @param request the request + * @param response the response + * @param chain the FilterChain + * @param env the RackEnvironent * @return true if the dispatcher should handle the request, false if it * shouldn't. - * @throws IOException - * @throws ServletException + * @throws IOException if there's an IO exception + * @throws ServletException if there's a servlet exception */ protected boolean isDoDispatch( RequestCapture request, ResponseCapture response, @@ -97,6 +101,14 @@ protected boolean isDoDispatch( /** * @deprecated use {@link #isDoDispatch(RequestCapture, ResponseCapture, FilterChain, RackEnvironment)} + * @param request the request + * @param response the response + * @param chain the FilterChain + * @param env the RackEnvironent + * @param responseEnv the RackResponseEnvironment + * @return isDoDispatch + * @throws IOException if there's an IO exception + * @throws ServletException if there's a servlet exception */ @Deprecated protected boolean isDoDispatch( @@ -109,7 +121,7 @@ protected boolean isDoDispatch( /** * Extension point if you'll need to customize {@link RequestCapture} - * @param request + * @param request the request * @return request capture */ protected RequestCapture wrapRequest(ServletRequest request) { @@ -118,7 +130,7 @@ protected RequestCapture wrapRequest(ServletRequest request) { /** * Extension point if you'll need to customize {@link ResponseCapture} - * @param response + * @param response the response * @return response capture */ protected ResponseCapture wrapResponse(ServletResponse response) { diff --git a/src/main/java/org/jruby/rack/DefaultRackApplication.java b/src/main/java/org/jruby/rack/DefaultRackApplication.java index aa944ad0..bbe04987 100644 --- a/src/main/java/org/jruby/rack/DefaultRackApplication.java +++ b/src/main/java/org/jruby/rack/DefaultRackApplication.java @@ -17,7 +17,7 @@ * (which is wrapped in a Rack::Handler::Servlet instance). * Returns the response converted to a Java {@link RackResponse} object. * - * @see rack/handler/servlet.rb + * See src/main/ruby/rack/handler/servlet.rb * * @author nicksieger */ @@ -34,8 +34,8 @@ public class DefaultRackApplication implements RackApplication { public DefaultRackApplication() { /* NOOP */ } /** - * @see #setApplication(IRubyObject) - * @param application + * @see DefaultRackApplication#setApplication(IRubyObject) + * @param application the application object */ public DefaultRackApplication(final IRubyObject application) { this(); @@ -88,7 +88,7 @@ public IRubyObject getApplication() { /** * Sets the application object. - * @param application + * @param application the application */ public void setApplication(IRubyObject application) { this.application = application; diff --git a/src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java b/src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java index 5784b03d..1455a359 100644 --- a/src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java +++ b/src/main/java/org/jruby/rack/DefaultRackApplicationFactory.java @@ -75,9 +75,9 @@ public void setRackupScript(String rackupScript) { /** * Initialize this factory using the given context. - *
+ * * NOTE: exception handling is left to the outer factory. - * @param rackContext + * @param rackContext the RackContext */ @Override public void init(final RackContext rackContext) { @@ -93,7 +93,7 @@ public void init(final RackContext rackContext) { /** * Creates a new application instance (without initializing it). - *
+ * * NOTE: exception handling is left to the outer factory. * @return new application instance */ @@ -108,7 +108,7 @@ public IRubyObject create(Ruby runtime) { /** * Creates a new application and initializes it. - *
+ * * NOTE: exception handling is left to the outer factory. * @return new, initialized application */ @@ -121,7 +121,7 @@ public RackApplication getApplication() { /** * Destroys the application (assumably) created by this factory. - *
+ * * NOTE: exception handling is left to the outer factory. * @param app the application to "release" */ @@ -147,7 +147,7 @@ public RackApplication getErrorApplication() { /** * Set the (default) error application to be used. - * @param errorApplication + * @param errorApplication the error application */ public synchronized void setErrorApplication(RackApplication errorApplication) { this.errorApplication = errorApplication; @@ -227,8 +227,8 @@ public IRubyObject create(Ruby runtime) { /** * @see #createRackServletWrapper(Ruby, String, String) - * @param runtime - * @param rackup + * @param runtime the JRuby runtime + * @param rackup the rackup string * @return (Ruby) built Rack Servlet handler */ protected IRubyObject createRackServletWrapper(Ruby runtime, String rackup) { @@ -237,9 +237,9 @@ protected IRubyObject createRackServletWrapper(Ruby runtime, String rackup) { /** * Creates the handler to bridge the Servlet and Rack worlds. - * @param runtime - * @param rackup - * @param filename + * @param runtime the JRuby runtime + * @param rackup the rackup string + * @param filename the filename * @return (Ruby) built Rack Servlet handler */ protected IRubyObject createRackServletWrapper(Ruby runtime, String rackup, String filename) { diff --git a/src/main/java/org/jruby/rack/PoolingRackApplicationFactory.java b/src/main/java/org/jruby/rack/PoolingRackApplicationFactory.java index 373a3890..4c6f5fb0 100644 --- a/src/main/java/org/jruby/rack/PoolingRackApplicationFactory.java +++ b/src/main/java/org/jruby/rack/PoolingRackApplicationFactory.java @@ -192,7 +192,7 @@ else if ( permit && ( initialSize != null && /** * @return true if a permit is acquired, false if no permit necessary - * @throws TimeoutException if a permit can not be acquired + * @throws AcquireTimeoutException if a permit can not be acquired */ protected boolean acquireApplicationPermit() throws AcquireTimeoutException { // NOTE: permits are only used if a pool maximum is specified ! @@ -276,7 +276,7 @@ public void fillInitialPool() throws RackInitializationException { } /** - * @param apps + * @param apps a queue of apps * @deprecated override {@link #launchInitialization(java.util.Queue)} */ @Deprecated diff --git a/src/main/java/org/jruby/rack/RackApplication.java b/src/main/java/org/jruby/rack/RackApplication.java index e5ac5a0d..809b553c 100644 --- a/src/main/java/org/jruby/rack/RackApplication.java +++ b/src/main/java/org/jruby/rack/RackApplication.java @@ -18,13 +18,20 @@ public interface RackApplication { void init() throws RackInitializationException; void destroy(); - /** Make a request into the Rack-based Ruby web application. */ + /** + * Make a request into the Rack-based Ruby web application. + * + * @param env the RackEnvironment + * @return the RackResponse + */ public RackResponse call(RackEnvironment env); /** * Get a reference to the underlying runtime that holds the application * and supporting code. Useful for embedding environments that wish to access * the application without entering through the web request/response cycle. + * + * @return the JRuby runtime */ Ruby getRuntime(); } diff --git a/src/main/java/org/jruby/rack/RackApplicationFactory.java b/src/main/java/org/jruby/rack/RackApplicationFactory.java index 42c46a59..df5bb385 100644 --- a/src/main/java/org/jruby/rack/RackApplicationFactory.java +++ b/src/main/java/org/jruby/rack/RackApplicationFactory.java @@ -20,32 +20,40 @@ public interface RackApplicationFactory { /** * Initialize the factory (using the given context). - * @param rackContext + * + * @param rackContext the context */ void init(RackContext rackContext) throws RackInitializationException; /** * Create a new, uninitialized application. The resulting object must be * initialized by calling its {@link RackApplication#init} method. + * + * @return a new application */ RackApplication newApplication() throws RackException; /** * Retrieve an application that is ready to use, possibly creating one * if it's necessary. + * + * @return the application */ RackApplication getApplication() throws RackException; /** * Return the application to the factory after processing. * e.g. for allowing the application to be pooled and/or cleaned up. + * @param app the application */ void finishedWithApplication(RackApplication app); /** * Get the designated error application. * The error application is expected to be a singleton and should not be - * returned to the factory. + * returned to the factory. + * + * @return the error application */ RackApplication getErrorApplication(); // TODO return ErrorApplication diff --git a/src/main/java/org/jruby/rack/RackApplicationFactoryDecorator.java b/src/main/java/org/jruby/rack/RackApplicationFactoryDecorator.java index a7984ec8..3ee4d757 100644 --- a/src/main/java/org/jruby/rack/RackApplicationFactoryDecorator.java +++ b/src/main/java/org/jruby/rack/RackApplicationFactoryDecorator.java @@ -85,7 +85,7 @@ public RuntimeException getInitError() { /** * Allows to set the initialization error for concrete factories. - * @param initError + * @param initError the initialization error to raise * @see #getApplication() */ protected synchronized void setInitError(RuntimeException initError) { @@ -94,8 +94,8 @@ protected synchronized void setInitError(RuntimeException initError) { /** * @see RackApplicationFactory#init(RackContext) - * @param context - * @throws RackInitializationException + * @param context the current RackContext + * @throws RackInitializationException if there's an error while initializing */ @Override public void init(final RackContext context) throws RackInitializationException { @@ -110,6 +110,7 @@ public void init(final RackContext context) throws RackInitializationException { /** * Perform the initialization for this factory. + * @throws Exception if there's an exception */ protected void doInit() throws Exception { getDelegate().init(context); @@ -130,7 +131,7 @@ public void destroy() { * factory. * @see RackApplicationFactory#getApplication() * @see #getApplicationImpl() - * @throws RackException + * @throws RackException if there is a failure to initialize */ @Override public RackApplication getApplication() throws RackException { @@ -165,8 +166,8 @@ protected RackConfig getConfig() { /** * Log a message. - * @param level - * @param message + * @param level the logger level + * @param message the log message */ protected void log(final RackLogger.Level level, final String message) { getContextBang().log(level, message); @@ -179,9 +180,9 @@ protected void log(final String level, final String message) { /** * Log a message (and an exception). - * @param level - * @param message - * @param e + * @param level the logger level + * @param message the log message + * @param e the exception raised */ protected void log(final RackLogger.Level level, final String message, Exception e) { getContextBang().log(level, message, e); diff --git a/src/main/java/org/jruby/rack/RackConfig.java b/src/main/java/org/jruby/rack/RackConfig.java index 90bb59d3..ff7f4f31 100644 --- a/src/main/java/org/jruby/rack/RackConfig.java +++ b/src/main/java/org/jruby/rack/RackConfig.java @@ -41,28 +41,36 @@ public interface RackConfig { /** * Return the rackup Ruby script to be used to launch the application. + * * @return the config.ru script */ String getRackup(); /** * Return the path to the Rackup script to be used to launch the application. + * * @see #getRackup() + * @return the rackup script path */ String getRackupPath(); /** - * Get the number of initial runtimes to be started, or null if unspecified. + * Get the number of initial runtimes to be started, or null if unspecified. + * + * @return the initial number of runtimes or null */ Integer getInitialRuntimes(); /** - * Get the number of maximum runtimes to be booted, or null if unspecified. + * Get the number of maximum runtimes to be booted, or null if unspecified. + * + * @return the maximum number of runtimes or null */ Integer getMaximumRuntimes(); /** * Returns (optional) command line arguments to be used when starting Ruby runtimes. + * * @return ARGV */ String[] getRuntimeArguments(); @@ -71,25 +79,35 @@ public interface RackConfig { * Allows to customize the environment runtimes will be running with. * By returning null the environment (JRuby sets up System.getenv) will be * kept as is. - *
+ * * NOTE: This method if not returning null should return a mutable map. + * * @return the ENV to be used in started Ruby runtimes */ Map getRuntimeEnvironment(); /** * Returns true if the outer environment (variables) should not be used. + * * @return whether to ENV.clear the Ruby runtime * @deprecated replaced with {@link #getRuntimeEnvironment()} */ @Deprecated boolean isIgnoreEnvironment(); - /** Return the configured amount of time before runtime acquisition times out (in seconds). */ + /** + * Return the configured amount of time before runtime acquisition times out (in seconds). + * + * @return the amount of time before runtimes acquisition times out + */ @Deprecated // TODO rename to Float getRuntimeAquireTimeout Integer getRuntimeTimeoutSeconds(); - /** Get the number of initializer threads, or null if unspecified. */ + /** + * Get the number of initializer threads, or null if unspecified. + * + * @return the number of initializer threads or null + */ @Deprecated // TODO rename to Integer getRuntimeInitThreads Integer getNumInitializerThreads(); @@ -98,24 +116,32 @@ public interface RackConfig { * (e.g. if the JVM environment does not allow creating threads). * By default if multiple application runtimes are used that they're booted * in multiple threads to utilize CPU cores for a faster startup time. + * + * @return true of runtimes should be initialized in serial */ boolean isSerialInitialization(); /** * Whether the request body will be rewindable (env[rack.input].rewind). * Disabling this might improve performance and memory usage a bit. + * + * @return true if the request body is rewindable */ boolean isRewindable(); /** - * Returns the initial size of the in-memory buffer used for request bodies. + * Returns the initial size of the in-memory buffer used for request bodies. + * * @see #isRewindable() + * @return the initial size of the in-memory buffer */ Integer getInitialMemoryBufferSize(); /** - * Returns the maximum size of the in-memory buffer used for request bodies. + * Returns the maximum size of the in-memory buffer used for request bodies. + * * @see #isRewindable() + * @return the maximum size of the in-memory buffer */ Integer getMaximumMemoryBufferSize(); @@ -133,7 +159,8 @@ public interface RackConfig { /** * Return true if passing through the filter should append '.html' * (or 'index.html') to the path. - * + * + * @return true if the filter should append .html * @deprecated configure filter with a nested init-param * @see RackFilter */ @@ -143,7 +170,8 @@ public interface RackConfig { /** * Return true if filter should verify the resource exists using * ServletContext#getResource before adding .html on the request. - * + * + * @return true if the filter should verify the resource * @deprecated configure filter with a nested init-param * @see RackFilter */ @@ -152,45 +180,70 @@ public interface RackConfig { /** * Return the JNDI name of the JMS connection factory. + * + * @return the JMS connection factory * @deprecated JMS is rarely used thus should not be here */ @Deprecated String getJmsConnectionFactory(); /** - * Return the JNDI properties for JMS. + * Return the JNDI properties for JMS. + * + * @return the JNDI properties * @deprecated JMS is rarely used thus should not be here */ @Deprecated String getJmsJndiProperties(); /** - * General property retrieval for custom configuration values. + * General property retrieval for custom configuration values. + * + * @param key the key + * @return the value of the property as a String */ String getProperty(String key); /** - * General property retrieval for custom configuration values. + * General property retrieval for custom configuration values. + * + * @param key the key + * @param defaultValue the default value + * @return the value of the property as a String or the default value */ String getProperty(String key, String defaultValue); /** - * General property retrieval for custom configuration values. + * General property retrieval for custom configuration values. + * + * @param key the key + * @return the value of the property as a Number */ Boolean getBooleanProperty(String key); /** - * General property retrieval for custom configuration values. + * General property retrieval for custom configuration values. + * + * @param key the key + * @param defaultValue the default value + * @return the value of the property as a Boolean or the default value */ Boolean getBooleanProperty(String key, Boolean defaultValue); /** - * General property retrieval for custom configuration values. + * General property retrieval for custom configuration values. + * + * @param key the key + * @return the value of the property as a Number */ Number getNumberProperty(String key); /** * General property retrieval for custom configuration values. + * + * @param key the key + * @param defaultValue the default value + * @return the value of the property as a Number or the default value */ Number getNumberProperty(String key, Number defaultValue); diff --git a/src/main/java/org/jruby/rack/RackEnvironment.java b/src/main/java/org/jruby/rack/RackEnvironment.java index bd5c2bcb..9f910abc 100644 --- a/src/main/java/org/jruby/rack/RackEnvironment.java +++ b/src/main/java/org/jruby/rack/RackEnvironment.java @@ -40,7 +40,7 @@ public interface RackEnvironment { /** * @see javax.servlet.ServletRequest#getInputStream() * @return the input as a stream - * @throws IOException + * @throws IOException if there's an IO exception */ public InputStream getInput() throws IOException; @@ -55,87 +55,107 @@ public interface RackEnvironment { /** * @see javax.servlet.http.HttpServletRequest#getPathInfo() + * @return the request path info */ public String getPathInfo(); /** * Request URI should include the query string if available. * @see javax.servlet.http.HttpServletRequest#getRequestURI() + * @return the request URI */ public String getRequestURI(); /** * @see javax.servlet.http.HttpServletRequest#getAttributeNames() + * @return an enumeration of all attribute names */ public Enumeration getAttributeNames(); /** * @see javax.servlet.http.HttpServletRequest#getAttribute(String) + * @param key the attribute key + * @return the attribute value */ public Object getAttribute(String key); /** * @see javax.servlet.http.HttpServletRequest#setAttribute(String, Object) + * @param key the key + * @param value the value */ public void setAttribute(String key, Object value); /** * @see javax.servlet.http.HttpServletRequest#getHeaderNames() + * @return an enumeration of all header names */ public Enumeration getHeaderNames(); /** * @see javax.servlet.http.HttpServletRequest#getHeader(String) + * @param name the header name + * @return the header value */ public String getHeader(String name); /** * @see javax.servlet.http.HttpServletRequest#getScheme() + * @return the request scheme */ public String getScheme(); /** * @see javax.servlet.http.HttpServletRequest#getContentType() + * @return the content type */ public String getContentType(); /** * @see javax.servlet.http.HttpServletRequest#getContentLength() + * @return the content length */ public int getContentLength(); /** * @see javax.servlet.http.HttpServletRequest#getMethod() + * @return the request method */ public String getMethod(); /** * @see javax.servlet.http.HttpServletRequest#getQueryString() + * @return the query string */ public String getQueryString(); /** * @see javax.servlet.http.HttpServletRequest#getServerName() + * @return the server name */ public String getServerName(); /** * @see javax.servlet.http.HttpServletRequest#getServerPort() + * @return the server port */ public int getServerPort(); /** * @see javax.servlet.ServletRequest#getRemoteHost() + * @return the remote host */ public String getRemoteHost(); /** * @see javax.servlet.ServletRequest#getRemoteAddr() + * @return the remote address */ public String getRemoteAddr(); /** * @see javax.servlet.http.HttpServletRequest#getRemoteUser() + * @return the remote user */ public String getRemoteUser(); diff --git a/src/main/java/org/jruby/rack/RackFilter.java b/src/main/java/org/jruby/rack/RackFilter.java index f9f789b5..b4494cac 100644 --- a/src/main/java/org/jruby/rack/RackFilter.java +++ b/src/main/java/org/jruby/rack/RackFilter.java @@ -44,7 +44,11 @@ public class RackFilter extends UnmappedRackFilter { public RackFilter() { } - /** Dependency-injected constructor for testing */ + /** + * Dependency-injected constructor for testing + * @param dispatcher the dispatcher + * @param context the context + */ public RackFilter(RackDispatcher dispatcher, RackContext context) { super(dispatcher, context); initializeFromConfig(); diff --git a/src/main/java/org/jruby/rack/RackResponse.java b/src/main/java/org/jruby/rack/RackResponse.java index 8e38b71a..e001bdab 100644 --- a/src/main/java/org/jruby/rack/RackResponse.java +++ b/src/main/java/org/jruby/rack/RackResponse.java @@ -35,7 +35,7 @@ public interface RackResponse { Map getHeaders() ; /** - * @note Normally, this method won't be used at all as we stream the + * Note: Normally, this method won't be used at all as we stream the * response body from {@link #respond(RackResponseEnvironment)}. * @return the response body (as a string) */ diff --git a/src/main/java/org/jruby/rack/RackResponseEnvironment.java b/src/main/java/org/jruby/rack/RackResponseEnvironment.java index ae4e67d2..48da1b58 100644 --- a/src/main/java/org/jruby/rack/RackResponseEnvironment.java +++ b/src/main/java/org/jruby/rack/RackResponseEnvironment.java @@ -38,55 +38,58 @@ public interface RackResponseEnvironment { /** * @see javax.servlet.ServletResponse#setContentType(String) + * @param type the content type */ void setContentType(String type) ; /** * @see javax.servlet.ServletResponse#setContentLength(int) + * @param length the content length */ void setContentLength(int length) ; /** * @see javax.servlet.ServletResponse#setCharacterEncoding(String) + * @param charset the charset */ void setCharacterEncoding(String charset) ; /** * Sets a (HTTP) header. - * @param name - * @param value + * @param name the header name + * @param value the header value as a String */ void setHeader(String name, String value) ; /** * Adds a (HTTP) header. - * @param name - * @param value + * @param name the header name + * @param value the header value as a String */ void addHeader(String name, String value) ; /** * Sets a (HTTP) header. - * @param name - * @param date + * @param name the header name + * @param date the header value as a long date */ void setDateHeader(String name, long date) ; /** * Adds a (HTTP) header. - * @param name - * @param date + * @param name the header name + * @param date the header value as a long date */ void addDateHeader(String name, long date) ; /** * Sets a (HTTP) header. - * @param name - * @param value + * @param name the header name + * @param value the header value as an int */ void setIntHeader(String name, int value) ; /** * Adds a (HTTP) header. - * @param name - * @param value + * @param name the header name + * @param value the header value as an int */ void addIntHeader(String name, int value) ; @@ -99,22 +102,28 @@ public interface RackResponseEnvironment { /** * Send a simple error page response (based on the status code). * @param code the (HTTP) status code - * @throws IOException + * @throws IOException if there's an IO exception */ void sendError(int code) throws IOException ; /** * @see javax.servlet.ServletResponse#getOutputStream() + * @return the output stream + * @throws IOException if there's an IO exception */ OutputStream getOutputStream() throws IOException ; /** * @see javax.servlet.ServletResponse#getWriter() + * @return the writer + * @throws IOException if there's an IO exception */ PrintWriter getWriter() throws IOException ; /** * @see RackResponse#respond(RackResponseEnvironment) + * @param response the response + * @throws IOException if there's an IO exception * @deprecated (should) no longer (be) used */ @Deprecated diff --git a/src/main/java/org/jruby/rack/RackServlet.java b/src/main/java/org/jruby/rack/RackServlet.java index 5771d7b1..e5bf4944 100644 --- a/src/main/java/org/jruby/rack/RackServlet.java +++ b/src/main/java/org/jruby/rack/RackServlet.java @@ -15,11 +15,17 @@ public class RackServlet extends AbstractServlet { private RackDispatcher dispatcher; private RackContext context; - /** Default constructor for servlet container */ + /** + * Default constructor for servlet container + */ public RackServlet() { } - /** dependency injection ctor, used by unit tests */ + /** + * dependency injection ctor, used by unit tests + * @param dispatcher the dispatcher + * @param context the context + */ public RackServlet(RackDispatcher dispatcher, RackContext context) { this.dispatcher = dispatcher; this.context = context; diff --git a/src/main/java/org/jruby/rack/SerialPoolingRackApplicationFactory.java b/src/main/java/org/jruby/rack/SerialPoolingRackApplicationFactory.java index 964e634c..5d3d5e2a 100644 --- a/src/main/java/org/jruby/rack/SerialPoolingRackApplicationFactory.java +++ b/src/main/java/org/jruby/rack/SerialPoolingRackApplicationFactory.java @@ -15,7 +15,7 @@ * Works like the pooling application factory, with the variation that it will * create all application instances (runtimes) serially, using no extra threads. * - * @author Ola Bini + * @author Ola Bini <ola.bini@gmail.com> */ public class SerialPoolingRackApplicationFactory extends PoolingRackApplicationFactory { diff --git a/src/main/java/org/jruby/rack/UnmappedRackFilter.java b/src/main/java/org/jruby/rack/UnmappedRackFilter.java index 64a223f6..96044f18 100644 --- a/src/main/java/org/jruby/rack/UnmappedRackFilter.java +++ b/src/main/java/org/jruby/rack/UnmappedRackFilter.java @@ -63,13 +63,19 @@ public class UnmappedRackFilter extends AbstractFilter { public UnmappedRackFilter() { /** constructor used by container */ } - /** Dependency-injected constructor for testing */ + /** + * Dependency-injected constructor for testing + * @param dispatcher the dispatcher + * @param context the context + */ public UnmappedRackFilter(RackDispatcher dispatcher, RackContext context) { this.context = context; this.dispatcher = dispatcher; } - /** Construct a new dispatcher with the servlet context */ + /** + * Construct a new dispatcher with the servlet context + */ @Override public void init(FilterConfig config) throws ServletException { this.context = (RackContext) @@ -134,11 +140,11 @@ protected void doFilterInternal( /** * Handle the filter chain response before dispatching the request. - * @param request - * @param response + * @param request the request + * @param response the response * @return true if the dispatcher should do a dispatch (to rails), otherwise * it is assumed that the request has been handled somewhere down the chain. - * @throws IOException + * @throws IOException if there's an IOException */ protected boolean handleChainResponse(RequestCapture request, ResponseCapture response) throws IOException { diff --git a/src/main/java/org/jruby/rack/embed/Context.java b/src/main/java/org/jruby/rack/embed/Context.java index 70bbcbea..6093a419 100644 --- a/src/main/java/org/jruby/rack/embed/Context.java +++ b/src/main/java/org/jruby/rack/embed/Context.java @@ -32,7 +32,7 @@ public Context(final String serverInfo) { } /** - * @param serverInfo + * @param serverInfo a string to describe the server software you have * @param config rack configuration */ public Context(final String serverInfo, final Config config) { diff --git a/src/main/java/org/jruby/rack/ext/Input.java b/src/main/java/org/jruby/rack/ext/Input.java index 3f951eef..e680e796 100644 --- a/src/main/java/org/jruby/rack/ext/Input.java +++ b/src/main/java/org/jruby/rack/ext/Input.java @@ -125,6 +125,8 @@ else if ( arg instanceof RackEnvironment ) { /** * gets must be called without arguments and return a string, or nil on EOF. + * @param context the current ThreadContext + * @return a gotten string */ @JRubyMethod() public IRubyObject gets(final ThreadContext context) { @@ -145,13 +147,16 @@ public IRubyObject gets(final ThreadContext context) { /** * read behaves like IO#read. Its signature is read([length, [buffer]]). If given, - * length must be an non-negative Integer (>= 0) or nil, and buffer must be a + * length must be an non-negative Integer (>= 0) or nil, and buffer must be a * String and may not be nil. If length is given and not nil, then this method * reads at most length bytes from the input stream. If length is not given or * nil, then this method reads all data until EOF. When EOF is reached, this * method returns nil if length is given and not nil, or "" if length is not * given or is nil. If buffer is given, then the read data will be placed into * buffer instead of a newly created String object. + * @param context the current ThreadContext + * @param args the read arguments + * @return the read content as a string or nil */ @JRubyMethod(optional = 2) public IRubyObject read(final ThreadContext context, final IRubyObject[] args) { @@ -167,7 +172,7 @@ public IRubyObject read(final ThreadContext context, final IRubyObject[] args) { if ( buffer != null ) { buffer.clear(); try { - int _ = (int) CONCAT_WITH_CODERANGE.invokeExact(new ByteList(bytes, false), StringSupport.CR_UNKNOWN); + int unused = (int) CONCAT_WITH_CODERANGE.invokeExact(new ByteList(bytes, false), StringSupport.CR_UNKNOWN); } catch (Throwable t) { Helpers.throwException(t); } @@ -185,6 +190,9 @@ public IRubyObject read(final ThreadContext context, final IRubyObject[] args) { /** * each must be called without arguments and only yield Strings. + * @param context the current ThreadContext + * @param block the block for iteration + * @return nil */ @JRubyMethod public IRubyObject each(final ThreadContext context, final Block block) { @@ -201,6 +209,8 @@ public IRubyObject each(final ThreadContext context, final Block block) { * to the beginning. It must not raise Errno::ESPIPE: that is, it may not be * a pipe or a socket. Therefore, handler developers must buffer the input * data into some rewindable object if the underlying input stream is not rewindable. + * @param context the current ThreadContext + * @return nil */ @JRubyMethod public IRubyObject rewind(final ThreadContext context) { @@ -226,6 +236,8 @@ public IRubyObject rewind(final ThreadContext context) { /** * Returns the size of the input. + * @param context the current ThreadContext + * @return the size of the input */ @JRubyMethod public IRubyObject size(final ThreadContext context) { diff --git a/src/main/java/org/jruby/rack/ext/Response.java b/src/main/java/org/jruby/rack/ext/Response.java index f14dd3af..20d05f4e 100644 --- a/src/main/java/org/jruby/rack/ext/Response.java +++ b/src/main/java/org/jruby/rack/ext/Response.java @@ -74,8 +74,8 @@ public class Response extends RubyObject implements RackResponse { /** * # Whether we swallow client abort exceptions (EOF received on the socket). - * @param context - * @param self + * @param context the current ThreadContext + * @param self the self object * @return a ruby boolean */ @JRubyMethod(name = "swallow_client_abort?", meta = true) @@ -85,7 +85,10 @@ public static IRubyObject is_swallow_client_abort(final ThreadContext context, f } /** - * @see #is_swallow_client_abort(ThreadContext, IRubyObject) + * @see Response#is_swallow_client_abort(ThreadContext, IRubyObject) + * @param self the self object + * @param value the value + * @return the given value */ @JRubyMethod(name = "swallow_client_abort=", meta = true, required = 1) public static IRubyObject set_swallow_client_abort(final IRubyObject self, final IRubyObject value) { @@ -102,8 +105,8 @@ public static IRubyObject set_swallow_client_abort(final IRubyObject self, final /** * Whether responses should de-chunk data (when chunked response detected). - * @param context - * @param self + * @param context the current ThreadContext + * @param self the self object * @return a ruby boolean */ @JRubyMethod(name = "dechunk?", meta = true) @@ -113,7 +116,10 @@ public static IRubyObject is_dechunk(final ThreadContext context, final IRubyObj } /** - * @see #is_dechunk(ThreadContext, IRubyObject) + * @see Response#is_dechunk(ThreadContext, IRubyObject) + * @param self the self object + * @param value the value + * @return the given value */ @JRubyMethod(name = "dechunk=", meta = true, required = 1) public static IRubyObject set_dechunk(final IRubyObject self, final IRubyObject value) { @@ -133,15 +139,15 @@ public static IRubyObject set_dechunk(final IRubyObject self, final IRubyObject * response is detected. By setting this value to nil you force an "explicit" * byte buffer to be used when copying between channels. * - * @note High values won't hurt when sending small files since most Java + * Note: High values won't hurt when sending small files since most Java * (file) channel implementations handle this gracefully. However if you're * on Windows it is recommended to not set this higher than the "magic" * number (64 * 1024 * 1024) - (32 * 1024) as there seems to be anecdotal * evidence that attempts to transfer more than 64MB at a time on certain * Windows versions results in a slow copy. * @see #get_channel_buffer_size(ThreadContext, IRubyObject) - * @param context - * @param self + * @param context the current ThreadContext + * @param self the self object * @return a (ruby) integer value */ @JRubyMethod(name = "channel_chunk_size", meta = true) @@ -152,6 +158,9 @@ public static IRubyObject get_channel_chunk_size(final ThreadContext context, fi /** * @see #get_channel_chunk_size(ThreadContext, IRubyObject) + * @param self the self object + * @param value the value + * @return the given value */ @JRubyMethod(name = "channel_chunk_size=", meta = true, required = 1) public static IRubyObject set_channel_chunk_size(final IRubyObject self, final IRubyObject value) { @@ -173,8 +182,8 @@ public static IRubyObject set_channel_chunk_size(final IRubyObject self, final I * channel backed object) as with file responses the response channel is * always transferable and thus {#channel_chunk_size} will be used. * @see #get_channel_chunk_size(ThreadContext, IRubyObject) - * @param context - * @param self + * @param context the current thread context + * @param self the self object * @return a (ruby) integer value */ @JRubyMethod(name = "channel_buffer_size", meta = true) @@ -184,6 +193,9 @@ public static IRubyObject get_channel_buffer_size(final ThreadContext context, f /** * @see #get_channel_buffer_size(ThreadContext, IRubyObject) + * @param self the self object + * @param value the value + * @return the given value */ @JRubyMethod(name = "channel_buffer_size=", meta = true, required = 1) public static IRubyObject set_channel_buffer_size(final IRubyObject self, final IRubyObject value) { @@ -213,8 +225,9 @@ protected Response(Ruby runtime, RubyClass metaClass) { /** * Expects a Rack response. - * @param context + * @param context the current ThreadContext * @param arg [status, headers, body] + * @return nil */ @JRubyMethod(required = 1) public IRubyObject initialize(final ThreadContext context, final IRubyObject arg) { @@ -521,10 +534,11 @@ private static class WrappedException extends RuntimeException { * Sends a file when a Rails/Rack file response (`body.to_path`) is detected. * This allows for potential application server overrides when file streaming. * By default JRuby-Rack will stream the file using a (native) file channel. - * @param context + * @param context the current ThreadContext * @param path the file path * @param response the response environment - * @throws IOException + * @return nil + * @throws IOException if there is an IO exception */ @JRubyMethod(name = "send_file") public IRubyObject send_file(final ThreadContext context, @@ -682,6 +696,7 @@ static IRubyObject invoke( return Helpers.invoke(context, self, method, block); } + @Override public Object toJava(Class target) { if ( target == null || target == RackResponse.class ) return this; diff --git a/src/main/java/org/jruby/rack/ext/Servlet.java b/src/main/java/org/jruby/rack/ext/Servlet.java index c2c06da1..1933321d 100644 --- a/src/main/java/org/jruby/rack/ext/Servlet.java +++ b/src/main/java/org/jruby/rack/ext/Servlet.java @@ -55,6 +55,7 @@ protected Servlet(Ruby runtime, RubyClass metaClass) { /** * @param app the rack app + * @return nil */ @JRubyMethod(required = 1) public IRubyObject initialize(final IRubyObject app) { @@ -75,7 +76,9 @@ public IRubyObject initialize(final IRubyObject app) { public IRubyObject get_app() { return app; } /** + * @param context the current ThreadContext * @param servlet_env the (servlet) environment + * @return a response from the servlet */ @JRubyMethod(required = 1) public IRubyObject call(final ThreadContext context, final IRubyObject servlet_env) { @@ -87,7 +90,9 @@ public IRubyObject call(final ThreadContext context, final IRubyObject servlet_e } /** + * @param context the current ThreadContext * @param servlet_env the (servlet) environment + * @return a new ENV hash */ @JRubyMethod(required = 1) public RubyHash create_env(final ThreadContext context, final IRubyObject servlet_env) { diff --git a/src/main/java/org/jruby/rack/servlet/RequestCapture.java b/src/main/java/org/jruby/rack/servlet/RequestCapture.java index 1c5ab6c5..d776a3dd 100644 --- a/src/main/java/org/jruby/rack/servlet/RequestCapture.java +++ b/src/main/java/org/jruby/rack/servlet/RequestCapture.java @@ -34,7 +34,7 @@ public class RequestCapture extends HttpServletRequestWrapper { /** * Wrap a request - * @param request + * @param request the request */ public RequestCapture(HttpServletRequest request) { super(request); @@ -42,7 +42,7 @@ public RequestCapture(HttpServletRequest request) { /** * @deprecated use {@link #RequestCapture(HttpServletRequest)} - * @param request + * @param request the request * @param config will be ignored */ @Deprecated diff --git a/src/main/java/org/jruby/rack/servlet/ResponseCapture.java b/src/main/java/org/jruby/rack/servlet/ResponseCapture.java index 11e77070..3569af15 100644 --- a/src/main/java/org/jruby/rack/servlet/ResponseCapture.java +++ b/src/main/java/org/jruby/rack/servlet/ResponseCapture.java @@ -38,7 +38,7 @@ public class ResponseCapture extends HttpServletResponseWrapper { /** * Wrap a response - * @param response + * @param response the response */ public ResponseCapture(HttpServletResponse response) { super(response); @@ -65,6 +65,7 @@ public boolean isStatusSet() { * * @param status the new HTTP status * @param error whether the status comes from a {@code sendError} + * @return the code handler * @see #isHandled(HttpServletRequest) */ protected boolean handleStatus(int status, boolean error) { @@ -197,6 +198,7 @@ public boolean isError() { /** * @deprecated no longer to be used from outside * @see #isHandled(HttpServletRequest) + * @return true if handled */ public boolean isHandled() { return isHandled(null); @@ -208,6 +210,7 @@ public boolean isHandled() { * Response is considered to be handled if a status has been set * and it is (by default) not a HTTP NOT FOUND (404) status. * + * @param request the request * @return true if this response should be considered as handled * @see #handleStatus(int, boolean) */ diff --git a/src/main/java/org/jruby/rack/servlet/RewindableInputStream.java b/src/main/java/org/jruby/rack/servlet/RewindableInputStream.java index d9e6a19e..54532797 100644 --- a/src/main/java/org/jruby/rack/servlet/RewindableInputStream.java +++ b/src/main/java/org/jruby/rack/servlet/RewindableInputStream.java @@ -46,7 +46,7 @@ public static int getDefaultInitialBufferSize() { /** * Set the (default) initial buffer size for all instances created using * {@link #RewindableInputStream(java.io.InputStream)}. - * @param iniBufferSize + * @param iniBufferSize the initial buffer size */ public static void setDefaultInitialBufferSize(int iniBufferSize) { RewindableInputStream.iniBufferSize = iniBufferSize; @@ -61,7 +61,7 @@ public static int getDefaultMaximumBufferSize() { /** * Set the (default) maximum buffer size for all instances created using * {@link #RewindableInputStream(java.io.InputStream)}. - * @param maxBufferSize + * @param maxBufferSize the max buffer size */ public static void setDefaultMaximumBufferSize(int maxBufferSize) { RewindableInputStream.maxBufferSize = maxBufferSize; @@ -85,7 +85,7 @@ public static void setDefaultMaximumBufferSize(int maxBufferSize) { /** * Wrap an input stream to be king and rewind ... - * @param input + * @param input the input stream */ public RewindableInputStream(InputStream input) { this(input, iniBufferSize, maxBufferSize); @@ -93,7 +93,7 @@ public RewindableInputStream(InputStream input) { /** * Wrap an input stream to be king and rewind ... - * @param input + * @param input the input stream * @param bufferSize the buffer size */ public RewindableInputStream(InputStream input, int bufferSize) { @@ -102,7 +102,7 @@ public RewindableInputStream(InputStream input, int bufferSize) { /** * Wrap an input stream to be king and rewind ... - * @param input + * @param input the input stream * @param iniBufferSize initial buffer size * @param maxBufferSize maximum buffer size (when reached content gets written into a file) */ @@ -216,7 +216,7 @@ public synchronized void close() throws IOException { /** * Rewind this stream (kindly) to the start. - * @throws IOException + * @throws IOException if there's an IO exception */ public synchronized void rewind() throws IOException { ensureOpen(); diff --git a/src/main/java/org/jruby/rack/servlet/ServletRackEnvironment.java b/src/main/java/org/jruby/rack/servlet/ServletRackEnvironment.java index 1d315b94..4cb7c313 100644 --- a/src/main/java/org/jruby/rack/servlet/ServletRackEnvironment.java +++ b/src/main/java/org/jruby/rack/servlet/ServletRackEnvironment.java @@ -41,9 +41,9 @@ public class ServletRackEnvironment extends HttpServletRequestWrapper /** * Creates an environment instance for the given request, response and context. - * @param request - * @param response - * @param context + * @param request the request + * @param response the response + * @param context the context */ public ServletRackEnvironment(HttpServletRequest request, HttpServletResponse response, RackContext context) { super(request); diff --git a/src/main/java/org/jruby/rack/servlet/ServletRackIncludedResponse.java b/src/main/java/org/jruby/rack/servlet/ServletRackIncludedResponse.java index 0f89db59..42cebcae 100644 --- a/src/main/java/org/jruby/rack/servlet/ServletRackIncludedResponse.java +++ b/src/main/java/org/jruby/rack/servlet/ServletRackIncludedResponse.java @@ -34,7 +34,7 @@ public class ServletRackIncludedResponse extends HttpServletResponseWrapper { /** * Wraps a response. - * @param response + * @param response the response * @see #setBufferSize(int) */ public ServletRackIncludedResponse(HttpServletResponse response) { @@ -47,6 +47,7 @@ public ServletRackIncludedResponse(HttpServletResponse response) { * Returns the output of the include as a string, encoded by the * character encoding available {@link #getCharacterEncoding()}}. * @return the included output as a String + * @throws IOException if there's an IO exception */ public String getOutput() throws IOException { flushBuffer();