Manual

Persism Manual

Getting started

Download Persism here and add it your project.

Using the Query Object

Persism uses a standard Connection object so all you need to do is Create the object passing in the Connection.

Query query = new Query(connection);

With the query object you can then run queries to retrieve lists of objects:

List<Customer> list = query.readList(Customer.class,"select * from Customers where name = ?", "Fred");

Note that generics are in place here. If you try reading a list of a mismatched type, you'll get a compiler error. Note also that the query follows the best practice of using parametrized queries. You can specify any number of parameters you like and you can also use stored procedures instead of query strings.

You can also read a single object with a query string like this:

Customer customer = new Customer(); 
query.readObject(customer, "select * from Customers where name = ?", "Fred");

This method returns true if the customer was found. Note you do this by pre-instantiating your object first. This allows you to control memory usage of your objects and you can re-use the same object if you need to run multiple queries.
You can also quickly initialize an Object from the database by specifying the Object's primary key. This way you do not need any SQL statement.

Customer customer = new Customer();
customer.setCustomerId(123); 
query.readObject(customer);

Again this method returns true to indicate the object was found and initialized.
The query object also contains methods to read primitive Java types by simply using them directly.

String result = query.read(String.class, "select Name from Customers where ID = ?", 10);

Objects may also be refreshed if you you have situations where an object is updated in the database by a different user.

Customer customer = new Customer();
customer.setCustomerId(123);
query.read(customer); // initializes object from the primary key

customer.setSomething("vlah");
query.read(customer); // resets the customer object by reading it again by primary key

Using the Command Object

The Command object is similar to the Query in that it uses a standard Connection for its constructor but unlike the Query, The Command object is used for performing updates to the database (updates, inserts and deletes).

Command command = new Command(connection);

To perform an operation simply use the appropriate method.

Customer customer = new Customer();
customer.setCustomerId(123);
customer.setCustomerName("Fred");
customer.setAddress("123 Sesame Street");

command.insert(customer);

customer.setCustomerName("Barney");
command.update(customer);

command.delete(customer);

Persism will use the primary keys for the update and delete methods and will set the primary keys for you if they are generated when you do an insert. Persism will usually auto-discover the primary keys so you usually do not have to specify them in your Data Object. Persisms will also set defaults to properites if they were not defined and there's a default defined for that mapped column in the database.

Writing Data Objects (POJOs)

Persism follows the usual JavaBean convention for data objects. In most situations a simple POJO class is all you will need.

Example Customer
Persism uses annotation in situations where it can't discover the mapping for you.
Persism uses the following annotations for the class:
Table - used to specify the table name in the database.
Query - used to specify that this class represents the result of a query. Ie there is no single table associated with it.

Persisms uses the following annotations for properties:
Column - used to specify the column name and whether or not the column is primary and/or generated. The 3 parameters are optional.
NoColumn - used to specify that this property has no matching column. Ie that it's a calculated value and not read from the database.
You can specify these annotations on the class field or on the getter or setter. Note that NoColumn is not required if your property has a getter only. Persism understands that a read-only property would not be in the database.

You might want to peruse how Persism uses [MappingRules] to map tables and columns to your classes.