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 com.android.tools.metalava.model.visitors 18 19 import com.android.tools.metalava.doclava1.ApiPredicate 20 import com.android.tools.metalava.model.ClassItem 21 import com.android.tools.metalava.model.FieldItem 22 import com.android.tools.metalava.model.Item 23 import com.android.tools.metalava.model.MethodItem 24 import com.android.tools.metalava.options 25 import java.util.function.Predicate 26 27 open class ApiVisitor( 28 /** 29 * Whether constructors should be visited as part of a [#visitMethod] call 30 * instead of just a [#visitConstructor] call. Helps simplify visitors that 31 * don't care to distinguish between the two cases. Defaults to true. 32 */ 33 visitConstructorsAsMethods: Boolean = true, 34 /** 35 * Whether inner classes should be visited "inside" a class; when this property 36 * is true, inner classes are visited before the [#afterVisitClass] method is 37 * called; when false, it's done afterwards. Defaults to false. 38 */ 39 nestInnerClasses: Boolean = false, 40 41 /** 42 * Whether to include inherited fields too 43 */ 44 val inlineInheritedFields: Boolean = true, 45 46 /** Comparator to sort methods with, or null to use natural (source) order */ 47 val methodComparator: Comparator<MethodItem>? = null, 48 49 /** Comparator to sort fields with, or null to use natural (source) order */ 50 val fieldComparator: Comparator<FieldItem>? = null, 51 52 /** The filter to use to determine if we should emit an item */ 53 val filterEmit: Predicate<Item>, 54 55 /** The filter to use to determine if we should emit a reference to an item */ 56 val filterReference: Predicate<Item>, 57 58 /** 59 * Whether the visitor should include visiting top-level classes that have 60 * nothing other than non-empty inner classes within. 61 * Typically these are not included in signature files, but when generating 62 * stubs we need to include them. 63 */ 64 val includeEmptyOuterClasses: Boolean = false, 65 66 /** 67 * Whether this visitor should visit elements that have not been 68 * annotated with one of the annotations passed in using the 69 * --show-annotation flag. This is normally true, but signature files 70 * sometimes sets this to false to make the signature file only contain 71 * the "diff" of the annotated API relative to the base API. 72 */ 73 val showUnannotated: Boolean = true 74 ) : ItemVisitor(visitConstructorsAsMethods, nestInnerClasses) { 75 constructor( 76 /** 77 * Whether constructors should be visited as part of a [#visitMethod] call 78 * instead of just a [#visitConstructor] call. Helps simplify visitors that 79 * don't care to distinguish between the two cases. Defaults to true. 80 */ 81 visitConstructorsAsMethods: Boolean = true, 82 /** 83 * Whether inner classes should be visited "inside" a class; when this property 84 * is true, inner classes are visited before the [#afterVisitClass] method is 85 * called; when false, it's done afterwards. Defaults to false. 86 */ 87 nestInnerClasses: Boolean = false, 88 89 /** Whether to ignore APIs with annotations in the --show-annotations list */ 90 ignoreShown: Boolean = true, 91 92 /** Whether to match APIs marked for removal instead of the normal API */ 93 remove: Boolean = false, 94 95 /** Comparator to sort methods with, or null to use natural (source) order */ 96 methodComparator: Comparator<MethodItem>? = null, 97 98 /** Comparator to sort fields with, or null to use natural (source) order */ 99 fieldComparator: Comparator<FieldItem>? = null 100 ) : this( 101 visitConstructorsAsMethods, nestInnerClasses, 102 true, methodComparator, 103 fieldComparator, 104 ApiPredicate(ignoreShown = ignoreShown, matchRemoved = remove), 105 ApiPredicate(ignoreShown = true, ignoreRemoved = remove) 106 ) 107 108 // The API visitor lazily visits packages only when there's a match within at least one class; 109 // this property keeps track of whether we've already visited the current package 110 var visitingPackage = false 111 includenull112 open fun include(cls: ClassItem): Boolean { 113 val filter = options.stubPackages 114 if (filter != null && !filter.matches(cls.containingPackage())) { 115 return false 116 } 117 118 return cls.emit || cls.codebase.preFiltered 119 } 120 } 121