LiteOrm Android Documentation

LiteOrm is a lightweight, high-performance, and powerful ORM (Object-Relational Mapping) framework for Android. It is designed to allow developers to perform CRUD (Create, Read, Update, Delete) operations, manage entity relationships, and handle automatic data mapping with minimal code.

Key characteristics include:

• Performance: Optimized to be significantly faster than standard SQLiteDatabase#insert methods.
• Simplicity: Follows a "convention over configuration" approach, requiring minimal annotations and often working without needing no-argument constructors.
• Automatic Schema Management: Supports automatic table creation and intelligent column detection (automatically adding new fields to the database when models change).
• Relationship Mapping: Supports persisting and recovering entity relationships (one-to-one, one-to-many, etc.) by marking relationship types on entity properties.
• Type Support: Automatically maps Java types to SQLite types (TEXT, REAL, INTEGER, BLOB) and handles serialized containers like Date, ArrayList, and Vector.

LiteOrm provides several advanced features for managing Android data:

• Multi-database Support: Each database file is managed by a separate LiteOrm management class instance.
• Flexible Storage: Supports storing database files in custom locations, including SD cards.
• Automatic Type Identification: Automatically maps Java types to SQLite types (TEXT, REAL, INTEGER, BLOB).
• Advanced Object Construction: Uses reflection and constructor parameter techniques, meaning you often do not need to provide a no-argument constructor for your entities.
• Complex Data Support: Can automatically store sequences and containers like Date, ArrayList, and Vector.
• Flexible Querying: Supports complex queries including where, order, limit, having, and group clauses.
• Binding Syntax: Supports standard SQLite constraints such as NOT NULL, UNIQUE, DEFAULT, COLLATE, CHECK, and PRIMARY KEY, including conflict algorithms.

LiteOrm provides a high-level API for common database operations. Most operations can be performed with a single line of code.

Save and Insert

• save(object): Performs an upsert (inserts if new, updates if exists).
• insert(object, ConflictAlgorithm): Inserts a new record with a specific conflict resolution strategy.

Update

• update(object): Updates the record matching the object's primary key.
• update(list, ColumnsValue, ConflictAlgorithm): Performs a batch update on specific columns for a list of objects.

Query

• query(Class): Retrieves all records of a specific type.
• queryById(id, Class): Retrieves a single record by its primary key.
• query(QueryBuilder): Uses a QueryBuilder for complex queries including where, limit, order, and distinct.

Delete

• delete(object): Deletes a specific entity.
• delete(Class, start, end, orderColumn): Deletes a range of records based on an ordered column.
• delete(WhereBuilder): Deletes records matching specific criteria.
• deleteAll(Class): Deletes all records of a type (including related objects if using a cascade instance).

// Save
School school = new School("hello");
liteOrm.save(school);

// Insert
Book book = new Book("good");
liteOrm.insert(book, ConflictAlgorithm.Abort);

// Update
book.setIndex(1988);
book.setAuthor("hehe");
liteOrm.update(book);

// Update specific columns
HashMap<String, Object> bookIdMap = new HashMap<String, Object>();
bookIdMap.put(Book.COL_AUTHOR, "liter");
liteOrm.update(bookList, new ColumnsValue(bookIdMap), ConflictAlgorithm.Fail);

// Query all
List list = liteOrm.query(Book.class);

// Query by ID
Student student = liteOrm.queryById(student1.getId(), Student.class);

// Delete entity
liteOrm.delete(student0);

// Delete all
liteOrm.deleteAll(School.class);

LiteOrm uses annotations to map Java classes to SQLite tables. You can define table names, primary keys, non-null constraints, and column names. It also supports ignoring specific fields so they are not persisted.

Key annotations:

• @Table(name): Specifies the database table name.
• @PrimaryKey(AssignType): Marks a field as the primary key. Use AssignType.AUTO_INCREMENT for auto-incrementing IDs.
• @NotNull: Ensures the column is NOT NULL.
• @Ignore: Prevents the field from being stored in the database.
• @Column(name): Specifies a custom column name.
• @Default(value): Sets a default value for the column.

@Table("test_model")
public class TestModel {

    // 指定自增，每个对象需要有一个主键
    @PrimaryKey(AssignType.AUTO_INCREMENT)
    private int id;

    // 非空字段
    @NotNull
    private String name;

    //忽略字段，将不存储到数据库
    @Ignore
    private String password;

    @Default("true")
    @Column("login")
    private Boolean isLogin;
}

LiteOrm provides a streamlined API for common database operations. The framework emphasizes a minimalist syntax to reduce boilerplate code.

Common Operations:

• db.save(object): Persists an object (supports replace logic).
• db.insert(object): Inserts a new record.
• db.update(object): Updates an existing record.
• db.delete(object): Deletes a record.
• db.query(Class): Queries the database for entities of a specific class.
• db.deleteAll(Class): Deletes all records of a specific type.

Advanced Features:

• Flexible Querying: Supports columns, where, order, limit, having, and group clauses.
• Constraint Support: Supports SQL constraints such as NOT NULL, UNIQUE, DEFAULT, COLLATE, CHECK, and PRIMARY KEY, including conflict resolution algorithms.
• Relationship Modes: Supports both Independent operations (high performance, saves only the object itself) and Cascading operations (saves the object along with its associated related objects).