Androrm - Documentation

The Basics

In order to get your model classes ready for automatic serialization and deserialization the first and most important step is to let them inherit from the androrm

Model

class. Doing so will immediately give you some predefined functions like

save

and

delete

, that can be used to store your models in the database or delete them, if you don't need them anymore.

Each model class will get a

mId

field assigned to it, that androrm uses, to reference models. By default this will be a

PrimaryKey

field, that is handled by the database. If you want to use your own IDs, you can call the

Model

constructor with the

suppressAutoincremt

flag set to

true

. Now you only have to look out, that when you save your model for the first time, you call the

save

function with the additional

id

parameter.

Example of model class, with autoincremented id field

// Foo inherits from Model and can be serialized
public class Foo extends Model {
    
    // initializes the standard ID field
    // and sets it to autoincrement
    public Foo() {
        super();
    }
    
}

Foo foo = new Foo();

// foo is saved to the database and a
// id is automatically created
foo.save(getApplicationContext());

Example of model class, with manually set id

// Foo inherits from Model and can be serialized
public class Foo extends Model {
    
    // initializes the standard ID field
    // and sets the flag to suppress the
    // autoincrement
    public Foo() {
        super(true);
    }
    
}

Foo foo = new Foo();

// foo is saved to the database, but now 1
// is used for the ID field. Note, that now _YOU_
// have to look out, that there are no duplicates
foo.save(getApplicationContext(), 1);

Of course a model also needs fields attached to it. Androrm comes with some predefined field types for you. As androrm doesn't determine the database column names through any annotations on the fields, but uses reflection on the model classes to find the fields, there visibility has to be at least

protected

, so that they are accessibale from the

Model

class. You also have to provide a zero-argument constructor, in which you initialize your fields. Let's look at the next example, to get things clear.

public class Book extends Model {
    
    // fields visibility is set to protected,
    // so the Model class can access it
    protected CharField mTitle;
    
    // zero-argument constructor, that can be called 
    // by androrm, to gather field information
    public Book() {
        super();
        
        // set up field with maxLength parameter
        mTitle = new CharField(80);
    }
    
}

The

Book

class defines a

CharField

called

mTitle

. Luckily this field is also defined with

protected

visibility. So when androrm examines this field it will create a database table called book and also a column called mTitle in this table.

Ok, books are normally written by someone. So what we would create next is the author model. That could look like the following:

public class Author extends Model {
    
    protected CharField mName;
    
    public Author() {
        super();
        
        mName = new CharField(80);
    }
    
}

Relational fields

Without androrm, you would now have to go and write all that SQL stuff, that links

Book

with

Author

. Overall, a mess. You don't want to do this. You want to create your app!

But anyway, you want that connection between

Book

and

Author

. Here come the relational fields of androrm. We can now just link each book to an author, by defining a

ForeignKeyField

inside the

Book

model.

public class Book extends Model {
    
    // fields visibility is set to protected,
    // so the Model class can access it
    protected CharField mTitle;
    
    // Link the Author model to the Book model.
    protected ForeignKeyField<Author> mAuthor;
    
    // zero-argument constructor, that can be called 
    // by androrm, to gather field information
    public Book() {
        super();
        
        // set up field with maxLength parameter
        mTitle = new CharField(80);
        
        // initialize the foreign key relation
        mAuthor = new ForeignKeyField<Author>(Author.class);
    }
    
}

Now actually we are not only talking about the relation of a

Book

to an

Author

. In many cases you probably also want to do queries asking an author for all of his books. Therefore androrm offers you the

OneToManyField

. Behind the scenes, it will use the

ForeignKey

Book

, but that is nothing you have to worry about.

public class Author extends Model {
    
    protected CharField mName;
    
    // implicit field, that uses the ForeignKey 
    // on the Book model
    protected OneToManyField<Author, Book> mBooks;
    
    public Author() {
        super();
        
        mName = new CharField(80);
        mBooks = new OneToManyField<Author, Book>(Author.class, Book.class);
    }
    
}

The objects method

To prepare your model for an easy to use query mechanism, you should also implement the

objects

method on each of your model classes. By default the

Model

class of androrm provides this method, but here you have to hand in the class of the model you are querying all the time. So, mostly only for convenience reasons, but also to have nicer looking code, implement your own

objects

method to be as DRY as possible.

class Book extends Model {
    
    public static final QuerySet<Book> objects(Context context) {
        return objects(context, Book.class);
    }
    
}

Don't be confused by the return type of this function. The Making Queries section will explain everything you need to know about this androrm mechanism.

If you want to learn more about field types, relations and how to make queries, then have a look at these pages:

Field Types

The Field Types section will give you reference pages for all field types, that are currently available in androrm. If you are looking for options and modifiers for fields, this is the place to go.