jRelationalFramework version 2.0

getting started

faq

tutorial

advanced

examples

jRF and EJB

javadoc api

license

sourceforge

feedback:
  user comments
  join mailing list
  submit a bug
  submit a patch

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: 

• 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 the application.
• Compound primary key tables - multiple columns make up the primary key.
• 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 a table).
• Finding of a portion of persistent instances that match an application-specific criteria.
• 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 constraints).
• 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 supported. more

• 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, HypersonicSQL , 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 of the 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 http://www.mozilla.org/MPL/

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.
• Erik Tennant - Contributed features, helped commit bug fixes and tested Jays code on Oracle.
• Jonathan Carlson - Original author of the 1.x versions.