title: Is onRestoreInstanceState only called when switching orientation horizontal-vertical - any other cases?
body: <p>The docs clearly state that "<a href="https://developer.android.com/reference/android/app/Activity.html#onRestoreInstanceState(android.os.Bundle)" rel="nofollow noreferrer">This method is called after onStart() when the activity is being re-initialized from a previously saved state, given here in savedInstanceState</a>".
  Several StackOverflow questions <a href="https://stackoverflow.com/questions/15362525/when-is-onrestoreinstancestate-called">concur</a>.</p>
  
  <p>However I am finding this is not entirely accurate and can be misleading.
  onRestoreInstanceState is <strong>only</strong> called when switching orientation between horizontal-vertical. It is not called whenever onStart is called.</p>
  
  <p>I modified this <a href="https://codelabs.developers.google.com/codelabs/android-training-create-an-activity/index.html?index=..%2F..android-training#11" rel="nofollow noreferrer">simple lab exercise</a> to print out the log traces, and to save mCount into the bundle and display it.</p>
  
  <p>onRestoreInstanceState is <strong>not</strong> called when you press back button to go back to main Activity <strong>nor</strong> when you press Home button and relaunch. </p>
  
  <p>Even though I see that onSaveInstanceState and onStop was called each time (from the logs), I do not see a corresponding onRestoreInstanceState after onStart. This is unexpected. The docs should clearly state that only if onDestroy is called, then after onStart, will onRestoreInstanceState be called. Are there are any other cases (other than switching orientation) when it is <strong>reliably</strong> called?</p>
  
  <p>Knowing these use cases is useful for white-box testing.</p>
  
  <p><strong>Update</strong>: android docs have since been clarified - see my answer below.</p>
  
  <p>MainActivity.java</p>
  
  <pre><code>public class MainActivity extends AppCompatActivity {
      private int mCount = 0;
      private TextView mShowCount;
      public static final String EXTRA_MESSAGE =
              "com.example.hellotoast.extra.MESSAGE";
  
      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          setContentView(R.layout.activity_main);
          mShowCount = (TextView) findViewById(R.id.show_count);
          Log.d("MainActivity", "Hello World");
      }
  
      public void showToast(View view) {
          Toast toast = Toast.makeText(this, R.string.toast_message,
                  Toast.LENGTH_SHORT);
          toast.show();
          Intent intent = new Intent(this, HelloCount.class);
          intent.putExtra(EXTRA_MESSAGE, mCount);
          startActivity(intent);
      }
  
      @Override
      public void onSaveInstanceState(Bundle outState) {
          outState.putInt(EXTRA_MESSAGE, mCount);
          super.onSaveInstanceState(outState);
          Log.d("MainActivity", "onSaveInstanceState. saved mCount = " + mCount);
  
      }
      @Override
      public void onRestoreInstanceState(Bundle b) {
          super.onRestoreInstanceState(b);
          Log.d("MainActivity", "onRestoreInstanceState");
  
          if(b != null) {
              mCount = b.getInt(EXTRA_MESSAGE);
              Log.d("MainActivity", "onRestoreInstanceState mCount = "+mCount);
              mShowCount.setText(Integer.toString(mCount));
          }
      }
  
      @Override
      protected void onStart() {
          super.onStart();
          Log.d("MainActivity", "onStart");
  
      }
  
      @Override
      protected void onStop() {
          super.onStop();
          Log.d("MainActivity", "onStop");
      }
  
      @Override
      protected void onDestroy() {
          super.onDestroy();
          Log.d("MainActivity", "onDestroy");
      }
  
      public void countUp(View view) {
          mCount++;
          if (mShowCount != null) {
              mShowCount.setText(Integer.toString(mCount));
          }
      }
  }
  </code></pre>
  
  <p>HelloCount.java</p>
  
  <pre><code>import static com.example.hellotoast.MainActivity.EXTRA_MESSAGE;
  
  public class HelloCount extends AppCompatActivity {
  
      @Override
      protected void onCreate(Bundle savedInstanceState) {
          super.onCreate(savedInstanceState);
          Log.d("HelloCount", "onCreate");
          setContentView(R.layout.activity_hello_count);
          TextView tv = findViewById(R.id.helloCount);
          int i =  getIntent().getIntExtra(EXTRA_MESSAGE,0);
          tv.setText(String.valueOf(i));
      }
  
      @Override
      protected void onStart() {
          super.onStart();
          Log.d("HelloCount", "onStart");
  
      }
  
      @Override
      protected void onStop() {
          super.onStop();
          Log.d("HelloCount", "onStop");
      }
  
      @Override
      protected void onDestroy() {
          super.onDestroy();
          Log.d("HelloCount", "onDestroy");
      }
  }
  </code></pre>
  
  <p>activity_main.xml</p>
  
  <pre><code>&lt;RelativeLayout
      xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      xmlns:tools="http://schemas.android.com/tools"
      android:layout_width="match_parent"
      android:layout_height="match_parent"
      tools:context="com.example.hellotoast.MainActivity"
      android:orientation="vertical"&gt;
  
      &lt;Button
          android:id="@+id/button_toast"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:layout_marginStart="8dp"
          android:layout_marginTop="8dp"
          android:layout_marginEnd="8dp"
          android:background="@color/colorPrimary"
          android:onClick="showToast"
          android:text="@string/button_label_toast"
          android:textColor="@android:color/white" /&gt;
  
  
      &lt;TextView
          android:id="@+id/show_count"
  
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:orientation="vertical"
          android:layout_marginBottom="8dp"
          android:layout_marginEnd="8dp"
          android:layout_marginStart="8dp"
          android:layout_marginTop="8dp"
          android:background="#FFFF00"
          android:gravity="center_vertical"
          android:text="@string/count_initial_value"
          android:textAlignment="center"
          android:textColor="@color/colorPrimary"
          android:textSize="120sp"
          android:textStyle="bold"
          android:layout_centerHorizontal="true"
          android:layout_below="@+id/button_toast"
          android:layout_alignParentLeft="true"
          android:layout_alignParentStart="true"
          /&gt;
  
      &lt;Button
          android:id="@+id/button_count"
          android:layout_below="@+id/show_count"
          android:layout_width="match_parent"
          android:layout_height="wrap_content"
          android:layout_marginStart="8dp"
          android:layout_marginEnd="8dp"
          android:layout_marginBottom="8dp"
          android:background="@color/colorPrimary"
          android:onClick="countUp"
          android:text="@string/button_label_count"
          android:textColor="@android:color/white" /&gt;
  &lt;/RelativeLayout&gt;
  </code></pre>
  
  <p>activity_second.xml</p>
  
  <pre><code>&lt;?xml version="1.0" encoding="utf-8"?&gt;
  &lt;android.support.constraint.ConstraintLayout
      xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      xmlns:tools="http://schemas.android.com/tools"
      android:layout_width="match_parent"
      android:layout_height="match_parent"&gt;
  
      &lt;TextView
          android:id="@+id/textView"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:layout_marginStart="8dp"
          android:layout_marginTop="156dp"
          android:layout_marginEnd="8dp"
          android:text="Hello"
          android:textColor="#8BC34A"
          android:textColorHighlight="#00882A2A"
          app:layout_constraintEnd_toEndOf="parent"
          app:layout_constraintStart_toStartOf="parent"
          app:layout_constraintTop_toTopOf="parent" /&gt;
  
      &lt;TextView
          android:id="@+id/helloCount"
          android:layout_width="wrap_content"
          android:layout_height="wrap_content"
          android:layout_marginStart="8dp"
          android:layout_marginTop="8dp"
          android:layout_marginEnd="8dp"
          android:layout_marginBottom="8dp"
          android:text="TextView"
          android:textAppearance="@style/TextAppearance.AppCompat.Medium"
          android:textStyle="bold"
          app:layout_constraintBottom_toBottomOf="parent"
          app:layout_constraintEnd_toEndOf="parent"
          app:layout_constraintStart_toStartOf="parent"
          app:layout_constraintTop_toBottomOf="@+id/textView"
          app:layout_constraintVertical_bias="0.099" /&gt;
  
  &lt;/android.support.constraint.ConstraintLayout&gt;
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/pDn8k.jpg" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/pDn8k.jpg" alt="Click Hello button to launch HelloCount Activity. pressing count button increments counter"></a>
  <a href="https://i.stack.imgur.com/uEW7R.jpg" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/uEW7R.jpg" alt="HelloCount"></a></p>