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 package androidx.lifecycle; 18 19 import androidx.annotation.MainThread; 20 import androidx.annotation.NonNull; 21 22 /** 23 * Defines an object that has an Android Lifecycle. {@link androidx.fragment.app.Fragment Fragment} 24 * and {@link androidx.fragment.app.FragmentActivity FragmentActivity} classes implement 25 * {@link LifecycleOwner} interface which has the {@link LifecycleOwner#getLifecycle() 26 * getLifecycle} method to access the Lifecycle. You can also implement {@link LifecycleOwner} 27 * in your own classes. 28 * <p> 29 * {@link Event#ON_CREATE}, {@link Event#ON_START}, {@link Event#ON_RESUME} events in this class 30 * are dispatched <b>after</b> the {@link LifecycleOwner}'s related method returns. 31 * {@link Event#ON_PAUSE}, {@link Event#ON_STOP}, {@link Event#ON_DESTROY} events in this class 32 * are dispatched <b>before</b> the {@link LifecycleOwner}'s related method is called. 33 * For instance, {@link Event#ON_START} will be dispatched after 34 * {@link android.app.Activity#onStart onStart} returns, {@link Event#ON_STOP} will be dispatched 35 * before {@link android.app.Activity#onStop onStop} is called. 36 * This gives you certain guarantees on which state the owner is in. 37 * <p> 38 * If you use <b>Java 8 Language</b>, then observe events with {@link DefaultLifecycleObserver}. 39 * To include it you should add {@code "androidx.lifecycle:common-java8:<version>"} to your 40 * build.gradle file. 41 * <pre> 42 * class TestObserver implements DefaultLifecycleObserver { 43 * {@literal @}Override 44 * public void onCreate(LifecycleOwner owner) { 45 * // your code 46 * } 47 * } 48 * </pre> 49 * If you use <b>Java 7 Language</b>, Lifecycle events are observed using annotations. 50 * Once Java 8 Language becomes mainstream on Android, annotations will be deprecated, so between 51 * {@link DefaultLifecycleObserver} and annotations, 52 * you must always prefer {@code DefaultLifecycleObserver}. 53 * <pre> 54 * class TestObserver implements LifecycleObserver { 55 * {@literal @}OnLifecycleEvent(ON_STOP) 56 * void onStopped() {} 57 * } 58 * </pre> 59 * <p> 60 * Observer methods can receive zero or one argument. 61 * If used, the first argument must be of type {@link LifecycleOwner}. 62 * Methods annotated with {@link Event#ON_ANY} can receive the second argument, which must be 63 * of type {@link Event}. 64 * <pre> 65 * class TestObserver implements LifecycleObserver { 66 * {@literal @}OnLifecycleEvent(ON_CREATE) 67 * void onCreated(LifecycleOwner source) {} 68 * {@literal @}OnLifecycleEvent(ON_ANY) 69 * void onAny(LifecycleOwner source, Event event) {} 70 * } 71 * </pre> 72 * These additional parameters are provided to allow you to conveniently observe multiple providers 73 * and events without tracking them manually. 74 */ 75 public abstract class Lifecycle { 76 /** 77 * Adds a LifecycleObserver that will be notified when the LifecycleOwner changes 78 * state. 79 * <p> 80 * The given observer will be brought to the current state of the LifecycleOwner. 81 * For example, if the LifecycleOwner is in {@link State#STARTED} state, the given observer 82 * will receive {@link Event#ON_CREATE}, {@link Event#ON_START} events. 83 * 84 * @param observer The observer to notify. 85 */ 86 @MainThread addObserver(@onNull LifecycleObserver observer)87 public abstract void addObserver(@NonNull LifecycleObserver observer); 88 89 /** 90 * Removes the given observer from the observers list. 91 * <p> 92 * If this method is called while a state change is being dispatched, 93 * <ul> 94 * <li>If the given observer has not yet received that event, it will not receive it. 95 * <li>If the given observer has more than 1 method that observes the currently dispatched 96 * event and at least one of them received the event, all of them will receive the event and 97 * the removal will happen afterwards. 98 * </ul> 99 * 100 * @param observer The observer to be removed. 101 */ 102 @MainThread removeObserver(@onNull LifecycleObserver observer)103 public abstract void removeObserver(@NonNull LifecycleObserver observer); 104 105 /** 106 * Returns the current state of the Lifecycle. 107 * 108 * @return The current state of the Lifecycle. 109 */ 110 @MainThread 111 @NonNull getCurrentState()112 public abstract State getCurrentState(); 113 114 @SuppressWarnings("WeakerAccess") 115 public enum Event { 116 /** 117 * Constant for onCreate event of the {@link LifecycleOwner}. 118 */ 119 ON_CREATE, 120 /** 121 * Constant for onStart event of the {@link LifecycleOwner}. 122 */ 123 ON_START, 124 /** 125 * Constant for onResume event of the {@link LifecycleOwner}. 126 */ 127 ON_RESUME, 128 /** 129 * Constant for onPause event of the {@link LifecycleOwner}. 130 */ 131 ON_PAUSE, 132 /** 133 * Constant for onStop event of the {@link LifecycleOwner}. 134 */ 135 ON_STOP, 136 /** 137 * Constant for onDestroy event of the {@link LifecycleOwner}. 138 */ 139 ON_DESTROY, 140 /** 141 * An {@link Event Event} constant that can be used to match all events. 142 */ 143 ON_ANY 144 } 145 146 /** 147 * Lifecycle states. You can consider the states as the nodes in a graph and 148 * {@link Event}s as the edges between these nodes. 149 */ 150 @SuppressWarnings("WeakerAccess") 151 public enum State { 152 /** 153 * Destroyed state for a LifecycleOwner. After this event, this Lifecycle will not dispatch 154 * any more events. For instance, for an {@link android.app.Activity}, this state is reached 155 * <b>right before</b> Activity's {@link android.app.Activity#onDestroy() onDestroy} call. 156 */ 157 DESTROYED, 158 159 /** 160 * Initialized state for a LifecycleOwner. For an {@link android.app.Activity}, this is 161 * the state when it is constructed but has not received 162 * {@link android.app.Activity#onCreate(android.os.Bundle) onCreate} yet. 163 */ 164 INITIALIZED, 165 166 /** 167 * Created state for a LifecycleOwner. For an {@link android.app.Activity}, this state 168 * is reached in two cases: 169 * <ul> 170 * <li>after {@link android.app.Activity#onCreate(android.os.Bundle) onCreate} call; 171 * <li><b>right before</b> {@link android.app.Activity#onStop() onStop} call. 172 * </ul> 173 */ 174 CREATED, 175 176 /** 177 * Started state for a LifecycleOwner. For an {@link android.app.Activity}, this state 178 * is reached in two cases: 179 * <ul> 180 * <li>after {@link android.app.Activity#onStart() onStart} call; 181 * <li><b>right before</b> {@link android.app.Activity#onPause() onPause} call. 182 * </ul> 183 */ 184 STARTED, 185 186 /** 187 * Resumed state for a LifecycleOwner. For an {@link android.app.Activity}, this state 188 * is reached after {@link android.app.Activity#onResume() onResume} is called. 189 */ 190 RESUMED; 191 192 /** 193 * Compares if this State is greater or equal to the given {@code state}. 194 * 195 * @param state State to compare with 196 * @return true if this State is greater or equal to the given {@code state} 197 */ isAtLeast(@onNull State state)198 public boolean isAtLeast(@NonNull State state) { 199 return compareTo(state) >= 0; 200 } 201 } 202 } 203