Google Git
Sign in
android / platform / tools / dokka-devsite-plugin / b72ee407da918639ff8be3e04391955f0caa8442 / . / testData / fragment / docs / reference / kotlin / androidx / fragment / app / package-summary.html
blob: 3c7e01063fb858afc242073a5cac74caf6ba83b7 [file] [log] [blame]
<html devsite="true">
<head>
<title>androidx.fragment.app</title>
{% setvar book_path %}/reference/kotlin/androidx/_book.yaml{% endsetvar %}
{% include "_shared/_reference-head-tags.html" %}
</head>
<body>
<h1>androidx.fragment.app</h1>
{% setvar page_path %}androidx/fragment/app/package-summary.html{% endsetvar %}
{% setvar can_switch %}1{% endsetvar %}
{% include "reference/_kotlin_switcher2.md" %}
<p>Room is a Database Object Mapping library that makes it easy to access database on Android applications. </p>
<p>Rather than hiding the details 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>
<p>There are 3 major components in Room. </p>
<ul>
<li>Database: This annotation marks a class as a database. It should be an abstract class that extends RoomDatabase. At runtime, you can acquire an instance of it via Room.databaseBuilder or Room.inMemoryDatabaseBuilder.
<p>The database class defines the list of entities and data access objects in the database. It is also the main access point for the underlying connection. </p>
</li>
<li>Entity: This annotation marks a class as a database row. For each Entity, a database table is created to hold the items. The Entity class must be referenced in the Database#entities array. Each field of the Entity (and its super class) is persisted in the database unless it is denoted otherwise (see Entity docs for details). </li>
<li>Dao: This annotation marks a class or interface as a Data Access Object. Data access objects are the main components of Room that are responsible for defining the methods that access the database. The class that is annotated with 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.
<p>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. </p>
</li>
</ul>
Below is a sample of a simple database.
<pre class="prettyprint">// File: Song.java
<code>{@literal @}</code>Entity
public class User {
<code>{@literal @}</code>PrimaryKey
private int id;
private String name;
<code>{@literal @}</code>ColumnInfo(name = &quot;release_year&quot;)
private int releaseYear;
// getters and setters are ignored for brevity but they are required for Room to work.
}
// File: SongDao.java
<code>{@literal @}</code>Dao
public interface SongDao {
<code>{@literal @}</code>Query(&quot;SELECT * FROM song&quot;)
List&lt;Song&gt; loadAll();
<code>{@literal @}</code>Query(&quot;SELECT * FROM song WHERE id IN (:songIds)&quot;)
List&lt;Song&gt; loadAllBySongId(int... songIds);
<code>{@literal @}</code>Query(&quot;SELECT * FROM song WHERE name LIKE :name AND release_year = :year LIMIT 1&quot;)
Song loadOneByNameAndReleaseYear(String first, int year);
<code>{@literal @}</code>Insert
void insertAll(Song... songs);
<code>{@literal @}</code>Delete
void delete(Song song);
}
// File: MusicDatabase.java
<code>{@literal @}</code>Database(entities = {Song.java})
public abstract class MusicDatabase extends RoomDatabase {
public abstract SongDao userDao();
}
</pre>
You can create an instance of <code>{@code MusicDatabase}</code> as follows:
<pre class="prettyprint">MusicDatabase db = Room
.databaseBuilder(getApplicationContext(), MusicDatabase.class, &quot;database-name&quot;)
.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 InvalidationTracker class which you can acquire via RoomDatabase.getInvalidationTracker. </p>
<p>For convenience, Room allows you to return LiveData from Query methods. It will automatically observe the related tables as long as the <code>{@code LiveData}</code> has active observers. </p>
<pre class="prettyprint">// This live data will automatically dispatch changes as the database changes.
<code>{@literal @}</code>Query(&quot;SELECT * FROM song ORDER BY name LIMIT 5&quot;)
LiveData&lt;Song&gt; loadFirstFiveSongs();
</pre>
<p>You can also return arbitrary data 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. </p>
<pre class="prettyprint">class IdAndSongHeader {
int id;
<code>{@literal @}</code>ColumnInfo(name = &quot;header&quot;)
String header;
}
// DAO
<code>{@literal @}</code>Query(&quot;SELECT id, name || '-' || release_year AS header FROM user&quot;)
public IdAndSongHeader[] loadSongHeaders();
</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.</p>
<h2>Interfaces</h2>
<div class="devsite-table-wrapper">
<table class="responsive">
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentManager.BackStackEntry.html">FragmentManager.BackStackEntry</a></code></td>
<td width="100%">
<p>Representation of an entry on the fragment back stack, as created with <code><a href="/reference/kotlin/androidx/fragment/app/FragmentTransaction.html#addToBackStack(java.lang.String)">FragmentTransaction.addToBackStack()</a></code>.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentManager.OnBackStackChangedListener.html">FragmentManager.OnBackStackChangedListener</a></code></td>
<td width="100%">
<p>Interface to watch for changes to the back stack.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentOnAttachListener.html">FragmentOnAttachListener</a></code></td>
<td width="100%">
<p>Listener for receiving a callback immediately following <code><a href="/reference/kotlin/androidx/fragment/app/Fragment.html#onAttach(android.content.Context)">Fragment#onAttach(Context)</a></code>.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentResultListener.html">FragmentResultListener</a></code></td>
<td width="100%">
<p>Listener for handling fragment results.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentResultOwner.html">FragmentResultOwner</a></code></td>
<td width="100%">
<p>A class that manages passing data between fragments.</p>
</td>
</tr>
</tbody>
</table>
</div>
<h2>Classes</h2>
<div class="devsite-table-wrapper">
<table class="responsive">
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/DialogFragment.html">DialogFragment</a></code></td>
<td width="100%">
<p>Static library support version of the framework's android.app.DialogFragment.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/Fragment.html">Fragment</a></code></td>
<td width="100%">
<p>Static library support version of the framework's android.app.Fragment.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/Fragment.SavedState.html">Fragment.SavedState</a></code></td>
<td width="100%">
<p>State information that has been retrieved from a fragment instance through <code><a href="/reference/kotlin/androidx/fragment/app/FragmentManager.html#saveFragmentInstanceState(androidx.fragment.app.Fragment)">FragmentManager.saveFragmentInstanceState</a></code>.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentActivity.html">FragmentActivity</a></code></td>
<td width="100%">
<p>Base class for activities that want to use the support-based <code><a href="/reference/kotlin/androidx/fragment/app/Fragment.html">Fragments</a></code>.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentContainer.html">FragmentContainer</a></code></td>
<td width="100%">
<p>Callbacks to a <code><a href="/reference/kotlin/androidx/fragment/app/Fragment.html">Fragment</a></code>'s container.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentContainerView.html">FragmentContainerView</a></code></td>
<td width="100%">
<p>FragmentContainerView is a customized Layout designed specifically for Fragments.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentController.html">FragmentController</a></code></td>
<td width="100%">
<p>Provides integration points with a <code><a href="/reference/kotlin/androidx/fragment/app/FragmentManager.html">FragmentManager</a></code> for a fragment host.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentFactory.html">FragmentFactory</a></code></td>
<td width="100%">
<p>Interface used to control the instantiation of <code><a href="/reference/kotlin/androidx/fragment/app/Fragment.html">Fragment</a></code> instances.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentHostCallback.html">FragmentHostCallback</a></code></td>
<td width="100%">
<p>Integration points with the Fragment host.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentManager.html">FragmentManager</a></code></td>
<td width="100%">
<p>Static library support version of the framework's android.app.FragmentManager.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentManager.FragmentLifecycleCallbacks.html">FragmentManager.FragmentLifecycleCallbacks</a></code></td>
<td width="100%">
<p>Callback interface for listening to fragment state changes that happen within a given FragmentManager.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentManagerNonConfig.html">FragmentManagerNonConfig</a></code></td>
<td width="100%">
<p><strong>This class is deprecated.</strong>
<p>Have your <code><a href="/reference/kotlin/androidx/fragment/app/FragmentHostCallback.html">FragmentHostCallback</a></code> implement androidx.lifecycle.ViewModelStoreOwner to automatically retain the Fragment's non configuration state.</p>
</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentPagerAdapter.html">FragmentPagerAdapter</a></code></td>
<td width="100%">
<p><strong>This class is deprecated.</strong>
<p>Switch to androidx.viewpager2.widget.ViewPager2 and use androidx.viewpager2.adapter.FragmentStateAdapter instead.</p>
</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentStatePagerAdapter.html">FragmentStatePagerAdapter</a></code></td>
<td width="100%">
<p><strong>This class is deprecated.</strong>
<p>Switch to androidx.viewpager2.widget.ViewPager2 and use androidx.viewpager2.adapter.FragmentStateAdapter instead.</p>
</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentTabHost.html">FragmentTabHost</a></code></td>
<td width="100%">
<p><strong>This class is deprecated.</strong>
<p>Use <a href="https://developer.android.com/guide/navigation/navigation-swipe-view ">TabLayout and ViewPager</a> instead.</p>
</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentTransaction.html">FragmentTransaction</a></code></td>
<td width="100%">
<p>Static library support version of the framework's android.app.FragmentTransaction.</p>
</td>
</tr>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/ListFragment.html">ListFragment</a></code></td>
<td width="100%">
<p>Static library support version of the framework's android.app.ListFragment.</p>
</td>
</tr>
</tbody>
</table>
</div>
<h2>Exceptions</h2>
<div class="devsite-table-wrapper">
<table class="responsive">
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/Fragment.InstantiationException.html">Fragment.InstantiationException</a></code></td>
<td width="100%">
<p>Thrown by <code><a href="/reference/kotlin/androidx/fragment/app/FragmentFactory.html#instantiate(java.lang.ClassLoader,java.lang.String)">FragmentFactory#instantiate(ClassLoader, String)</a></code> when there is an instantiation failure.</p>
</td>
</tr>
</tbody>
</table>
</div>
<h2>Annotations</h2>
<div class="devsite-table-wrapper">
<table class="responsive">
<tbody>
<tr>
<td><code><a href="/reference/kotlin/androidx/fragment/app/FragmentStateManagerControl.html">FragmentStateManagerControl</a></code></td>
<td width="100%"></td>
</tr>
</tbody>
</table>
</div>
</body>
</html>