com.j256.ormlite.field
Annotation Type DatabaseField


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

Annotation that identifies a field in a class that corresponds to a column in the database and will be persisted. Fields that are not to be persisted such as transient or other temporary fields probably should be ignored. For example:

 @DatabaseField(id = true)
 private String name;
 
 @DatabaseField(columnName = "passwd", canBeNull = false)
 private String password;
 

WARNING: If you add any extra fields here, you will need to add them to DatabaseFieldConfig, DatabaseFieldConfigLoader, DatabaseFieldConfigLoaderTest, and DatabaseTableConfigUtil as well.

Author:
graywatson

Optional Element Summary
 boolean allowGeneratedIdInsert
          If this is set to true then inserting an object with the ID field already set (i.e.
 boolean canBeNull
          Whether the field can be assigned to null or have no value.
 String columnDefinition
          Specify the SQL necessary to create this field in the database.
 String columnName
          The name of the column in the database.
 DataType dataType
          The DataType associated with the field.
 String defaultValue
          The default value of the field for creating the table.
 boolean foreign
          Field is a non-primitive object that corresponds to another class that is also stored in the database.
 boolean foreignAutoCreate
          Set this to be true (default false) to have the foreign field will be automagically created using its internal DAO if the ID field is not set (null or 0).
 boolean foreignAutoRefresh
          Set this to be true (default false) to have a foreign field automagically refreshed when an object is queried.
 String foreignColumnName
          Name of the foreign object's field that is tied to this table.
 String format
          Optional format information that can be used by various field types.
 boolean generatedId
          Whether the field is an auto-generated id field.
 String generatedIdSequence
          The name of the sequence number to be used to generate this value.
 boolean id
          Whether the field is the id field or not.
 boolean index
          Set this to be true (default false) to have the database add an index for this field.
 String indexName
          Set this to be a string (default none) to have the database add an index for this field with this name.
 int maxForeignAutoRefreshLevel
          Set this to be the number of times to refresh a foreign object's foreign object.
 boolean persisted
          Set this to be false (default true) to not store this field in the database.
 Class<? extends DataPersister> persisterClass
          Allows you to set a custom persister class to handle this field.
 boolean readOnly
          Set this to be true (default false) if this field is a read-only field.
 boolean throwIfNull
          If this is set to true (default false) then it will throw a SQLException if a null value is attempted to be de-persisted into a primitive.
 boolean unique
          Set this to be true (default false) to have the database insure that the column is unique to all rows in the table.
 boolean uniqueCombo
          Set this to be true (default false) to have the database insure that _all_ of the columns marked with this as true will together be unique.
 boolean uniqueIndex
          Set this to be true (default false) to have the database add a unique index for this field.
 String uniqueIndexName
          Set this to be a string (default none) to have the database add a unique index for this field with this name.
 String unknownEnumName
          If the field is an Enum and the database has a value that is not one of the names in the enum then this name will be used instead.
 boolean useGetSet
          Package should use get...() and set...() to access the field value instead of the default direct field access via reflection.
 boolean version
          Set this to be true (default false) to have this field to be a version field similar to javax.persistence.Version.
 int width
          Width of array fields (often for strings).
 

columnName

public abstract String columnName
The name of the column in the database. If not set then the name is taken from the field name.

Default:
""

dataType

public abstract DataType dataType
The DataType associated with the field. If not set then the Java class of the field is used to match with the appropriate DataType. This should only be set if you are overriding the default database type or if the field cannot be automatically determined (ex: byte[]).

Default:
com.j256.ormlite.field.DataType.UNKNOWN

defaultValue

public abstract String defaultValue
The default value of the field for creating the table. Default is none.

NOTE: If the field has a null value then this value will be inserted in its place when you call you call Dao.create(Object). This does not apply to primitive fields so you should just assign them in the class instead.

Default:
"__ormlite__ no default value string was specified"

width

public abstract int width
Width of array fields (often for strings). Default is 0 which means to take the data-type and database-specific default. For strings that means 255 characters although some databases do not support this.

Default:
0

canBeNull

public abstract boolean canBeNull
Whether the field can be assigned to null or have no value. Default is true.

Default:
true

id

public abstract boolean id
Whether the field is the id field or not. Default is false. Only one field can have this set in a class. If you don't have it set then you won't be able to use the query, update, and delete by ID methods. Only one of this, generatedId(), and generatedIdSequence() can be specified.

Default:
false

generatedId

public abstract boolean generatedId
Whether the field is an auto-generated id field. Default is false. With databases for which DatabaseType.isIdSequenceNeeded() is true then this will cause the name of the sequence to be auto-generated. To specify the name of the sequence use generatedIdSequence(). Only one of this, id(), and generatedIdSequence() can be specified.

Default:
false

generatedIdSequence

public abstract String generatedIdSequence
The name of the sequence number to be used to generate this value. Default is none. This is only necessary for database for which DatabaseType.isIdSequenceNeeded() is true and you already have a defined sequence that you want to use. If you use generatedId() instead then the code will auto-generate a sequence name. Only one of this, id(), and generatedId() can be specified.

Default:
""

foreign

public abstract boolean foreign
Field is a non-primitive object that corresponds to another class that is also stored in the database. It must have an id field (either id(), generatedId(), or generatedIdSequence() which will be stored in this table. When an object is returned from a query call, any foreign objects will just have the id field set in it. To get all of the other fields you will have to do a refresh on the object using its own Dao.

Default:
false

useGetSet

public abstract boolean useGetSet
Package should use get...() and set...() to access the field value instead of the default direct field access via reflection. This may be necessary if the object you are storing has protections around it.

NOTE: The name of the get method must match getXxx() where Xxx is the name of the field with the first letter capitalized. The get must return a class which matches the field's. The set method must match setXxx(), have a single argument whose class matches the field's, and return void. For example:

 @DatabaseField
 private Integer orderCount;
 
 public Integer getOrderCount() {
        return orderCount;
 }
 
 public void setOrderCount(Integer orderCount) {
        this.orderCount = orderCount;
 }
 

Default:
false

unknownEnumName

public abstract String unknownEnumName
If the field is an Enum and the database has a value that is not one of the names in the enum then this name will be used instead. It must match one of the enum names. This is mainly useful when you are worried about backwards compatibility with older database rows or future compatibility if you have to roll back to older data definition.

Default:
""

throwIfNull

public abstract boolean throwIfNull
If this is set to true (default false) then it will throw a SQLException if a null value is attempted to be de-persisted into a primitive. This must only be used on a primitive field. If this is false then if the database field is null, the value of the primitive will be set to 0.

Default:
false

persisted

public abstract boolean persisted
Set this to be false (default true) to not store this field in the database. This is useful if you want to have the annotation on all of your fields but turn off the writing of some of them to the database.

Default:
true

format

public abstract String format
Optional format information that can be used by various field types. For example, if the Date is to be persisted as a string, this can set what format string to use for the date.

Default:
""

unique

public abstract boolean unique
Set this to be true (default false) to have the database insure that the column is unique to all rows in the table. Use this when you wan a field to be unique even if it is not the identify field. For example, if you have the firstName and lastName fields, both with unique=true and you have "Bob", "Smith" in the database, you cannot insert either "Bob", "Jones" or "Kevin", "Smith".

Default:
false

uniqueCombo

public abstract boolean uniqueCombo
Set this to be true (default false) to have the database insure that _all_ of the columns marked with this as true will together be unique. For example, if you have the firstName and lastName fields, both with unique=true and you have "Bob", "Smith" in the database, you cannot insert another "Bob", "Smith" but you can insert "Bob", "Jones" and "Kevin", "Smith".

Default:
false

index

public abstract boolean index
Set this to be true (default false) to have the database add an index for this field. This will create an index with the name columnName + "_idx". To specify a specific name of the index or to index multiple fields, use indexName().

Default:
false

uniqueIndex

public abstract boolean uniqueIndex
Set this to be true (default false) to have the database add a unique index for this field. This is the same as the index() field but this ensures that all of the values in the index are unique..

Default:
false

indexName

public abstract String indexName
Set this to be a string (default none) to have the database add an index for this field with this name. You do not need to specify the index() boolean as well. To index multiple fields together in one index, each of the fields should have the same indexName value.

Default:
""

uniqueIndexName

public abstract String uniqueIndexName
Set this to be a string (default none) to have the database add a unique index for this field with this name. This is the same as the indexName() field but this ensures that all of the values in the index are unique.

Default:
""

foreignAutoRefresh

public abstract boolean foreignAutoRefresh
Set this to be true (default false) to have a foreign field automagically refreshed when an object is queried. This will _not_ automagically create the foreign object but when the object is queried, a separate database call will be made to load of the fields of the foreign object via an internal DAO. The default is to just have the ID field in the object retrieved and for the caller to call refresh on the correct DAO.

Default:
false

maxForeignAutoRefreshLevel

public abstract int maxForeignAutoRefreshLevel
Set this to be the number of times to refresh a foreign object's foreign object. If you query for A and it has an foreign field B which has an foreign field C ..., then querying for A could get expensive. Setting this value to 1 will mean that when you query for A, B will be auto-refreshed, but C will just have its id field set. This also works if A has an auto-refresh field B which has an auto-refresh field A.

NOTE: Increasing this value will result in more database transactions whenever you query for A, so use carefully. Default value is DEFAULT_MAX_FOREIGN_AUTO_REFRESH_LEVEL.

Default:
-1

persisterClass

public abstract Class<? extends DataPersister> persisterClass
Allows you to set a custom persister class to handle this field. This class must have a getSingleton() static method defined which will return the singleton persister.

See Also:
DataPersister
Default:
com.j256.ormlite.field.types.VoidType.class

allowGeneratedIdInsert

public abstract boolean allowGeneratedIdInsert
If this is set to true then inserting an object with the ID field already set (i.e. not null, 0) will not override it with a generated-id. If the field is null or 0 then the id will be generated. This is useful when you have a table where items sometimes have IDs and sometimes need them generated. This only works if the database supports this behavior and if generatedId() is also true for the field.

Default:
false

columnDefinition

public abstract String columnDefinition
Specify the SQL necessary to create this field in the database. This can be used if you need to tune the schema to enable some per-database feature or to override the default SQL generated.

Default:
""

foreignAutoCreate

public abstract boolean foreignAutoCreate
Set this to be true (default false) to have the foreign field will be automagically created using its internal DAO if the ID field is not set (null or 0). So when you call dao.create() on the parent object, any field with this set to true will possibly be created via an internal DAO. By default you have to create the object using its DAO directly. This only works if generatedId() is also set to true.

 Order order1 = new Order();
 // account1 has not been created in the db yet and it's id == null
 order1.account = account1;
 // this will create order1 _and_ pass order1.account to the internal account dao.create().
 orderDao.create(order1);
 

Default:
false

version

public abstract boolean version
Set this to be true (default false) to have this field to be a version field similar to javax.persistence.Version. When an update is done on a row the following happens: The field should be a short, integer, long, Date, Date-string, or Date-long type.

Default:
false

foreignColumnName

public abstract String foreignColumnName
Name of the foreign object's field that is tied to this table. This does not need to be specified if you are using the ID of the foreign object which is recommended. For example, if you have an Order object with a foreign Account then you may want to key off of the Account name instead of the Account ID.

NOTE: Setting this implies foreignAutoRefresh() is also set to true because there is no way to refresh the object since the id field is not stored in the database. So when this is set, the field will be automatically refreshed in another database query.

Default:
""

readOnly

public abstract boolean readOnly
Set this to be true (default false) if this field is a read-only field. This field will be returned by queries however it will be ignored during insert/create statements.

Default:
false


This documentation is licensed by Gray Watson under the Creative Commons Attribution-Share Alike 3.0 License.