From: fhanik Date: Fri, 10 Jul 2009 18:10:30 +0000 (+0000) Subject: javadoc corrections X-Git-Url: https://git.internetallee.de/?a=commitdiff_plain;h=fb162ee98ebd8d2c41edf6197250da9d581d248f;p=tomcat7.0 javadoc corrections git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@793060 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java index c2c69f5f1..a258179f5 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/ConnectionPool.java @@ -139,7 +139,7 @@ public class ConnectionPool { * until a connection has become available. * If a connection is not retrieved, the Future must be cancelled in order for the connection to be returned * to the pool. - * @return + * @return a Future containing a reference to the connection or the future connection * @throws SQLException */ public Future getConnectionAsync() throws SQLException { @@ -234,7 +234,7 @@ public class ConnectionPool { * All calls on {@link java.sql.Connection} methods will be propagated down to the actual JDBC connection except for the * {@link java.sql.Connection#close()} method. * @param con a {@link PooledConnection} to wrap in a Proxy - * @return a {@java.sql.Connection} object wrapping a pooled connection. + * @return a {@link java.sql.Connection} object wrapping a pooled connection. * @throws SQLException if an interceptor can't be configured, if the proxy can't be instantiated */ protected Connection setupConnection(PooledConnection con) throws SQLException { diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSource.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSource.java index 03637ad59..dd818596c 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSource.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSource.java @@ -16,6 +16,7 @@ */ package org.apache.tomcat.jdbc.pool; +import java.io.PrintWriter; import java.lang.management.ManagementFactory; import java.sql.SQLException; import java.util.Hashtable; @@ -108,7 +109,7 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } /** - * Registers the ConnectionPoolMBean + * Registers the ConnectionPoolMBean under a unique name based on the ObjectName for the DataSource */ protected void registerJmx() { try { @@ -134,6 +135,10 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav //=============================================================================== // Expose JMX attributes through Tomcat's dynamic reflection //=============================================================================== + /** + * Forces an abandon check on the connection pool. + * If connections that have been abandoned exists, they will be closed during this run + */ public void checkAbandoned() { try { createPool().checkAbandoned(); @@ -142,6 +147,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * Forces a check for downsizing the idle connections + */ public void checkIdle() { try { createPool().checkIdle(); @@ -150,6 +158,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return number of connections in use by the application + */ public int getActive() { try { return createPool().getActive(); @@ -158,10 +169,17 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return number of connections in use by the application + * {@link DataSource#getActive()} + */ public int getNumActive() { return getActive(); } + /** + * @return number of threads waiting for a connection + */ public int getWaitCount() { try { return createPool().getWaitCount(); @@ -170,6 +188,10 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * NOT USED ANYWHERE + * @return nothing + */ public String getConnectionProperties() { try { return createPool().getPoolProperties().getConnectionProperties(); @@ -178,6 +200,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return connection properties passed into the JDBC Driver upon connect + */ public Properties getDbProperties() { try { return createPool().getPoolProperties().getDbProperties(); @@ -186,6 +211,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured default catalog + */ public String getDefaultCatalog() { try { return createPool().getPoolProperties().getDefaultCatalog(); @@ -194,6 +222,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured default isolation level + */ public int getDefaultTransactionIsolation() { try { return createPool().getPoolProperties().getDefaultTransactionIsolation(); @@ -202,6 +233,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured driver class name + */ public String getDriverClassName() { try { return createPool().getPoolProperties().getDriverClassName(); @@ -210,6 +244,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the number of established but idle connections + */ public int getIdle() { try { return createPool().getIdle(); @@ -217,11 +254,17 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav throw new RuntimeException(x); } } - + + /** + * {@link #getIdle()} + */ public int getNumIdle() { return getIdle(); } + /** + * @return the configured number of initial connections + */ public int getInitialSize() { try { return createPool().getPoolProperties().getInitialSize(); @@ -230,6 +273,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured initialization SQL + */ public String getInitSQL() { try { return createPool().getPoolProperties().getInitSQL(); @@ -238,6 +284,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configuration string for interceptors + */ public String getJdbcInterceptors() { try { return createPool().getPoolProperties().getJdbcInterceptors(); @@ -246,6 +295,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured number of maximum allowed connections + */ public int getMaxActive() { try { return createPool().getPoolProperties().getMaxActive(); @@ -254,6 +306,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured number of maximum idle connections + */ public int getMaxIdle() { try { return createPool().getPoolProperties().getMaxIdle(); @@ -262,6 +317,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured maximum wait time in milliseconds if a connection is not available + */ public int getMaxWait() { try { return createPool().getPoolProperties().getMaxWait(); @@ -270,6 +328,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured idle time, before a connection that is idle can be released + */ public int getMinEvictableIdleTimeMillis() { try { return createPool().getPoolProperties().getMinEvictableIdleTimeMillis(); @@ -278,6 +339,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured minimum amount of idle connections + */ public int getMinIdle() { try { return createPool().getPoolProperties().getMinIdle(); @@ -286,6 +350,11 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured maxAge for a connection. + * A connection that has been established for longer than this configured value in milliseconds + * will be closed upon a return + */ public long getMaxAge() { try { return createPool().getPoolProperties().getMaxAge(); @@ -294,6 +363,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the name of the pool + */ public String getName() { try { return createPool().getName(); @@ -302,6 +374,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the configured value - not used in this implementation + */ public int getNumTestsPerEvictionRun() { try { return createPool().getPoolProperties().getNumTestsPerEvictionRun(); @@ -310,10 +385,16 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return DOES NOT RETURN THE PASSWORD, IT WOULD SHOW UP IN JMX + */ public String getPassword() { return "Password not available as DataSource/JMX operation."; } + /** + * @return the configured remove abandoned timeout in seconds + */ public int getRemoveAbandonedTimeout() { try { return createPool().getPoolProperties().getRemoveAbandonedTimeout(); @@ -322,6 +403,9 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav } } + /** + * @return the current size of the pool + */ public int getSize() { try { return createPool().getSize(); @@ -465,6 +549,5 @@ public class DataSource extends DataSourceProxy implements MBeanRegistration,jav throw new RuntimeException(x); } } - } diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceFactory.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceFactory.java index 54e45c858..6883bd8f9 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceFactory.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceFactory.java @@ -428,7 +428,7 @@ public class DataSourceFactory implements ObjectFactory { } /** - * Creates and configures a {@link BasicDataSource} instance based on the + * Creates and configures a {@link DataSource} instance based on the * given properties. * * @param properties the datasource configuration properties diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceProxy.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceProxy.java index 430bad376..17d5ee911 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceProxy.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/DataSourceProxy.java @@ -66,7 +66,7 @@ public class DataSourceProxy { } /** - * {@inheritDoc} + * {@link javax.sql.DataSource#getConnection()} */ public Connection getConnection(String username, String password) throws SQLException { return getConnection(); @@ -91,7 +91,7 @@ public class DataSourceProxy { } /** - * {@inheritDoc} + * {@link javax.sql.DataSource#getConnection()} */ public Connection getConnection() throws SQLException { @@ -102,7 +102,7 @@ public class DataSourceProxy { /** * Invokes an sync operation to retrieve the connection. - * @return + * @return a Future containing a reference to the connection when it becomes available * @throws SQLException */ public Future getConnectionAsync() throws SQLException { @@ -112,14 +112,14 @@ public class DataSourceProxy { } /** - * {@inheritDoc} + * {@link javax.sql.DataSource#getConnection()} */ public PooledConnection getPooledConnection() throws SQLException { return (PooledConnection) getConnection(); } /** - * {@inheritDoc} + * {@link javax.sql.DataSource#getConnection()} */ public PooledConnection getPooledConnection(String username, String password) throws SQLException { @@ -134,41 +134,7 @@ public class DataSourceProxy { return pool.getName(); } - /** - * {@inheritDoc} - */ - public PrintWriter getLogWriter() throws SQLException { - return null; - } - - /** - * {@inheritDoc} - */ - public void setLogWriter(PrintWriter out) throws SQLException { - } - - /** - * {@inheritDoc} - */ - public int getLoginTimeout() { - if (poolProperties == null) { - return 0; - } else { - return poolProperties.getMaxWait() / 1000; - } - } - - /** - * {@inheritDoc} - */ - public void setLoginTimeout(int i) { - if (poolProperties == null) { - return; - } else { - poolProperties.setMaxWait(1000 * i); - } - - } + public void close() { @@ -354,4 +320,43 @@ public class DataSourceProxy { this.getPoolProperties().setUseEquals(useEquals); } + /** + * no-op + * {@link javax.sql.DataSource#getLogWriter} + */ + public PrintWriter getLogWriter() throws SQLException { + return null; + } + + /** + * {@link javax.sql.DataSource#setLogWriter(PrintWriter)} + */ + public void setLogWriter(PrintWriter out) throws SQLException { + } + + /** + * {@link javax.sql.DataSource#getLoginTimeout} + */ + public int getLoginTimeout() { + if (poolProperties == null) { + return 0; + } else { + return poolProperties.getMaxWait() / 1000; + } + } + + /** + * {@link javax.sql.DataSource#setLoginTimeout(int)} + */ + public void setLoginTimeout(int i) { + if (poolProperties == null) { + return; + } else { + poolProperties.setMaxWait(1000 * i); + } + + } + + + } diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java index 8d7dcf4be..3b13cfc7e 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/JdbcInterceptor.java @@ -77,7 +77,7 @@ public abstract class JdbcInterceptor implements InvocationHandler { /** * Returns the next interceptor in the chain - * @return + * @return the next interceptor in the chain */ public JdbcInterceptor getNext() { return next; @@ -95,7 +95,7 @@ public abstract class JdbcInterceptor implements InvocationHandler { * Performs a string comparison, using references unless the useEquals property is set to true. * @param name1 * @param name2 - * @return + * @return true if name1 is equal to name2 based on {@link #useEquals} */ public boolean compare(String name1, String name2) { if (isUseEquals()) { @@ -107,7 +107,7 @@ public abstract class JdbcInterceptor implements InvocationHandler { /** * Compares a method name (String) to a method (Method) - * {@link compare(String,String)} + * {@link #compare(String,String)} * Uses reference comparison unless the useEquals property is set to true * @param methodName * @param method @@ -157,7 +157,7 @@ public abstract class JdbcInterceptor implements InvocationHandler { } /** - * Set to true if string comparisons (for the {@link compare} method) should use the Object.equals(Object) method + * Set to true if string comparisons (for the {@link #compare(String, Method)} and {@link #compare(String, String)} methods) should use the Object.equals(Object) method * The default is false * @param useEquals */ diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java index e9eadc88b..5ca08df59 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/PooledConnection.java @@ -382,7 +382,7 @@ public class PooledConnection { /** * Returns the underlying connection - * @return + * @return the underlying JDBC connection as it was returned from the JDBC driver */ public java.sql.Connection getConnection() { return this.connection; @@ -396,7 +396,7 @@ public class PooledConnection { /** * Returns the first handler in the interceptor chain - * @return + * @return the first interceptor for this connection */ public JdbcInterceptor getHandler() { return (handler!=null)?handler.get():null; diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java index 11acf01ab..72d16e4d1 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractCreateStatementInterceptor.java @@ -55,12 +55,12 @@ public abstract class AbstractCreateStatementInterceptor extends JdbcIntercepto /** * This method should return a wrapper object around a - * java.sql.Statement, java.sql.PreparedStatement or java.sql.CallableStatement + * {@link java.sql.Statement}, {@link java.sql.PreparedStatement} or {@link java.sql.CallableStatement} * @param proxy * @param method * @param args * @param statement - * @return + * @return a {@link java.sql.Statement} object */ public abstract Object createStatement(Object proxy, Method method, Object[] args, Object statement, long time); diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java index 46b1763cc..81347b386 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/AbstractQueryReport.java @@ -60,7 +60,7 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce /** * Invoked when prepareCall has been called and completed. - * @param sql - the string used to prepare the statement with + * @param query - the string used to prepare the statement with * @param time - the time it took to invoke prepare */ protected abstract void prepareCall(String query, long time); @@ -90,7 +90,7 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce * @param args * @param name * @param start - * @param t + * @param delta * @return - the SQL that was executed or the string "batch" */ protected String reportQuery(String query, Object[] args, final String name, long start, long delta) { @@ -109,7 +109,7 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce * @param args * @param name * @param start - * @param t + * @param delta * @return - the SQL that was executed or the string "batch" */ protected String reportSlowQuery(String query, Object[] args, final String name, long start, long delta) { @@ -125,7 +125,7 @@ public abstract class AbstractQueryReport extends AbstractCreateStatementInterce /** * returns the query measure threshold. * This value is in milliseconds. If the query is faster than this threshold than it wont be accounted for - * @return + * @return the threshhold in milliseconds */ public long getThreshold() { return threshold; diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReport.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReport.java index dada2cf06..b319919b4 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReport.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReport.java @@ -57,7 +57,7 @@ public class SlowQueryReport extends AbstractQueryReport { /** * Returns the query stats for a given pool - * @param pool - the pool we want to retrieve stats for + * @param poolname - the name of the pool we want to retrieve stats for * @return a hash map containing statistics for 0 to maxQueries */ public static ConcurrentHashMap getPoolStats(String poolname) { diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReportJmx.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReportJmx.java index 11c675e9d..2718a542f 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReportJmx.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/interceptor/SlowQueryReportJmx.java @@ -187,7 +187,7 @@ public class SlowQueryReportJmx extends SlowQueryReport implements NotificationE /** * JMX operation - return the names of all the pools - * @return + * @return - all the names of pools that we have stored data for */ public String[] getPoolNames() { Set keys = perPoolStats.keySet(); @@ -196,7 +196,7 @@ public class SlowQueryReportJmx extends SlowQueryReport implements NotificationE /** * JMX operation - return the name of the pool - * @return + * @return the name of the pool, unique within the JVM */ public String getPoolName() { return poolName; @@ -225,7 +225,7 @@ public class SlowQueryReportJmx extends SlowQueryReport implements NotificationE /** * JMX operation - returns all the queries we have collected. - * @return + * @return - the slow query report as composite data. */ public CompositeData[] getSlowQueriesCD() throws OpenDataException { CompositeDataSupport[] result = null; diff --git a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/jmx/ConnectionPool.java b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/jmx/ConnectionPool.java index 64526bb48..25be605b0 100644 --- a/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/jmx/ConnectionPool.java +++ b/modules/jdbc-pool/java/org/apache/tomcat/jdbc/pool/jmx/ConnectionPool.java @@ -92,7 +92,7 @@ public class ConnectionPool extends NotificationBroadcasterSupport implements Co * Return true if the notification was sent successfully, false otherwise. * @param type * @param message - * @return + * @return true if the notification succeeded */ public boolean notify(final String type, String message) { try {