JField (JSimpleDB Main Classes 2.1.2 API)

```
@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`	`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.
    
    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

Annotation Type JField

Optional Element Summary

Element Detail

name

type

storageId

indexed

onDelete

cascadeDelete

unique

uniqueExclude

uniqueExcludeNull