/**
* Copyright 2010 Tristan Tarrant
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package net.dataforte.cassandra.pool;
/**
* A list of properties that are configurable for a connection pool.
*
* @author Tristan Tarrant
*
*/
public interface PoolConfiguration {
/**
* Provides a generic setter for any of the declared properties of the PoolConfiguration
*
* @param name the name of the property
* @param value the new value of the property
*/
public void set(String name, Object value);
/**
* Provides a generic getter for any of the declared properties of the PoolConfiguration
*
* @param name the name of the property
* @return the value of the property
*/
public Object get(String name);
/**
* Sets the Cassandra host. May be a comma-separated list of addresses
*
* @param host
*/
public void setHost(String host);
/**
* Returns the Cassandra hosts
*
* @return a single string representing the Cassandra host addresses separated by commas
*/
public String getHost();
/**
* Sets the Cassandra connection URL.
* The url is in the form cassandra:thrift://[host]:[port]
*
* @param url
*/
public void setUrl(String url);
/**
* Returns the Cassandra connection URL
*
* @return
*/
public String getUrl();
/**
* Sets the Cassandra port
*
* @param port
*/
public void setPort(int port);
/**
* Returns the Cassandra port (defaults to 9160)
*
* @return the Cassandra port
*/
public int getPort();
/**
* Sets whether to use framed connection mode (default false)
* @param framed
*/
public void setFramed(boolean framed);
/**
* Returns whether framed connection mode is being used
* @return whether framed connection mode is being used
*/
public boolean isFramed();
/**
* Sets whether Cassandra hosts should be queried to automatically obtain a list of other hosts
* @param autoDiscovery
*/
public void setAutomaticHostDiscovery(boolean autoDiscovery);
/**
* Returns whether automatic host discovery is being used
*
* @return whether automatic host discovery is being used
*/
public boolean isAutomaticHostDiscovery();
/**
* Sets the host failover policy, i.e. what to do when connecting to a host fails
*/
public void setFailoverPolicy(HostFailoverPolicy failoverPolicy);
/**
* Returns the failover policy.
*
* @return the failover policy
*/
public HostFailoverPolicy getFailoverPolicy();
/**
* Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
* above the percentage defined by abandonWhenPercentageFull.
* The value should be between 0-100.
* The default value is 0, which implies that connections are eligible for
* closure as soon as removeAbandonedTimeout has been reached.
* @param percentage a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
*/
public void setAbandonWhenPercentageFull(int percentage);
/**
* Connections that have been abandoned (timed out) wont get closed and reported up unless the number of connections in use are
* above the percentage defined by abandonWhenPercentageFull.
* The value should be between 0-100.
* The default value is 0, which implies that connections are eligible for
* closure as soon as removeAbandonedTimeout has been reached.
* @return percentage - a value between 0 and 100 to indicate when connections that have been abandoned/timed out are considered abandoned
*/
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
*/
public boolean isFairQueue();
/**
* Set to true if you wish that calls to getConnection
* should be treated fairly in a true FIFO fashion.
* 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
*/
public void setFairQueue(boolean fairQueue);
/**
* Returns the number of connections that will be established when the connection pool is started.
* Default value is 10
* @return number of connections to be started when pool is started
*/
public int getInitialSize();
/**
* Set the number of connections that will be established when the connection pool is started.
* Default value is 10.
* If this value exceeds {@link #setMaxActive(int)} it will automatically be lowered.
* @param initialSize the number of connections to be established.
*
*/
public void setInitialSize(int initialSize);
/**
* boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
* Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
* The default value is false.
* @return true if the connection pool logs stack traces when connections are borrowed from the pool.
*/
public boolean isLogAbandoned();
/**
* boolean flag to set if stack traces should be logged for application code which abandoned a Connection.
* Logging of abandoned Connections adds overhead for every Connection borrow because a stack trace has to be generated.
* The default value is false.
* @param logAbandoned set to true if stack traces should be recorded when {@link DataSource#getConnection()} is called.
*/
public void setLogAbandoned(boolean logAbandoned);
/**
* The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
* @return the maximum number of connections used by this pool
*/
public int getMaxActive();
/**
* The maximum number of active connections that can be allocated from this pool at the same time. The default value is 100
* @param maxActive hard limit for number of managed connections by this pool
*/
public void setMaxActive(int maxActive);
/**
* The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false.
* If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive}
* and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting.
* Default value is maxActive:100
* @return the maximum number of idle connections.
*/
public int getMaxIdle();
/**
* The maximum number of connections that should be kept in the idle pool if {@link #isPoolSweeperEnabled()} returns false.
* If the If {@link #isPoolSweeperEnabled()} returns true, then the idle pool can grow up to {@link #getMaxActive}
* and will be shrunk according to {@link #getMinEvictableIdleTimeMillis()} setting.
* Default value is maxActive:100
* @param maxIdle the maximum size of the idle pool
*/
public void setMaxIdle(int maxIdle);
/**
* The maximum number of milliseconds that the pool will wait (when there are no available connections and the
* {@link #getMaxActive} has been reached) for a connection to be returned
* before throwing an exception. Default value is 30000 (30 seconds)
* @return the number of milliseconds to wait for a connection to become available if the pool is maxed out.
*/
public int getMaxWait();
/**
* The maximum number of milliseconds that the pool will wait (when there are no available connections and the
* {@link #getMaxActive} has been reached) for a connection to be returned
* before throwing an exception. Default value is 30000 (30 seconds)
* @param maxWait the maximum number of milliseconds to wait.
*/
public void setMaxWait(int maxWait);
/**
* The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
* The default value is 60000 (60 seconds).
* @return the minimum amount of idle time in milliseconds before a connection is considered idle and eligible for eviction.
*/
public int getMinEvictableIdleTimeMillis();
/**
* The minimum amount of time an object must sit idle in the pool before it is eligible for eviction.
* The default value is 60000 (60 seconds).
* @param minEvictableIdleTimeMillis the number of milliseconds a connection must be idle to be eligible for eviction.
*/
public void setMinEvictableIdleTimeMillis(int minEvictableIdleTimeMillis);
/**
* The minimum number of established connections that should be kept in the pool at all times.
* The connection pool can shrink below this number if validation queries fail and connections get closed.
* Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)}
* The idle pool will not shrink below this value during an eviction run, hence the number of actual connections
* can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()}
* @return the minimum number of idle or established connections
*/
public int getMinIdle();
/**
* The minimum number of established connections that should be kept in the pool at all times.
* The connection pool can shrink below this number if validation queries fail and connections get closed.
* Default value is derived from {@link #getInitialSize()} (also see {@link #setTestWhileIdle(boolean)}
* The idle pool will not shrink below this value during an eviction run, hence the number of actual connections
* can be between {@link #getMinIdle()} and somewhere between {@link #getMaxIdle()} and {@link #getMaxActive()}
*
* @param minIdle the minimum number of idle or established connections
*/
public void setMinIdle(int minIdle);
/**
* Returns the name of the connection pool. By default a JVM unique random name is assigned.
* @return the name of the pool, should be unique in a JVM
*/
public String getName();
/**
* Sets the name of the connection pool
* @param name the name of the pool, should be unique in a runtime JVM
*/
public void setName(String name);
/**
* Property not used
* @return unknown value
*/
public int getNumTestsPerEvictionRun();
/**
* Property not used
* @param numTestsPerEvictionRun parameter ignored.
*/
public void setNumTestsPerEvictionRun(int numTestsPerEvictionRun);
/**
* Returns the password used when establishing connections to the database.
* @return the password in string format
*/
public String getPassword();
/**
* Sets the password to establish the connection with.
*
* @param password
*/
public void setPassword(String password);
/**
* @see #getName()
* @return name
*/
public String getPoolName();
/**
* Returns the keyspace
*/
public String getKeySpace();
/**
* Sets the keyspace
* @param keySpace
*/
public void setKeySpace(String keySpace);
/**
* Returns the username used to establish the connection with
* @return the username used to establish the connection with
*/
public String getUsername();
/**
* Sets the username used to establish the connection with
*
* @param username
*/
public void setUsername(String username);
/**
* boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout.
* If set to true a connection is considered abandoned and eligible for removal if it has
* been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for
* {@link #getAbandonWhenPercentageFull()} is met.
* Setting this to true can recover db connections from applications that fail to close a connection.
* See also {@link #isLogAbandoned()} The default value is false.
* @return true if abandoned connections can be closed and expelled out of the pool
*/
public boolean isRemoveAbandoned();
/**
* boolean flag to remove abandoned connections if they exceed the removeAbandonedTimout.
* If set to true a connection is considered abandoned and eligible for removal if it has
* been in use longer than the {@link #getRemoveAbandonedTimeout()} and the condition for
* {@link #getAbandonWhenPercentageFull()} is met.
* Setting this to true can recover db connections from applications that fail to close a connection.
* See also {@link #isLogAbandoned()} The default value is false.
* @param removeAbandoned set to true if abandoned connections can be closed and expelled out of the pool
*/
public void setRemoveAbandoned(boolean removeAbandoned);
/**
* The time in seconds before a connection can be considered abandoned.
* The timer can be reset upon queries using an interceptor.
* @param removeAbandonedTimeout the time in seconds before a used connection can be considered abandoned *
*/
public void setRemoveAbandonedTimeout(int removeAbandonedTimeout);
/**
* The time in seconds before a connection can be considered abandoned.
* The timer can be reset upon queries using an interceptor.
* @return the time in seconds before a used connection can be considered abandoned
*/
public int getRemoveAbandonedTimeout();
/**
* The indication of whether objects will be validated before being borrowed from the pool.
* If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
* Default value is false
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
* @return true if the connection is to be validated upon borrowing a connection from the pool
* @see #getValidationInterval()
*/
public boolean isTestOnBorrow();
/**
* The indication of whether objects will be validated before being borrowed from the pool.
* If the object fails to validate, it will be dropped from the pool, and we will attempt to borrow another.
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
* Default value is false
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
* @param testOnBorrow set to true if validation should take place before a connection is handed out to the application
* @see #getValidationInterval()
*/
public void setTestOnBorrow(boolean testOnBorrow);
/**
* The indication of whether objects will be validated after being returned to the pool.
* If the object fails to validate, it will be dropped from the pool.
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
* Default value is false
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
* @return true if validation should take place after a connection is returned to the pool
* @see #getValidationInterval()
*/
public boolean isTestOnReturn();
/**
* The indication of whether objects will be validated after being returned to the pool.
* If the object fails to validate, it will be dropped from the pool.
* NOTE - for a true value to have any effect, the validationQuery parameter must be set to a non-null string.
* Default value is false
* In order to have a more efficient validation, see {@link #setValidationInterval(long)}
* @param testOnReturn true if validation should take place after a connection is returned to the pool
* @see #getValidationInterval()
*/
public void setTestOnReturn(boolean testOnReturn);
/**
* Set to true if query validation should take place while the connection is idle.
* @return true if validation should take place during idle checks
* @see #setTimeBetweenEvictionRunsMillis(int)
*/
public boolean isTestWhileIdle();
/**
* Set to true if query validation should take place while the connection is idle.
* @param testWhileIdle true if validation should take place during idle checks
* @see #setTimeBetweenEvictionRunsMillis(int)
*/
public void setTestWhileIdle(boolean testWhileIdle);
/**
* The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner
* and idle pool resizing. This value should not be set under 1 second.
* It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool.
* The default value is 5000 (5 seconds)
* @return the sleep time in between validations in milliseconds
*/
public int getTimeBetweenEvictionRunsMillis();
/**
* The number of milliseconds to sleep between runs of the idle connection validation, abandoned cleaner
* and idle pool resizing. This value should not be set under 1 second.
* It dictates how often we check for idle, abandoned connections, and how often we validate idle connection and resize the idle pool.
* The default value is 5000 (5 seconds)
* @param timeBetweenEvictionRunsMillis the sleep time in between validations in milliseconds
*/
public void setTimeBetweenEvictionRunsMillis(int timeBetweenEvictionRunsMillis);
/**
* avoid excess validation, only run validation at most at this frequency - time in milliseconds.
* If a connection is due for validation, but has been validated previously
* within this interval, it will not be validated again.
* The default value is 30000 (30 seconds).
* @return the validation interval in milliseconds
*/
public long getValidationInterval();
/**
* avoid excess validation, only run validation at most at this frequency - time in milliseconds.
* If a connection is due for validation, but has been validated previously
* within this interval, it will not be validated again.
* The default value is 30000 (30 seconds).
* @param validationInterval the validation interval in milliseconds
*/
public void setValidationInterval(long validationInterval);
/**
* Returns true if we should run the validation query when connecting to the database for the first time on a connection.
* Normally this is always set to false.
* @return true if we should run the validation query upon connect
*/
public boolean isTestOnConnect();
/**
* Set to true if we should run the validation query when connecting to the database for the first time on a connection.
* Normally this is always set to false.
*
* @param testOnConnect set to true if we should run the validation query upon connect
*/
public void setTestOnConnect(boolean testOnConnect);
/**
* If set to true, the connection pool creates a {@link net.dataforte.cassandra.pool.jmx.ConnectionPoolMBean} object
* that can be registered with JMX to receive notifications and state about the pool.
* The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
* @return true if the mbean object will be created upon startup.
*/
public boolean isJmxEnabled();
/**
* If set to true, the connection pool creates a {@link net.dataforte.cassandra.pool.jmx.ConnectionPoolMBean} object
* that can be registered with JMX to receive notifications and state about the pool.
* The ConnectionPool object doesn't register itself, as there is no way to keep a static non changing ObjectName across JVM restarts.
* @param jmxEnabled set to to if the mbean object should be created upon startup.
*/
public void setJmxEnabled(boolean jmxEnabled);
/**
* 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);
return result;
</source>
*
* @return true if a background thread is or will be enabled for this pool
*/
public boolean isPoolSweeperEnabled();
/**
* Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of
* <code>==</code> when comparing method names.
* This property does not apply to added interceptors as those are configured individually.
* The default value is <code>false</code>.
* @return true if pool uses {@link String#equals(Object)} instead of == when comparing method names on {@link java.sql.Connection} methods
*/
public boolean isUseEquals();
/**
* Set to true if you wish the <code>ProxyConnection</code> class to use <code>String.equals</code> instead of
* <code>==</code> when comparing method names.
* This property does not apply to added interceptors as those are configured individually.
* The default value is <code>false</code>.
* @param useEquals set to true if the pool should use {@link String#equals(Object)} instead of ==
* when comparing method names on {@link java.sql.Connection} methods
*/
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.
* 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.
* 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
*/
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.
* 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.
* 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
*/
public void setMaxAge(long maxAge);
/**
* Return true if a lock should be used when operations are performed on the connection object.
* Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking
* such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
* @return true if a lock is used.
*/
public boolean getUseLock();
/**
* Set to true if a lock should be used when operations are performed on the connection object.
* Should be set to false unless you plan to have a background thread of your own doing idle and abandon checking
* such as JMX clients. If the pool sweeper is enabled, then the lock will automatically be used regardless of this setting.
* @param useLock set to true if a lock should be used on connection operations
*/
public void setUseLock(boolean useLock);
/**
* Similar to {@link #setRemoveAbandonedTimeout(int)} but instead of treating the connection
* as abandoned, and potentially closing the connection, this simply logs the warning if
* {@link #isLogAbandoned()} returns true. If this value is equal or less than 0, no suspect
* checking will be performed. Suspect checking only takes place if the timeout value is larger than 0 and
* the connection was not abandoned or if abandon check is disabled. If a connection is suspect a WARN message gets
* logged and a JMX notification gets sent once.
* @param seconds - the amount of time in seconds that has to pass before a connection is marked suspect.
*/
public void setSuspectTimeout(int seconds);
/**
* Returns the time in seconds to pass before a connection is marked an abanoned suspect.
* Any value lesser than or equal to 0 means the check is disabled.
* @return Returns the time in seconds to pass before a connection is marked an abanoned suspect.
*/
public int getSuspectTimeout();
/**
* Returns the socket timeout in milliseconds
*
* @return the socket timeout in milliseconds
*/
int getSocketTimeout();
/**
* Sets the socket timeout in milliseconds
*
* @param socketTimeout
*/
void setSocketTimeout(int socketTimeout);
/**
* Returns an array of configured hosts (may be different from the actual list if dynamic discovery is enabled)
*
* @return an array of strings representing the addresses of the configured Cassandra hosts
*/
String[] getConfiguredHosts();
/**
* Returns the interval in milliseconds before retrying a host to which a connection has failed in the past.
* Default is 300000 (5 minutes)
*
* @return milliseconds before host retry
*/
public long getHostRetryInterval();
/**
* Sets the interval in milliseconds before retrying a host to which a connection has failed in the past.
* @param hostRetryInterval number of millieseconds before retrying a host
*/
void setHostRetryInterval(long hostRetryInterval);
/**
* Configure the connection pool to use a DataSource according to {@link PoolConfiguration#setDataSource(Object)}
* But instead of injecting the object, specify the JNDI location.
* After a successful JNDI look, the {@link PoolConfiguration#getDataSource()} will not return null.
* @param jndiDS -the JNDI string @TODO specify the rules here.
*/
public void setDataSourceJNDI(String jndiDS);
/**
* Returns the JNDI string configured for data source usage.
* @return the JNDI string or null if not set
*/
public String getDataSourceJNDI();
/**
* Injects a datasource that will be used to retrieve/create connections.
*
* @param ds the {@link javax.sql.DataSource} to be used for creating connections to be pooled.
*/
public void setDataSource(Object ds);
/**
* Returns a datasource, if one exists that is being used to create connections.
*
* @return the datasource object
*/
public Object getDataSource();
}