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-unsubscr...@tomcat.apache.org For additional commands, e-mail: dev-h...@tomcat.apache.org