You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by ma...@apache.org on 2019/09/09 10:15:42 UTC
[tomcat] branch 7.0.x updated: Fix Javadoc errors with Java 9.
Align with 8.5.x.
This is an automated email from the ASF dual-hosted git repository.
markt pushed a commit to branch 7.0.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/7.0.x by this push:
new de17b2f Fix Javadoc errors with Java 9. Align with 8.5.x.
de17b2f is described below
commit de17b2fe096a6fab4fb42eb0e77f060cabacd459
Author: Mark Thomas <ma...@apache.org>
AuthorDate: Mon Sep 9 11:15:08 2019 +0100
Fix Javadoc errors with Java 9. Align with 8.5.x.
---
.../apache/catalina/ha/tcp/SimpleTcpCluster.java | 22 +++---
java/org/apache/catalina/startup/TldConfig.java | 2 +-
java/org/apache/catalina/startup/Tomcat.java | 80 +++++++++++++++++-----
.../apache/catalina/tribes/group/RpcChannel.java | 3 +-
java/org/apache/catalina/users/MemoryUser.java | 31 +++------
.../apache/catalina/util/ExtensionValidator.java | 10 ++-
java/org/apache/catalina/util/RequestUtil.java | 4 +-
java/org/apache/coyote/AbstractProtocol.java | 25 +++++--
java/org/apache/coyote/OutputBuffer.java | 17 +++--
java/org/apache/coyote/ProtocolHandler.java | 29 ++++++--
java/org/apache/coyote/ajp/AjpMessage.java | 37 +++++++---
.../compiler/tagplugin/TagPluginContext.java | 14 +++-
.../apache/tomcat/dbcp/dbcp/AbandonedConfig.java | 2 +-
.../tomcat/dbcp/jocl/JOCLContentHandler.java | 2 +-
.../tomcat/util/digester/SetPropertiesRule.java | 14 ++--
.../apache/tomcat/util/net/AbstractEndpoint.java | 4 +-
.../apache/tomcat/jdbc/pool/PoolConfiguration.java | 65 ++++++++++--------
17 files changed, 226 insertions(+), 135 deletions(-)
diff --git a/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java b/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java
index c664751..c527df8 100644
--- a/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java
+++ b/java/org/apache/catalina/ha/tcp/SimpleTcpCluster.java
@@ -147,7 +147,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
protected PropertyChangeSupport support = new PropertyChangeSupport(this);
/**
- * The context name <->manager association for distributed contexts.
+ * The context name <-> manager association for distributed contexts.
*/
protected Map<String, ClusterManager> managers =
new HashMap<String, ClusterManager>();
@@ -261,7 +261,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
*/
@Override
public Container getContainer() {
- return (this.container);
+ return this.container;
}
/**
@@ -307,6 +307,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
/**
* Get the cluster listeners associated with this cluster. If this Array has
* no listeners registered, a zero-length array is returned.
+ * @return the listener array
*/
public ClusterListener[] findClusterListeners() {
if (clusterListeners.size() > 0) {
@@ -321,6 +322,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
/**
* Add cluster message listener and register cluster to this listener.
*
+ * @param listener The new listener
* @see org.apache.catalina.ha.CatalinaCluster#addClusterListener(org.apache.catalina.ha.ClusterListener)
*/
@Override
@@ -334,6 +336,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
/**
* Remove message listener and deregister Cluster from listener.
*
+ * @param listener The listener to remove
* @see org.apache.catalina.ha.CatalinaCluster#removeClusterListener(org.apache.catalina.ha.ClusterListener)
*/
@Override
@@ -345,7 +348,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
}
/**
- * get current Deployer
+ * @return the current Deployer
*/
@Override
public ClusterDeployer getClusterDeployer() {
@@ -354,6 +357,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
/**
* set a new Deployer, must be set before cluster started!
+ * @param clusterDeployer The associated deployer
*/
@Override
public void setClusterDeployer(ClusterDeployer clusterDeployer) {
@@ -568,6 +572,7 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
/**
* Remove an application from cluster replication bus.
*
+ * @param manager The manager
* @see org.apache.catalina.Cluster#removeManager(Manager)
*/
@Override
@@ -583,11 +588,6 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
}
}
- /**
- * @param name
- * @param manager
- * @return TODO
- */
@Override
public String getManagerName(String name, Manager manager) {
String clusterName = name ;
@@ -603,11 +603,6 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
return clusterName;
}
- /*
- * Get Manager
- *
- * @see org.apache.catalina.ha.CatalinaCluster#getManager(java.lang.String)
- */
@Override
public Manager getManager(String name) {
return managers.get(name);
@@ -950,7 +945,6 @@ public class SimpleTcpCluster extends LifecycleMBeanBase
}
}
}
- return;
}
// --------------------------------------------------------- Logger
diff --git a/java/org/apache/catalina/startup/TldConfig.java b/java/org/apache/catalina/startup/TldConfig.java
index 9c0ba24..eac4f37 100644
--- a/java/org/apache/catalina/startup/TldConfig.java
+++ b/java/org/apache/catalina/startup/TldConfig.java
@@ -237,7 +237,7 @@ public final class TldConfig implements LifecycleListener {
* order defined in the JSP spec. It allows tag libraries packaged as JAR
* files to be shared by web applications by simply dropping them in a
* location that all web applications have access to (e.g.,
- * <CATALINA_HOME>/lib). It also supports some of the weird and
+ * <CATALINA_HOME>/lib). It also supports some of the weird and
* wonderful arrangements present when Tomcat gets embedded.
*
* The set of shared JARs to be scanned for TLDs is narrowed down by
diff --git a/java/org/apache/catalina/startup/Tomcat.java b/java/org/apache/catalina/startup/Tomcat.java
index dd531e3..d638f8a 100644
--- a/java/org/apache/catalina/startup/Tomcat.java
+++ b/java/org/apache/catalina/startup/Tomcat.java
@@ -93,8 +93,8 @@ import org.apache.tomcat.util.res.StringManager;
* Requirements:
* <ul>
* <li>all tomcat classes and possibly servlets are in the classpath.
- * ( for example all is in one big jar, or in eclipse CP, or in
- * any other combination )</li>
+ * (for example all is in one big jar, or in eclipse CP, or in
+ * any other combination)</li>
*
* <li>we need one temporary directory for work files</li>
*
@@ -111,7 +111,7 @@ import org.apache.tomcat.util.res.StringManager;
*
* <p>
* This class provides a set of convenience methods for configuring webapp
- * contexts, all overloads of the method <pre>addWebapp</pre>. These methods
+ * contexts, all overloads of the method <code>addWebapp</code>. These methods
* create a webapp context, configure it, and then add it to a {@link Host}.
* They do not use a global default web.xml; rather, they add a lifecycle
* listener that adds the standard DefaultServlet, JSP processing, and welcome
@@ -121,7 +121,7 @@ import org.apache.tomcat.util.res.StringManager;
* In complex cases, you may prefer to use the ordinary Tomcat API to create
* webapp contexts; for example, you might need to install a custom Loader
* before the call to {@link Host#addChild(Container)}. To replicate the basic
- * behavior of the <pre>addWebapp</pre> methods, you may want to call two
+ * behavior of the <code>addWebapp</code> methods, you may want to call two
* methods of this class: {@link #noDefaultWebXmlPath()} and
* {@link #getDefaultWebXmlListener()}.
*
@@ -214,6 +214,7 @@ public class Tomcat {
/**
* Set the port for the default connector. Must
* be called before start().
+ * @param port The port number
*/
public void setPort(int port) {
this.port = port;
@@ -222,18 +223,24 @@ public class Tomcat {
/**
* The the hostname of the default host, default is
* 'localhost'.
+ * @param s The default host name
*/
public void setHostname(String s) {
hostname = s;
}
/**
- * This is equivalent to adding a web application to Tomcat's webapps
+ * This is equivalent to adding a web application to Tomcat's webapps
* directory. The equivalent of the default web.xml will be applied to the
* web application and any WEB-INF/web.xml and META-INF/context.xml packaged
* with the application will be processed normally. Normal web fragment and
* {@link javax.servlet.ServletContainerInitializer} processing will be
* applied.
+ *
+ * @param contextPath The context mapping to use, "" for root context.
+ * @param docBase Base directory for the context, for static files.
+ * Must exist, relative to the server home
+ * @return the deployed context
*/
public Context addWebapp(String contextPath, String docBase) {
return addWebapp(getHost(), contextPath, docBase);
@@ -338,17 +345,17 @@ public class Tomcat {
* <p>
* TODO: add the rest
*
- * @param contextPath "" for root context.
- * @param docBase base dir for the context, for static files. Must exist,
- * relative to the server home
+ * @param contextPath The context mapping to use, "" for root context.
+ * @param docBase Base directory for the context, for static files.
+ * Must exist, relative to the server home
+ * @return the deployed context
*/
public Context addContext(String contextPath, String docBase) {
return addContext(getHost(), contextPath, docBase);
}
/**
- * Equivalent with
- * <servlet><servlet-name><servlet-class>.
+ * Equivalent to <servlet><servlet-name><servlet-class>.
*
* <p>
* In general it is better/faster to use the method that takes a
@@ -427,9 +434,9 @@ public class Tomcat {
/**
- * Initialise the server.
+ * Initialize the server.
*
- * @throws LifecycleException
+ * @throws LifecycleException Init error
*/
public void init() throws LifecycleException {
getServer();
@@ -441,7 +448,7 @@ public class Tomcat {
/**
* Start the server.
*
- * @throws LifecycleException
+ * @throws LifecycleException Start error
*/
public void start() throws LifecycleException {
getServer();
@@ -452,7 +459,7 @@ public class Tomcat {
/**
* Stop the server.
*
- * @throws LifecycleException
+ * @throws LifecycleException Stop error
*/
public void stop() throws LifecycleException {
getServer();
@@ -463,6 +470,8 @@ public class Tomcat {
/**
* Destroy the server. This object cannot be used once this method has been
* called.
+ *
+ * @throws LifecycleException Destroy error
*/
public void destroy() throws LifecycleException {
getServer();
@@ -473,14 +482,18 @@ public class Tomcat {
/**
* Add a user for the in-memory realm. All created apps use this
* by default, can be replaced using setRealm().
- *
+ * @param user The user name
+ * @param pass The password
*/
public void addUser(String user, String pass) {
userPass.put(user, pass);
}
/**
+ * Add a role to a user.
* @see #addUser(String, String)
+ * @param user The user name
+ * @param role The role name
*/
public void addRole(String user, String role) {
List<String> roles = userRoles.get(user);
@@ -527,6 +540,7 @@ public class Tomcat {
/**
* Get the service object. Can be used to add more
* connectors and few other global settings.
+ * @return The service
*/
public Service getService() {
getServer();
@@ -538,7 +552,7 @@ public class Tomcat {
* be added to this host. When tomcat starts, the
* host will be the default host.
*
- * @param host
+ * @param host The current host
*/
public void setHost(Host host) {
this.host = host;
@@ -570,6 +584,7 @@ public class Tomcat {
/**
* Access to the engine, for further customization.
+ * @return The engine
*/
public Engine getEngine() {
if(engine == null ) {
@@ -589,6 +604,7 @@ public class Tomcat {
/**
* Get the server object. You can add listeners and few more
* customizations. JNDI is disabled by default.
+ * @return The Server
*/
public Server getServer() {
@@ -609,10 +625,27 @@ public class Tomcat {
return server;
}
+ /**
+ * @param host The host in which the context will be deployed
+ * @param contextPath The context mapping to use, "" for root context.
+ * @param dir Base directory for the context, for static files.
+ * Must exist, relative to the server home
+ * @return the deployed context
+ * @see #addContext(String, String)
+ */
public Context addContext(Host host, String contextPath, String dir) {
return addContext(host, contextPath, contextPath, dir);
}
+ /**
+ * @param host The host in which the context will be deployed
+ * @param contextPath The context mapping to use, "" for root context.
+ * @param contextName The context name
+ * @param dir Base directory for the context, for static files.
+ * Must exist, relative to the server home
+ * @return the deployed context
+ * @see #addContext(String, String)
+ */
public Context addContext(Host host, String contextPath, String contextName,
String dir) {
silence(host, contextName);
@@ -630,6 +663,14 @@ public class Tomcat {
return ctx;
}
+ /**
+ * @param host The host in which the context will be deployed
+ * @param contextPath The context mapping to use, "" for root context.
+ * @param docBase Base directory for the context, for static files.
+ * Must exist, relative to the server home
+ * @return the deployed context
+ * @see #addWebapp(String, String)
+ */
public Context addWebapp(Host host, String contextPath, String docBase) {
LifecycleListener listener = null;
try {
@@ -645,6 +686,12 @@ public class Tomcat {
}
/**
+ * @param host The host in which the context will be deployed
+ * @param contextPath The context mapping to use, "" for root context.
+ * @param docBase Base directory for the context, for static files.
+ * Must exist, relative to the server home
+ * @param config Custom context configurator helper
+ * @return the deployed context
* @see #addWebapp(String, String)
*
* @param name Ignored. The contextPath will be used
@@ -1043,7 +1090,6 @@ public class Tomcat {
}
}
} catch (ClassCastException e) {
- return;
}
}
}
diff --git a/java/org/apache/catalina/tribes/group/RpcChannel.java b/java/org/apache/catalina/tribes/group/RpcChannel.java
index 56acb26..049f5e2 100644
--- a/java/org/apache/catalina/tribes/group/RpcChannel.java
+++ b/java/org/apache/catalina/tribes/group/RpcChannel.java
@@ -238,8 +238,7 @@ public class RpcChannel implements ChannelListener {
public long timeout;
/**
- * @deprecated Use {@link RpcChannel.RpcCollector#RpcChannel.RpcCollector(
- * RpcChannel.RpcCollectorKey, int, int)}
+ * @deprecated Use {@link RpcChannel.RpcCollector#RpcCollector(RpcCollectorKey, int, int)}
*/
@Deprecated
public RpcCollector(RpcCollectorKey key, int options, int destcnt,
diff --git a/java/org/apache/catalina/users/MemoryUser.java b/java/org/apache/catalina/users/MemoryUser.java
index 09b94ae..d9ac84b 100644
--- a/java/org/apache/catalina/users/MemoryUser.java
+++ b/java/org/apache/catalina/users/MemoryUser.java
@@ -90,11 +90,9 @@ public class MemoryUser extends AbstractUser {
*/
@Override
public Iterator<Group> getGroups() {
-
synchronized (groups) {
- return (groups.iterator());
+ return groups.iterator();
}
-
}
@@ -103,11 +101,9 @@ public class MemoryUser extends AbstractUser {
*/
@Override
public Iterator<Role> getRoles() {
-
synchronized (roles) {
- return (roles.iterator());
+ return roles.iterator();
}
-
}
@@ -116,9 +112,7 @@ public class MemoryUser extends AbstractUser {
*/
@Override
public UserDatabase getUserDatabase() {
-
- return (this.database);
-
+ return this.database;
}
@@ -166,11 +160,9 @@ public class MemoryUser extends AbstractUser {
*/
@Override
public boolean isInGroup(Group group) {
-
synchronized (groups) {
- return (groups.contains(group));
+ return groups.contains(group);
}
-
}
@@ -183,11 +175,9 @@ public class MemoryUser extends AbstractUser {
*/
@Override
public boolean isInRole(Role role) {
-
synchronized (roles) {
- return (roles.contains(role));
+ return roles.contains(role);
}
-
}
@@ -252,8 +242,9 @@ public class MemoryUser extends AbstractUser {
*
* <p><strong>IMPLEMENTATION NOTE</strong> - For backwards compatibility,
* the reader that processes this entry will accept either
- * <code>username</code> or </code>name</code> for the username
+ * <code>username</code> or <code>name</code> for the username
* property.</p>
+ * @return the XML representation
*/
public String toXml() {
@@ -298,10 +289,10 @@ public class MemoryUser extends AbstractUser {
}
}
sb.append("/>");
- return (sb.toString());
-
+ return sb.toString();
}
+
/**
* <p>Return a String representation of this user.</p>
*/
@@ -346,8 +337,6 @@ public class MemoryUser extends AbstractUser {
sb.append("\"");
}
}
- return (sb.toString());
+ return sb.toString();
}
-
-
}
diff --git a/java/org/apache/catalina/util/ExtensionValidator.java b/java/org/apache/catalina/util/ExtensionValidator.java
index c565539..76e03ef 100644
--- a/java/org/apache/catalina/util/ExtensionValidator.java
+++ b/java/org/apache/catalina/util/ExtensionValidator.java
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.catalina.util;
import java.io.File;
@@ -119,7 +118,7 @@ public final class ExtensionValidator {
* file in the /META-INF/ directory of the application and all
* MANIFEST.MF files in each JAR file located in the WEB-INF/lib
* directory and creates an <code>ArrayList</code> of
- * <code>ManifestResource<code> objects. These objects are then passed
+ * <code>ManifestResource</code> objects. These objects are then passed
* to the validateManifestResources method for validation.
*
* @param dirContext The JNDI root of the Web Application
@@ -127,6 +126,7 @@ public final class ExtensionValidator {
* application
*
* @return true if all required extensions satisfied
+ * @throws IOException Error reading resources needed for validation
*/
public static synchronized boolean validateApplication(
DirContext dirContext,
@@ -222,6 +222,7 @@ public final class ExtensionValidator {
* it to the container's manifest resources.
*
* @param jarFile The system JAR whose manifest to add
+ * @throws IOException Error reading JAR file
*/
public static void addSystemResource(File jarFile) throws IOException {
InputStream is = null;
@@ -392,9 +393,7 @@ public final class ExtensionValidator {
* @param inStream Input stream to a WAR or JAR file
* @return The WAR's or JAR's manifest
*/
- private static Manifest getManifest(InputStream inStream)
- throws IOException {
-
+ private static Manifest getManifest(InputStream inStream) throws IOException {
Manifest manifest = null;
JarInputStream jin = null;
@@ -412,7 +411,6 @@ public final class ExtensionValidator {
}
}
}
-
return manifest;
}
diff --git a/java/org/apache/catalina/util/RequestUtil.java b/java/org/apache/catalina/util/RequestUtil.java
index 625590b..e18cd93 100644
--- a/java/org/apache/catalina/util/RequestUtil.java
+++ b/java/org/apache/catalina/util/RequestUtil.java
@@ -130,7 +130,7 @@ public final class RequestUtil {
* <strong>IMPLEMENTATION NOTE</strong>: URL decoding is performed
* individually on the parsed name and value elements, rather than on
* the entire query string ahead of time, to properly deal with the case
- * where the name or value includes an encoded "=" or "&" character
+ * where the name or value includes an encoded "=" or "&" character
* that would otherwise be interpreted as a delimiter.
*
* @param map Map that accumulates the resulting parameters
@@ -350,7 +350,7 @@ public final class RequestUtil {
* <strong>IMPLEMENTATION NOTE</strong>: URL decoding is performed
* individually on the parsed name and value elements, rather than on
* the entire query string ahead of time, to properly deal with the case
- * where the name or value includes an encoded "=" or "&" character
+ * where the name or value includes an encoded "=" or "&" character
* that would otherwise be interpreted as a delimiter.
*
* NOTE: byte array data is modified by this method. Caller beware.
diff --git a/java/org/apache/coyote/AbstractProtocol.java b/java/org/apache/coyote/AbstractProtocol.java
index c85f9c5..4ced5f9 100644
--- a/java/org/apache/coyote/AbstractProtocol.java
+++ b/java/org/apache/coyote/AbstractProtocol.java
@@ -101,6 +101,12 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
* more specific setter. That means the property belongs to the Endpoint,
* the ServerSocketFactory or some other lower level component. This method
* ensures that it is visible to both.
+ *
+ * @param name The name of the property to set
+ * @param value The value, in string form, to set for the property
+ *
+ * @return <code>true</code> if the property was set successfully, otherwise
+ * <code>false</code>
*/
public boolean setProperty(String name, String value) {
return endpoint.setProperty(name, value);
@@ -110,6 +116,10 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
/**
* Generic property getter used by the digester. Other code should not need
* to use this.
+ *
+ * @param name The name of the property to get
+ *
+ * @return The value of the property converted to a string
*/
public String getProperty(String name) {
return endpoint.getProperty(name);
@@ -318,6 +328,7 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
/**
* Concrete implementations need to provide access to their logger to be
* used by the abstract classes.
+ * @return the logger
*/
protected abstract Log getLog();
@@ -325,12 +336,14 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
/**
* Obtain the prefix to be used when construction a name for this protocol
* handler. The name will be prefix-address-port.
+ * @return the prefix
*/
protected abstract String getNamePrefix();
/**
* Obtain the name of the protocol, (Http, Ajp, etc.). Used with JMX.
+ * @return the protocol name
*/
protected abstract String getProtocolName();
@@ -415,16 +428,15 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
@Override
public void init() throws Exception {
- if (getLog().isInfoEnabled())
- getLog().info(sm.getString("abstractProtocolHandler.init",
- getName()));
+ if (getLog().isInfoEnabled()) {
+ getLog().info(sm.getString("abstractProtocolHandler.init", getName()));
+ }
if (oname == null) {
// Component not pre-registered so register it
oname = createObjectName();
if (oname != null) {
- Registry.getRegistry(null, null).registerComponent(this, oname,
- null);
+ Registry.getRegistry(null, null).registerComponent(this, oname, null);
}
}
@@ -487,6 +499,7 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
}
}
+
@Override
public void resume() throws Exception {
if(getLog().isInfoEnabled())
@@ -523,6 +536,7 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
getLog().info(sm.getString("abstractProtocolHandler.destroy",
getName()));
}
+
try {
endpoint.destroy();
} catch (Exception e) {
@@ -533,6 +547,7 @@ public abstract class AbstractProtocol<S> implements ProtocolHandler,
if (oname != null) {
Registry.getRegistry(null, null).unregisterComponent(oname);
}
+ }
if (tpOname != null)
Registry.getRegistry(null, null).unregisterComponent(tpOname);
diff --git a/java/org/apache/coyote/OutputBuffer.java b/java/org/apache/coyote/OutputBuffer.java
index 74c6776..93d18ce 100644
--- a/java/org/apache/coyote/OutputBuffer.java
+++ b/java/org/apache/coyote/OutputBuffer.java
@@ -14,19 +14,17 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.coyote;
import java.io.IOException;
import org.apache.tomcat.util.buf.ByteChunk;
-
/**
* Output buffer.
*
* This class is used internally by the protocol implementation. All writes from
- * higher level code should happen via Resonse.doWrite().
+ * higher level code should happen via Response.doWrite().
*
* @author Remy Maucherat
*/
@@ -34,15 +32,16 @@ public interface OutputBuffer {
/**
- * Write the response. The caller ( tomcat ) owns the chunks.
+ * Write the given data to the response. The caller owns the chunks.
*
* @param chunk data to write
- * @param response used to allow buffers that can be shared by multiple
- * responses.
- * @throws IOException
+ *
+ * @return The number of bytes written which may be less than available in
+ * the input chunk
+ *
+ * @throws IOException an underlying I/O error occurred
*/
- public int doWrite(ByteChunk chunk, Response response)
- throws IOException;
+ public int doWrite(ByteChunk chunk, Response response) throws IOException;
/**
* Bytes written to the underlying socket. This includes the effects of
diff --git a/java/org/apache/coyote/ProtocolHandler.java b/java/org/apache/coyote/ProtocolHandler.java
index 344d406..5c7cdf7 100644
--- a/java/org/apache/coyote/ProtocolHandler.java
+++ b/java/org/apache/coyote/ProtocolHandler.java
@@ -14,7 +14,6 @@
* See the License for the specific language governing permissions and
* limitations under the License.
*/
-
package org.apache.coyote;
import java.util.concurrent.Executor;
@@ -22,10 +21,8 @@ import java.util.concurrent.Executor;
/**
* Abstract the protocol implementation, including threading, etc.
- * Processor is single threaded and specific to stream-based protocols,
- * will not fit Jk protocols like JNI.
*
- * This is the main interface to be implemented by a coyote connector.
+ * This is the main interface to be implemented by a coyote protocol.
* Adapter is the main interface to be implemented by a coyote servlet
* container.
*
@@ -36,50 +33,72 @@ import java.util.concurrent.Executor;
public interface ProtocolHandler {
/**
+ * Return the adapter associated with the protocol handler.
+ * @return the adapter
+ */
+ public Adapter getAdapter();
+
+
+ /**
* The adapter, used to call the connector.
+ *
+ * @param adapter The adapter to associate
*/
public void setAdapter(Adapter adapter);
- public Adapter getAdapter();
/**
* The executor, provide access to the underlying thread pool.
+ *
+ * @return The executor used to process requests
*/
public Executor getExecutor();
/**
* Initialise the protocol.
+ *
+ * @throws Exception If the protocol handler fails to initialise
*/
public void init() throws Exception;
/**
* Start the protocol.
+ *
+ * @throws Exception If the protocol handler fails to start
*/
public void start() throws Exception;
/**
* Pause the protocol (optional).
+ *
+ * @throws Exception If the protocol handler fails to pause
*/
public void pause() throws Exception;
/**
* Resume the protocol (optional).
+ *
+ * @throws Exception If the protocol handler fails to resume
*/
public void resume() throws Exception;
/**
* Stop the protocol.
+ *
+ * @throws Exception If the protocol handler fails to stop
*/
public void stop() throws Exception;
/**
* Destroy the protocol (optional).
+ *
+ * @throws Exception If the protocol handler fails to destroy
*/
public void destroy() throws Exception;
diff --git a/java/org/apache/coyote/ajp/AjpMessage.java b/java/org/apache/coyote/ajp/AjpMessage.java
index 2bbc236..03ef613 100644
--- a/java/org/apache/coyote/ajp/AjpMessage.java
+++ b/java/org/apache/coyote/ajp/AjpMessage.java
@@ -46,8 +46,7 @@ public class AjpMessage {
/**
* The string manager for this package.
*/
- protected static final StringManager sm =
- StringManager.getManager(Constants.Package);
+ protected static final StringManager sm = StringManager.getManager(AjpMessage.class);
// ------------------------------------------------------------ Constructor
@@ -114,6 +113,8 @@ public class AjpMessage {
/**
* Return the underlying byte buffer.
+ *
+ * @return The buffer
*/
public byte[] getBuffer() {
return buf;
@@ -121,9 +122,11 @@ public class AjpMessage {
/**
- * Return the current message length. For read, it's the length of the
- * payload (excluding the header). For write, it's the length of
- * the packet as a whole (counting the header).
+ * Return the current message length.
+ *
+ * @return For read, it's the length of the payload (excluding the header).
+ * For write, it's the length of the packet as a whole (counting the
+ * header).
*/
public int getLen() {
return len;
@@ -132,6 +135,8 @@ public class AjpMessage {
/**
* Add a short integer (2 bytes) to the message.
+ *
+ * @param val The integer to append
*/
public void appendInt(int val) {
buf[pos++] = (byte) ((val >>> 8) & 0xFF);
@@ -141,6 +146,8 @@ public class AjpMessage {
/**
* Append a byte (1 byte) to the message.
+ *
+ * @param val The byte value to append
*/
public void appendByte(int val) {
buf[pos++] = (byte) val;
@@ -148,8 +155,10 @@ public class AjpMessage {
/**
- * Write a MessageBytes out at the current write position.
- * A null MessageBytes is encoded as a string with length 0.
+ * Write a MessageBytes out at the current write position. A null
+ * MessageBytes is encoded as a string with length 0.
+ *
+ * @param mb The data to write
*/
public void appendBytes(MessageBytes mb) {
if (mb == null) {
@@ -172,8 +181,10 @@ public class AjpMessage {
/**
- * Write a ByteChunk out at the current write position.
- * A null ByteChunk is encoded as a string with length 0.
+ * Write a ByteChunk out at the current write position. A null ByteChunk is
+ * encoded as a string with length 0.
+ *
+ * @param bc The data to write
*/
public void appendByteChunk(ByteChunk bc) {
if (bc == null) {
@@ -190,6 +201,8 @@ public class AjpMessage {
/**
* Write a CharChunk out at the current write position.
* A null CharChunk is encoded as a string with length 0.
+ *
+ * @param cc The data to write
*/
public void appendCharChunk(CharChunk cc) {
if (cc == null) {
@@ -283,6 +296,8 @@ public class AjpMessage {
* it. Integers are encoded as two unsigned bytes with the
* high-order byte first, and, as far as I can tell, in
* little-endian order within each byte.
+ *
+ * @return The integer value read from the message
*/
public int getInt() {
int b1 = buf[pos++] & 0xFF;
@@ -340,6 +355,8 @@ public class AjpMessage {
* it. Integers are encoded as four unsigned bytes with the
* high-order byte first, and, as far as I can tell, in
* little-endian order within each byte.
+ *
+ * @return The long value read from the message
*/
public int getLongInt() {
int b1 = buf[pos++] & 0xFF; // No swap, Java order
@@ -377,7 +394,7 @@ public class AjpMessage {
(!toContainer && mark != 0x4142)) {
log.error(sm.getString("ajpmessage.invalid", "" + mark));
if (log.isDebugEnabled()) {
- dump("In: ");
+ dump("In");
}
return -1;
}
diff --git a/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java b/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java
index 83cb96a..16ea265 100644
--- a/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java
+++ b/java/org/apache/jasper/compiler/tagplugin/TagPluginContext.java
@@ -56,21 +56,24 @@ public interface TagPluginContext {
* invoked with the same id more than once in the translation
* unit, only the first declaration will be taken.
* @param text The text of the declaration.
- **/
+ */
void generateDeclaration(String id, String text);
/**
- * Generate Java source codes
+ * Generate Java source code scriptlet
+ * @param s the scriptlet (raw Java source)
*/
void generateJavaSource(String s);
/**
+ * @param attribute The attribute name
* @return true if the attribute is specified and its value is a
* translation-time constant.
*/
boolean isConstantAttribute(String attribute);
/**
+ * @param attribute The attribute name
* @return A string that is the value of a constant attribute. Undefined
* if the attribute is not a (translation-time) constant.
* null if the attribute is not specified.
@@ -112,17 +115,22 @@ public interface TagPluginContext {
/**
* Associate the attribute with a value in the current tagplugin context.
* The plugin attributes can be used for communication among tags that
- * must work together as a group. See <c:when> for an example.
+ * must work together as a group. See <c:when> for an example.
+ * @param attr The attribute name
+ * @param value The attribute value
*/
void setPluginAttribute(String attr, Object value);
/**
* Get the value of an attribute in the current tagplugin context.
+ * @param attr The attribute name
+ * @return the attribute value
*/
Object getPluginAttribute(String attr);
/**
* Is the tag being used inside a tag file?
+ * @return <code>true</code> if inside a tag file
*/
boolean isTagFile();
}
diff --git a/java/org/apache/tomcat/dbcp/dbcp/AbandonedConfig.java b/java/org/apache/tomcat/dbcp/dbcp/AbandonedConfig.java
index 9c64e19..5b2f462 100644
--- a/java/org/apache/tomcat/dbcp/dbcp/AbandonedConfig.java
+++ b/java/org/apache/tomcat/dbcp/dbcp/AbandonedConfig.java
@@ -82,7 +82,7 @@ public class AbandonedConfig {
* <li>{@link AbandonedObjectPool#getNumIdle() numIdle} < 2</li>
* <li>{@link AbandonedObjectPool#getNumActive() numActive} >
* {@link AbandonedObjectPool#getMaxActive() maxActive} - 3</li>
- * </ul></p>
+ * </ul>
*
* <p>The default value is 300 seconds.</p>
*/
diff --git a/java/org/apache/tomcat/dbcp/jocl/JOCLContentHandler.java b/java/org/apache/tomcat/dbcp/jocl/JOCLContentHandler.java
index 199da8a..6ed953d 100644
--- a/java/org/apache/tomcat/dbcp/jocl/JOCLContentHandler.java
+++ b/java/org/apache/tomcat/dbcp/jocl/JOCLContentHandler.java
@@ -91,7 +91,7 @@ import java.util.ArrayList;
* <code>new mypackage.Foo(new mypackage.Bar())</code>.
* <p>
* There is a special syntax available creating primitive values and arguments,
- * as well as for constructing {@link java.lang.String <code>String</code>}s. Some examples:
+ * as well as for constructing {@link java.lang.String String}s. Some examples:
* <pre> <byte value="3"/>
* <boolean value="false"/>
* <char value="c"/>
diff --git a/java/org/apache/tomcat/util/digester/SetPropertiesRule.java b/java/org/apache/tomcat/util/digester/SetPropertiesRule.java
index 013b336..ac9a86e 100644
--- a/java/org/apache/tomcat/util/digester/SetPropertiesRule.java
+++ b/java/org/apache/tomcat/util/digester/SetPropertiesRule.java
@@ -83,7 +83,7 @@ public class SetPropertiesRule extends Rule {
}
/**
- * <p>Constructor allows attribute->property mapping to be overridden.</p>
+ * <p>Constructor allows attribute->property mapping to be overridden.</p>
*
* <p>Two arrays are passed in.
* One contains the attribute names and the other the property names.
@@ -94,27 +94,27 @@ public class SetPropertiesRule extends Rule {
* <p>If a property name is null or the attribute name has no matching
* property name, then this indicates that the attribute should be ignored.</p>
*
- * <h5>Example One</h5>
+ * <h2>Example One</h2>
* <p> The following constructs a rule that maps the <code>alt-city</code>
* attribute to the <code>city</code> property and the <code>alt-state</code>
* to the <code>state</code> property.
* All other attributes are mapped as usual using exact name matching.
- * <code><pre>
+ * <pre>
* SetPropertiesRule(
* new String[] {"alt-city", "alt-state"},
* new String[] {"city", "state"});
- * </pre></code>
+ * </pre>
*
- * <h5>Example Two</h5>
+ * <h2>Example Two</h2>
* <p> The following constructs a rule that maps the <code>class</code>
* attribute to the <code>className</code> property.
* The attribute <code>ignore-me</code> is not mapped.
* All other attributes are mapped as usual using exact name matching.
- * <code><pre>
+ * <pre>
* SetPropertiesRule(
* new String[] {"class", "ignore-me"},
* new String[] {"className"});
- * </pre></code>
+ * </pre>
*
* @param attributeNames names of attributes to map
* @param propertyNames names of properties mapped to
diff --git a/java/org/apache/tomcat/util/net/AbstractEndpoint.java b/java/org/apache/tomcat/util/net/AbstractEndpoint.java
index b5f3936..9a8cec8 100644
--- a/java/org/apache/tomcat/util/net/AbstractEndpoint.java
+++ b/java/org/apache/tomcat/util/net/AbstractEndpoint.java
@@ -1043,8 +1043,8 @@ public abstract class AbstractEndpoint<S> {
* Configures SSLEngine to honor cipher suites ordering based upon
* endpoint configuration.
*
- * @throws java.security.InvalidAlgorithmParameterException If the runtime
- * JVM doesn't support this setting.
+ * @throws UnsupportedOperationException If the runtime JVM doesn't support
+ * this setting.
*/
protected void configureUseServerCipherSuitesOrder(SSLEngine engine) {
String useServerCipherSuitesOrderStr = this
diff --git a/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java b/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java
index 8fa5c33..2359fc8 100644
--- a/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java
+++ b/modules/jdbc-pool/src/main/java/org/apache/tomcat/jdbc/pool/PoolConfiguration.java
@@ -24,7 +24,6 @@ import org.apache.tomcat.jdbc.pool.PoolProperties.InterceptorDefinition;
* A list of properties that are configurable for a connection pool.
* The {@link DataSource} object also implements this interface so that it can be easily configured through
* an IoC container without having to specify a secondary object with a setter method.
- * @author fhanik
*
*/
@@ -56,8 +55,8 @@ public interface PoolConfiguration {
public int getAbandonWhenPercentageFull();
/**
- * Returns true if a fair queue is being used by the connection pool
- * @return true if a fair waiting queue is being used
+ * Returns <code>true</code> if a fair queue is being used by the connection pool
+ * @return <code>true</code> if a fair waiting queue is being used
*/
public boolean isFairQueue();
@@ -67,7 +66,7 @@ public interface PoolConfiguration {
* This uses the {@link FairBlockingQueue} implementation for the list of the idle connections.
* The default value is true.
* This flag is required when you want to use asynchronous connection retrieval.
- * @param fairQueue
+ * @param fairQueue <code>true</code> to use a fair queue
*/
public void setFairQueue(boolean fairQueue);
@@ -75,7 +74,7 @@ public interface PoolConfiguration {
* Property not used. Access is always allowed.
* Access can be achieved by calling unwrap on the pooled connection. see {@link javax.sql.DataSource} interface
* or call getConnection through reflection or cast the object as {@link javax.sql.PooledConnection}
- * @return true
+ * @return <code>true</code>
*/
public boolean isAccessToUnderlyingConnectionAllowed();
@@ -90,6 +89,7 @@ public interface PoolConfiguration {
* Format of the string is [propertyName=property;] <br>
* NOTE - The "user" and "password" properties will be passed explicitly, so they do not need to be included here.
* The default value is null.
+ * @return the connection properties
*/
public String getConnectionProperties();
@@ -109,7 +109,7 @@ public interface PoolConfiguration {
/**
* Overrides the database properties passed into the {@link java.sql.Driver#connect(String, Properties)} method.
- * @param dbProperties
+ * @param dbProperties The database properties
*/
public void setDbProperties(Properties dbProperties);
@@ -342,14 +342,14 @@ public interface PoolConfiguration {
/**
* Sets the password to establish the connection with.
* The password will be included as a database property with the name 'password'.
- * @param password
+ * @param password The password
* @see #getDbProperties()
*/
public void setPassword(String password);
/**
* @see #getName()
- * @return name
+ * @return the pool name
*/
public String getPoolName();
@@ -362,7 +362,7 @@ public interface PoolConfiguration {
/**
* Sets the username used to establish the connection with
* It will also be a property called 'user' in the database properties.
- * @param username
+ * @param username The user name
* @see #getDbProperties()
*/
public void setUsername(String username);
@@ -533,6 +533,7 @@ public interface PoolConfiguration {
/**
* The timeout in seconds before a connection validation queries fail.
* A value less than or equal to zero will disable this feature. Defaults to -1.
+ * @param validationQueryTimeout The timeout value
*/
public void setValidationQueryTimeout(int validationQueryTimeout);
@@ -560,6 +561,7 @@ public interface PoolConfiguration {
* Sets the validator object
* If this is a non null object, it will be used as a validator instead of the validationQuery
* If this is null, remove the usage of the validator.
+ * @param validator The validator object
*/
public void setValidator(Validator validator);
@@ -666,12 +668,12 @@ public interface PoolConfiguration {
/**
* Returns true if the pool sweeper is enabled for the connection pool.
* The pool sweeper is enabled if any settings that require async intervention in the pool are turned on
- * <source>
- boolean result = getTimeBetweenEvictionRunsMillis()>0;
- result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0);
- result = result || (isTestWhileIdle() && getValidationQuery()!=null);
+ * <code>
+ boolean result = getTimeBetweenEvictionRunsMillis()>0;
+ result = result && (isRemoveAbandoned() && getRemoveAbandonedTimeout()>0);
+ result = result || (isTestWhileIdle() && getValidationQuery()!=null);
return result;
- </source>
+ </code>
*
* @return true if a background thread is or will be enabled for this pool
*/
@@ -697,12 +699,13 @@ public interface PoolConfiguration {
public void setUseEquals(boolean useEquals);
/**
- * Time in milliseconds to keep this connection alive even when used.
- * When a connection is returned to the pool, the pool will check to see if the
- * ((now - time-when-connected) > maxAge) has been reached, and if so,
- * it closes the connection rather than returning it to the pool.
+ * Time in milliseconds to keep this connection before reconnecting.
+ * When a connection is idle, returned to the pool or borrowed from the pool, the pool will
+ * check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so,
+ * it reconnects. Note that the age of idle connections will only be checked if
+ * {@link #getTimeBetweenEvictionRunsMillis()} returns a value greater than 0.
* The default value is 0, which implies that connections will be left open and no
- * age check will be done upon returning the connection to the pool.
+ * age checks will be done.
* This is a useful setting for database sessions that leak memory as it ensures that the session
* will have a finite life span.
* @return the time in milliseconds a connection will be open for when used
@@ -710,12 +713,13 @@ public interface PoolConfiguration {
public long getMaxAge();
/**
- * Time in milliseconds to keep this connection alive even when used.
- * When a connection is returned to the pool, the pool will check to see if the
- * ((now - time-when-connected) > maxAge) has been reached, and if so,
- * it closes the connection rather than returning it to the pool.
+ * Time in milliseconds to keep this connection before reconnecting.
+ * When a connection is idle, returned to the pool or borrowed from the pool, the pool will
+ * check to see if the ((now - time-when-connected) > maxAge) has been reached, and if so,
+ * it reconnects. Note that the age of idle connections will only be checked if
+ * {@link #getTimeBetweenEvictionRunsMillis()} returns a value greater than 0.
* The default value is 0, which implies that connections will be left open and no
- * age check will be done upon returning the connection to the pool.
+ * age checks will be done.
* This is a useful setting for database sessions that leak memory as it ensures that the session
* will have a finite life span.
* @param maxAge the time in milliseconds a connection will be open for when used
@@ -817,6 +821,7 @@ public interface PoolConfiguration {
/**
* @see PoolConfiguration#setCommitOnReturn(boolean)
+ * @return <code>true</code> if the pool should commit when a connection is returned to it
*/
public boolean getCommitOnReturn();
@@ -831,20 +836,21 @@ public interface PoolConfiguration {
/**
* @see PoolConfiguration#setRollbackOnReturn(boolean)
+ * @return <code>true</code> if the pool should rollback when a connection is returned to it
*/
public boolean getRollbackOnReturn();
/**
- * If set to true, the connection will be wrapped with facade that will disallow the connection to be used after
- * {@link java.sql.Connection#close()} is called. If set to true, after {@link java.sql.Connection#close()} all calls except
+ * If set to <code>true</code>, the connection will be wrapped with facade that will disallow the connection to be used after
+ * {@link java.sql.Connection#close()} is called. If set to <code>true</code>, after {@link java.sql.Connection#close()} all calls except
* {@link java.sql.Connection#close()} and {@link java.sql.Connection#isClosed()} will throw an exception.
- * @param useDisposableConnectionFacade
+ * @param useDisposableConnectionFacade <code>true</code> to use a facade
*/
public void setUseDisposableConnectionFacade(boolean useDisposableConnectionFacade);
/**
- * Returns true if this connection pool is configured to use a connection facade to prevent re-use of connection after
+ * Returns <code>true</code> if this connection pool is configured to use a connection facade to prevent re-use of connection after
* {@link java.sql.Connection#close()} has been invoked
- * @return true if {@link java.sql.Connection#close()} has been invoked.
+ * @return <code>true</code> if {@link java.sql.Connection#close()} has been invoked.
*/
public boolean getUseDisposableConnectionFacade();
@@ -885,6 +891,7 @@ public interface PoolConfiguration {
public void setIgnoreExceptionOnPreLoad(boolean ignoreExceptionOnPreLoad);
/**
+ * @return <code>true</code> to ignore exceptions
* @see PoolConfiguration#setIgnoreExceptionOnPreLoad(boolean)
*/
public boolean isIgnoreExceptionOnPreLoad();
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org