Defining Domain Objects

All Domain Objects must extend DalObject. The DalObject provides a getter and setter for the primary key (a member called pk). If also provides an equals() method and a hashCode() method, both based on the primary key and optionally on business keys (See below).

The Primary Key and Business Keys

The primary key of all domain objects is an Integer object. This is done to force you to use surrogate keys.

Surrogate keys are replacement keys for a business key. A surrogate key has no meaning. It's just a number. If you give it a meaning it ceases to be a surrogate key and becomes a business key. Examples for giving this key a meaning could be: using it for ordinance, imposing rules on the key like making it bigger or lower than certain values, or making any reference to the key other than using it to locate objects by their primary key.

While the infrastructure can only impose that the primary key be an Integer, it cannot enforce this integer not having a meaning. It is up to you to do it. If you don't, someone who knows what he is doing will have to deal with you.

If your design makes references to primary keys that are incompatible with this system, then the design must be changed.

Business keys, however, are not an obscene word. It is perfectly fine for an application to define business keys.

A business key is a unique non-nullable identifier of any data type for an object. In simple words a business key can uniquely identify an object just like the primary key.

Though the business key may be of any data type it is encouraged that the key be composed of as simple data types as possible (preferably primitives), and consist as little fields as possible.

To define a business key use the @BusinessKey annotation. For example:

 @BusinessKey
 @Column(length = 255, nullable = false, unique = true)
 public String getName() {
   return name;
 }

The @BusinessKey annotation may appear on fields or methods. It is encouraged that you use it over methods. (In fact, some features of the framework will not operate correctly in this version when field-level business keys are used).

Good Practices

• The domain object sould be as simple as possible.
• Even though it is not a requirement, the domain object should have the same name of the table it relates to (translated into camel case).
• Try to avoid complicated relationships if possible.
• Try to avoid multiple cascades if possible.
• Use named queries - write all your queries in the domain object if possible. This will allow the DAO to activate them.

Programming Conventions

• All domain objects should be placed in a package called: net.sf.shineframework.XXX.dal.dm whereas XXX is the name of your project.