Cascading Policy

Cascading is used to customize how your ORM interacts based on the needs of your business requirements. Onyx supplies several options on how to cascade your data. Here are a few examples.

Policy Description


Persist relationship entity upon invoking a save. This will leave the related entity alone when deleting. It will however remove the relationship reference without persisting the related entity.


When deleting an entity, the related entities will be deleted. The expected response may be different when working to a To Many relationship rather than a To One. When removing an entity from a relationship list, the cascade will not occur. Cascade Delete will only occur when deleting an entity.


Includes both CascadePolicy.SAVE and CascadePolicy.DELETE policies.


There may be times when batch insertion of entities is required. The Defer Save Cascade Policy can help improve the performance of batch persistence. This will tell the Persistence Manager to ignore related entities and their relationship references upon saving. You can later invoke the PersistenceManager.saveRelationshipsForEntity method to perform the relationship association.


When persisting entities, the relationships are ignored.

In this tutorial you will learn how to defer the cascading of relationship data. This is not a typical workflow but, it will showcase the flexibility of the cascade policy.

There are more examples that illustrate how the Cascade Policy impacts the data model and persistence:


  1. Define an entity and its relationship.
    For relationship actors, we have defined a cascade policy of CascadePolicy.DEFER_SAVE
  2. Create some test data including a movie and several actors.
    When you save the movie entity, the relationships are not persisted.
    This feature was created in order to save time that it takes to persist thousands of records.
    In order for the saveRelationshipsForEntity to have an impact you must save all of the entities prior to setting up the relationship.
  3. Verify the actors were not associated to the movie
    The relationship actors should return with a count of 0.
  4. Save relationship data for the movie Star Wars.
    Using the saveRelationshipsForEntity method you can batch associate relationships.
    The saveRelationshipsForEntity method requires a Set of entity identifiers.
  5. Fetch the entity and view its relationships
    There should be 2 actors associated to the movie.
  6. Fetch Policy