1 /*
2  * Copyright 2022 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.credentials.exceptions.domerrors
18 
19 import androidx.annotation.RestrictTo
20 import androidx.annotation.VisibleForTesting
21 import androidx.credentials.exceptions.publickeycredential.CreatePublicKeyCredentialDomException
22 
23 /**
24  * While CredentialManager flows use Exceptions, in some cases, the exceptions are focused on a
25  * range of widely used, uncommonly named 'errors'. This class should be used to generate subclass
26  * errors, packaged under an Exception superclass. Please see the example below for usage details.
27  *
28  * For this codebase, we use this widely with errors from the public key credential and general web
29  * error specs, shown [here](https://webidl.spec.whatwg.org/#idl-DOMException-error-names).
30  *
31  * In this example, we create a wrapper exception named [CreatePublicKeyCredentialDomException].
32  * This contains a constructor that accepts a DomError. We then employ various sub classes to the
33  * DomError for individual error types, such as [AbortError].
34  *
35  * ```
36  * class AbortError : DomError(type_var) { ... }
37  * ```
38  *
39  * Then it is expected that when abort errors show up in code, one can create the wrapper exception
40  * with the designed DomError subclass.
41  *
42  * ```
43  * // ... (logic checking for abort error) ...
44  * val exception = CreatePublicKeyCredentialDomException(AbortError(), e.getMessage())
45  * // ... (logic using exception to throw or pass in callback) ...
46  * ```
47  *
48  * This utilization may vary by use case.
49  */
50 abstract class DomError(
51     @get:VisibleForTesting(otherwise = VisibleForTesting.PACKAGE_PRIVATE)
52     @get:RestrictTo(RestrictTo.Scope.LIBRARY_GROUP)
53     open val type: String
54 )
55