3. Architecture

This chapter has two goals. First, it explains the architecture of the library itself, and then it shows a few architectures in which the library can be used, ranging from simple applications to enterprise front-end applications.

3.1 Framework Architecture

The following image is a general overview of the BeanKeeper framework:

As a caller, one can access the Store class, and it's methods (save(),remove(),find()). If there are multiple datasources in an application, each can have it's own Store object, but usually there is only one datasource (or database) in an application, so usually there is only one Store instance. All methods invokable through this class are thread-safe, so a single instance is enough for the whole runtime (for a single data source). It is possible to instantiate many instances of a Store class for the same datasource (same database), for example in a load-balanced environment, or failover architectures (see diagrams below).

The TransactionTracker object can be accessed through the Store object. The tracker manages Transaction objects, which themselves contain the Connection to the physical database. Transactions have the usual methods for transaction demarcation, but also, they implement the Map interface. This is useful if you want to add data to the transaction itself, for example the user who is manipulating data. If a locking exception occurs, the exception will contain the Transaction which accesses the object currently, so by getting for example the user object from the Transaction itself, you can create a meaningful message, or tell the other user to hurry up with her work.

The LockTracker object is also published through the Store. This tracker can be used to lock objects, so other threads or other nodes can not modify the object. The save() and remove() operations of the Store all lock an object before it is processed, so if an object is locked by some code, no operations can take place on that object except query.

There are a few internal modules which are not directly accessible:

• The Class Tracker keeps all classes and their schema in memory, and also their subclass/superclass relations. If a new class enters the system through the Store, the Class Tracker determines whether to create the appropriate table, or whether to alter an existing table.
• The Object Tracker tracks object instances. The object tracker keeps a weak reference to all objects, and keeps also all related information on them, such as last known attribute states, as well as the identities themselves.
• The Cache contains the most recently used queries and their results.
• The Query Parser is a LALR(1) parser (and a compiler), which transforms the string queries into an object model, which will be transformed back to the specific sql dialect of the database by the lower level database implementations.
• The Serial Tracker is responsible for assigning unique, date based serial numbers for transactions, and data manipulations. This serial is used to version objects, and as such must be coordinated with other nodes which act on the same database.
• The Database subsystem contains abstractions of data access, and specific implementations for different databases, so generic database operations can be applied to all kinds of database servers.
• The Node Subystem is responsible for keeping connected to other nodes who use the same database. This is necessary, because some operations, as getting serials, locking and state-related operations must be coordinated with all nodes, so that no conflicts happen. The connections are plain network connections, and the protocol is object serialization based.

The lowest layer of the library is the Database access layer itself. The task of this layer is to offer an abstraction over sql, to use by the above layers. All database manipulations are categorized into a few operations:

• Save
• Insert
• Remove
• Schema check
• Search

Before these abstract operations delegate the work to the appropriate, database specific implementation, some basic transformations take place. All table and attribute names are checked, that they do not exceed the maximum length supported by the database implementation, and that they do not match some database reserved word. If they do, they are abbreviated or renamed, and the new name will be noted, so all subsequent references to the specific identifier is always renamed the same way.

3.2 Usage Architectures

This section describes some example architectures of different applications, and the library's place in them. Of course, you are free to create your own model, these are just the most common ones.

3.2.1 Standalone Application

In this case, the most straightforward way to use the library is to let it persist the beans of your object/data model, and use those same beans (queried from the library, and saved by the library) on the user interface. Even if you employ a strict MVC (Model-View-Controller) model, the beans can traverse the whole stack without re-packaging and without affecting the separation.

The best way to guarantee, that only a single instance of the Store will be used, you should use the singleton programming pattern.

3.2.2 Webapplication With Direct Database

This is very similar to the standalone application case. The difference is, that the Controller and View roles are now replaced by different technology (Servlet/JSP, or other web framework). The usage is the same though, the preferred way is to use the simple beans to communicate between each layer. The persistence library does not care, if an object leaves or re-enters the controller layer, or if it returns at all. If an object is read from the database, that object is tracked throughout it's lifetime, regardless, whether it stays in the same transaction, or goes out to be rendered on a webpage. The same is true for result lists. Result lists can leave the transaction they were created in, or re-enter into a different transaction, it does not matter, so no special care needs to be taken when handling data received from or sent to the persistence library.

As before, the Store object should be a singleton though.

3.2.3 Web Container Managed Datasource

Most web applications do not handle their JDBC driver directly, but the web container (application server) handles and pools connections for them, and it publishes a DataSource object through JNDI. You can construct the Store object with a DataSource object, in which case the architecture of the web application will be something like this:

3.2.4 Web Container Managed Datasource with Multiple Servers

Commonly, webapplications are deployed on a cluster, or are load-balanced, using multiple application servers, and a single database server (or a database server cluster, but with a single entry point). In this case, there needs to be multiple Store objects instantiated in different JVMs to support this architecture (one in each application server). BeanKeeper will in this case automatically detect, that more than one Store objects (also called Nodes in this case) are connected to the database, and will connect to these Nodes to coordinate the work.

This document was generated by Robert Brautigam on November, 21 2009 using texi2html 1.78.