Setup & Basic Usage

Setup & Basic Usage

To start using the ORM you will first have to add it to your project. The preferred way is to use a Gradle dependency:

compile 'za.co.cporm:CPOrm:3.0'

Now that the library has been included, you can start creating your domain model objects, this is an example of what it should look like.

@Table
public class User extends CPDefaultRecord<User> {

    @Column
    @Unique
    private String userName;

    @Column
    private String givenName;

    @Column
    private String familyName;

    @Column
    private long roleId;

    //Getters and Setters left out for clarity
}

Note the use of the @Table and @Column annotations, these tell the ORM that this is table object and what fields represent columns. The table and column annotations have extra properties to specify their names etc. To create a view you need to implement the TableView interface and include the table and column annotation as usual. For convenience you can extend the CPRecord or CPDefaultRecord classes, they contain ease of use methods for inserting and updating your model objects. The CPDefault record class already has @PrimaryKey annotation with and android compatible ID field, if not extending this class you will have to specify your own primary key column, for the best support use a long field type for primary key columns.

Once all of the model objects have been created, you can tell the ORM about them by creating a Config class.

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(User.class);
        domainObjects.add(Role.class);

        return domainObjects;
    }
}

Your config class will need to implement the CPOrmConfiguration interface. Database version must start at 1 and be incremented when ever the model is changed, the ORM will the regenerate the database with the new models. Query logging can be enable to print out all of the queries that are executed on the data base.

Once the configuration class is set up, you need to tell the ORM where to find it, and specify the android authority name that will be used to listen for queries. This is done on the Android Manifest inside of the application tag.

<meta-data android:name="CPORM_CONFIG" android:value="za.co.cporm.example.model.MyCPOrmConfiguration" />
<meta-data android:name="AUTHORITY" android:value="om.cp.orm.example" /> <!-- Should match provider-->

Next you need to tell android that your application has a content provider that can listen for requests, you need to specify this in the Android Manifest in the application tag

<provider
            android:authorities="za.co.cporm.example"
            android:name="za.co.cporm.provider.CPOrmContentProvider"
            android:exported="false"/>

The authority for the provider must be the same as the one specified in the meta data tag, otherwise the ORM will not know what provider to query. The provider name should be left as is, this is the Content Provider created by the ORM to server request. The exported=false tells android that the data should not be available to other applications, you can set this to true if you want to expose you data to 3rd party applications.

As a convenience you can initialize the ORM in your Application class, this will allow you to execute queries without supplying the context every time.

CPOrm.initialize(Application application)

Now that everything is set up, you can start querying the ORM and inserting data. Here are some example operations

//Create a new user
User newUser = new User();
newUser.setUserName("JohnDoe");
newUser.setGivenName("John");
newUser.setFamilyName("Doe");
newUser.setRoleId(1);
newUser.save();

//Retrieve created user
User retrievedUser = Select.from(User.class).whereLike("user_name", "John").first();

//Delete created user
newUser.delete();

This will create a new user in the database, then retrieve the first user where the user name is like John, and the delete the created user. Note that fields without the column name specified will have an underscore in front of every capital letter in the field name. For maintainability create a Contract class containing static fields with the column names.