Author: rhauch Date: 2008-06-06 17:19:46 -0400 (Fri, 06 Jun 2008) New Revision: 244 Modified: trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheConnection.java trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheSource.java trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnection.java trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnectionPool.java trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySource.java trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySourceException.java trunk/dna-spi/src/test/java/org/jboss/dna/spi/graph/connection/MockRepositorySource.java Log: DNA-67: Create graph API for federation engine http://jira.jboss.org/jira/browse/DNA-67 Moved the "getDefaultCachePolicy" from RepositorySource to RepositoryConnection. Modified: trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheConnection.java =================================================================== --- trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheConnection.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheConnection.java 2008-06-06 21:19:46 UTC (rev 244) @@ -30,6 +30,7 @@ import org.jboss.cache.Cache; import org.jboss.cache.Fqn; import org.jboss.cache.Node; +import org.jboss.dna.spi.cache.CachePolicy; import org.jboss.dna.spi.graph.Name; import org.jboss.dna.spi.graph.Path; import org.jboss.dna.spi.graph.Property; @@ -97,6 +98,13 @@ /** * {@inheritDoc} */ + public CachePolicy getDefaultCachePolicy() { + return source.getDefaultCachePolicy(); + } + + /** + * {@inheritDoc} + */ public XAResource getXAResource() { return null; } Modified: trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheSource.java =================================================================== --- trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheSource.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/connectors/dna-connector-jbosscache/src/main/java/org/jboss/dna/connector/jbosscache/JBossCacheSource.java 2008-06-06 21:19:46 UTC (rev 244) @@ -113,7 +113,9 @@ } /** - * {@inheritDoc} + * Get the default cache policy for this source, or null if the global default cache policy should be used + * + * @return the default cache policy, or null if this source has no explicit default cache policy */ public CachePolicy getDefaultCachePolicy() { return defaultCachePolicy; Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnection.java =================================================================== --- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnection.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnection.java 2008-06-06 21:19:46 UTC (rev 244) @@ -23,6 +23,7 @@ import java.util.concurrent.TimeUnit; import javax.transaction.xa.XAResource; +import org.jboss.dna.spi.cache.CachePolicy; import org.jboss.dna.spi.graph.commands.GraphCommand; /** @@ -31,6 +32,7 @@ * These connections need not support concurrent operations by multiple threads, since the federation engine never uses them this * way. * </p> + * * @author Randall Hauch */ public interface RepositoryConnection { @@ -38,6 +40,7 @@ /** * Get the name for this repository source. This value should be the same as that {@link RepositorySource#getName() returned} * by the same {@link RepositorySource} that created this connection. + * * @return the identifier; never null or empty */ String getSourceName(); @@ -45,12 +48,14 @@ /** * Return the transactional resource associated with this connection. The transaction manager will use this resource to manage * the participation of this connection in a distributed transaction. + * * @return the XA resource, or null if this connection is not aware of distributed transactions */ XAResource getXAResource(); /** * Ping the underlying system to determine if the connection is still valid and alive. + * * @param time the length of time to wait before timing out * @param unit the time unit to use; may not be null * @return true if this connection is still valid and can still be used, or false otherwise @@ -60,12 +65,21 @@ /** * Set the listener that is to receive notifications to changes to content within this source. + * * @param listener the new listener, or null if no component is interested in the change notifications */ void setListener( RepositorySourceListener listener ); /** + * Get the default cache policy for this repository. If none is provided, a global cache policy will be used. + * + * @return the default cache policy + */ + CachePolicy getDefaultCachePolicy(); + + /** * Execute the supplied commands against this repository source. + * * @param env the environment in which the commands are being executed; never null * @param commands the commands to be executed; never null * @throws RepositorySourceException if there is a problem loading the node data @@ -75,6 +89,7 @@ /** * Close this connection to signal that it is no longer needed and that any accumulated resources are to be released. + * * @throws InterruptedException if the thread has been interrupted while the close was in progress */ void close() throws InterruptedException; Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnectionPool.java =================================================================== --- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnectionPool.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositoryConnectionPool.java 2008-06-06 21:19:46 UTC (rev 244) @@ -43,6 +43,7 @@ import org.jboss.dna.common.util.LogContext; import org.jboss.dna.common.util.Logger; import org.jboss.dna.spi.SpiI18n; +import org.jboss.dna.spi.cache.CachePolicy; import org.jboss.dna.spi.graph.commands.GraphCommand; /** @@ -52,6 +53,21 @@ public class RepositoryConnectionPool implements RepositoryConnectionFactory { /** + * The core pool size for default-constructed pools is {@value}. + */ + public static final int DEFAULT_CORE_POOL_SIZE = 1; + + /** + * The maximum pool size for default-constructed pools is {@value}. + */ + public static final int DEFAULT_MAXIMUM_POOL_SIZE = 10; + + /** + * The keep-alive time for connections in default-constructed pools is {@value} seconds. + */ + public static final long DEFAULT_KEEP_ALIVE_TIME_IN_SECONDS = 30; + + /** * Permission for checking shutdown */ private static final RuntimePermission shutdownPerm = new RuntimePermission("modifyThread"); @@ -146,7 +162,20 @@ private final Logger logger = Logger.getLogger(this.getClass()); /** + * Create the pool to use the supplied connection factory, which is typically a {@link RepositorySource}. This constructor + * uses the {@link #DEFAULT_CORE_POOL_SIZE default core pool size}, {@link #DEFAULT_MAXIMUM_POOL_SIZE default maximum pool + * size}, and {@link #DEFAULT_KEEP_ALIVE_TIME_IN_SECONDS default keep-alive time (in seconds)}. + * + * @param connectionFactory the factory for connections + * @throws IllegalArgumentException if the connection factory is null or any of the supplied arguments are invalid + */ + public RepositoryConnectionPool( RepositoryConnectionFactory connectionFactory ) { + this(connectionFactory, DEFAULT_CORE_POOL_SIZE, DEFAULT_MAXIMUM_POOL_SIZE, DEFAULT_KEEP_ALIVE_TIME_IN_SECONDS, TimeUnit.SECONDS); + } + + /** * Create the pool to use the supplied connection factory, which is typically a {@link RepositorySource}. + * * @param connectionFactory the factory for connections * @param corePoolSize the number of connections to keep in the pool, even if they are idle. * @param maximumPoolSize the maximum number of connections to allow in the pool. @@ -226,6 +255,7 @@ * Sets the time limit for which connections may remain idle before being closed. If there are more than the core number of * connections currently in the pool, after waiting this amount of time without being used, excess threads will be terminated. * This overrides any value set in the constructor. + * * @param time the time to wait. A time value of zero will cause excess connections to terminate immediately after being * returned. * @param unit the time unit of the time argument @@ -240,6 +270,7 @@ /** * Returns the connection keep-alive time, which is the amount of time which connections in excess of the core pool size may * remain idle before being closed. + * * @param unit the desired time unit of the result * @return the time limit * @see #setKeepAliveTime @@ -259,6 +290,7 @@ /** * Sets the maximum allowed number of connections. This overrides any value set in the constructor. If the new value is * smaller than the current value, excess existing but unused connections will be closed. + * * @param maximumPoolSize the new maximum * @throws IllegalArgumentException if maximumPoolSize less than zero or the {@link #getCorePoolSize() core pool size} * @see #getMaximumPoolSize @@ -284,6 +316,7 @@ /** * Returns the core number of connections. + * * @return the core number of connections * @see #setCorePoolSize(int) */ @@ -295,6 +328,7 @@ * Sets the core number of connections. This overrides any value set in the constructor. If the new value is smaller than the * current value, excess existing and unused connections will be closed. If larger, new connections will, if needed, be * created. + * * @param corePoolSize the new core size * @throws RepositorySourceException if there was an error obtaining the new connection * @throws InterruptedException if the thread was interrupted during the operation @@ -328,7 +362,9 @@ // ------------------------------------------------- /** - * Returns the current number of connections in the pool. + * Returns the current number of connections in the pool, including those that are checked out (in use) and those that are not + * being used. + * * @return the number of connections */ public int getPoolSize() { @@ -336,7 +372,8 @@ } /** - * Returns the approximate number of connections that have been checked out from the pool. + * Returns the approximate number of connections that are currently checked out from the pool. + * * @return the number of checked-out connections */ public int getInUseCount() { @@ -351,6 +388,7 @@ /** * Get the total number of connections that have been created by this pool. + * * @return the total number of connections created by this pool */ public long getTotalConnectionsCreated() { @@ -359,6 +397,7 @@ /** * Get the total number of times connections have been {@link #getConnection()} used. + * * @return the total number */ public long getTotalConnectionsUsed() { @@ -371,6 +410,7 @@ /** * Call the supplied operation, using a connection from this pool. + * * @param <T> the return type for the operation * @param operation the operation to be run using a connection in this pool * @return the results from the operation @@ -378,7 +418,7 @@ * @throws InterruptedException if the thread was interrupted during the operation * @throws IllegalArgumentException if the operation is null * @see #callable(RepositoryOperation) - * @see #callables(Collection) + * @see #callables(Iterable) * @see #callables(RepositoryOperation...) */ public <T> T call( RepositoryOperation<T> operation ) throws RepositorySourceException, InterruptedException { @@ -399,11 +439,12 @@ /** * Return a callable object that, when run, performs the supplied repository operation against a connection in this pool. + * * @param <T> the return type for the operation * @param operation the operation to be run using a connection in this pool * @return the callable * @see #call(RepositoryOperation) - * @see #callables(Collection) + * @see #callables(Iterable) * @see #callables(RepositoryOperation...) */ public <T> Callable<T> callable( final RepositoryOperation<T> operation ) { @@ -413,6 +454,7 @@ /** * Execute by getting a connection from this pool, running the client, and return the connection to the pool. + * * @return the operation's result * @throws Exception */ @@ -425,12 +467,13 @@ /** * Return a collection of callable objects that, when run, perform the supplied repository operations against connections in * this pool. + * * @param <T> the return type for the operations * @param operations the operations to be run using connection from this pool * @return the collection of callables * @see #call(RepositoryOperation) * @see #callable(RepositoryOperation) - * @see #callables(Collection) + * @see #callables(Iterable) */ public <T> List<Callable<T>> callables( RepositoryOperation<T>... operations ) { List<Callable<T>> callables = new ArrayList<Callable<T>>(); @@ -443,6 +486,7 @@ /** * Return a collection of callable objects that, when run, perform the supplied repository operations against connections in * this pool. + * * @param <T> the return type for the operations * @param operations the operations to be run using connection from this pool * @return the collection of callables @@ -450,7 +494,7 @@ * @see #callable(RepositoryOperation) * @see #callables(RepositoryOperation...) */ - public <T> List<Callable<T>> callables( Collection<RepositoryOperation<T>> operations ) { + public <T> List<Callable<T>> callables( Iterable<RepositoryOperation<T>> operations ) { List<Callable<T>> callables = new ArrayList<Callable<T>>(); for (final RepositoryOperation<T> operation : operations) { callables.add(callable(operation)); @@ -466,6 +510,7 @@ * Starts a core connection, causing it to idly wait for use. This overrides the default policy of starting core connections * only when they are {@link #getConnection() needed}. This method will return <tt>false</tt> if all core connections have * already been started. + * * @return true if a connection was started * @throws RepositorySourceException if there was an error obtaining the new connection * @throws InterruptedException if the thread was interrupted during the operation @@ -483,6 +528,7 @@ /** * Starts all core connections, causing them to idly wait for use. This overrides the default policy of starting core * connections only when they are {@link #getConnection() needed}. + * * @return the number of connections started. * @throws RepositorySourceException if there was an error obtaining the new connection * @throws InterruptedException if the thread was interrupted during the operation @@ -500,9 +546,11 @@ /** * Initiates an orderly shutdown in which connections that are currently in use are allowed to be used and closed as normal, * but no new connections will be created. Invocation has no additional effect if already shut down. - * @throws SecurityException if a security manager exists and shutting down this ConnectionPool may manipulate threads that - * the caller is not permitted to modify because it does not hold {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>, - * or the security manager's <tt>checkAccess</tt> method denies access. + * + * @throws SecurityException if a security manager exists and shutting down this pool may manipulate threads that the caller + * is not permitted to modify because it does not hold {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>, or + * the security manager's <tt>checkAccess</tt> method denies access. + * @see #shutdownNow() */ public void shutdown() { // Fail if caller doesn't have modifyThread permission. We @@ -548,14 +596,12 @@ } /** - * Attempts to stop all actively executing tasks, halts the processing of waiting tasks, and returns a list of the tasks that - * were awaiting execution. - * <p> - * This implementation cancels tasks via {@link Thread#interrupt}, so if any tasks mask or fail to respond to interrupts, - * they may never terminate. - * @throws SecurityException if a security manager exists and shutting down this ExecutorService may manipulate threads that - * the caller is not permitted to modify because it does not hold {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>, - * or the security manager's <tt>checkAccess</tt> method denies access. + * Attempts to close all connections, including those connections currently in use, and prevent the use of other connections. + * + * @throws SecurityException if a security manager exists and shutting down this pool may manipulate threads that the caller + * is not permitted to modify because it does not hold {@link java.lang.RuntimePermission}<tt>("modifyThread")</tt>, or + * the security manager's <tt>checkAccess</tt> method denies access. + * @see #shutdown() */ public void shutdownNow() { // Almost the same code as shutdown() @@ -608,25 +654,67 @@ if (fullyTerminated) terminated(); } + /** + * Return whether this connection pool is running and is able to {@link #getConnection() provide connections}. Note that this + * method is effectively <code>!isShutdown()</code>. + * + * @return true if this pool is running, or false otherwise + * @see #isShutdown() + * @see #isTerminated() + * @see #isTerminating() + */ + public boolean isRunning() { + return runState == RUNNING; + } + + /** + * Return whether this connection pool is in the process of shutting down or has already been shut down. A result of + * <code>true</code> signals that the pool may no longer be used. Note that this method is effectively + * <code>!isRunning()</code>. + * + * @return true if this pool has been shut down, or false otherwise + * @see #isShutdown() + * @see #isTerminated() + * @see #isTerminating() + */ public boolean isShutdown() { return runState != RUNNING; } /** - * Returns true if this executor is in the process of terminating after <tt>shutdown</tt> or <tt>shutdownNow</tt> but has - * not completely terminated. This method may be useful for debugging. A return of <tt>true</tt> reported a sufficient - * period after shutdown may indicate that submitted tasks have ignored or suppressed interruption, causing this executor not - * to properly terminate. - * @return true if terminating but not yet terminated. + * Returns true if this pool is in the process of terminating after {@link #shutdown()} or {@link #shutdownNow()} has been + * called but has not completely terminated. This method may be useful for debugging. A return of <tt>true</tt> reported a + * sufficient period after shutdown may indicate that submitted tasks have ignored or suppressed interruption, causing this + * executor not to properly terminate. + * + * @return true if terminating but not yet terminated, or false otherwise + * @see #isTerminated() */ public boolean isTerminating() { return runState == STOP; } + /** + * Return true if this pool has completed its termination and no longer has any open connections. + * + * @return true if terminated, or false otherwise + * @see #isTerminating() + */ public boolean isTerminated() { return runState == TERMINATED; } + /** + * Method that can be called after {@link #shutdown()} or {@link #shutdownNow()} to wait until all connections in use at the + * time those methods were called have been closed normally. This method accepts a maximum time duration, after which it will + * return even if all connections have not been closed. + * + * @param timeout the maximum time to wait for all connections to be closed and returned to the pool + * @param unit the time unit for <code>timeout</code> + * @return true if the pool was terminated in the supplied time (or was already terminated), or false if the timeout occurred + * before all the connections were closed + * @throws InterruptedException if the thread was interrupted + */ public boolean awaitTermination( long timeout, TimeUnit unit ) throws InterruptedException { long nanos = unit.toNanos(timeout); final ReentrantLock mainLock = this.mainLock; @@ -645,14 +733,14 @@ } /** - * Method invoked when the Executor has terminated. Default implementation does nothing. Note: To properly nest multiple + * Method invoked when the pool has terminated. Default implementation does nothing. Note: To properly nest multiple * overridings, subclasses should generally invoke <tt>super.terminated</tt> within this method. */ protected void terminated() { } /** - * Invokes <tt>shutdown</tt> when this executor is no longer referenced. + * Invokes <tt>shutdown</tt> when this pool is no longer referenced. */ @Override protected void finalize() { @@ -743,6 +831,7 @@ /** * This method is automatically called by the {@link ConnectionWrapper} when it is {@link ConnectionWrapper#close() closed}. + * * @param wrapper the wrapper to the connection that is being returned to the pool */ protected void returnConnection( ConnectionWrapper wrapper ) { @@ -786,6 +875,7 @@ /** * Validate the supplied connection, returning the connection if valid or null if the connection is not valid. + * * @param connection the connection to be validated; may not be null * @return the validated connection, or null if the connection did not validate and was removed from the pool */ @@ -814,6 +904,7 @@ * connection would violate the {@link #maximumPoolSize maximum pool size} nor does it add the new connection to the * {@link #availableConnections available connections} (as the caller may want it immediately), but it does increment the * {@link #poolSize pool size}. + * * @return the connection wrapper with a new connection * @throws RepositorySourceException if there was an error obtaining the new connection * @throws InterruptedException if the thread was interrupted during the operation @@ -829,6 +920,7 @@ /** * Close a connection that is in the pool but no longer in the {@link #availableConnections available connections}. This * method does decrement the {@link #poolSize pool size}. + * * @param wrapper the wrapper for the connection to be closed * @throws InterruptedException if the thread was interrupted during the operation */ @@ -957,6 +1049,14 @@ /** * {@inheritDoc} */ + public CachePolicy getDefaultCachePolicy() { + if (closed) throw new IllegalStateException(SpiI18n.closedConnectionMayNotBeUsed.text()); + return this.original.getDefaultCachePolicy(); + } + + /** + * {@inheritDoc} + */ public void execute( ExecutionEnvironment env, GraphCommand... commands ) throws RepositorySourceException, InterruptedException { if (closed) throw new IllegalStateException(SpiI18n.closedConnectionMayNotBeUsed.text()); this.original.execute(env, commands); Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySource.java =================================================================== --- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySource.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySource.java 2008-06-06 21:19:46 UTC (rev 244) @@ -23,7 +23,6 @@ import java.io.Serializable; import javax.naming.Referenceable; -import org.jboss.dna.spi.cache.CachePolicy; /** * A repository source is a description of a resource that can be used to access or store repository information. This class @@ -39,6 +38,7 @@ * {@link Referenceable} and {@link Serializable} so that such objects can be stored in any JNDI naming context and enable proper * system recovery, * </p> + * * @author Randall Hauch */ public interface RepositorySource extends RepositoryConnectionFactory, Referenceable, Serializable { @@ -47,6 +47,7 @@ * Get the maximum number of retries that may be performed on a given operation when using * {@link #getConnection() connections} created by this source. This value does not constitute a minimum number of retries; in * fact, the connection user is not required to retry any operations. + * * @return the maximum number of allowable retries, or 0 if the source has no limit */ int getRetryLimit(); @@ -55,14 +56,9 @@ * Set the maximum number of retries that may be performed on a given operation when using * {@link #getConnection() connections} created by this source. This value does not constitute a minimum number of retries; in * fact, the connection user is not required to retry any operations. + * * @param limit the maximum number of allowable retries, or 0 if the source has no limit */ void setRetryLimit( int limit ); - /** - * Get the default cache policy for this source. If none is provided, a global cache policy will be used. - * @return the default cache policy - */ - CachePolicy getDefaultCachePolicy(); - } Modified: trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySourceException.java =================================================================== --- trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySourceException.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/dna-spi/src/main/java/org/jboss/dna/spi/graph/connection/RepositorySourceException.java 2008-06-06 21:19:46 UTC (rev 244) @@ -70,4 +70,12 @@ return this.sourceName; } + /** + * {@inheritDoc} + */ + @Override + public String toString() { + return super.toString(); + } + } Modified: trunk/dna-spi/src/test/java/org/jboss/dna/spi/graph/connection/MockRepositorySource.java =================================================================== --- trunk/dna-spi/src/test/java/org/jboss/dna/spi/graph/connection/MockRepositorySource.java 2008-06-06 21:18:50 UTC (rev 243) +++ trunk/dna-spi/src/test/java/org/jboss/dna/spi/graph/connection/MockRepositorySource.java 2008-06-06 21:19:46 UTC (rev 244) @@ -75,9 +75,6 @@ this.retryLimit.set(limit); } - /** - * {@inheritDoc} - */ public CachePolicy getDefaultCachePolicy() { return defaultCachePolicy; } @@ -170,6 +167,13 @@ /** * {@inheritDoc} */ + public CachePolicy getDefaultCachePolicy() { + return MockRepositorySource.this.getDefaultCachePolicy(); + } + + /** + * {@inheritDoc} + */ public XAResource getXAResource() { return this.xaResource.get(); }