SimpleORM

See the white paper for a detailed description of what SimpleORM does and why it is good.

README.html describes how to build SimpleORM and contains information about the current release.

The website is www.SimpleORM.org which contains current information. (A local copy is at ../../webSite/index.html).

Note that most non public declarations have package scope, not private scope. This includes instance variables. Further, the simpleorm jar is not sealed. This means that if you do need to hack SimpleORM you can generally create a new class within the simpleorm.core package with appropriate static methods, and thus not need to change the SimpleORM classes themselves. Of course this is not supported, and make sure you let us know what you did so that we can incorporate the changes into the main package.

The following image contains provides an overview of SimpleORM's internal classes which may prove useful.

Design Issues

Old, Obsolete Design notes follow

Relationship to SimpleORM

• No references, just scalar values.  No lazy fetch.
  
• No SProperty lists etc. for meta data.  SRecord|FieldMeta just have ordinary field variables to store information about them.
• No fancy logic to select some but not all fields etc.  (But I actually need this for my non-relational database.)
  

• Generating correct DDL queries on the different databases.
• DQuery interface, but keep it simple and rely on rawClauses for non-trivial cases.  (The vast majority of queries are simple.) 
  (No separate SPreparedStatement interface, just the DQuery one.)
  
• Optimistic locking.
  
• DML Create table statements, with all the ugly data type problems.
• Generating record numbers.
• Threadlocal connection access.
• ValidateRecord/Field hooks.
  

Sub-Record Types

Issues

Identity is key question

• Requires map of all records/primary keys within a dataset.  Fairly easy to do.
  
• No Subrecords.  Or tricky partial record update logic.
• APIs, local and remote.  hmm.
  Employee.Swiggle(DeptId) vs.
  Employee.Swiggle(DeptRecord)
• Multiple instances of a record in different states -- the external, internal, temporary, permanent, previous...
• Thus no automatic flushing.  The caller needs to explicitly call Update, Delete etc.

How could a multi record business rule be written with no identity?

• Just read the extra Department record redundantly as needed.
  Simple.  Inefficient.  May be stale (need to update db often).
  
• Insist that Department record is passed in manually as a simple field.  Messy.
  
• People don't write rules like this in practice.  But we want them to be able to.  It is precicely what makes a data oriented application sing.
  

What would it look like to add DataSet/Identity to identity less core?

With 1.5 annotations, should we just use conventional reflection?

SimpleData as an Application API

Miscellaneous Thoughts

• "Adaptor" does know about DRecord structures and also DQuery structures.
  
• No DResultSet, just iterators.  Implementing the adapors becomes needlessly messy.
  
• Sub Relational adaptors
• Rewrite of SimpleORM ok, really a new product.
• Adaptor/Database == Connection.  No need for separate Statement object BECAUSE adaptor knows about record structures.
• For relational, thread local connection etc. separate.  "Session" better term?
  

Related Work

JDBC

SimpleORM

Hibernate

ADO.Net -- SQLDataReader

ADO.Net -- SQLDataSet

/* Performance:-  Creating 100K records with 5 string fields each
* ArrayList: 6 us/rec
* LinkedHashMap: 10 us/rec
* Both negligible, RDBMS reads at best 1ms/rec.
*/

SPropertyMaps are essentially a hash map of SPropertys and their correspondign values. Properties mainly describe SFields, such as whether they are a primary key.

However, unlike basic Java properties SProperties support dynamic inheritance of values from property list to another. In particular, default values of user inteface objects can be placed on SFields and inherited by UI objects.

Further, because the keys are SProperty objects, they can provide intelligent default values based on calculations.

A SPropertyValue object simply stores a property and a value. They are used to make the SField definitions more elegant.

See SPropertyTest for an example of how they are used.

See the white paper for information on how SimpeORM.org uses them.

Note that although these classes were writen for use by SimpleORM, they have no dependency on it.

SimpleORMGenerator provides a simple way of generating the SimpleORM class files for an existing database. Since SimpleORMGenerator uses the meta data extracted from the database the class files produced should exactly match the database's schema.

Every table produces two class files, a base class that contains the field definitions and a public class that extends the base class.

Example given table EMPLOYEE

The Employee_base class is defined as package private, which means that it can't be seen from outside of the package. All interaction to the database table has to pass through Employee and therefore through any business rules that you add.

The base class is regenerated every time SimpleORMGenerator is run, while the public class is only generated if it does not exit. This allows you to edit the pubic class to your hearts content and still be easily update your classes with any changes made to the database.

SimpleORMGenerator produces getters and setters for every field in the table. As these methods are creates automatically there is no method maintenance is required. Having getters and setters makes it easy to insure that the correct data type is passed to a field at compile time instead of runtime.

Example

SimpleORMGenerator does generate code that uses SFieldReference fields to represent foreign keys. This is because SfieldReference fields represent links between tables in a conceptual model of the database. Trying to re-engineer these conceptual links from a physical model has not proved very successful. The mapping is complex and it appears that SimpleORM may contain a number of bugs in this area.

To get around this problem SimpleORMGenerator uses a simple solution - getters and setters for reference fields.

Example (simplified)

One side effect of this approach is that if the classes are to generate database tables, the foreign keys between tables will be lost. The pay off is that there is no type casting required when getting a record!

SimpleORMGenerator creates a set of static FindOrCreate methods for the classes. These are far simple to use that provided by the meta object as the parameters are implicitly defined.

Example

If a foreign key appears in the primary keys of the table then additional FindOrCreate method will be generated with the foreign key as one of its parameters

Example

SimpleORMGenerator uses a version of adapter pattern to allow uses to implement their own field name strategy. When running SimpleORMGenerator a class that implements interface simpleorm.quickstart.IniceNameFormatter. This class can then implement the required field naming algorithm. See simpleorm.quickstart.SimpleORMNiceNameFormatter for an example.

The required system properties must be set. Create an instance of SimpleORMGenerator and then call the execute() method. Or do what I do and simply edit the code in the main() method!

JSTL Gotchas Checklist

• No >taglib> declaration. Tags such as &lgt;c:foreach...> are then silently ignored, but their contents are still output in the gnerated HTML.
• Missing Bean property get method, eg. getColor(). If your lucky you'll get a message, else HTML generation is just mysteriously aborted. (It needs the method, not just the field.)

The main focus is to relate UI properties such as data types, validation, and prompts to the simpleORM properties.

Only Embryonic at this stage. See the white paper for information on how SimpeORM.org uses them.

Note that although the ui package uses the core package the core package have no dependency on the ui package.