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<User> 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