Version 1 docs
jRF and EJB
join mailing list
submit a bug
submit a patch
| The first official beta for version 2 is now available.
There are a lot of changes and improvements. The release
notes and upgrade instructions are
This free java SQL framework is intended to abstract out the
SQL database code so the important business logic doesn't get lost in the
trivial and distracting database access code. Taking a little time
to learn to use it will pay off in simpler database code that is easier to
maintain and understand.
This framework is not intended to completely shield the developer
from needing to understand basic SQL constructs. It is a lightweight
framework that was written to automate the most tedious 80% of relational
database access coding and leave the other 20% to the developer. If
we attempted to automate the last 20%, the size of this framework would
grow dramatically... not to mention the fact that "java coders love
to code" -- so if we removed all the coding involved it wouldn't be any
fun to learn and use.
The Standard Behaviors provided by this framework are:
Behaviors not directly supported (However, most of these can
be done with custom code in the domain subclass):
- Object-to-relational mapping for:
- Sequenced primary key tables - the primary key is assigned
by the framework (with help from the database).
- Natural primary key tables - the primary key is assigned by
- Compound primary key tables - multiple columns make up the
- Use either PreparedStatements or regular Statements.
- Insertion of a new object instance into the database.
(In other words: Insertion of a new row into a table).
- Updating of existing object instances.
- Deleting of existing object instances.
- Finding of persistent instances by primary key.
- Finding all persistent instances. (Finding all rows in
- Finding of a portion of persistent instances that match an application-specific
- Augmentation of persistent object instances with columns from
other tables (Joining of tables).
- Aggregation - creation of multiple objects from one result set.
- Flexibility to define custom SQL queries for specialized searches.
- Database independent validation of objects based on the metadata
defined in the AbstractDomain subclass. (i.e. REQUIRED and UNIQUE field
- Database independent defaulting of attribute values when updating
and selecting from the database.
- Optimistic locking of an object/row using a Timestamp or Integer
column. When conflicts occur, an ObjectHasChanged exception is thrown
by the framework.
- Linking of related objects at retrieval time through the use
of a postFind() method.
- Plenty of "hooks" by which you can customize your object before
saving, after saving, after finding, etc...
- Compatible with database triggers that change the tables.
- Generation of basic PersistentObject and AbstractDomain subclasses
from an existing database (using the jrf-extras jar).
- Connection pooling (Either via the included JDBCHelperPool or
via your application server pooling).
- (As of version 1.7) Supertype/Subtype tables are now
- Primitive field datatypes (int,float,boolean,etc.) are not supported
by the framework. Only the Object wrappers of these (Integer,Float,Boolean,etc.)
are supported. Primitives do not fit with the very important object-oriented
concept of polymorphism. (That is, each type of primitive has to be treated
specially. While this could be done, it would add too much complexity
to the code and hence decreases the maintainability). However, as long
as you have Object wrapper field getters and setters you can do whatever
you want with primitives inside the PersistentObject subclass.
- Updating of columns from a joined table. It is necessary
to update the joined table through its own AbstractDomain subclass or else
add custom update code.
- Multi-column uniqueness validation is not directly supported,
but could be added in a later release.
- BLOBs (Binary Large OBjects) -- This is something that is currently
being looking into (April 2001).
This framework has been tested on Oracle, Sybase/SQLServer,
, and InstantDB
, and MySQL
. It supports these through the use of the DatabasePolicy interface.
This interface defines methods that return database-specific information.
It is a relatively simple task to support another ANSI-compliant
database by implementing this interface. If you do,
please share it
This framework has been very effectively used in Session
beans in a couple of EJB applications built by is.com.
See the short white-paper
that covers some of what we have learned about scalable EJB architectures.
Also see the September 2000 issue of JavaReport (p. 98) for an article
that describes a technique similar to this. The jRF solution combines the
best features of the first two solutions presented while removing or minimizing
their inherent disadvantages.
EJB/J2EE patterns - jRelational Framework is an implementation
Data Access Object
pattern. While jRF can be used for Bean-Managed-Persistence, it is
better used from a Session Bean because it populates and returns lists
of Value objects.
This framework requires Java 2 (JDK 1.2) or higher
since it uses Lists, Iterators, and Maps instead of Vectors, Enumerators,
and Hashtables. If you must use this with JDK1.1, then you would need to
convert these in the source.
This code is subject to the
Mozilla Public License Version 1.1
(the "License"); you may not use this code except in compliance with
the License. You may obtain a copy of the License at
Contributors - if we missed you, please
let us know
Software distributed under the License is distributed on
an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied.
See the License for the specific language governing rights and limitations
under the License. This library has an option for you to convert the
license to the GNU GPL or LPGL.
- Jay Evans
- Refactored and added lots (an understatement) for version 2.
- Contributed features, helped commit bug fixes and tested Jays code
- Jonathan Carlson
- Original author of the 1.x versions.