RimuDB Logo
Database Access Framework for Java

Basic Operations


Once the configuration is complete, database tasks can be performed.

Connecting to the Database

Create an instance of CompoundDatabase, passing the compounddatabase.xml filename and a boolean to prevent validating the XML, and connect using the database-id defined in that file.


CompoundDatabase cdb = new CompoundDatabase("/myapplication/compounddatabase.xml", false);
cdb.connect("database-id", "userid", "password");


The CompoundDatabase contains context information for connecting to any of the databases defined in the configuration file. An application typically only ever creates one CompoundDatabase.

Many of the classes in the framework will accept a CompoundDatabase as a parameter, but sometimes a specific database is required. To get a particular database, there are two methods: retrieval by ID, or retrieval by a data object class.


// Retrieval by ID
Database testDatabase = compoundDatabase.getDatabase("database-id");

// Retrieval by DO class
Database otherDatabase = compoundDatabase.getDatabase(OrderTransactionDO.class);


Inserting a record

By creating a xxxDO record with the CompoundDatabase (or Database) constructor, the framework will expect that you will be inserting a new record when the commit() method is called.


OrderTransactionDO orderTransaction = new OrderTransactionDO(compoundDatabase);
orderTransaction.setOrderNr(12345);
orderTransaction.setName("test1name");
orderTransaction.setValue("test1value");
orderTransaction.commit();


Reading records

One of the xxxFinder class's primary purposes is to retrieve records from the database table.

It is common to retrieve a record by primary key, so when the Finder is created, a special find() method is generated that has parameters matching the primary key of the underlying table.


// Reading the primary key
OrderTransactionFinder finder = new OrderTransactionFinder(compoundDatabase);
OrderTransactionDO orderTransaction = finder.find(12345);
System.out.println("somecolumn="+orderTransaction.getSomeColumn());

For access of records by other keys, search() methods are used. Some basic search() methods are provided in the Finder class when it is initially generated.

There are two ways of constructing queries: Use a WhereList or a Generic Query. WhereLists can be used to construct simple queries, whereas there are no limitations for GenericQueries. WhereLists have the advantage of strictly controlling the where clause of an SQL statement that is created. This means that at compile time you can insure the SQL statement contains valid column names, operators and type safe values.

A WhereList is a list of property names, comparison operators and associated values. These names and values are then converted to column names and an SQL where clause like the following is built: where column1 = ? and column2 = ? and column3 = ?. A prepared statement is created and the values substituted.


// Reading records that match a Wherelist
WhereList wherelist = new WhereList();
wherelist.add(OrderTransactionDO.F_LAST_NAME, Operator.EQ, "Smith");
wherelist.add(OrderTransactionDO.F_FIRST_NAME, Operator.EQ, "John");
OrderTransactionDO[] orderTransactions = finder.search(wherelist, null);

// SQL Generated:
SELECT * FROM order_transactions 
WHERE last_name = ? AND first_name = ?

The order by clause can be defined with an OrderByList.


// Reading records that match a Wherelist
WhereList wherelist = new WhereList();
wherelist.add(OrderTransactionDO.F_LAST_NAME, Operator.EQ, "Smith");
wherelist.add(OrderTransactionDO.F_FIRST_NAME, Operator.EQ, "John");
OrderByList orderByList = new OrderByList();
orderByList.add(OrderTransactionDO.F_CUSTOMER_NR);
OrderTransactionDO[] orderTransactions = finder.search(wherelist, null);

// SQL Generated:
SELECT * FROM order_transactions 
WHERE last_name = "Smith" AND first_name = "John"
ORDER BY customer_nr

By default multiple conditions in a WhereLists uses an AND boolean operator, but if needed, an OR operator can be specified.


// Reading records that match a Wherelist
WhereList wherelist = new WhereList();
wherelist.add(OrderTransactionDO.F_LAST_NAME, Operator.EQ, "Smith");
wherelist.add(BooleanOperator.OR, OrderTransactionDO.F_FIRST_NAME, Operator.EQ, "John");
OrderByList orderByList = new OrderByList();
orderByList.add(OrderTransactionDO.F_CUSTOMER_NR);
OrderTransactionDO[] orderTransactions = finder.search(wherelist, null);

// SQL Generated:
SELECT * FROM order_transactions 
WHERE last_name = "Smith" OR first_name = "John"
ORDER BY customer_nr

For simple queries, WhereLists and OrderByLists are a simple, type-safe means of constructing the query. However, sometimes queries have to be more sophisticated. In that case, the GenericQuery class can be used to represent any SQL select statement.


Updating a record

By retrieving the xxxDO from a finder, the framework will expect that if you call the commit() method on the xxxDO instance, then you will be updating that record.


OrderTransactionFinder finder = new OrderTransactionFinder(compoundDatabase);
OrderTransactionDO orderTransaction = finder.find(12345);
orderTransaction.setValue("Some other value");
orderTransaction.commit();


Deleting a record

Deleting a record can be done two different ways. If the record was returned from a finder, then simply calling the xxxDO.delete() method will remove it from the database. Calling the Finder.delete() method will perform the delete without having to first read the record. Deleting by primary key is common, so when the Finder is created, a special delete() method is generated that has parameters matching the primary key of the underlying table.


OrderTransactionFinder finder = new OrderTransactionFinder(compoundDatabase);
OrderTransactionDO orderTransaction = finder.find(12345);
orderTransaction.delete();

Or

OrderTransactionFinder finder = new OrderTransactionFinder(compoundDatabase);
OrderTransactionDO orderTransaction = finder.delete(12345);