CPOrm
A Powerful Content Provider ORM for android. This ORM uses an android sqlite database as a backing store, but interacts with it using content providers. You use it like a normal ORM, by creating java objects, and then do all of you interactions through the objects. And you get the added benefits of using it like normal content providers, so integration with list views and other components are simple.
Have a look at the Wiki for more information.
Please star the repo if you find this library usefull, thank you :)
Features
- Supports table creation from the data model.
- Supports view creation from the data model.
- Advanced querying capabilities, allowing you to created complex queries easily.
- It is extendable, allowing you to define custom column type mappings.
- It is really quick to query, as well as doing bulk inserts. From my own tests you can insert around 5000 objects per second and queries return around 9 000 objects per second.
- Allows you to add table change listeners for views.
- Most importantly, it is easy to use.
Planned Features For Future Release
- Contract Class Generator
- Direct DB Access
Install it
There are four ways to install CPOrm:
As a Gradle dependency
This is the preferred way. Simply add:
compile 'za.co.cporm:CPOrm:3.0.7'
to your project dependencies and run gradle build
or gradle assemble
.
As a Maven dependency
Declare the dependency in Maven:
<dependency>
<groupId>za.co.cporm</groupId>
<artifactId>CPOrm</artifactId>
<version>3.0.7</version> </dependency>
As a library project
Download the source code and import it as a library project in Eclipse. The project is available in the folder library. For more information on how to do this, read here.
As a jar
Visit the releases page to download aar directly. You can drop them into your libs
folder and configure the Java build path to include the library. See this tutorial for an excellent guide on how to do this.
Proguard
In order to use CPOrm in Android release mode include the following proguard rules
# CPORM CONFIGURATION -keepattributes *Annotation* -keepclasseswithmembernames class ** {
@za.co.cporm.model.annotation.* *;
}
-keep class za.co.cporm.** {
*;
}
-dontwarn za.co.cporm.**
===================
Use it
To use the ORM, include it as a library in you project. Create a configuration that will tell the ORM all the important stuff like the domain model objects, database name etc. You can define a custom SQLColumnMapping factory as well if you want to handle more that the standard java types.
For more information, check out the example app.
-
Install the project via any of the method above. and extend
Application
class and use it as following:public class SampleApplication extends Application { @Override public void onCreate() { super.onCreate(); CPOrm.initialize(this); } }
-
register this application class in Manifest file:
<application android:name=".SampleApplication" ... >
-
add following meta data in
<application>
tag<meta-data android:name="CPORM_CONFIG" android:value="za.co.cporm.example.model.MyCPOrmConfiguration" /> <meta-data android:name="MAPPING_FACTORY" android:value="om.cp.orm.example.MyMappingFactory" /><!-- This is optional--> <meta-data android:name="AUTHORITY" android:value="za.co.cporm.example" /> <!-- Should match provider-->
-
register content provider:
<provider android:authorities="za.co.cporm.example" <!-- Should match the Authority Meta Tag--> android:name="za.co.cporm.provider.CPOrmContentProvider" android:exported="false" android:process=":provider" />
-
Now, you just have to create model classes by:
-
annotation:
@Table public class Book { ... }
-
extending class:
@Table public class Author extends CPDefaultRecord<Author> { @Column public String name; ... }
#####Notes:
-
When you extend CPDefaultRecord you have access to all default access methods such as save(), update(), delete(), etc. and If you are using just @Table annotation, you can use those methods from CPOrm class. for e.g. CPOrm.insert(authorObject); .
-
When you extend CPDefaultRecord you have already a auto increment primary key with name '_id'. So while using just @Table annotation, consider creating a primary key.
-
Name of columns and tables will convert from camelCasing to under_score. for e.g. field bookName in a model will become book_name in database.
#####Column Constraint annotations:
@Column
will allow to change name of column and allow to make it NOT NULL. Default values for not null is false. for e.g.
@Column(columnName = "cover_name") private String bookName;
@Column(required = true) private String isbn;
@PrimaryKey
will allow to make a column as primary key, and auto increment. Default value for autoIncrement is true. For now the library only supports keys of type long. for e.g.
@PrimaryKey private String isbn;
@PrimaryKey(autoIncrement = false) private String isbn;
@Unique
will allow you to make a column value unique.
-
-
Register your model classes
public class MyCPOrmConfiguration implements CPOrmConfiguration {
@Override
public String getDatabaseName() {
return "example.db";
}
@Override
public int getDatabaseVersion() {
return 1;
}
@Override
public boolean isQueryLoggingEnabled() {
return false;
}
@Override
public List<Class<?>> getDataModelObjects() {
List<Class<?>> domainObjects = new ArrayList<Class<?>>();
domainObjects.add(Book.class);
domainObjects.add(Author.class);
return domainObjects;
}
}
-
Access:
Book book = new Book(); book.name = "Sorcerer's Stone"; book.isbn = "122342564"; CPOrm.insert(book);
Author author = new Author(); author.name = "J.K. Rollings"; author.save();
Author first = Select.from(Author.class).first(); first.name = "J. K. Rowling"; first.update();
CPOrm.deleteAll(Book.class); Author first = Select.from(Author.class).first(); first.delete();
=========================
For detailed configuration and advance usages, go through the Wiki