Home | History | Annotate | Download | only in navigation 
      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.navigation;
     18 
     19 import android.annotation.SuppressLint;
     20 import android.support.annotation.NonNull;
     21 import android.support.annotation.Nullable;
     22 
     23 /**
     24  * A NavigationProvider stores a set of {@link Navigator}s that are valid ways to navigate
     25  * to a destination.
     26  */
     27 @SuppressLint("TypeParameterUnusedInFormals")
     28 public interface NavigatorProvider {
     29     /**
     30      * Retrieves a registered {@link Navigator} using the name provided by the
     31      * {@link Navigator.Name Navigator.Name annotation}.
     32      *
     33      * @param navigatorClass class of the navigator to return
     34      * @return the registered navigator with the given {@link Navigator.Name}
     35      *
     36      * @throws IllegalArgumentException if the Navigator does not have a
     37      * {@link Navigator.Name Navigator.Name annotation}
     38      * @throws IllegalStateException if the Navigator has not been added
     39      *
     40      * @see #addNavigator(Navigator)
     41      */
     42     @NonNull
     43     <D extends NavDestination, T extends Navigator<? extends D>> T getNavigator(
     44             @NonNull Class<T> navigatorClass);
     45 
     46     /**
     47      * Retrieves a registered {@link Navigator} by name.
     48      *
     49      * @param name name of the navigator to return
     50      * @return the registered navigator with the given name
     51      *
     52      * @throws IllegalStateException if the Navigator has not been added
     53      *
     54      * @see #addNavigator(String, Navigator)
     55      */
     56     @NonNull
     57     <D extends NavDestination, T extends Navigator<? extends D>> T getNavigator(
     58             @NonNull String name);
     59 
     60     /**
     61      * Register a navigator using the name provided by the
     62      * {@link Navigator.Name Navigator.Name annotation}. {@link NavDestination destinations} may
     63      * refer to any registered navigator by name for inflation. If a navigator by this name is
     64      * already registered, this new navigator will replace it.
     65      *
     66      * @param navigator navigator to add
     67      * @return the previously added Navigator for the name provided by the
     68      * {@link Navigator.Name Navigator.Name annotation}, if any
     69      */
     70     @Nullable
     71     Navigator<? extends NavDestination> addNavigator(
     72             @NonNull Navigator<? extends NavDestination> navigator);
     73 
     74     /**
     75      * Register a navigator by name. {@link NavDestination destinations} may refer to any
     76      * registered navigator by name for inflation. If a navigator by this name is already
     77      * registered, this new navigator will replace it.
     78      *
     79      * @param name name for this navigator
     80      * @param navigator navigator to add
     81      * @return the previously added Navigator for the given name, if any
     82      */
     83     @Nullable
     84     Navigator<? extends NavDestination> addNavigator(@NonNull String name,
     85             @NonNull Navigator<? extends NavDestination> navigator);
     86 }
     87