Each data object (DO) represents a record in the database, that means that for every table in the database, there is a data object class. CRM.COM software uses Hibernate, a data persistence framework used to retrieve and persist data to the database.
What does this section cover?
In the following example, we will create and map a data object class for the table BANKBRANCHES.
BANKBRANCHES table
| Column Name | Data Type | Description |
|---|
| BANKBRANCHID | varchar(32) | The primary key. |
| BANKID | varchar(32) | The related bank. Foreign Key to BANKS table. |
| BANKBRANCHNAME | varchar(256) | The bank branch name. |
| BANKBRANCHALTCODE | varchar(32) | The bank branch alternative code. |
| BANKBRANCHDELETED | integer | The deleted flag. Note that records are not physically deleted but marked as deleted. |
| RECVERSION | integer | The record version number. This number is increased every time the record is updated. |
| BANKBRANCHCREATEDBYUSERID | varchar(32) | The user that created the record. Foreign key to USERS table. |
| BANKBRANCHUPDATEDBYUSERID | varchar(32) | The user that updated the record. Foreign key to USERS table. |
| BANKBRANCHCREATEDBYOUUID | varchar(32) | The user's unit that created the record. Foreign key to OUUNITS table. |
| BANKBRANCHUPDATEDBYOUUID | varchar(32) | The user's unit that updated the record. Foreign key to OUUNITS table. |
| BANKBRANCHCREATEDDATE | timestamp | The date the record was created. |
| BANKBRANCHUPDATEDDATE | timestamp | The date the record was updated. |
Creating the Data Object Classes
All data objects should be placed under com.crm.dataobject.* named packages, extend either com.crm.dataobject.CRMDO or one of its subclasses and follow this naming convention: CRMDO<classname>.java.
Creating CRMDOBankBranch.java
package com.crm.dataobject.accounts;
import java.util.Set;
import com.crm.dataobject.CRMDO;
/**
*
* table="BANKBRANCHES"
*
*/
public class CRMDOBankBranch extends CRMDO {
private static final long serialVersionUID = 1L;
private CRMDOBank bank;
private Set<CRMDOPaymentPreference> paymentPreferences;
public CRMDOBank getBank() {
return bank;
}
public void setBank(CRMDOBank bank) {
setChange("bank", this.bank, bank);
this.bank = bank;
}
public Set<CRMDOPaymentPreference> getPaymentPreferences() {
return paymentPreferences;
}
public void setPaymentPreferences(Set<CRMDOPaymentPreference> paymentPreferences) {
setChange("paymentPreferences", this.paymentPreferences,
paymentPreferences);
this.paymentPreferences = paymentPreferences;
}
public static long getSerialversionuid() {
return serialVersionUID;
}
}
For each database field, a java property is defined. In some cases, transient fields might also exist. All the properties must be defined as private variables, and for each property, two accessor methods should be created: a getter and a setter method. In the setter methods of the persistent fields, setChange method (implemented in com.crm.dataobject.CRMDO) must be called in order to mark the specific field as modified and track its changes.
Note that id, name, altCode, createdByUser, updatedByUser, createdByUnit, updatedByUnit, createdDate, updatedDate, isDeleted and recVersion properties are defined in com.crm.dataobject.CRMDO class.
Mapping the Data Object Classes
Hibernate is used by CRM.COM to map a defined class to a database table and its properties to the table's fields.
Creating Hibernate Mapping Files
Hibernate Mapping files should always have the following format: <classname>.hbm.xml
<?xml version="1.0"?>
<!DOCTYPE hibernate-mapping PUBLIC
"-//Hibernate/Hibernate Mapping DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-mapping-3.0.dtd" >
<hibernate-mapping default-access="field">
<class
lazy="true"
name="com.crm.dataobject.accounts.CRMDOBankBranch"
table="BANKBRANCHES"
>
<meta attribute="class-description" inherit="false">
@hibernate.class
table="BANKBRANCHES"
</meta>
<meta attribute="extends" inherit="false">com.crm.dataobject.CRMDO</meta>
<cache usage="read-write" />
<id access="property"
name="id"
type="java.lang.String"
column="BANKBRANCHID"
>
<meta attribute="field-description">
@hibernate.id
generator-class="assigned"
type="java.lang.String"
column="BANKBRANCHID"
</meta>
<generator class="assigned" />
</id>
<version
name="recVersion"
type="java.lang.Integer"
column="RECVERSION"
access="property"
unsaved-value="undefined"
>
<meta attribute="field-description">
@hibernate.property
column="RECVERSION"
length="10"
</meta>
</version>
<many-to-one
name="createdByUser"
class="com.crm.dataobject.users.CRMDOUser"
not-null="true"
>
<meta attribute="field-description">
@hibernate.many-to-one
not-null="true"
@hibernate.column name="BANKBRANCHCREATEDBYUSERID"
</meta>
<column name="BANKBRANCHCREATEDBYUSERID" />
</many-to-one>
<many-to-one
name="updatedByUser"
class="com.crm.dataobject.users.CRMDOUser"
not-null="true"
>
<meta attribute="field-description">
@hibernate.many-to-one
not-null="true"
@hibernate.column name="BANKBRANCHUPDATEDBYUSERID"
</meta>
<column name="BANKBRANCHUPDATEDBYUSERID" />
</many-to-one>
<many-to-one
name="createdByUnit"
class="com.crm.dataobject.networkmanagement.CRMDOUnit"
not-null="true"
>
<meta attribute="field-description">
@hibernate.many-to-one
not-null="true"
@hibernate.column name="BANKBRANCHCREATEDBYOUUID"
</meta>
<column name="BANKBRANCHCREATEDBYOUUID" />
</many-to-one>
<many-to-one
name="updatedByUnit"
class="com.crm.dataobject.networkmanagement.CRMDOUnit"
not-null="true"
>
<meta attribute="field-description">
@hibernate.many-to-one
not-null="true"
@hibernate.column name="BANKBRANCHUPDATEDBYOUUID"
</meta>
<column name="BANKBRANCHUPDATEDBYOUUID" />
</many-to-one>
<property
name="createdDate"
type="java.sql.Timestamp"
column="BANKBRANCHCREATEDDATE"
length="23"
>
<meta attribute="field-description">
@hibernate.property
column="BANKBRANCHCREATEDDATE"
length="23"
</meta>
</property>
<property
name="updatedDate"
type="java.sql.Timestamp"
column="BANKBRANCHUPDATEDDATE"
length="23"
>
<meta attribute="field-description">
@hibernate.property
column="BANKBRANCHUPDATEDDATE"
length="23"
</meta>
</property>
<property
name="isDeleted"
type="java.lang.Integer"
column="BANKBRANCHDELETED"
length="10"
>
<meta attribute="field-description">
@hibernate.property
column="BANKBRANCHDELETED"
length="10"
</meta>
</property>
<many-to-one
name="bank"
class="com.crm.dataobject.accounts.CRMDOBank"
not-null="true"
>
<meta attribute="field-description">
@hibernate.many-to-one
not-null="true"
@hibernate.column name="BANKID"
</meta>
<column name="BANKID" />
</many-to-one>
<property
name="name"
type="java.lang.String"
column="BANKBRANCHNAME"
length="256"
>
<meta attribute="field-description">
@hibernate.property
column="BANKBRANCHNAME"
length="256"
</meta>
</property>
<property
name="altCode"
type="java.lang.String"
column="BANKBRANCHALTCODE"
length="32"
>
<meta attribute="field-description">
@hibernate.property
column="BANKBRANCHALTCODE"
length="32"
</meta>
</property>
<property
name="description"
type="java.lang.String"
column="BANKBRANCHDESC"
length="32"
>
<meta attribute="field-description">
@hibernate.property
column="BANKBRANCHDESC"
length="32"
</meta>
</property>
<set
name="paymentPreferences"
lazy="true"
inverse="true"
cascade="none"
>
<meta attribute="field-description">
@hibernate.set
lazy="true"
inverse="true"
cascade="none"
@hibernate.collection-key
column="BANKBRANCHID"
@hibernate.collection-one-to-many
class="com.crm.dataobject.accounts.CRMDOPaymentPreference"
</meta>
<key><column name="BANKBRANCHID" /></key>
<one-to-many class="com.crm.dataobject.accounts.CRMDOPaymentPreference" />
</set>
</class>
</hibernate-mapping>
To map a variable, the <property> element is used.
- The name attribute is used to specify the property name.
- The column attribute is used to specify the table column the property is mapped on.
- The type attribute is used to specify the variable type.
- The length attribute is used to specify the length of the specific table column.
In case we have a many-to-one relation with another table, the <many-to-one> element is used.
- The name attribute is used to specify the property name.
- The <column> element is used to specify the foreign key.
- The class attribute is used to specify the related class name.
In case we have a collection of objects defined in our class, the <set> element is used.
- The name attribute is used to specify the property name.
- In the <one-to-many> element, the related class is specified.
- In the <key> element the related table column that references the current table is specified.
.
<id> and <version> elements are used to map the primary key and the version properties of the java class. Through the version property, Hibernate can provide optimistic locking.
Hibernate Configuration File
Hibernate Configuration file (hibernate.cfg.xml) is used for defining all the hibernate mapping files. During the application's initialization process, hibernate reads this configuration file and maps the classes defined, to the database tables.
<hibernate-configuration>
<session-factory>
...
<mapping resource="com/crm/dataobject/accounts/CRMDOBankBranch.hbm.xml" />
...
</session-factory>
</hibernate-configuration>
For more information on creating custom data object classes, go to Customise Existing Business Logic.
To continue implementing the model layer, go to Business Objects