Other DAO Operations

To get data out of a database, generally it is useful to put data into it. We have seen basic @Insert, @Update, and @Delete DAO methods on TripStore:

package com.commonsware.android.room;

import android.arch.persistence.room.Dao;
import android.arch.persistence.room.Delete;
import android.arch.persistence.room.Insert;
import android.arch.persistence.room.OnConflictStrategy;
import android.arch.persistence.room.Query;
import android.arch.persistence.room.Update;
import java.util.List;

@Dao
interface TripStore {
  @Query("SELECT * FROM trips ORDER BY title")
  List<Trip> selectAll();

  @Query("SELECT * FROM trips WHERE id=:id")
  Trip findById(String id);

  @Insert
  void insert(Trip... trips);

  @Update
  void update(Trip... trips);

  @Delete
  void delete(Trip... trips);
}

Generally speaking, these scenarios are simpler than @Query. The @Insert, @Update, and @Delete set up simple methods for inserting, updating, or deleting entities passed to their methods… and that is pretty much it. However, there are a few additional considerations that we should explore.

Parameters

@Insert, @Update, and @Delete work with entities. TripStore uses varargs, so we can pass zero, one, or several Trip objects, though passing zero objects would be a waste of time.

However, in addition to varargs, you can have these methods accept:

• A single entity
• Individual entities as separate parameters (void insert(Trip trip1, Trip trip2))
• A List of entities

Return Values

Frequently, you just have these methods return void.

However:

• For @Update and @Delete, you can have them return an int, which will be the number of rows affected by the update or delete operation
• For an @Insert method accepting a single entity, you can have it return a long which will be the ROWID of the entity (and, if you are using an auto-increment int as your primary key, this will also be that key)
• For an @Insert method accepting multiple entities, you can have it return an array of long objects or a List of Long objects, being the corresponding ROWID values for those inserted entities

Conflict Resolution

@Insert and @Update support an optional onConflict property. This maps to SQLite’s ON CONFLICT clause and indicates what should happen if there is either a uniqueness violation (e.g., duplicate primary keys) or a NOT NULL violation when the insert or update should occur.

The value of onConflict is an OnConflictStrategy enum:

The default strategy for @Insert and @Update is ABORT.

We wille explore these conflict strategies in greater detail much later in the book.

Other Operations

The primary problem with @Insert, @Update, and @Delete is that they need entities. In part, that is so the DAO method knows what table to work against.

For anything else, use @Query. @Query not only works with operations that return result sets, but with any SQL that you wish to execute, even if that SQL does not return a result set.

So, for example, you could have:

@Query("DELETE FROM Customer")
void nukeCustomersFromOrbit();

…or:

  @Query("DELETE FROM Customer WHERE id IN (:ids)")
  int nukeCertainCustomersFromOrbit(String... ids);

…or INSERT INTO ... SELECT FROM ... syntax, or pretty much any other combination that cannot be supported directly by @Insert, @Update, and @Delete annotations.

Consider @Insert, @Update, and @Delete to be “convenience annotations” for entity-based operations, where @Query is the backbone for your DAO methods.