1 /* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /** 18 * Room is a Database Object Mapping library that makes it easy to access database on Android 19 * applications. 20 * <p> 21 * Rather than hiding the detail of SQLite, Room tries to embrace them by providing convenient APIs 22 * to query the database and also verify such queries at compile time. This allows you to access 23 * the full power of SQLite while having the type safety provided by Java SQL query builders. 24 * <p> 25 * There are 3 major components in Room. 26 * <ul> 27 * <li>{@link androidx.room.Database Database}: This annotation marks a 28 * class as a database. It should be an abstract class that extends 29 * {@link androidx.room.RoomDatabase RoomDatabase}. At runtime, you can acquire 30 * an instance of it via {@link androidx.room.Room#databaseBuilder( 31 * android.content.Context,java.lang.Class, java.lang.String) Room.databaseBuilder} or 32 * {@link androidx.room.Room#inMemoryDatabaseBuilder(android.content.Context, 33 * java.lang.Class) Room.inMemoryDatabaseBuilder}. 34 * <p> 35 * This class defines the list of entities and data access objects in the database. It is 36 * also the main access point for the underlying connection. 37 * </li> 38 * <li>{@link androidx.room.Entity Entity}: This annotation marks a class as a 39 * database row. For each {@link androidx.room.Entity Entity}, a database table 40 * is created to hold the items. The Entity class must be referenced in the 41 * {@link androidx.room.Database#entities() Database#entities} array. Each field 42 * of the Entity (and its super class) is persisted in the database unless it is denoted 43 * otherwise (see {@link androidx.room.Entity Entity} docs for details). 44 * </li> 45 * <li>{@link androidx.room.Dao Dao}: This annotation marks a class or interface 46 * as a Data Access Object. Data access objects are the main component of Room that are 47 * responsible for defining the methods that access the database. The class that is annotated 48 * with {@link androidx.room.Database Database} must have an abstract method 49 * that has 0 arguments and returns the class that is annotated with Dao. While generating the 50 * code at compile time, Room will generate an implementation of this class. 51 * <pre> 52 * Using Dao classes for database access rather than query builders or direct queries allows you 53 * to keep a separation between different components and easily mock the database access while 54 * testing your application. 55 * </li> 56 * </ul> 57 * Below is a sample of a simple database. 58 * <pre> 59 * // File: User.java 60 * {@literal @}Entity 61 * public class User { 62 * {@literal @}PrimaryKey 63 * private int uid; 64 * private String name; 65 * {@literal @}ColumnInfo(name = "last_name") 66 * private String lastName; 67 * // getters and setters are ignored for brevity but they are required for Room to work. 68 * } 69 * // File: UserDao.java 70 * {@literal @}Dao 71 * public interface UserDao { 72 * {@literal @}Query("SELECT * FROM user") 73 * List<User> loadAll(); 74 * {@literal @}Query("SELECT * FROM user WHERE uid IN (:userIds)") 75 * List<User> loadAllByUserId(int... userIds); 76 * {@literal @}Query("SELECT * FROM user where name LIKE :first AND last_name LIKE :last LIMIT 1") 77 * User loadOneByNameAndLastName(String first, String last); 78 * {@literal @}Insert 79 * void insertAll(User... users); 80 * {@literal @}Delete 81 * void delete(User user); 82 * } 83 * // File: AppDatabase.java 84 * {@literal @}Database(entities = {User.java}) 85 * public abstract class AppDatabase extends RoomDatabase { 86 * public abstract UserDao userDao(); 87 * } 88 * </pre> 89 * You can create an instance of {@code AppDatabase} as follows: 90 * <pre> 91 * AppDatabase db = Room 92 * .databaseBuilder(getApplicationContext(), AppDatabase.class, "database-name") 93 * .build(); 94 * </pre> 95 * Since Room verifies your queries at compile time, it also detects information about which tables 96 * are accessed by the query or what columns are present in the response. 97 * <p> 98 * You can observe a particular table for changes using the 99 * {@link androidx.room.InvalidationTracker InvalidationTracker} class which you can 100 * acquire via {@link androidx.room.RoomDatabase#getInvalidationTracker() 101 * RoomDatabase.getInvalidationTracker}. 102 * <p> 103 * For convenience, Room allows you to return {@link androidx.lifecycle.LiveData 104 * LiveData} from {@link androidx.room.Query Query} methods. It will automatically 105 * observe the related tables as long as the {@code LiveData} has active observers. 106 * <pre> 107 * // This live data will automatically dispatch changes as the database changes. 108 * {@literal @}Query("SELECT * FROM user ORDER BY name LIMIT 5") 109 * LiveData<User> loadFirstFiveUsers(); 110 * </pre> 111 * <p> 112 * You can also return arbitrary Java objects from your query results as long as the fields in the 113 * object match the list of columns in the query response. This makes it very easy to write 114 * applications that drive the UI from persistent storage. 115 * <pre> 116 * class IdAndFullName { 117 * public int uid; 118 * {@literal @}ColumnInfo(name = "full_name") 119 * public String fullName; 120 * } 121 * // DAO 122 * {@literal @}Query("SELECT uid, name || lastName as full_name FROM user") 123 * public IdAndFullName[] loadFullNames(); 124 * </pre> 125 * If there is a mismatch between the query result and the POJO, Room will print a warning during 126 * compilation. 127 * <p> 128 * Please see the documentation of individual classes for details. 129 */ 130 package androidx.room; 131
