androidx/room/package-info.java (1 lines of code) (raw):
/*
* Copyright (C) 2017 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* Room is a Database Object Mapping library that makes it easy to access database on Android
* applications.
* <p>
* Rather than hiding the detail of SQLite, Room tries to embrace them by providing convenient APIs
* to query the database and also verify such queries at compile time. This allows you to access
* the full power of SQLite while having the type safety provided by Java SQL query builders.
* <p>
* There are 3 major components in Room.
* <ul>
* <li>{@link androidx.room.Database Database}: This annotation marks a
* class as a database. It should be an abstract class that extends
* {@link androidx.room.RoomDatabase RoomDatabase}. At runtime, you can acquire
* an instance of it via {@link androidx.room.Room#databaseBuilder(
* android.content.Context,java.lang.Class, java.lang.String) Room.databaseBuilder} or
* {@link androidx.room.Room#inMemoryDatabaseBuilder(android.content.Context,
* java.lang.Class) Room.inMemoryDatabaseBuilder}.
* <p>
* This class defines the list of entities and data access objects in the database. It is
* also the main access point for the underlying connection.
* </li>
* <li>{@link androidx.room.Entity Entity}: This annotation marks a class as a
* database row. For each {@link androidx.room.Entity Entity}, a database table
* is created to hold the items. The Entity class must be referenced in the
* {@link androidx.room.Database#entities() Database#entities} array. Each field
* of the Entity (and its super class) is persisted in the database unless it is denoted
* otherwise (see {@link androidx.room.Entity Entity} docs for details).
* </li>
* <li>{@link androidx.room.Dao Dao}: This annotation marks a class or interface
* as a Data Access Object. Data access objects are the main component of Room that are
* responsible for defining the methods that access the database. The class that is annotated
* with {@link androidx.room.Database Database} must have an abstract method
* that has 0 arguments and returns the class that is annotated with Dao. While generating the
* code at compile time, Room will generate an implementation of this class.
* <pre>
* Using Dao classes for database access rather than query builders or direct queries allows you
* to keep a separation between different components and easily mock the database access while
* testing your application.
* </li>
* </ul>
* Below is a sample of a simple database.
* <pre>
* // File: User.java
* {@literal @}Entity
* public class User {
* {@literal @}PrimaryKey
* private int uid;
* private String name;
* {@literal @}ColumnInfo(name = "last_name")
* private String lastName;
* // getters and setters are ignored for brevity but they are required for Room to work.
* }
* // File: UserDao.java
* {@literal @}Dao
* public interface UserDao {
* {@literal @}Query("SELECT * FROM user")
* List<User> loadAll();
* {@literal @}Query("SELECT * FROM user WHERE uid IN (:userIds)")
* List<User> loadAllByUserId(int... userIds);
* {@literal @}Query("SELECT * FROM user where name LIKE :first AND last_name LIKE :last LIMIT 1")
* User loadOneByNameAndLastName(String first, String last);
* {@literal @}Insert
* void insertAll(User... users);
* {@literal @}Delete
* void delete(User user);
* }
* // File: AppDatabase.java
* {@literal @}Database(entities = {User.java})
* public abstract class AppDatabase extends RoomDatabase {
* public abstract UserDao userDao();
* }
* </pre>
* You can create an instance of {@code AppDatabase} as follows:
* <pre>
* AppDatabase db = Room
* .databaseBuilder(getApplicationContext(), AppDatabase.class, "database-name")
* .build();
* </pre>
* Since Room verifies your queries at compile time, it also detects information about which tables
* are accessed by the query or what columns are present in the response.
* <p>
* You can observe a particular table for changes using the
* {@link androidx.room.InvalidationTracker InvalidationTracker} class which you can
* acquire via {@link androidx.room.RoomDatabase#getInvalidationTracker()
* RoomDatabase.getInvalidationTracker}.
* <p>
* For convenience, Room allows you to return {@link androidx.lifecycle.LiveData
* LiveData} from {@link androidx.room.Query Query} methods. It will automatically
* observe the related tables as long as the {@code LiveData} has active observers.
* <pre>
* // This live data will automatically dispatch changes as the database changes.
* {@literal @}Query("SELECT * FROM user ORDER BY name LIMIT 5")
* LiveData<User> loadFirstFiveUsers();
* </pre>
* <p>
* You can also return arbitrary Java objects from your query results as long as the fields in the
* object match the list of columns in the query response. This makes it very easy to write
* applications that drive the UI from persistent storage.
* <pre>
* class IdAndFullName {
* public int uid;
* {@literal @}ColumnInfo(name = "full_name")
* public String fullName;
* }
* // DAO
* {@literal @}Query("SELECT uid, name || lastName as full_name FROM user")
* public IdAndFullName[] loadFullNames();
* </pre>
* If there is a mismatch between the query result and the POJO, Room will print a warning during
* compilation.
* <p>
* Please see the documentation of individual classes for details.
*/
package androidx.room;