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
17package androidx.lifecycle;
18
19/**
20 * ViewModel is a class that is responsible for preparing and managing the data for
21 * an {@link android.app.Activity Activity} or a {@link androidx.fragment.app.Fragment Fragment}.
22 * It also handles the communication of the Activity / Fragment with the rest of the application
23 * (e.g. calling the business logic classes).
24 * <p>
25 * A ViewModel is always created in association with a scope (an fragment or an activity) and will
26 * be retained as long as the scope is alive. E.g. if it is an Activity, until it is
27 * finished.
28 * <p>
29 * In other words, this means that a ViewModel will not be destroyed if its owner is destroyed for a
30 * configuration change (e.g. rotation). The new instance of the owner will just re-connected to the
31 * existing ViewModel.
32 * <p>
33 * The purpose of the ViewModel is to acquire and keep the information that is necessary for an
34 * Activity or a Fragment. The Activity or the Fragment should be able to observe changes in the
35 * ViewModel. ViewModels usually expose this information via {@link LiveData} or Android Data
36 * Binding. You can also use any observability construct from you favorite framework.
37 * <p>
38 * ViewModel's only responsibility is to manage the data for the UI. It <b>should never</b> access
39 * your view hierarchy or hold a reference back to the Activity or the Fragment.
40 * <p>
41 * Typical usage from an Activity standpoint would be:
42 * <pre>
43 * public class UserActivity extends Activity {
44 *
45 *     {@literal @}Override
46 *     protected void onCreate(Bundle savedInstanceState) {
47 *         super.onCreate(savedInstanceState);
48 *         setContentView(R.layout.user_activity_layout);
49 *         final UserModel viewModel = ViewModelProviders.of(this).get(UserModel.class);
50 *         viewModel.userLiveData.observer(this, new Observer<User>() {
51 *            {@literal @}Override
52 *             public void onChanged(@Nullable User data) {
53 *                 // update ui.
54 *             }
55 *         });
56 *         findViewById(R.id.button).setOnClickListener(new View.OnClickListener() {
57 *             {@literal @}Override
58 *             public void onClick(View v) {
59 *                  viewModel.doAction();
60 *             }
61 *         });
62 *     }
63 * }
64 * </pre>
65 *
66 * ViewModel would be:
67 * <pre>
68 * public class UserModel extends ViewModel {
69 *     public final LiveData&lt;User&gt; userLiveData = new LiveData<>();
70 *
71 *     public UserModel() {
72 *         // trigger user load.
73 *     }
74 *
75 *     void doAction() {
76 *         // depending on the action, do necessary business logic calls and update the
77 *         // userLiveData.
78 *     }
79 * }
80 * </pre>
81 *
82 * <p>
83 * ViewModels can also be used as a communication layer between different Fragments of an Activity.
84 * Each Fragment can acquire the ViewModel using the same key via their Activity. This allows
85 * communication between Fragments in a de-coupled fashion such that they never need to talk to
86 * the other Fragment directly.
87 * <pre>
88 * public class MyFragment extends Fragment {
89 *     public void onStart() {
90 *         UserModel userModel = ViewModelProviders.of(getActivity()).get(UserModel.class);
91 *     }
92 * }
93 * </pre>
94 * </>
95 */
96public abstract class ViewModel {
97    /**
98     * This method will be called when this ViewModel is no longer used and will be destroyed.
99     * <p>
100     * It is useful when ViewModel observes some data and you need to clear this subscription to
101     * prevent a leak of this ViewModel.
102     */
103    @SuppressWarnings("WeakerAccess")
104    protected void onCleared() {
105    }
106}
107