1 /*
2  * Copyright 2025 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.webkit;
18 
19 import android.os.Bundle;
20 import android.webkit.WebView;
21 
22 import org.jspecify.annotations.Nullable;
23 
24 /**
25  * The Navigation instance passed by the navigation callbacks.
26  * <p>
27  * The same object will be used by the relevant callbacks for the same navigation,
28  * allowing the instance itself to be used as a key/ID to connect the callbacks for
29  * the same navigations.
30  */
31 @WebNavigationClient.ExperimentalNavigationCallback
32 public interface Navigation {
33     /**
34      * Returns the Page that the navigation commits into.
35      * <p>
36      * Note: This method will initially return {@code null} when navigation begins.
37      * If the navigation successfully commits a page, this method will return the corresponding
38      * {@link Page} object. This could be a newly created {@link Page} or a previously seen
39      * {@link Page} in the case of BFCache (Back/Forward Cache).
40      * <p>
41      * Note: Once this method returns a non-null {@link Page} object for a
42      * specific navigation, it will always return the same {@link Page} object for that navigation.
43      * <p>
44      *
45      * @return The {@link Page} object, or {@code null} if the navigation does not commit or
46      * result in a Page
47      * (e.g., <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/204">204</a>
48      * /download).
49      */
50     @Nullable
getPage()51     Page getPage();
52 
53     /**
54      * Indicates whether the navigation is initiated by the page/renderer (e.g., link clicks, JS
55      * script)
56      * instead of the browser/app (e.g., loadUrl calls).
57      *
58      * @return True if page-initiated, false otherwise.
59      */
wasInitiatedByPage()60     boolean wasInitiatedByPage();
61 
62     /**
63      * Indicates whether the navigation is a same-document navigation.
64      *
65      * @return True if same-document, false otherwise.
66      */
isSameDocument()67     boolean isSameDocument();
68 
69     /**
70      * Indicates whether the navigation is a reload navigation.
71      *
72      * @return True if reload, false otherwise.
73      */
isReload()74     boolean isReload();
75 
76     /**
77      * Indicates whether the navigation is a history navigation.
78      *
79      * @return True if history, false otherwise.
80      */
isHistory()81     boolean isHistory();
82 
83     /**
84      * Indicates whether the navigation is a history back navigation.
85      *
86      * @return True if back navigation, false otherwise.
87      */
isBack()88     boolean isBack();
89 
90     /**
91      * Indicates whether the navigation is a history forward navigation.
92      *
93      * @return True if forward navigation, false otherwise.
94      */
isForward()95     boolean isForward();
96 
97     /**
98      * Indicates whether the navigation committed (i.e., did not get aborted/return 204/etc).
99      *
100      * @return True if committed, false otherwise.
101      */
didCommit()102     boolean didCommit();
103 
104     /**
105      * Indicates whether the navigation committed an error page.
106      *
107      * @return True if an error page was committed, false otherwise.
108      */
didCommitErrorPage()109     boolean didCommitErrorPage();
110 
111     /**
112      * Returns the status code received by the navigation.
113      *
114      * @return The HTTP status code.
115      */
getStatusCode()116     int getStatusCode();
117 
118     /**
119      * Indicates whether the navigation is a restore navigation after calling
120      * {@link WebView#restoreState(Bundle)}.
121      *
122      * @return True if session restore, false otherwise.
123      */
isRestore()124     boolean isRestore();
125 
126 }
127