Each data object 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.
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. |
| 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 the USERS table. |
| BANKBRANCHUPDATEDBYUSERID | varchar(32) | The user that updated the record. Foreign key to the USERS table. |
| BANKBRANCHCREATEDBYOUUID | varchar(32) | The user's unit that created the record. Foreign key to the OUUNITS table. |
| BANKBRANCHUPDATEDBYOUUID | varchar(32) | The user's unit that updated the record. Foreign key to the 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 and extend com.crm.dataobject.CRMDO.
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
*.hbm.xml files are used to map a defined class to a database table and its properties to the table's fields.
<?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>
As you can see, there is an element in the mapping document for each one of the class variables.
To map a variable, the <property> element is used.
- The name attribute is used to specify the class variable 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 that specifies the length of the specific table column.
In the case we have a many-to-one relation with another table, the <many-to-one> element is used.
- The <column> element is used to specify the foreign key.
- The class attribute to specify the related class name.
In the case we have a collection of objects defined in our class, the <set> element is used.
- The <one-to-many> element specifies the relation with the other class.
- The class attribute to specify the related class name.
The hibernate configuration file
The last step of the mapping process is to let somehow the Hibernate framework know which classes should map. This is done by specifying the location of the mapping XML document in the hibernate.cfg.xml configuration file.
<hibernate-configuration>
<session-factory>
...
<mapping resource="com/crm/dataobject/accounts/CRMDOBank.hbm.xml" />
...
</session-factory>
</hibernate-configuration>
During the application's initialization process, hibernate reads this configuration file and maps the classes defined to the database tables.
To continue implementing the model layer, go to Business Objects