Defining Models
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);
Basic field types
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 on 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);
}
}
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.
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.
In this section you will learn how to upgrade your existing model classes. With migrations you can add fields and relations, as well as rename models after you initially created them. Thus you no longer need to drop all your data and restore it afterwards in order to get your models to the newest version.
