jRelationalFramework

frequently asked questions

where can I find JDBC drivers to use with this framework?
why should I use this framework instead of building my own?
what is the Mozilla Public License?
what are the advantages to using this framework?
what main concepts should I understand in order to get the most benefit out of this framework?
how can I see the SQL that is generated?
how do I change the location of the jrf.properties file?
why do you put the curly braces where you do?
how does this framework know whether to insert or update?
how do I lock a row or a table?
how do I manage transactions with nontransactional databases like mysql?
how do I manage transactions involving two or more DBMS's?
who were the developers on this framework?
who/what is is.com?
is is.com hiring?

Q: Where can I find JDBC drivers to use with this framework?
A: You can search for JDBC drivers here.

Q: Why should I use this framework instead of building my own?
A: One word: Documentation. It is hard to write good framework documentation, and while this documentation maybe isn't what you always wanted, it is far better than most developers have time to write. Future maintainers of your system will thank you. The other reason is that we've taken a lot of time to make this system flexible so it can work for more than just one project. Most projects would do better to modify a flexible framework that is already written than write one from scratch.

Q: What is the Mozilla Public License?
A: This is the license that was created by Netscape when it wanted to open-source it's Netscape browser. The gist of the license is that if you distribute this product (with or without modifications), you must also distribute the source code (including all of your modifications--see the license for the definition of "modification"). Your right to the source code for this library is automatically transferred to anyone you distribute any part of this library to. See the License for the specific language governing rights and limitations under the License. We have added a convertibility option to the license so that you may use this code under the GNU GPL or LGPL if you so wish.

This is a question from a potential user:

> Instead of developing a O-R  mapping framework from
> scratch I'm wondering if we can use jRelationalFramework
> as a starting point for our development.  According to
> Mozilla Public License 1.1 we need to contribute back
> our enhancements, which could be a problem to us.

You only need to have your enhancements to jRF licensed under the MPL. The MPL is nice and specific about what constitutes an enhancement. This protects your business code which I'm sure you don't want to open-source.

There is no requirement to send your jRF enhancements to the jRF project. Technically, anyone you distribute your app to can request the source code for the relational framework, but this will likely never happen. And even if it does, all you would have to supply would be the relational framework code that fits into the MPL definition of a modification to jRF.

It's a good license for protecting the interests of the users. The GNU GPL (General Public License) is much more restrictive. Just using a GPL class can force your calling code to be GPL, but not so with the MPL. The GNU LGPL (Lesser General Public License) is better about not "infecting" calling code, but the license is still written for non-JVM programs and is open to a bit of interpretation when dealing with Java.

Q: What are the advantages to using this framework?
A: This framework can be relatively easily learned and used and it is flexible enough to let you do what needs to be done. Many relational frameworks were created with the philosophy that shielding the developer from the database is a good idea. We don't buy this. Developers need to be able to understand SQL and the database schema in order to create applications that perform sufficiently well.

Q: What main concepts should I understand in order to get the most benefit out of this framework?
A: A stab at a short list is as follows:

JDBCHelper - How to create, when to reuse, how to reuse.
postFind() method -- when to create a domain with the NO_POST_FIND option.
preValidate(), preSave(), postSave(), preDelete(), postDelete().
validate()

how to turn off validation. (hint: put this.setValidateOnSave(false); in the setup() method)
What types of validation are done? (unique attribute, required attribute)

Table joining, when to use the different types:

use a JoinTable instance when you want to include extra columns in your object.
use a custom join when you just want to limit the instances returned.

Current Timestamp for the current date and time.
Optimistic Locking.

Q: How can I see the SQL that is generated?
A: Look at the file called log4j.properties at the base of the distribution tree. Look for the JDBCHelper.willExecute category line that looks like this:
log4j.category.JDBCHelper.willExecute=something

To see the SQL, make sure that DEBUG is where the something is above. You could also put DEBUG, StdOut if the JDBCHelper category that this inherits from does not have StdOut. DEBUG tells log4j the priority of log messages that you want to print, and StdOut is the appender you want the messages to go to. Visit http://www.log4j.org to get a more complete understanding of how to configure the log processing with Log4j.

Q: How do I change the location of the jrf.properties file?
A: If you are using the JDBCHelperFactory and JRFProperties classes you can change the location of the jrf properties file by adding a JVM parameter like this: -DjrfPropertiesFile=com.myco.pkg1.myapp (where the file is called myapp.properties in the com.myco.pkg1 package). It's important that the disk file has a suffix of .properties since the java.util.ResourceBundle class won't be able to find the file otherwise.

Q: I've looked at the code. Why do you put the curly braces where you do?
A: Studies have shown that lining up curly braces makes Java code much easier to comprehend. We have found that to be the case in our company as well, especially when trying to make sense out of another developer's code. We use Emacs as our IDE which does a nice job of automatically formatting the code for us so we don't even have to think about it.

Q: How does the framework know whether to insert or update?
A: PersistentObject (the superclass of all objects stored or retrieved by the framework) stores a state object. Objects with a NewPersistentState are inserted, objects with a ModifiedPersistentState are updated, and objects with a CurrentPersistentState do neither. The methods hasModifiedPersistentState(), hasNewPersistentState(), and hasCurrentPersistentState() on PersistentObject will tell you which persistent state the object is in.

Q: How do I lock a row or a table?
A: There is no pessimistic locking built in to the jRelationalFramework. Consider using optimistic locking in your database and system design. JRF has good support for this built into the framework for either version number or timestamp type optimistic locks.

Q: How do I manage transactions with non-transactional databases like MySQL?
A: You can't (unless you use the newer MySQL BDT table types).

Q: How do I manage transactions involving two or more DBMS's ?
A: Unless your backend RDBMS has explicit support for this (e.g. Oracle synonyms) that allow you to do this through a single JDBC connection you won't be able to do this. In JRF a JDBCHelper is the abstraction that wraps/hides a JDBC connection. Transactions that involve multiple databases spanning more than one JDBC connection would require the use of an external transaction monitor in any environment.

Q: Who were the developers on this project?
A:The primary developer is Jonathan Carlson (joncrlsn). Others who contributed pieces are Tim Dawson, Craig Laurent, and CJ Hurst.

Q: Who/what is is.com?
A: We is the coolest company this side of the Mississippi -- OK, so we're biased. We specialize in creating heavy-duty web applications using Java, UNIX, and Microsoft web technologies. We are a wholly-owned subsidiary of Wam!Net. We are located in Eagan, Minnesota, a southeast suburb of Minneapolis and St. Paul. Much of our work is done at our facilities here in Eagan where we have a foosball table, darts, shower, and a full refrigerator.

Q: Is is.com hiring?
A: We often are. Contact us at careers@is.com. We'd love to talk to you!