Domain model description options
- int, double, string, blob, clob fields
- fields with multiple values
- hard linked records (normal db links)
- field values can be limited (choices) either statically (xml description) or programmatically (validation)
- for removing records cascade-delete, cascade-keep (don't delete when there are references to the record) or normal null all references behaviour can be used
- field (type) templates can be used
- powerful proxies are used which make objects available remotely. Similar to detached objects, but completely transparent (no need to instantiate)
- lazy collection instantiation, when a selector contains lots of objects, the results are still batched (and counting works too)
- inheritance sensitive selectors
As a bonus, when your client only uses the proxies, it is straightforward to replace the backend (this way the data could for example be based on webservices instead of EJB3 entity beans).
How the domain model is generated
A whole set of classes are being generated. To handle the inheritance, the inheritance tree is flattened and a "root-table" is created which contains all fields, actions, selectors for all the tables in the inhertance tree. When is distinction needs to be made, this is handled in the code.
The preferred way to access the data is through the proxies. These have names which equal the names of the root tables and allow remote access to the data, the selectors and actions while hiding the details of looking up beans etc. They are built to transparently instantiate fields when required.
Alternatively, you can access the data though a set of session beans for each root table. One is the /ObjectSelectorBean/ which is stateless and allows executing the selectors which are defined. The second is the /ObjectBean/ which is a stateful session bean faÃ§ade for the entity bean. To make accessing these beans slightly easier, there is a /EquandaGlobal/ class which (amongst other things) allows you to retrieve the beans.
For constraint checking a smart set of intermediate classes called "mediators" are used. These are built in such a way to assure the declarative constraints can be handled and updated when the generation is re-run, but constraints added by manual coding are also maintained. For this a /MediatorRoot/ is used to start by constraining all access (nothing allowed). Then for each class there is a /MediatorBase/ which contains the declarative constraints and a /Mediator/ which is supposed to be filled in by the used and contains the programmatic constraints.
This results in the following classes. The classes you are most likely to use/need are indicated in bold. Where a name contains "Object" this should be replaced with the table name.
- LazyEJBList.java : lazy list with beans, generated to allow package private access to some methods.
- LazyProxyList.java : lazy list with proxies, generated to allow package private access to some methods.
- ObjectUpdater.java : used internally for updating the proxies.
- EquandaGlobal.java : utility class which allows getting instance of the beans, and some extra utility methods including access to the base selector EJBQL qeries.
For each root table
- ObjectSelectorBean.java : stateless session bean, allows access to the selectors
- ObjectBean.java : stateful session bean, providing access to the entity bean with all the constraints checking through the mediators
- DMNameBean.java : ejb3 entity bean
- ObjectSelectorEJB.java : selector bean interface
- ObjectEJB.java : (remote) interface for the ObjectBean
- ObjectEJBLocal.java : local interface for the ObjectBean
- ObjectState.java : the proxy state, use internally in the proxy to allow updating without replacing the actual proxy
- ObjectMediatorRoot : root of the mediator object tree,
- ObjectConstants : contains the constants like type identifiers and possibe values for choice fields
- ObjectSelectorHelperBase : base for the ObjectSelectorHelper
- ObjectSelectorHelper : allows code to be inserted for the builders.
- DMObjectSelector : class for handling selections at the entity bean level
- ObjectBase : shared interface between ObjectEJB and ObjectEJBLocal
For each table
- ObjectMediatorBase : contains the programmatic constraints
- ObjectMediator : empty file, should be used for programmatic constraints and defining the actions
- ObjectType : type handling and testing
- ObjectTypeChoice : validator to possible types
For each multiple field
- DMObject_FieldBean : entity bean which represents the multiple field values
They are generated in three different packages, of which you define the prefix using the following settings in "dm.ini".
Note that the "package" setting is commented. WHen both settings are specified they should be equals or you will get compilation problems. However the ejb3 package setting defaults to the "ejb-package" setting in the "extra" section.
- /prefix/.client : contains all the classes which may be required for remote access to the data.
- /prefix/.server : contains the classes which should only be available inside the application server. The client does not need access to these.
- /prefix/.server/dm : separate package for the ejb3 entity beans (which are server-side only).
Customizing the generated domain model
Generated database structure
All table and field names have prefixes.
Tables names :
- T_x : normal table; details can be found in table "x" in the domain model.
- M_x_y : multiple field, definition can be found in the table "x", the field "y".
- L_x_y : link table, for the link defined in table "x", the field "y". Table "x" is the owner side of the link.
All fields which are defined in the domain model have "F_" as prefix.
The following fields are additionally defined :
- EQUANDA_UOID Char(14) NOT NULL : a db-wide unique key which is use to link records together, has to be 14 characters in length
- EQUANDA_TYPE Char(4) : type indicator. In the portfolio product this is always ' ' (four spaces). For tables with have templates (inheritance) this makes a distinction between the instance used. The value is defined in the table definition as the "type" attribute.
- EQUANDA_MODIFIED Timestamp : timestamp of mast modification
- EQUANDA_VERSION Integer default 0 NOT NULL : record version number, incremented on each change, used for optimistic locking
- EQUANDA_STATUS Char(1) : status flag for the record. This is usable for bulk/batch export. On each change in the record, the field is set to "M".
- EQUANDA_CREATION Timestamp : timestamp of record creation
- For tables representing multiple fields :
- EQUANDA_UOID Char(14) NOT NULL : db-wide unique key for this record, has to be 14 characters in length
- EQUANDA_CREATION Timestamp : timestamp of record creation
- EQUANDA_PARENT_UOID Char(14) : key for the record this value belongs to.
- F_y : actual field value, "y" if the field name (as from "M_x_y")
- x_UOID Char(14) NOT NULL : "x" is the table name (as from "L_x_y"), key for the record on the owner side of the link, in table "x"
- F_y_UOID Char(14) NOT NULL : key for the other side of the link, for field "y"