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.
BANKBRANCHDESC	varchar(512)	The bank branch description.
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.

To create your database tables, you can follow this how-to guide.

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<entityname>.java.

Creating CRMDOBankBranch.java

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, description, createdByUser, updatedByUser, createdByUnit, updatedByUnit, createdDate, updatedDate, isDeleted and recVersion properties are inherited from com.crm.dataobject.CRMDO super 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

CRMDOBankBranch.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="512"
	>
		<meta attribute="field-description">
			@hibernate.property
			column="BANKBRANCHDESC"
			length="512"
		</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.cfg.xml

<hibernate-configuration>
    <session-factory>
		...
		<mapping resource="com/crm/dataobject/accounts/CRMDOBankBranch.hbm.xml" />
		...
    </session-factory>
</hibernate-configuration>

To continue implementing the model layer, go to Developing the Business Objects

CRM.COM Development

Developing the Data Objects

Creating the Data Object Classes

Mapping the Data Object Classes

Creating Hibernate Mapping Files

Hibernate Configuration File