Define Relationships

Cascade options

In an association, it is cumbersome to apply an action performed on object to the other object. For example, in case of an Department-Employee one-to-many association, if you add an employee, the same change needs to be updated on the Department as well. The cascade option in Hibernate allows you to perform such operations.

You can specify the following values in the cascade attribute:

• all: Allows you to apply all operations to be cascaded to the associated object.

• save-update: If the parent object is saved, the associated objects are saved as well.

• delete: Deletes the child object if the delete operation is called on the parent object.

• delete-orphan: This is a special kind of cascade option that applies to one-to-many relation only. Deletes all child objects for which the association has been removed.

• all-delete-orphan: Cascades all operations to child objects, and performs delete-orphan action.

• refresh: Cascades the refresh action to the child object. The refresh action is used to reload an object and its collections.

Typically, cascade attribute is not used on a many-to-one or a many-to-many relationship.

You can also specify comma separated cascade values in the cascade attribute. For a one-to-one or a one-to-many relationship, the most common values are all-delete-orphan.

For an association where the child object can continue to exist even if the parent object is deleted, you can apply the save-update cascade value.

Applying filter on associated objects

In one-to-many and many-to-many relationships, an array or struct is retrieved. Filters can be applied to retrieve a subset of the associated objects. The filter can be specified in the where attribute, which is an SQL where clause. In a one-to-many association for artist and artwork:

<cfproperty name="unsoldArts" cfc="Art" fieldtype="one-to-many" fkcolumn="ARTISTID" where="issold=0">

Inverse

In a bidirectional relationship, the inverse attribute is used on an association property to specify whether an SQL query should be executed for the association, when persisting the object.

Consider the ART and ARTIST CFCs, which have a bidirectional one-to-many relationship. This means that each ART object has a reference to the ARTIST object and ARTIST object has a reference to the ART object. While persisting ARTIST and the associated ART, the relationship can be established in the database from both sides of the object. Setting inverse=true on one side of the relation tells ORM to ignore this side of relation for executing the SQL.

As a general rule, in a bidirectional relation, one side must set inverse to true. For one-to-many or many-to-one relation, inverse should be set on the many side of the relation. For example, in ARTIST-ART relation, inverse should be set to true on the 'art' property in ARTIST.

In many-to-many relation, you can set inverse=true on any side of the relation.

Primary key association

In this type of association, the primary key of one table references to the primary key of another table. That is, both the tables share the same primary key.

The following example shows how to define this mapping.

Example

Consider the EMPLOYEE and OFFICECUBICLE example. Both the tables share the same primary key. The mapping for these tables are as follows:

• EMPLOYEE.cfc

  <cfcomponent persistent="true" table="Employee"> 
      <cfproperty name="id" fieldtype="id" generator="native"> 
      <cfproperty name="firstname"> 
      <cfproperty name="lastname"> 
      <cfproperty name="officecubicle" fieldtype="one-to-one" cfc="OfficeCubicle"> 
  </cfcomponent>

• OFFICECUBICLE.cfc

  <cfcomponent persistent="true" table="OfficeCubicle"> 
      <cfproperty name="id" fieldtype="id" generator="foreign" params="{property='Employee'}" ormtype="int"> 
      <cfproperty name="Employee" fieldtype="one-to-one" cfc="Employee" constrained="true"> 
      <cfproperty name="Location"> 
      <cfproperty name="Size"> 
  </cfcomponent>

  fieldtype=one-to-one specifies that the property is a one-to-one property.

  constrained=true on Employee property in OFFICECUBICLE.cfc, means that a constraint is set on the OFFICECUBICLE table for its ID to reference the ID in the EMPLOYEE table.

  The ID of EMPLOYEE table is auto-generated. The ID of the OFFICECUBICLE table should be the same as the ID of the Employee table. For this, set generator="foreign". Foreign generator takes one parameter 'property' as input, which should be the relationship property name of OFFICECUBICLE entity which is 'EMPLOYEE' in this case.

  Here, primary key values of related rows in both the tables must be the same. The identity generator algorithm in the mapping for the component (whose mapped table has the constraint), must be set to foreign.

Unique foreign key association

In this type of association, the foreign key of one table references the primary key of another table, and the foreign key column has a unique constraint. To define this relationship, fkcolumn attribute should be specified on the relationship-property of the CFC whose table contains the foreign key column. The other end of relation should use mappedby attribute.

<cfproperty 
name="fieldname" 
fieldtype="one-to-one" 
cfc="Referenced_CFC_Name" 
linktable="Link table name" 
linkcatalog="Catalog for the link table" 
linkschema="Schema for the link table" 
fkcolumn="Foreign Key column name" 
inversejoincolumn="Column name or comma-separated list of primary key columns" 
mappedby="Mapped_Field_name_in_referenced_CFC" 
cascade="none" 
fetch="join|[select]" 
lazy="[true]|false">

Example

In the EMPLOYEE and OFFICECUBICLE example, OFFICECUBICLE has a foreign key column, EMPLOYEEID. This foreign key references the primary key of the Employee table. OFFICECUBICLE has an auto-generated primary key, which does not participate in the relationship.

EMPLOYEE.cfc

<cfcomponent persistent="true" table="Employee"> 
    <cfproperty name="EmployeeID" fieldtype="id" generator="native"> 
    <cfproperty name="firstname"> 
    <cfproperty name="lastname"> 
    <cfproperty name="officecubicle" fieldtype="one-to-one" cfc="officecubicle" mappedby="Employee"> 
</cfcomponent>

OFFICECUBICLE.cfc

<cfcomponent persistent="true" table="officecubicle"> 
    <cfproperty name="id" fieldtype="id" generator="native"> 
    <cfproperty name="Employee" fieldtype="one-to-one" cfc="Employee" fkcolumn="EmployeeID"> 
    <cfproperty name="Location"> 
    <cfproperty name="Size"> 
</cfcomponent>

In this case, OFFICECUBICLE entity has a independent Primary key which is auto-generated.

Array

An Artist object can contain the Art objects as an array. To define this mapping in the CFC, use the following syntax:

Syntax

<cfproperty 
name="field_name" 
fieldtype="one-to-many" 
cfc="Referenced_CFC_name" 
linktable="Link table name" 
linkcatalog="Catalog for the link table" 
linkschema="Schema for the link table" 
fkcolumn="Foreign Key column name" 
inversejoincolumn="Column name or comma-separated list of primary key columns " 
type="array" 
orderby="order_by_string" 
cascade="cascade_options" 
lazy="[true]|false|extra" 
fetch="join|[select]" 
inverse="true|[false]" 
batchsize="N" 
optimisticlock="[true]|false" 
readonly="true|[false]">

For the artist-art example, the relationship property in Artist.cfc is defined as follows:

<cfproperty name="art" type="array" fieldtype="one-to-many" cfc="Art" fkcolumn="ARTISTID">

• type-array specifies that the artist object will contain art objects in an array.

• fkcolumn="ArtistID" specifies that the foreign key column is ARTISTID that references the primary key of ARTIST table.

Struct

An Artist object can contain the Art objects as a struct. The key would be any column in the ART table (usually the primary key or a unique key). The value would be the Art object. To define this mapping, use the following syntax.

Syntax

<cfproperty 
name="field_name" 
fieldtype="one-to-many" 
cfc="Referenced_CFC_name" 
linktable="Link table name" 
linkcatalog="Catalog for the link table" 
linkschema="Schema for the link table" 
fkcolumn="Foreign Key column name" 
inversejoincolumn="Column name or comma-separated list of primary key columns" 
type="struct" 
orderby="order_by_String" 
structkeycolumn = "Structure_Key_Column" 
structkeytype="ormtype" 
cascade="cascade_options" 
lazy="[true]|false|extra" 
fetch="join|[select]" 
inverse="true|[false]" 
batchsize="N" 
optimisticlock="[true]|false" 
readonly="true|[false]">

For the artist-art example, you can define the relationship property as:

<cfproperty name="art" type="struct" fieldtype="one-to-many" cfc="Art" fkcolumn="ARTISTID" structkeytype="int" structkeycolumn="ArtID">

• type=struct specifies that the artist object will contain art objects in a struct.

• structkeycolumn="ArtID" specifies that the key of the struct would be ArtID.

  Note that ARTID is the primary key in Art table.

• structkeytype="int" specifies the datatype of structkeycolumn.

• fkcolumn="ArtistID" specifies that the foreign key column is ARTISTID that references the primary key of Artist table.

Syntax

<cfproperty 
name="fieldname" 
fieldtype="many-to-one" 
cfc="Referenced_CFC_Name" 
linktable="Link table name" 
linkcatalog="Catalog for the link table" 
linkschema="Schema for the link table" 
fkcolumn="Foreign Key column name" 
inversejoincolumn="Column name or comma-separated list of primary key columns" 
column="Foreign_Key_Column" 
mappedby="Mapped_Field_name_in_referenced_CFC" 
cascade="cascade_options" 
fetch="join|[select]" 
lazy="true|false" 
insert="[true]|false" 
update="[true]|false" 
optimisticlock="[true]|false" 
missingrowIgnored="true|[false]">

For the art-artist example, the relationship in the ART.cfc can be defined as:

<cfproperty name="artist" fieldtype="many-to-one" fkcolumn="artistid" cfc="Artist">

fkcolumn="ARTISTID" indicates that the foreign key column in Art table references the primary key ARTISTID of ARTIST table.

Syntax

Order.cfc

<cfproperty 
name="fieldname" 
fieldtype="many-to-many" 
cfc="fully qualified name" 
linktable="Link table name" 
linkcatalog="Catalog for the link table" 
linkschema="Schema for the link table" 
fkcolumn="Foreign Key column name" 
inversejoincolumn="Column name or a composite key with comma-separated primary key columns" 
mappedby="Property in the target component that is referenced by fkcolumn in join table" 
type="[array]|struct" 
orderby="order by String 
structkeycolumn="The structure key column name" 
structkeydatatype="datatype". 
cascade="cascade options" inverse="true|[false]" lazy = "[true]|false" [optional] fetch="join|[select]" [optional] batchsize="integer" optimisticlock="[true]|false" readonly="true|[false]" 
missingrowIgnored="true|[false]">

For the Order-Product example, the many-to-many relationship is established using a third table "OrderProduct" that has two foreign keys: OrderId and ProductId. OrderId references the primary key orderId in the order table, and ProductId references the primary key productId in the Product table. This relationship can be defined as follows:

• Order.cfc

  <cfproperty 
  name="products" 
  fieldtype="many-to-many" 
  CFC="Product" 
  linktable="Order_Product" 
  FKColumn="orderId" 
  inversejoincolumn="productId" 
  lazy="true" 
  cascade="all" 
  orderby="productId">

• Product.cfc

  <cfproperty 
  name="orders" 
  fieldtype="many-to-many" 
  CFC="Order" 
  linktable="Order_Product" 
  FKColumn="productId" 
  inversejoincolumn="orderId" 
  lazy="true" 
  cascade="all" 
  orderby="orderId">

  The fkcolumn here is the foreign key in the link table that references the primary key of the source table.

  InverseJoinColumn is the foreign key in the link table that references the primary key of the target table. This attribute can also take a composite key value, for example you can specify inversejoincolumn=”field1, field2”, where field1 and field2 form the composite key.