README

                                 SmartPool 		
                                Version 1.1


Contents

	* Introduction
	* Installation
	* Features
	* Features expected in future releases
	* System Requirements
	* User Documentation
	* Source (not for people with object oriented MIND-SET and  
		   don't want to peek into a closed box component)
	* Java Doc			   
	


Introduction   

	 Thank you for downloading this release of 	SmartPool 1.1.
	 SmartPool is a ready to use Connection pooling component.
	 It provides much more features than a conventional connection pooling
	 component that is available on the net for free. It's basically modeled
	 on the pooling features of an Application Server provides.
	 The basic objective behind building this pooling component (I have just
	 started  it rather) is to provide an Application Server like features
	 to a web server or rather any other application which needs continuous 
	 access to the database and thus needs to maintains a pool of 
	 connections. This is just the beginning of a huge effort, 
	 and would appreciate suggestions, reporting/cribbing on 
	 bugs (No program is Bug Free until the last user is dead) and 
	 suggested modifications.

	 NOTE: 
	 This Component is for people who are familiar with the concept 
	 of connection pooling and have experienced nightmares trying to  
	 detect leaks, and connection mixing i.e. (state of the 
	 Connection being retained even after the connection is released and 
	 allocated to some other component).
	 Novices can use it, but may find it difficult to understand why some 
	 things are as the way they are.
	
	 Words from the wise:
	 The API is very easy to use, initially you might get little confused
	 but soon you will get used to the confusion.


Installation	

	 Unzip the downloaded file. I guess you have already done it, other wise 
	 you would not be reading this README.txt. 
	 You just need to put $EXTRACT_DIR/classes.jar file 
	 in your class path and you are ready to write code accessing 
	 the SmartPool API.
	 For more information on how to use it, refer to User Documentation. Before
	 using the component you need to build a XML (read Exaggerated Markup 
	 Language) file, believe me even a Pipe Delimited Configuration file 
	 would have served the purpose, but I chose to use XML because people 
	 around me said that such easy to generate/parse delimited format is no 
	 longer cool and XML is the hottest thing. To check on the syntax
	 of configuration file check the pool-config.dtd and the sample 
	 file pool-config.xml.
	 If you are not familiar with XML, don't be scared of the configuration,
	 even I am equally unfamiliar with it, edit the sample file and your job
	 is done.

Distinguishing Features 

	* Manages multiple pools
		Multiple pools with totally different configurations can be
		maintained and yet providing a Singleton single point access to 
		the pools.
		
	* Detect leaks based on configurable time-outs
		Supports detecting of connection leaks based on time-outs
		through Connection Leak Listener Interface. Along with detecting
		leaks other information such as the time at which the connection was
		obtained, owner of the connection, last accesses time, etc is provided.
		
	* Connection pool grows when the load is high, and shrinks when there are
		too many free connections by closing down excessive free connections
		thus avoiding blocking of other accesses to the database.

	* Complete monitoring of the Connection pool.  
		Well defined interfaces are provided to get the run time status of the
		connection pool such as current pool size, no of used connections, 
		status of the used connections, owners of the connection.

	* Automatic connection recovery in case of connection failures. Every
	  	connection is validated against a query specified in the
		configuration file before it is leased out to the consumer. Failed
		connection is replaced with a new connection. Three consecutive
		invalid connections results in a exception thrown to the consumer.

	* Automatic closing of associated Statements, PreparedStatements, 
		CallableStatements when a connection is returned back to the pool.
		
	* Wrap SmartPool to an existing pool such as a DataSource of an 
	  	Application server. The role of SmartPool in this case is just to
	  	provide features like leak detection, automatic closing of Statement
	  	Objects etc. SmartPool does not maintain any pool of connections, it
	  	expects the parent pool to do the pooling
	
	* Automatic rollback, if the connection is used  in a transaction	
		and returned to pool with auto-commit set to false.

	* Scalable/Flexible/Configurable (J2EE buzz words again).
		I don't know whether it is Scalable & Flexible (I thinks it is), 
		but it is certainly	configurable with almost all the above 
		mentioned features can be configured and even turned off if 
		not needed.


		
Features expected in future releases

	* Logging of time taken for database operations.
	* Hot Deployment i.e. allowing changes to be made to the pool 
		configuration without requiring to restart the JVM.
	* Support for Distributed Transactions
	* Forced recovery of least recently used connections.
	* Compliant with J2EE JDBC/pooling Specifications

System Requirements 
	
	* JDK 1.3 or higher. 
	* Sun's JAXP API for parsing the configuring the XML API.

	
User Documentation

	* $EXTRACT_DIR/doc/ 
	
Source 
	
	* $EXTRACT_DIR/source

Java Doc
	
	* $EXTRACT_DIR/doc/java_doc