V I L L A G E
=============


What is it?
-----------
Village is a 100% Pure Java API that sits on top of the JDBC API. The purpose 
of this API is to make it easier to interact with a JDBC compliant relational database. 
By using Village, it is possible to execute and manage 
select/insert/update/delete SQL statements without having to actually write 
a single line of SQL. Village can use any valid JDBC Connection object, so it 
is possible to use Village with a JDBC Connection pool. 

This software is being freely released under an Apache 1.1 Style license. Please see 
docs/LICENSE.txt in the distribution for more information.


Why the name Village?
---------------------
A Village is an interface to the database. The huts are the tables and the 
people are the rows.


History
-------
Village is inspired by the dbKona API documents available on BEA/Weblogic's website
<http://weblogic.beasys.com/>.

The BEA WebXpress product is an excellent piece of software and it is highly 
recommended that you purchase it.


How to use it
-------------
Documentation included with Village is extremely thin at this point. Although, 
there is comprehensive documentation of dbKona on the BEA/Weblogic website. 
All of the methods in Village are lightly documented in the javadoc format. There 
is also some example code in the javadoc for TableDataSet and QueryDataSet.

Please also refer to the com.workingdogs.village.Test*.java class for some 
other examples of code. 


Support
-------
The Village website is at: <http://www.working-dogs.com/village/>

Please subscribe to the Village mailing list by sending email to:
  
  village-on@list.working-dogs.com
 
You can post messages by sending email to:
  
  village@list.working-dogs.com
  
You can remove yourself from the list by sending email to:
  
  village-off@list.working-dogs.com

I will do my best to provide timely replies to the mailing list, bug fixes 
and updates to this software, but in /no way/ should you ever contact 
BEA/Weblogic asking for support with Village. If you want them to support 
you, then purchase their software and maintence contracts. 


How to get the latest version from CVS
--------------------------------------
It is possible to use CVS (concurrent version control) in order to get 
the latest version of this software at any time. In order to do this, 
you need to set your CVSROOT to:

  :pserver:anon@cvs.working-dogs.com:/products/cvs/external

Use the password: "anon" when prompted for a password during login.

It is also possible to browse the CVS via CVSWeb:
  
  <http://www.working-dogs.com/external/>


Frequently Asked Questions

Why is the package name com.workingdogs.village 
instead of com.working-dogs.village?
-----------------------------------------------
Because for some reason, Sun decided that package naming conventions should 
conform to domain names for which the package originated. But, they did not 
consider the fact that domain names can contain a "-" in it and made that 
an illegal character in package names. Arrrggg...


Could you tell me the difference between Village and SQLJ?
Why should/would I choose your API over an ANSI standard?
From what I have read at http://www.oracle.com/java/sqlj/index.html
I dont see why you are creating your own standard.
-----------------------------------------------

SQLJ might be an ANSI standard, but who said that screwing up Java
standards is right? SQLJ requires a pre-compiler to convert
your .sqlj files into .java files. Hello? javac doesn't have a
pre-compiler for a reason! How can you reliably do rapid java
development if you have to first run your pre-source code through
something that munges it into something else?

Also, I'm not creating my own standard, Village is inspired by the
dbKona API that WebLogic/BEA developed for use with their WebXpress
product. WebLogic/BEA's product is the number one java application server in
use today. I think that point alone justifies the creation of this API.

Lastly, this API is easy to use and easy to learn. It will save you 
hours worth of typing as well as help prevent you from making countless 
mistakes. The PreparedStatement handling alone makes using this API worth it.
