How to use cascading operations

Up to Castor 1.3.1, users of Castor JDO have been able to automatically store/update or delete objects across relations by issueing ...

Database.setAutostore(true)

before going starting a transaction. This feature was useful, indeed, but on a second look its limitation (global definition across all entities) became obvious, especially on big projects. You might want to have cascading operations activated selectively (activated for one object, but not for another). Or even more tricky, you might like to automatically track changes across one relation from a starting object, but but not across another relation from the very same object.

As of Castor 1.3.2, a new cascading attribute has been introduced to the <sql> tag of the JDO mapping file.

This and all other cascading documents address people familiar with the basic concepts of mapping domain entities to database tables and defining relations between objects (on database level as well as on object level). But in particular, this document applies to the following user groups:

1. Everyone who wants to cascade operations across (any type of) object relation(s).

2. Everyone who now uses Database.setAutoStore(boolean) to have persistence operations cascaded across relations.

Note

Especially the second user group should change their approach towards using cascading operations, and switch to using the new cascading attribute. As of Castor 1.3.2, the current Database.setAutoStore(boolean) methods will be deprecated, and in the long run, this operations will be removed from the JDO interfaces.

You should have a valid mapping file, containing at least two objects, being in relation with each other. For the remainder of this document, we'll be using the following example mapping file as a starting point.

<mapping>
  <class name="org.castor.cascading.Author" identity="id">
    <cache-type type="none" />
    <map-to table="OneToOne_Author" />
    <field name="id" type="integer">
      <sql name="id" type="integer" />
    </field>
    <field name="timestamp" type="long">
      <sql name="time_stamp" type="numeric" />
    </field>
    <field name="name" type="string">
      <sql name="name" type="char" />
    </field>
  </class>
  <class name="org.castor.cascading.Book" identity="id">
    <cache-type type="none" />
    <map-to table="OneToOne_Book" />
    <field name="id" type="integer">
      <sql name="id" type="integer" />
    </field>
    <field name="timestamp" type="long">
      <sql name="time_stamp" type="numeric" />
    </field>
    <field name="name" type="string">
      <sql name="name" type="char" />
    </field>
    <field name="author" type="org.castor.cascading.Author">
      <sql name="author_id"/>
    </field>
  </class>
</mapping>

In order to activate cascading for create operations for the author relation defined in the mapping file above, you have to add the following attribute to the field mapping of the author property:

<class name="org.castor.cascading.one_to_one.Book" identity="id">
   <cache-type type="none" />
   ...
	
   <field name="author" type="org.castor.cascading.one_to_one.Author">
      <sql name="author_id" cascading="create"/>
   </field>
</class>

Remember that the code above adding a cascading attribute with a value of create is only an example. You can define any combination of cascading attributes, delimiting those values by spaces, as shown in the following example:

<field name="author" type="org.castor.cascading.one_to_one.Author">
   <sql name="author_id" cascading="create update"/>
</field>

In order to achieve an optimal granulation of activating and de-activating functionality, there are 5 possible values, out of which 3 can be activated separately or in any combination.

In general, what you have to keep in mind is that some cascading types do not only affect the the (coincidentally) identically named database operation, but also other persistence operations. For more details please read the following references carefully.

If no cascading attribute is defined, its default value will be none.