Skip to content

Object scheme mapping

Default orient mapping is limited in some cases, and that's why custom mapper implementation provided (extending default mapper).

Note

This is development time solution to quickly update scheme. Its usage in production is obviously limited.

Default object scheme mapping

See orient object mapping documentation for object mapping (and general object database page).

  • Orient ignore package, so class may be moved between packages
  • If model class extends some other class it will be also registered as separate scheme class.
  • When entity field removed, orient will hold all data already stored in records of that field
  • When entity field type changes, orient WILL NOT migrate automatically (you need to handle it manually, using custom scheme initializer or through orient studio).
  • When class renamed orient will register it as new entity and you will have to manually migrate all data (it's possible to use sql commands to rename entity in scheme)
  • To use entity within optimistic transaction, it must have version field (annotated with @Version). You should add field manually or extend all entities from provided base class: VersionedEntity
  • JPA annotations can be used to define cascades
  • JPA @Id annotation may be used to bind object id (String or Object to bind as RID)

Most useful are id and version mapping:

@Id
private String id;
@Version
private Long version;

Version property is required for optimistic transactions (enabled by default).

Graph types

Graph types are usual types with just one difference: its root class must extend V or E (for vertex or edge). You may register scheme class (even with default orient mapper) and later make it as extends V and it will be valid vertex type, usable for graph api. Extended mapper support this case with @EdgeType and @VertexType annotations.

Setup

Mapper is registered as scheme initializer bean, but mapper may be used directly too: ObjectSchemeInitializer.

Two scheme initializer implementations provided:

  • PackageSchemeInitializer - use all classes in package to init or update scheme (package should be specified as module constructor argument).
  • AutoScanSchemeInitializer - search classpath for entities annotated with @Persistent annotation and use them to create/update scheme.

They can be enabled by PackageSchemeModule and AutoScanSchemeModule modules.

Note

Modules must be registered together with main OrientModule.

For example:

install(new AutoScanSchemeModule("my.model.root.package"));

Mapping annotations

Extended mapper provides additional annotations:

Class:

  • @EdgeType - register class as edge type
  • @VertexType - register class as vertex type
  • @RenameFrom - renames existing scheme class before class registration
  • @Recreate - drop and create fresh scheme on each start
  • @CompositeIndex - creates composite index for class (index span multiple properties)
  • @CompositeLuceneIndex - creates composite lucene index for class (index span multiple properties)
  • @DropIndexes - drops existing indexes on start

Field:

Tip

New annotations could be implemented easily as plugins.

All annotations are safe: they may remain in model even after performing required action (they will just do nothing). This makes possible to use them as simple migration mechanism (but its better to use something stronger for production).

Important

Remember that scheme created from objects maintain same hierarchy as your objects. E.g. if you use provided VersionedEntity class as base class for entities, it will be also registered in scheme (nothing bad, you may not notice it). But for graphs hierarchies its more important: both vertex and edge objects can't extend same class (root class in hierarchy must extend V or E). So if you use @VertexType or @EdgeType annotations make sure their hierarchy not intersect.

See documentation:

How it works

Suppose we have model: 

class Model extends BaseModel

When model class is registered (note that this will be performed by scheme module automatically)

objectSchemeInitializer.register(Model.class);

Its hierarchy parsed and first BaseModel class registered and then Model class.

During registration initializer lookups all type and field annotations and execute them before and after orient registration.

To avoid registration of same base classes many times, registered classes are cached and not processed next time. Usually, scheme initialization is performed on application startup so you should not notice cache presence. But if you need to register class one more time, you may clear cache manually:

objectSchemeInitializer.clearModelCache();

(ObjectSchemeInitializer is registered as guice bean and so available for injection)