ActiveAndroid Basics – Saving and Querying
All code for this series is located here.
Part 3 of this series gave an in-depth look at how to set up your model classes using ActiveAndroid. This post will focus on how to save your models to your database and how to perform basic queries. We will also implement a basic UI and develop the first iteration of our car building app.
The first version of the app will be very simple. In our main activity we will build a car and save it to the database. The layout will contain a single Button and a TextView. When the button is pressed, we will query the database for our car that we previously saved and display it in the TextView. To see the full object structure I am going to represent the car as a formatted JSON string; this will require the gson library and some helper methods that I will briefly touch upon. To learn more about JSON, check out this link.
To start, let’s look at how we will build our first car. In our MainActivity.java class we will implement a
buildCar() method that will piece together our first car and save it to the database.
Persisting data with ActiveAndroid is extremely easy. After setting the different parameters for our engine class, we call
e.save(). This method, which is implemented in the ActiveAndroid Model class, takes care of saving our Engine object to our database; it writes all primitive data members to the database and sets up any foreign key column references. That’s it. That’s all. It really is that simple. Next we set up our Body object and the Wheel object that we are going to use to build our car. Once again, after each respective object is created and the correct member variables are set we call our handy
Finally we build our car. I implemented a simple CarBuilder class that can assist us in creating our car (check out the source here). The
addWheelsUniform(Wheel w) method of the CarBuilder class takes in a single wheel object and sets all four of our cars wheels to that specific wheel. The
SERIAL_NUMBER that we pass in will be our unique identifier for our car and will also be how we query our car later. After calling the
build() method we are given a Car object that we can then call
save() on. IMPORTANT NOTE: You MUST call
save() on the car parts BEFORE calling
save() on your Car. This is required for ActiveAndroid to properly (in ORM fashion) persist your objects to the database. If you do not save your objects first, when you query your Car all of its non-primitive members will be null.
Querying the Database
Now that we know how to save our first car to the database let’s look at how we go about querying the database for our car. Once again in our MainActivity.java file we will implement a method called
The query in lines 10-15 from the snippet above is checking to see if an object exists in the database. Let’s break this down one piece at a time:
- By calling
new Select()we are creating a new ActiveAndroid database query.
.from(Car.class)method tells ActiveAndroid we want to query the table containing our Car objects.
- To search for a specific parameter (in our case the Car’s serialNumber) we call
.where("serialNumber = ?", SERIAL_NUMBER).
- Since we only want to know if the Car even exists at the point, we call the
.exists()method that returns true if the object exists and false otherwise.
As seen above, queries with ActiveAndroid are easy to build and read exactly as they function. Moving on, if a Car with the given serial number does exist then we want to load the actual object from the database and display it. In the event that it doesn’t exist, for now we’ll just log an error message. The query in lines 19-24 from above is basically identical to the first query except for the final action. To retrieve the Car object itself, we call
executeSingle() which returns a Car object with the given serial number. The Select class also has a
.execute() method that will return a list of all Car objects that match the query parameters.
Displaying our Car
As I mentioned previously, I am going to use a formatted JSON string to display our object. This will require some simple helper methods to be added to our existing model classes and main activity. So first thing first – we need to get gson up and running in our app. We’ll need to update our apps build.gradle file to include the gson library dependency:
Now we need to actually represent our car as a JSON object. If you noticed in the last tutorial, our CarPart class that our Engine, Wheel, and Body classes are derived from includes a
public JsonObject getJsonObject() method. Our other classes will override this method to properly format themselves. Since the Classes that make up our Car contain only primitives, it is easy to build
JsonObjects for each by using the overloaded
addProperty(String name, <type> value) method that is part of the JsonObject class. The
getJsonObject() implementations for each of our CarParts are below:
Building the JsonObject for our Car class is still easy, but takes a little more JSON knowledge.
For readability, we create two JsonObjects: one to encapsulate the entire Car and one to build up the object hierarchy. For the
serialNumber we use the basic
addProperty() method. However for our CarPart member variables we call the
add(String name, JsonElement element) method. For now we are only adding JsonObjects, but we will also be adding JsonArrays in the future. Note that we are not adding the list of wheels to the JsonObject just yet. This is because ActiveAndroid can’t handle Java’s List type; we will implement a custom TypeSerializer to fix this in the next part of the series. So for now we will have a wheel-less car; not great for driving but it’s a start!
Finally we can set up our UI, wire everything together, and try out our app. Below is the simple main_activity.xml:
Now let’s make some additions to our MainActivity.java class:
formatString(String text) helper method takes our JsonObject as a string and formats it to be a pretty, properly indented String that we can stick directly in our TextView. This will allow us to view the object hierarchy inherent in our Car model class. In our
onCreate() we find our views, set up our button’s OnClickListener, and build our car. Nothing fancy here, just your standard Android UI boilerplate. In our
() method we set our TextView to display our Car as a formatted JSON String.
Below you can check out two screenshots I took while testing the app; one is before the button is pressed and the other is after the button is pressed.
So that’s it! We have successfully built a car, saved it to our database, queried it, and displayed it again after retrieving it from the database. For simple applications this may be all you need, but there are a lot more features of ActiveAndroid that are worth exploring.
What is next?
In the next post we will look at implementing a custom TypeSerializer for Java’s List class.