[JPA] ObjectDB Manual (02 - Entity Classes)

[JPA Persistable Types]

• JPA persistable types:
• User defined classes
• Entity classes
• Mapped superclasses
• Embeddable classes.
• Instances of an embeddable class can only be stored in the database as embedded objects, i.e. as part of a containing entity object.
• Instances of embeddable classes are always embedded in other entity objects and do not require separate space allocation and separate store and retrieval operations. Therefore, using embeddable classes can save space in the database and improve efficiency.
• Simple Java data types
• Primitive types
• Wrappers
• String
• Date and Math types.
• java.sql.Date - represents date only (e.g. 2010-12-31).
• java.sql.Time - represents time only (e.g. 23:59:59).
• java.sql.Timestamp - represents date and time (e.g. 2010-12-31 23:59:59).
• @Temporal(TemporalType.DATE)
• Multi value types
• Collections
• Maps
• Arrays.
• Miscellaneous types
• Enum types
• Serializable types (user or system defined).
• [Note] Only instances of entity classes can be stored in the database directly. Other persistable types can only be embedded in entity classes as fields.
• A portable JPA entity class:
• Should be a top-level class (i.e. not a nested / inner class).
• Should have a public or protected no-arg constructor.
• Cannot be final and cannot have final methods or final instance variables.
• Mapped superclasses are really only useful in applications that use an ORM-based JPA provider (such as Hibernate, TopLink, EclipseLink, OpenJPA, JPOX, DataNucleus, etc.).

[JPA Entity Fields]

Fields of persistable user defined classes can be classified into the following five groups:

• Transient fields
• Do not participate in persistence and their values are never stored in the database
• Static and final entity fields are always considered to be transient
• Persistent fields
• Every persistent field can be marked with one of the following annotations:
• OneToOne, ManyToOne - for references of entity types.
• OneToMany, ManyToMany - for collections and maps of entity types.
• Basic - for any other persistable type.
• Specifying optional=false causes an exception to be thrown on any attempt to store an entity with a null value in that field.
• Inverse fields
• Inverse (or mapped by) fields contain data that is not stored as part of the entity in the database, but is still available after retrieval by a special automatic query.
• The mappedBy element specifies that the field is an inverse field rather than a persistent field. The content of the field is not stored as part of outer entity. Instead, the inverse field is automatically populated when the outer entity is retrieved from the database.
• The mappedBy element defines a bidirectional relationship. In a bidirectional relationship, the side that stores the data is the owner. Only changes to the owner side affect the database, since the other side is not stored and calculated by a query.
• Inverse fields may improve efficiency when managing very large collections that are changed often.
• Primary key (ID) fields
• Version field
• Should be treated as read only by the application and no mutator methods should be written against them. Only one version field per entity class is allowed.

• The first three groups (transient, persistent and inverse fields) can be used in both entity classes and embeddable classes.
• The last two groups (primary key and version fields) can only be used in entity classes.

[JPA Primary Key]

* Entity Identification

• Only entity objects have primary keys.

* Automatic Primary Key

• By default the primary key is a sequential 64 bit number (long) that is set automatically by ObjectDB for every new entity object that is stored in the database.
• The primary key of the first entity object in the database is 1.
• Primary key values are not recycled when entity objects are deleted from the database.
• The @GeneratedValue annotation specifies that the primary key is automatically allocated by ObjectDB.

* Application Set Primary Key

• If an entity has a primary key field that is not marked with @GeneratedValue, automatic primary key value is not generated and the application is responsible to set a primary key by initializing the primary key field.

* Composite Primary Key

• A composite primary key consist of multiple primary key fields.
• When an entity has multiple primary key fields, JPA requires defining a special ID class that is attached to the entity class using the @IdClass annotation.

* Embedded Primary Key

• An alternate way to represent a composite primary key is to use an embeddable class.
• The entity contains a single primary key field that is annotated with @EmbeddedId and contains an instance of that embeddable class.

* Using Primary Keys for Object Clustering

• it is useful to choose a primary key that helps clustering entity objects in the database in an efficient way. This is especially useful when using queries that return large result sets.

[Auto Generated Values]

• Marking a field with the @GeneratedValue annotation specifies that a value will be automatically generated for that field.
• This is primarily intended for primary key fields but ObjectDB also supports this annotation for non-key numeric persistent fields as well.

* The Auto Strategy

• @GeneratedValue(strategy=GenerationType.AUTO)
• But AUTO is the default strategy

* The Identity Strategy

• The IDENTITY strategy also generates an automatic value during commit for every new entity object.
• The difference is that a separate identity generator is managed per type hierarchy, so generated values are unique only per type hierarchy.

* The Sequence Strategy

• Defining a named sequence
• The @SequenceGenerator annotation is used to define a sequence and accepts a name, an initial value (the default is 1) and an allocation size (the default is 50).
• The number of IDs in each allocation is specified by the allocationSize attribute.

• Using the named sequence in one or more fields in one or more classes
• Unlike AUTO and IDENTITY, the SEQUENCE strategy generates an automatic value as soon as a new entity object is persisted (i.e. before commit).
• This may be useful when the primary key value is needed earlier.

* The Table Strategy

• Is very similar to the SEQUENCE strategy
• ORM-based JPA providers (such as Hibernate, TopLink, EclipseLink, OpenJPA, JPOX, etc.) simulate a sequence using a table to support this strategy.
• Whereas the SEQUENCE strategy maintains the next sequence number to be used the TABLE strategy maintains the last value that was used.

[Index Definition]

• Using proper indexes the iteration can be avoided and complex queries over millions of objects can be executed quickly.
• Index management introduces overhead in terms of maintenance time and storage space.

* Single Field Index

• @Unique represents a unique index that prevents duplicate values in the indexed field.
• A PersistenceException is thrown on commit (or flush) if different entities have the same value in a unique field (similar to how primary keys behave).
• @Index represents either an ordinary index with no unique constraint or a unique index if unique="true" is specified (the default is false).
• Indexes can only be defined on ordinary persistent fields (not on primary key / version fields).

* Composite Index

• A composite index is an index on more than one persistent field.
• It is defined by specifying multiple fields in the members attribute of the the @Index or @Unique annotations.
• Multiple @Index annotations can be wrapped with an @Indices annotation
• the @Uniques annotation can wrap multiple @Unique annotations.

* Multi Part Path Index

• Indexes must always refer to values that are stored as part of the entity.
• Indexes on multi part paths are only allowed when using embeddable classes as fields of embedded object are stored as part of the containing entity.
• Multi part paths in a composite index must have the same length.

* Indexes in Queries

• A BTree is an ordered map data structure that ObjectDB maintains in the file system rather than in memory.
• Indexes require maintenance time and consume storage space.
• Indexes are especially efficient in lookup and range queries.
• the order of the fields in the composite index definition is important, because it determines which field is used as the BTree's primary sort key and which field is used as a secondary sort key. If x is specified first, the BTree is ordered by x values, so a range scan on x values is supported.
• Indexes on collections are useful in JOIN queries.

[Database Schema Evolution]

• New entity objects have to be stored in the new class schema, and old entity objects, which were stored previously in the old class schema, have to be converted to the new schema.
• [Note] In client-server mode the ObjectDB server must be restarted after a schema change.

* Automatic Schema Evolution

• When an entity object of an old schema is loaded into memory it is automatically converted into an instance of the up to date entity class.
• The database object is only updated to the new schema when that entity object is stored to the database again.
• A matching field is a field with the same name and either the same type or a convertible type.
• A matching field might also be located in a different place in the class hierarchy.

[JPA Persistence Unit]

• A JPA Persistence Unit is a logical grouping of user defined persistable classes (entity classes, embeddable classes and mapped superclasses) with related settings.
• Defining a persistence unit is optional when using ObjectDB, but required by JPA.

* persistence.xml

• One persistence.xml file can include definitions for one or more persistence units.
• The portable way to instantiate an EntityManagerFactory in JPA requires a persistence unit.
• <provider>
• Indicates which JPA implementation should be used. 
• ObjectDB is represented by the com.objectdb.jpa.Provider string.
• If not specified, the first JPA implementation that is found is used.
• <mapping-file>
• Specify XML mapping files that are added to the default META-INF/orm.xml mapping file.
• Every annotation that is described in this manual can be replaced by equivalent XML in the mapping files (as explained below).
• <jar-file>
• Specify JAR files that should be searched for managed persistable classes.
• <class>
• Specify names of managed persistable classes .
• <property>
• Specify general properties. 
• JPA 2 defines standard properties for specifying database url, username and password, as demonstrated above.

* Managed Persistable Classes

• JPA requires registration of all the user defined persistable classes (entity classes, embeddable classes and mapped superclasses), which are referred to by JPA as managed classes, as part of a persistence unit definition.

* Reference
- ObjectDB 2.2 Developer's Guide