How to use cascading operations

# How to use cascading operations

## Overview

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

      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.

## Intended Audience

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.

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.

## Prerequisites

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>

## Use of the cascading attribute

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>

## Values for the cascading attribute

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.

- create: details on create operation

- delete: details on delete operation

- update: details on update operation

- none: cascading operations are disabled.

- all: Using the value `all`, you are providing a shortcut specifying that all three basic operations should be defined at the same moment. This basically equals to a value of `'create delete update'`.

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

## References

- JDO Mapping