org.jsimpledb.annotation

Annotation Type JField

@Retention(value=RUNTIME)
 @Target(value=METHOD)
 @Documented
public @interface JField

Java annotation for defining simple fields, including reference fields that refer to other Java model object types.

This annotation is used in two scenarios:

• To describe a simple database field by annotating the corresponding abstract Java bean property `getter' method
• To describe the sub-field(s) of a complex database field (i.e., set, list, or map), that is, the collection element or map key and value. In this case this annotation nests within the corresponding @JListField, @JSetField, or @JMapField annotation.

Note that this annotation can be applied to superclass and interface methods to have the corresponding field defined in all sub-types.

When auto-generation of properties is enabled, use of this annotation is not required unless you need to override the defaults; see JSimpleClass.autogenFields().

Non-Reference Fields

If the field is not a reference field, the property type is inferred from the type of the annotated method or, in the case of complex sub-fields, the generic type of the collection class. The name of the property type must be registered in the FieldTypeRegistry (perhaps via @JFieldType), and the corresponding FieldType is then used to encode/decode field values. The type name may also be specified explicitly by name().

Simple fields may be indexed(); see org.jsimpledb.index for information on querying indexes.

Reference Fields

If the type of the field is (assignable to) a @JsimpleClass-annotated Java model object type, then the field is a reference field.

Reference fields are always indexed; the value of indexed() is ignored.

Delete Cascades

Reference fields have configurable behavior when the referring object or the referred-to object is deleted; see onDelete() and cascadeDelete().

Uniqueness Constraints

Fields that are not complex sub-fields may be marked as unique() to impose a uniqueness constraint on the value. Fields with uniqueness constraints must be indexed. Uniqueness constraints are handled at the JSimpleDB layer and function as an implicit validation constraint. In other words, the constraint is verified when the validation queue is processed and is affected by the transaction's configured ValidationMode.

Optionally, specific field values may be marked as excluded from the uniqueness constraint via uniqueExclude(). If so, the specified values may appear in multiple objects without violating the constraint. Because null values are not allowed in annotations, uniqueExcludeNull() is provided to exclude the null value.

In ValidationMode.AUTOMATIC, any upgraded JObjects are automatically added to the validation queue, so a uniqueness constraint added in a new schema version will be automatically verified when any object is upgraded.

Note however, that uniqueness constraints can be added or changed on a field without a schema version change. Therefore, after such changes, pre-existing database objects that were previously valid could become suddenly invalid. To avoid this possibililty, change the schema version number and update them manually.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
boolean	allowDeleted Allow assignment to deleted objects in normal transactions.
boolean	allowDeletedSnapshot Allow assignment to deleted objects in snapshot transactions.
boolean	cascadeDelete For reference fields, configure cascading behavior when the referring object is deleted.
boolean	indexed Whether this field is indexed or not.
String	name The name of this field.
DeleteAction	onDelete For reference fields, configure the behavior when the referred-to object is deleted.
int	storageId Storage ID for this field.
String	type Optional override for the type of this field.
boolean	unique Require this field's value to be unique among all database objects.
String[]	uniqueExclude Specify field value(s) which are excluded from the uniqueness constraint.
boolean	uniqueExcludeNull Specify that the null value is excluded from the uniqueness constraint.

Element Detail

name

public abstract String name

The name of this field.

If equal to the empty string (default value), the name is inferred from the name of the annotated Java bean getter method.

For sub-fields of complex fields, this property must be left unset.

Returns:

the name of the field

Default:

""

type

public abstract String type

Optional override for the type of this field.

If set, this must equal the name of a type registered in the FieldTypeRegistry associated with the Database instance, and the annotated method's return type must match the FieldType's supported Java type.

If equal to the empty string (default value), then the Java type is inferred from the return type of the getter method and the FieldType is found via FieldTypeRegistry.getFieldType().

For reference fields (i.e., methods with return value equal to a @JSimpleClass-annotated class), this property must be left unset.

For sub-fields of complex fields, this property can be used to force a primitive sub-field type instead of a primitive wrapper type. In that case, the complex field will disallow null values. For example:

  @JSetField(element = @JField(type = "float")) // nulls will be disallowed
  public abstract List<Float> getScores();
 

Returns:

the name of the field's type

Default:

""

storageId

public abstract int storageId

Storage ID for this field. Value should be positive and unique within the contained class. If zero, the configured StorageIdGenerator will be consulted to auto-generate a value unless JSimpleClass.autogenFields() is false (in which case an error occurs).

Returns:

the field's storage ID

See Also:

StorageIdGenerator.generateFieldStorageId(), StorageIdGenerator.generateSetElementStorageId(), StorageIdGenerator.generateListElementStorageId(), StorageIdGenerator.generateMapKeyStorageId(), StorageIdGenerator.generateMapValueStorageId()

Default:

0

indexed

public abstract boolean indexed

Whether this field is indexed or not.

Setting this property to true creates a simple index on this field. To have this field participate in a composite index on multiple fields, use JSimpleClass.compositeIndexes().

Note: reference fields are always indexed (for reference fields, this property is ignored).

Returns:

whether the field is indexed

Default:

false

onDelete

public abstract DeleteAction onDelete

For reference fields, configure the behavior when the referred-to object is deleted.

For non-reference fields this property must be equal to its default value.

Returns:

desired behavior when a referenced object is deleted

See Also:

cascadeDelete(), JObject.delete()

Default:

org.jsimpledb.core.DeleteAction.EXCEPTION

cascadeDelete

public abstract boolean cascadeDelete

For reference fields, configure cascading behavior when the referring object is deleted. If set to true, the referred-to object is automatically deleted as well.

For non-reference fields this property must be equal to its default value.

Returns:

whether deletion should cascade to the referred-to object

See Also:

onDelete(), JObject.delete()

Default:

false

unique

public abstract boolean unique

Require this field's value to be unique among all database objects.

This property creates an implicit uniqueness validation constraint.

The constraint will be checked any time normal validation is performed on an object containing the field. More precisely, a uniqueness constraint behaves like a JSR 303 validation constraint with groups() = { Default.class, UniquenessConstraints.class }. Therefore, uniqueness constraints are included in default validation, but you can also validate only uniqueness constraints via myobj.revalidate(UniquenessConstraints.class).

This property must be false for sub-fields of complex fields, and for any field that is not indexed.

Returns:

whether the field's value should be unique

See Also:

uniqueExclude(), uniqueExcludeNull(), UniquenessConstraints

Default:

false

uniqueExclude

public abstract String[] uniqueExclude

Specify field value(s) which are excluded from the uniqueness constraint.

The specified values must be valid String encodings of the associated field. For example:

  @JField(indexed = true, unique = true, uniqueExclude = { "Infinity", "-Infinity" })
  public abstract float getPriority();
 

This property must be left empty when unique() is false.

Returns:

values to exclude from the uniqueness constraint

See Also:

unique(), uniqueExcludeNull()

Default:

{}

uniqueExcludeNull

public abstract boolean uniqueExcludeNull

Specify that the null value is excluded from the uniqueness constraint.

This property must be left false when unique() is false or the field has primitive type.

Returns:

whether null should be excluded from the uniqueness constraint

See Also:

unique(), uniqueExclude()

Default:

false

allowDeleted

public abstract boolean allowDeleted

Allow assignment to deleted objects in normal transactions.

For non-reference fields, this property must be equal to its default value.

For reference fields, when true this property prevents setting this field to reference a deleted object, causing a DeletedObjectException to be thrown instead. Used together with DeleteAction.EXCEPTION (see onDelete()), this guarantees this field won't contain any dangling references.

This property only controls validation in regular (non-snapshot transactions); allowDeletedSnapshot() separately controls validation for SnapshotJTransactions.

For consistency, this property must be set to true when onDelete() is set to DeleteAction.NOTHING.

Returns:

whether the reference field should allow assignment to deleted objects in normal transactions

See Also:

onDelete(), allowDeletedSnapshot(), JSimpleClass.autogenAllowDeleted()

Default:

false

allowDeletedSnapshot

public abstract boolean allowDeletedSnapshot

Allow assignment to deleted objects in snapshot transactions.

For non-reference fields, this property must be equal to its default value.

This property is equivalent to allowDeleted(), but applies to SnapshotJTransactions instead of normal JTransactions; see allowDeleted() for details.

Snapshot transactions typically hold a copy of some small portion of the database. If this property is set to false, then it effectively creates a requirement that this "small portion" be transitively closed under object references.

For consistency, this property must be set to true when onDelete() is set to DeleteAction.NOTHING.

Returns:

whether the reference field should allow assignment to deleted objects in snapshot transactions

See Also:

onDelete(), allowDeleted(), JSimpleClass.autogenAllowDeletedSnapshot()

Default:

true