1. FlexORM
  2. FlexORM
  3. FlexORM

Wiki

Clone wiki

FlexORM / Usage_Instructions

1. You must set the following Flex-compiler properties in addition to any existing properties

-keep-as3-metadata+=Table,Id,Column,OneToOne,ManyToOne,OneToMany,ManyToMany,Transient,MappedSuperclass

The += is important to retain metadata defined by the SDK.

2. Create an instance of the EntityManager

The following example code creates an initialised instance of EntityManager:

private var em:EntityManager = EntityManager.instance;
public function setUp():void
{
    em.openSyncConnection("database_name");
}
public function tearDown():void
{
    em.sqlConnection.close();
}

EntityManager is a singleton.

3. Configure table (Optional)

[Table(name="table_name", inheritsFrom="pkg.name.SuperClass")]
public class MyEntity

The [Bindable] annotation is required on all persistent objects.

The table name will default to the pluralised class name.

Inheritance mapping is resolved automatically if the super class belongs to the same package as the entity. If the super class belongs to a different package, the qualified class name of the super class must be specified using the 'inheritsFrom' attribute, otherwise public properties of the super class will not be persisted.

Instead of inheritsFrom="pkg.name.SuperClass" one can also use inheritsFromSuperclass = "true".

4. Configure column (Optional)

[Column(name="column_name")]
public var myProperty:String

All public properties, unless annotated as [Transient] will be treated as a persistent property.

The column name will default to the name of the property.

5. Configure ID (Optional)

[Id]
public var id:int

An int must be used as the data type.

If [Id] is not specified, the ID column will default to the first public property that ends with "id" (case insensitive).

A Composite Key may be specified with multiple [Id] annotations as follows:

public class Schedule
{
    [Id]
    [ManyToOne]
    public var student:Student;

    [Id]
    [ManyToOne]
    public var lesson:Lesson;

    public var scheduledDate:Date;
}

If you want to save objects when the ID is already set (from a different db for example) you have to replace [id] with

[Id(strategy="assigned")]

6. Configure one-to-one association (Optional)

[OneToOne(cascade="save-update", constrain="false", name="organisation_id")]
public var organisationDetail:Organisation;

The 'cascade' attribute is optional. The cascade type will default to "save-update".

Valid values are:

  • "save-update" save or update the associated entities on save of the owning entity
  • "delete" delete the associated entities on deletion of the owning entity
  • "all" support cascade save, update, and delete
  • "none" do not cascade any changes to the associated entities

The 'constrain' attribute is optional. If true or by default, foreign key constraints are added to foreign key relationships. This is implemented using triggers since SQLite does not support foreign key semantics.

The 'name' attribute is optional. The column name will default to the name of the property.

If a property has a data type of a class within the same package as the persistent object, and the [OneToOne] annotation has not been specified, then it will be assumed.

7. Configure many-to-one association (Optional)

[ManyToOne(cascade="save-update", constrain="false", name="organisation_id")]
public var organisation:Organisation;

The 'cascade' attribute is optional. The cascade type will default to "save-update".

Valid values are:

  • "save-update" save or update the associated entities on save of the owning entity
  • "delete" delete the associated entities on deletion of the owning entity
  • "all" support cascade save, update, and delete
  • "none" do not cascade any changes to the associated entities

The 'constrain' attribute is optional. If true or by default, foreign key constraints are added to foreign key relationships. This is implemented using triggers since SQLite does not support foreign key semantics.

The 'name' attribute is optional. The column name will default to the name of the property.

If a property has a data type of a class within the same package as the persistent object, and the [ManyToOne] annotation has not been specified, then it will be assumed.

8. Configure one-to-many association (Optional)

[OneToMany(type="model.Order", cascade="delete",
           constrain="false", lazy="true", indexed="true", fkColumn="parent_id")]
public var orders:IList;

The 'type' attribute is required to determine the class of the listed object.

The 'cascade' attribute is optional. The cascade type will default to "save-update".

Valid values are:

  • "save-update" save or update the associated entities on save of the owning entity
  • "delete" delete the associated entities on deletion of the owning entity
  • "all" support cascade save, update, and delete
  • "none" do not cascade any changes to the associated entities

The 'constrain' attribute is optional. If true or by default, foreign key constraints are added to foreign key relationships. This is implemented using triggers since SQLite does not support foreign key semantics.

The 'lazy' attribute is optional. By default, associations are loaded eagerly ('lazy' = fetch when needed, 'eagerly' = fetch immediately). Lazy loaded associations must use the IList interface, since the framework uses a custom ArrayCollection to implement the lazy loading behaviour.

The 'indexed' attribute is optional. List associations are not indexed by default. If true, an index column with the name of the property and "_idx" suffix will be created in the associated entity's table and populated when the owner entity is saved. If 'indexed' is set to true, then 'cascade' must be set to "save-update".

The 'fkColumn' attribute is optional. It can be used to specify the column name in the associated table.

If a property has a data type of IList, Array, or ArrayCollection, and the [OneToMany] annotation has not been specified, then the framework will look for an already mapped entity with the same name as the singular inflection of the property name, and assume the property is one-to-many of the type found. Otherwise, the property will be ignored and not mapped to the database.

9. Configure many-to-many association

[ManyToMany(type="model.Role", table="name_of_association_table", tableIsView="false", joinColumns = "[joinColumnName = 'pk1', joinColumnName = 'pk2']", inverseJoinColumns = "[joinColumnName = 'role_id']", cascade="none", constrain="false", indexed="false")]
public var roles:IList;

The 'type' attribute is required to determine the class of the listed object.

The 'table' attribute is optional. The 'table' attribute can be used to specify the name of the association table. If nothing is specfied, it will default to a generated name composed of the names of both entities separated by an underscore.

The 'tableIsView' attribute is optional. If false or by default, the association table will not be regarded as a database view (see View Support).

The 'joinColumns' and 'inverseJoinColumns' attributes are optional. They can be used to specify the column names for the association table. If nothing is specified, it will default to the names of the Primary Keys of both entities.

The 'cascade' attribute is optional. The cascade type will default to "save-update".

Valid values are:

  • "save-update" save or update the associated entities on save of the owning entity
  • "delete" delete the associated entities on deletion of the owning entity
  • "all" support cascade save, update, and delete
  • "none" do not cascade any changes to the associated entities

The 'constrain' attribute is optional. If true or by default, foreign key constraints are added to foreign key relationships. This is implemented using triggers since SQLite does not support foreign key semantics.

The 'indexed' attribute is optional. List associations are not indexed by default. If true, an index column with the name of the property and "_idx" suffix will be created in the associated entity's table and populated when the owner entity is saved. If 'indexed' is set to true, then 'cascade' must be set to "save-update".

10. Support for Views

FlexORM supports Views, in that there is

  • no database table created,
  • no constraint created,
  • no index created

The same can be achieved with the 'createTable', 'constrain' and 'indexed' attributes.

This allows for database views generated outside of FlexORM or by code using em.query(). While the creation of the database table is not performed, the SELECT statements are still generated from the entities and can be used as with regular database tables.

To specify, that an entity corresponds to a database view, use the 'isView' attribute:

    [Table(name = "vuser", isView = "true")]
    public class UserLightView

To specify, that the association table of a ManyToMany relation is a database view, use the 'tableIsView' attribute.

        [ArrayElementType("ormtest.model8.RoleGroup8")]
        [ManyToMany(type = "ormtest.model8.RoleGroup8", table = "vSYS_USER_GROUP8", tableIsView="true" ,joinColumns = "[joinColumnName = 'sys_user_id_fromView']", inverseJoinColumns = "[joinColumnName = 'permissions_id_fromView']", lazy = "false")]
        public var permissions_fromView:ArrayCollection;

11. Configure transient property

[Transient]
public var derivedValue:int;

The [Transient] annotation will tell the EntityManager to ignore and not attempt to persist the property.

12. MappedSuperclass

[MappedSuperclass]
public class AbstractUser

The [MappedSuperclass] annotation will tell the EntityManager to include the properties of this superclass in all inheriting entities instead of creating a reference table for the superclass instead.

13. Public API methods:

findAll(c:Class)

Returns an ArrayCollection of all saved objects of type c.

loadItem(c:Class, id:int)

Returns an object of type c, identified by id.

loadByCompositeKey(c:Class, compositeKeys:Array)

Returns an object of type c, identified by an array of objects, which make up the composite key. For example:

em.loadItemByCompositeKey(Schedule, [student, lesson])
save(obj:Object)

insert (if new) or update (if previously saved) the persistent object

remove(obj:Object)

permanently remove the given object from the database

Transactions may be delimited using:

em.startTransaction();

and

em.endTransaction();

Updated