EZPersistence

Thank you for choosing EZPersistence. The absolute easiest way to hook your code into a database without database coding! Has transactions, finder methods, no JDBC or SQL code needed, can auto-create your schema for you, and C.R.U.D. operations through one method call.
No BS here, just jump in;

• Coding For EZPersistence
• Connecting EZPersistence To Your Database
• Looking At the Example and Setting up your application's environment
• Feature List
• Addendum
• Javadocs
• Sourceforge Project Page

Coding For EZPersistence

To make a persistent class just follow the three simple steps;

1) Make your class extend com.ezsoft.ezpersistence.BasePersistence
2) Create public variables. These variables will be the data stored in the database.
3) Make a constructor with parameter that you want to be your primary key or the main index of the object.

That's it! This is pretty much the way most Value Objects (or View Objects) work anyway. You dont have to know ANY SQL! You dont have to create ANY tables! It does it all for you! It is really ALL done for you! You write your bean and set up your database connection using the included GUI and its all handled.

This program was designed to perform C.R.U.D. operations seamlessly on java beans. C.R.U.D. operations stand for Create, Read, Update and Delete. The basic operations one would need to perform. I've also added another nifty one called find.

You can read the javadocs for BasePersistence to see a more detailed description of each of these operations. The three classes you should really look at are first Employee.java, then EmployeeGuiFrame.java to see how it uses Employee.java and then BasePersistence.java to see complete javadocs on the supported functionality for a persisted object.

The syntax for these operations are;

   Employee employee = new Employee(email.getText());
   employee.setFirstName(fname.getText());
   .....
   employee.setAge(new Integer(age.getText())));
   employee.create();

This code is from com.ezsoft.ezpersistence.gui.EmployeeGuiFrame.java. It shows how a java object is created using EZ Persistence. But you can then use the same object to perform the R.U.D. operations of C.R.U.D. by just calling;

   employee.create() // Creates a row in the database populated with the current object and it's populated fields.
   employee.read() // updates the object from database. Forced read, not from object cache. Wipes out all object data with database data.
   employee.update() // updates database with the values the object contains
   employee.delete() // deletes the current object from the database

   Employee.delete(new Employee(email.getText())); // static method to delete an object from the database
   Employee employee = (Employee)BasePersistence.getPersistenceObject(new Employee(email.getText()));    // reads the object from EZPersistence cache if it exists, otherwise, it pulls from the database

   employee.find(); // Looks at all the populated fields in your object and creates a vector of objects that match the given data.
     ie: If an Employee object is created with only the last name populated, a vector of Employee objects will be returned of all employees with the last name given.

     Employee employee = new Employee();
     employee.lastName("Lee");
     Vector employees = employee.find();
     ....
     Employee employeeFromVector = (Employee)employees.elementAt(2);  // gets the second employee from the list

There is a new feature that allows a developer to have a more feature rich find(). It was modeled after Apache's PersistenceBroker framework's Criteria object. You can now create a com.ezsoft.ezpersistence.Criteria object and populate it with criteria you wish each field to search on. If no criteria is set for a field, a literal match is done on a populated field. Criteria types can be BETWEEN, LESS_THAN, GREATER_THAN and can be applied to most data types (Dates, numbers, etc). Criteria take a list of CriteriaItem objects that each hold the field you wish to search on and the criteria type to search. The criteria types are noted above. The CriteriaItem object also has a value field that holds the second value for the BETWEEN criteria type. Here's a code example;

     Employee employee = new Employee();
     Criteria criteria = new Criteria();
     employee.setAge("21");
     criteria.addCriteria(new CriteriaItem("age", CriteriaItem.LESS_THAN));
     Vector employees = employee.find(criteria);

Here are some rules to keep in mind when coding your persitent class;
- Primary key is passed into the constructor and is NOT part of the subclass (the class you create)
- All classes that extend BasePersistence CAN create a primary key variable name;
static String PKNAME = "yourPKName"; If you do not, the database column will be named 'ID'.
If, on your constructor, you want to have the database automatically create a primary key for you (auto-indexing) then just call super(primaryKeyObject, true) where 'primaryKeyObject' is the primary key object (could be null, just needs this to get the object type).
ie:

public Employee(Integer employeeID)
{
    super(employeeID, true); super.PKNAME = "employee_id";
}

    try
    {
        Connection connection = PersistenceSystem.instance().getDefaultConnection();
        connection.setAutoCommit(false);
        Employee emp = new Employee("userid");
        emp.setFirstName("Bob");
....
        emp.create(connection);
        InsurancePolicy insurance = new InsurancePolicy(new Integer(someInsVal));
        insurance.setEmployee(emp);
        insurance.update(connection);
        connection.commit();
    }
    catch(Exception ex)
    {
        try{connection.rollback();}
        catch(Exception exc) { exc.printStackTrace(); }
        ex.printStackTrace();
    }

Connecting EZPersistence To Your Database

To hook your code into the database, just run the admin utility included in this archive. Just double click on the ezpersistence.jar file and you will see a screen like this;

Persistence Admin GUI

The administration program (double click on the jar) fills in most of the parameters needed to connect to your database. You may have to change the fields to connect to your database. In this case (the default) it is connecting to My SQL database with its default configuration installed with a username and password of persistence/persistence on a database I created called persistence. I highly reccommend this database if you do not already have one. It is very stable, fast and free! And, considering your using this program because its easy, this just makes it even easier on you. Follow this link to download My SQL.

The Admin utility creates a file called persistence.properties. This file has to be in the directory where your app runs. Considering everything we use is in jars, it should stick it in that directory. The EmployeeGui example uses this file. If your database connection is not set up properly, then the example will not work (obviously). The max number of objects in pool is the number of EZPersistence java objects (a java class that extends BasePersistence) created/read/updated. You can increase/decrease this number to tweak your performance. The number of objects to remove is the number of objects to remove from the pool at a time. These objects are removed when an EZPersistence object is created/updated/read that does not exist in the cache. Keep in mind, this is a cached read, not the employee.read() which forces a database read and overwrites the objects fields with those in the database.

EZPersistence uses the apache commons connection pooling.

To help you find what values to enter for the different fields, here are some mappings for the tested databases;

Looking At the Example

The Admin tool will create a file called persistence.properties. It has to be placed in the same directory where you run your program.

All this code can be found in the class com.ezsoft.ezpersistence.gui.EmployeeGuiFrame.java. The program that uses this class is contained in ezpersistence_x_x_x.jar. You can find the source code at the project page. To set up your application the same way you set up this example;
Include the following jars in your application's classpath

• Your database JDBC driver (unless you use odbc for something like MS Access)
• The EZ Persistence binary jar.
• The apache commons database connection pooling jars which are
  • Jakarta commons Collections
  • Jakarta commons DBCP
  • Jakarta commons Pool

Run java -jar ezpersistence_x_x_x.jar com.ezsoft.ezpersistence.gui.EmployeeGui.
You should see this screen;

Employee EZPersistence Example GUI

This screen shows many fields that are typical to most employee databases. The six buttons show many of the common features you could do to an employee database (look familiar :)). This example took me less than 2 hours to write. Almost all of that was gui work. The code is included in the file employee.jar. Two of the main files you might want to look at are Employee.java and EmployeeGuiFrame.java. Employee.java is the bean object I want to persist and EmployeeGuiFrame.java is the code that manipulates the object. The code examples given above were, more of less, from EmployeeGuiFrame.java. Just type in the employee's information and click create and it will create that employee in the database. There is no coding on your part what so ever to connect to the database. You can concentrate on business code. If the table does not exist, it will create it for you! Create a bunch of employees. Then click the clear button to wipe out the form. Type just the email of one of the employees. It updates automatically! Change just a bit of their information and click update. All that has to happen in the code is to call employee.update() and thats it! Click delete and that employee is gone from the database! Click clear again and type in a few fields that you want to search on. Then click the Find button. You will see a list of email addresses at the bottom that match your criteria. Thats the employee.find()! Just double click on any of the matches to load that employee's data! Its that easy! Beautiful thing is, it's all cached too so it's EXTREMELY fast! It uses LRU algorithms and parameters you can set up to optimize your program!

Feature List

• Persists Java objects transparently. No need to know JDBC or even SQL!
• Creates most database tables for you.
• Transactional integrity and rollbacks.
• Supports C.R.U.D. operations (Create, Read, Update, Delete)
• Flexible and easy find() method to find all objects matching given criteria.
• Administration GUI to hook into almost any database with no coding needed!

Addendum

This has been tested to work on Oracle, MS SQL Server, Access, HSQLDB, PostgreSQL and My SQL (recommended).

That said, there are some data types that do not have equivalents on particular databases. For example;
SQL Types that all databases tested may not support that map to equivalent java objects are:
Boolean=BIT, java.sql.Date=DATE, java.sql.Timestamp=TIMESTAMP, java.lang.Short=SMALLINT

The java object types supported are String, Integer, java.sql.Date, java.math.BigDecimal, Boolean, Byte, Double, Float, Long, Short, Character, java.sql.Time, java.sql.Timestamp.

Future plans;
- Additional java types
- Database Foreign keys references. In the code you can create a field that is an object that extends BasePersistence and it matches up to another table (foreign key references). And it loads transparently also.
- Use JNDI and Data Sources
- Multi object primary keys
- Empty constructors
- Remove need to extend BasePersistence but Rather implement interface.

Here is an excellent article that shows what types are supported by all databases. I used all of these in my code, and a few extras where they could be used. For example, take the object Boolean, which Oracle does not like. Oracle can use a character instead.

If you find any bugs, have any suggestions, check out the project page.
Happy coding!