Read Me

Stronghead - a lightweight persistence framework
------------------------------------------------

What it is
==========

Stronghead is a simple persistence framework implemented in Java. I did it as a
part of a student research project. So it's intention is to show others how one
could develop a framework in general and a persistence framework in particular.

It's simple and therefore very easy to use with applications in need of simple
persistence mechanisms. Since it's small compared to other more extensive
solutions, it's also easy to understand.


Prerequisites
=============

Java SDK 1.5 or higher
MySql Server 4.x or higher


Technical Details
=================

The package contains a very small example application, which uses the
framework. It's two classes in a n-m relationship demonstrating the frameworks
ability to handle relation tables automatically.

In the current implementation it uses the MySql database servers (version 4.x or
higher) InnoDB engine. If some other database should be used, only the
DBConnection class must be partly rewritten or replaced. The catalogs name,
server, port and drivers name are configured via a properties file.

Stronghead features Transactions. In this context it also provides completely
transparent timestamp based row locking, so that it's impossible to write
outdated data to a row. Connection pooling is also realised.

There's a logger and an ExceptionHandler included, so if something doesn't work
as expected no erros get lost.

The creation of SQL-statements is semi-automatic. Every persistent class has to
provide some methods, that create appropriate statements. To make this as easy
as possible a class called SQLFactory could be used. It provides methods which
could create SQL based on parameters.

The framework is not thread save though.


Project Structure
=================

There are two parts to the project:

1. The actual software licensed under the terms of the Gnu General Public
License v3 (GPL). See http://www.gnu.org/licenses/gpl.html for further
information.

2. The documentation licensed under the Creative Commons Public License
(CCPL) Attribution-Noncommercial-No Derivative Works 3.0. See
http://creativecommons.org/about/license/ for further information. It consists
of some models and a seminar paper in german language. Since Sourceforge didn't
want to host the documentation, it's hosted on our site:
http://velian.de/doc/stronghead.pdf
http://velian.de/doc/stronghead-figures.pdf


Test the example application
============================

To test the example just execute the stronghead.jar located in the "impl"
directory. You need a running MySql Server and a database account. The catalog
(database) will be created automatically by the example. Please create a new
account with your MySql server for that purpose. You need to put that
information (host, port, user, password, database driver) in a "db.properties"
file. You'll find an example in software/properties/db.properties.


Make it work with you own project
=================================

To use Stronghead as a framework in you Java projects simply add the
stronghead.jar located in the "software" directory to you project and make sure
the "properties" folder containing the "db.properties" is located in the same
directory as the Jar.


Author
======

Daniel Rogowski
d.rogowski@velian.de
www.velian.de