org.sormula.annotation.cascade

Annotation Type OneToManyCascade

@Retention(value=RUNTIME)
 @Target(value=FIELD)
public @interface OneToManyCascade

Cascade annotation for a one to many relationship between source row and target row. Insert, update, and delete cascades default to standard primary key operations. Select cascade must be defined since SelectCascade.sourceParameterFieldNames() are not known by default. For more complex cascade relationships, use Cascade.

More than one operation is allowed per field even though it is not likely that you would need more than one. selects(), updates(), inserts(), deletes(), and saves() accepts arrays which allow an empty array to mean "do nothing".

OneToManyCascade is the default for non-static, non-transient fields that are Collection, Map, or array. For example:

   public class SomeParent
   {
        @Column(primaryKey=true)
       int someParentId;

       List<SomeChild> someChildList; // defaults to  @OneToManyCascade
       ...
   }
   
   // equivalent to
   public class SomeParent
   {
        @Column(primaryKey=true)
       int someParentId;
       
        @OneToManyCascade
       List<SomeChild> someChildList;
       ...
   }
   
   public class SomeChild
   {
        @Column(primaryKey=true)
       int someChildId;
       int someParentId; // required foreign key name must be same as parent primary key for default OneToManyCascade
       ...
   }
 

For a Map, the default cascade parameters are:

   public class SomeParent
   {
        @Column(primaryKey=true)
       int someParentId;

       Map<Integer, SomeChild> someChildList; // defaults to  @OneToManyCascade
       ...
   }
   
   // equivalent to
   public class SomeParent
   {
        @Column(primaryKey=true)
       int someParentId;
       
       // uses SomeChild.hashCode for map key
        @OneToManyCascade(selects=@SelectCascade(operation=HashMapSelectOperation.class,
            sourceParameterFieldNames="#primaryKeyFields", targetWhereName="#sourceFieldNames"))
       Map<Integer, SomeChild> someChildList;
       ...
   }
 

Since:

1.0

Author:

Jeff Miller

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
DeleteCascade[]	deletes The cascade operations to perform when source row is deleted.
java.lang.String	foreignKeyReferenceField Defines foreign key reference on target (child) rows.
java.lang.String[]	foreignKeyValueFields Defines foreign key(s) on target (child) rows.
InsertCascade[]	inserts The cascade operations to perform when source row is inserted.
java.lang.String	name Names the cascade so that it occurs only when desired.
boolean	readOnly Indicates if cascade should never modify the database.
SaveCascade[]	saves The cascade operations to perform when source row is saved.
SelectCascade[]	selects Select cascade operations that will select target rows.
java.lang.Class<?>	targetClass Class type of target field to affect.
UpdateCascade[]	updates The cascade operations to perform when source row is updated.

Element Detail

readOnly

public abstract boolean readOnly

Indicates if cascade should never modify the database. An equivalent to using readOnly=true would be to set inserts={}, updates={}, and deletes={}.

Returns:

true to use only the select operations (never modify); false to cascade all operations

Default:

false

targetClass

public abstract java.lang.Class<?> targetClass

Class type of target field to affect. Used as parameter to Database.getTable(Class) to get table for cascade operation. targetClass() is optional for scalar fields since target class can be obtained from target field at runtime.

For nonscalar target field types, like arrays, Collection types, and Map types, targetClass can be determined from the field. Array types can be determined through Class.getComponentType(). For collections and maps, target class can be determined through the parameterized type with Field.getGenericType() if the generic type is not parameterized. For complex parameterized types, target class must be specified.

The following are examples of fields where targetClass=Something.class is optional in cascade annotations because it can be determined through reflection:

 Something scalar;
 Something[] array;
 List<Something> list;
 Map<String, Something> map;
 

Returns:

class of field that is involved in cascade; Object.class to indicate that class is to be obtained from field at runtime by reflection

Default:

java.lang.Object.class

selects

public abstract SelectCascade[] selects

Select cascade operations that will select target rows. Typical values would be:

• @SelectCascade(operation=ArrayListSelectOperation.class, sourceParameterFieldNames="...")
• @SelectCascade(operation=HashMapSelectOperation.class, sourceParameterFieldNames="...")

Returns:

select annotations for cascade; use empty array for no select cascade

Default:

@org.sormula.annotation.cascade.SelectCascade(sourceParameterFieldNames="#primaryKeyFields", targetWhereName="#sourceFieldNames")

inserts

public abstract InsertCascade[] inserts

The cascade operations to perform when source row is inserted.

Returns:

insert annotations for cascade; use empty array for no insert cascade

Default:

@org.sormula.annotation.cascade.InsertCascade

updates

public abstract UpdateCascade[] updates

The cascade operations to perform when source row is updated.

Returns:

update annotations for cascade; use empty array for no update cascade

Default:

@org.sormula.annotation.cascade.UpdateCascade

saves

public abstract SaveCascade[] saves

The cascade operations to perform when source row is saved.

Returns:

save annotations for cascade; use empty array for no save cascade

Since:

1.9.3 and 2.3.3

Default:

@org.sormula.annotation.cascade.SaveCascade

deletes

public abstract DeleteCascade[] deletes

The cascade operations to perform when source row is deleted.

Returns:

delete annotations for cascade; use empty array for no delete cascade

Default:

@org.sormula.annotation.cascade.DeleteCascade

foreignKeyValueFields

public abstract java.lang.String[] foreignKeyValueFields

Defines foreign key(s) on target (child) rows. Used by cascades when the following is true: SelectCascade.setForeignKeyValues(), InsertCascade.setForeignKeyValues(), UpdateCascade.setForeignKeyValues(), DeleteCascade.setForeignKeyValues(), SaveCascade.setForeignKeyValues().

When target (parent) row is cascaded, then each target (child) row foreign key setters are invoked with values from source (parent) primary key.

Source row key(s) are primary keys in source row defined by Column.primaryKey(), Column.identity(), or Row.primaryKeyFields().

When "#" is used, then cascade assumes that source key field names are the same as target (child) key field names. For example: Parent.parentId --> Child.parentId.

If explicit fields are named, then they must be in same order as source row primary key fields.

Returns:

names of foreign key fields in child (target) row; "#" means target foreign key names are same as source (parent) primary key field names; empty array means no foreign keys are defined

Since:

3.0

Default:

{}

foreignKeyReferenceField

public abstract java.lang.String foreignKeyReferenceField

Defines foreign key reference on target (child) rows. Used by cascades when the following is true: SelectCascade.setForeignKeyReference(), InsertCascade.setForeignKeyReference(), UpdateCascade.setForeignKeyReference(), DeleteCascade.setForeignKeyReference(), SaveCascade.setForeignKeyReference().

When target (parent) row is cascaded, then each target (child) row foreign key reference setter is invoked with reference to source (parent).

When "class" is used, then cascade assumes that target (child) key reference field name is parent class simple name (begins with lower case). For example: SomeParent (source) of SomeChild (target) will use SomeChild.someParent field and invoke SomeChild.setSomeParent(SomeParent).

Returns:

name of foreign key reference field in child (target) row; "class" means target field name is same as source (parent) class name; empty string means no foreign key reference is defined

Since:

3.0

Default:

""

name

public abstract java.lang.String name

Names the cascade so that it occurs only when desired. Set desired cascades with Table.setRequiredCascades(String...) or SqlOperation.setRequiredCascades(String...). If no name is specified (empty string) and no required cascades are specified, then cascade will occur by default since the default required cascade for Table is an empty string.

Returns:

name of cascade; "*" to cascade always regardless of required cascade names

Since:

3.0

Default:

""