1 /* 2 * Copyright (C) 2024 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 com.android.tools.metalava.model.item 18 19 import com.android.tools.metalava.model.ClassItem 20 import com.android.tools.metalava.model.Codebase 21 import com.android.tools.metalava.model.Item 22 import com.android.tools.metalava.model.ItemDocumentation.Companion.toItemDocumentationFactory 23 import com.android.tools.metalava.model.PackageItem 24 import com.android.tools.metalava.model.VisibilityLevel 25 import com.android.tools.metalava.model.createImmutableModifiers 26 27 /** 28 * A factory that will create a [DefaultCodebase] for a specific [CodebaseAssembler]. 29 * 30 * An implementation of this must not try and access any [CodebaseAssembler] functions as it will 31 * not be fully initialized at the time this is called. 32 */ 33 typealias DefaultCodebaseFactory = (CodebaseAssembler) -> DefaultCodebase 34 35 /** 36 * A [CodebaseAssembler] is responsible for providing a [Codebase] with access to classes which are 37 * present in the underlying model but not yet present in the [Codebase]. 38 * 39 * Although, the interface is simple, the implementation will do a vast amount of the work of 40 * mapping an underlying model's representation of the API to a [Codebase], if not all of it. 41 */ 42 interface CodebaseAssembler { 43 /** 44 * Create a [DefaultPackageItem] for package called [packageName], with additional information 45 * from [packageDoc] whose containing package, if any, is [containingPackage]. 46 */ createPackageItemnull47 fun createPackageItem( 48 packageName: String, 49 packageDoc: PackageDoc, 50 containingPackage: PackageItem?, 51 ): DefaultPackageItem 52 53 /** 54 * A [ClassItem] with [qualifiedName] could not be found in the associated [Codebase] so look in 55 * the underlying model's set of classes to see if one could be found there. If it could then 56 * create a [ClassItem] representation of it and return that, otherwise return null. 57 */ 58 fun createClassFromUnderlyingModel(qualifiedName: String): ClassItem? 59 60 /** 61 * Overrideable hook, called from [DefaultCodebase.registerClass] for each new 62 * [DefaultClassItem]. 63 */ 64 fun newClassRegistered(classItem: DefaultClassItem) {} 65 } 66 67 /** 68 * Base [CodebaseAssembler] for use by models that do not use model specific implementations of the 69 * [Item] classes. 70 */ 71 abstract class DefaultCodebaseAssembler : CodebaseAssembler { 72 73 /** Factory for creating appropriate [Item] subclasses for the [Codebase] this is assembling. */ 74 abstract val itemFactory: DefaultItemFactory 75 createPackageItemnull76 override fun createPackageItem( 77 packageName: String, 78 packageDoc: PackageDoc, 79 containingPackage: PackageItem?, 80 ): DefaultPackageItem { 81 val documentationFactory = packageDoc.commentFactory ?: "".toItemDocumentationFactory() 82 return itemFactory.createPackageItem( 83 packageDoc.fileLocation, 84 packageDoc.modifiers ?: createImmutableModifiers(VisibilityLevel.PUBLIC), 85 documentationFactory, 86 packageName, 87 containingPackage, 88 packageDoc.overview, 89 ) 90 } 91 } 92