@Retention(value=RUNTIME) @Target(value=METHOD) @Documented public @interface JField
This annotation is used in two scenarios:
@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.
| 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.
|
public abstract String name
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.
public abstract String type
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();
public abstract int storageId
StorageIdGenerator will be consulted to auto-generate a value
unless JSimpleClass.autogenFields() is false (in which case an error occurs).StorageIdGenerator.generateFieldStorageId(),
StorageIdGenerator.generateSetElementStorageId(),
StorageIdGenerator.generateListElementStorageId(),
StorageIdGenerator.generateMapKeyStorageId(),
StorageIdGenerator.generateMapValueStorageId()public abstract boolean indexed
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).
public abstract DeleteAction onDelete
For non-reference fields this property must be equal to its default value.
cascadeDelete(),
JObject.delete()public abstract boolean cascadeDelete
For non-reference fields this property must be equal to its default value.
onDelete(),
JObject.delete()public abstract boolean unique
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.
uniqueExclude(),
uniqueExcludeNull(),
UniquenessConstraintspublic abstract String[] uniqueExclude
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.
unique(),
uniqueExcludeNull()public abstract boolean uniqueExcludeNull
This property must be left false when unique() is false or the field has primitive type.
unique(),
uniqueExclude()public abstract boolean allowDeleted
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.
onDelete(),
allowDeletedSnapshot(),
JSimpleClass.autogenAllowDeleted()public abstract boolean allowDeletedSnapshot
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.
onDelete(),
allowDeleted(),
JSimpleClass.autogenAllowDeletedSnapshot()Copyright © 2017. All rights reserved.