org.sormula.annotation.cascade

Annotation Type Cascade

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

A general purpose cascade annotation. It may be used on any class variable that is either scalar or a collection. Use this as an alternative to OneToManyCascade or OneToOneCascade.

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

Since:

1.0

Author:

Jeff Miller

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
DeleteCascade[]	deletes Delete cascade operations for target fields.
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 Insert cascade operations for target fields.
java.lang.String	name Names the cascade so that it occurs only when desired.
SaveCascade[]	saves Save cascade operations for target fields.
SelectCascade[]	selects Select cascade operations for target fields.
java.lang.Class<?>	targetClass Class type of target field to affect.
UpdateCascade[]	updates Update cascade operations for target fields.

Element Detail

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 non-scalar 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 relfection

Default:

java.lang.Object.class

selects

public abstract SelectCascade[] selects

Select cascade operations for target fields. Use empty array to perform no select cascades.

Returns:

select annotations for cascade

Default:

{}

inserts

public abstract InsertCascade[] inserts

Insert cascade operations for target fields. Use empty array to perform no insert cascades.

Returns:

insert annotations for cascade

Default:

{}

updates

public abstract UpdateCascade[] updates

Update cascade operations for target fields. Use empty array to perform no update cascades.

Returns:

update annotations for cascade

Default:

{}

saves

public abstract SaveCascade[] saves

Save cascade operations for target fields. Use empty array to perform no update cascades.

Returns:

update annotations for cascade

Since:

1.9.3 and 2.3.3

Default:

{}

deletes

public abstract DeleteCascade[] deletes

Delete cascade operations for target fields. Use empty array to perform no delete cascades.

Returns:

delete annotations for cascade

Default:

{}

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:

""