1 /*
2  * Copyright 2020 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 // @exportToFramework:skipFile()
17 package androidx.appsearch.app;
18 
19 import androidx.appsearch.exceptions.AppSearchException;
20 
21 import org.jspecify.annotations.NonNull;
22 
23 import java.util.List;
24 import java.util.Map;
25 
26 /**
27  * An interface for factories which can convert between instances of classes annotated with
28  * \@{@link androidx.appsearch.annotation.Document} and instances of {@link GenericDocument}.
29  *
30  * @param <T> The document class type this factory converts to and from {@link GenericDocument}.
31  */
32 public interface DocumentClassFactory<T> {
33     /**
34      * Returns the name of this schema type, e.g. {@code Email}.
35      *
36      * <p>This is the name used in queries for type restricts.
37      */
getSchemaName()38     @NonNull String getSchemaName();
39 
40     /** Returns the schema for this document class. */
getSchema()41     @NonNull AppSearchSchema getSchema() throws AppSearchException;
42 
43     /**
44      * Returns document classes that this document class depends on. This is useful so clients
45      * are not required to explicitly set all dependencies.
46      */
getDependencyDocumentClasses()47     @NonNull List<Class<?>> getDependencyDocumentClasses() throws AppSearchException;
48 
49     /**
50      * Converts an instance of the class annotated with
51      * \@{@link androidx.appsearch.annotation.Document} into a
52      * {@link androidx.appsearch.app.GenericDocument}.
53      */
toGenericDocument(@onNull T document)54     @NonNull GenericDocument toGenericDocument(@NonNull T document) throws AppSearchException;
55 
56     /**
57      * Converts a {@link androidx.appsearch.app.GenericDocument} into an instance of the document
58      * class. For nested document properties, this method should pass
59      * {@code documentClassMappingContext} down to the nested calls of
60      * {@link GenericDocument#toDocumentClass(Class, DocumentClassMappingContext)}.
61      *
62      * @param genericDoc                  The document to convert.
63      * @param documentClassMappingContext The context object that holds mapping information for
64      *                                    document classes and their parent types. This context
65      *                                    typically comes from
66      *                                    {@link SearchResult#getDocument(Class, Map)}.
67      */
68     @ExperimentalAppSearchApi
fromGenericDocument(@onNull GenericDocument genericDoc, @NonNull DocumentClassMappingContext documentClassMappingContext)69     @NonNull T fromGenericDocument(@NonNull GenericDocument genericDoc,
70             @NonNull DocumentClassMappingContext documentClassMappingContext)
71             throws AppSearchException;
72 }
73