|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## How to use cascading operations

Overview
Intended Audience
Prerequisites
Use of the cascading attribute
Values for the cascading attribute
References

## Overview

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.

## 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.

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.

## 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

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>