1 /* 2 * Copyright (C) 2018 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 package com.google.currysrc.aosp; 17 18 import com.google.currysrc.api.process.Processor; 19 import com.google.currysrc.api.process.ast.BodyDeclarationLocators; 20 import com.google.currysrc.processors.AddAnnotation; 21 import com.google.currysrc.processors.AnnotationInfo.AnnotationClass; 22 import com.google.currysrc.processors.AnnotationInfo.Placeholder; 23 import java.io.IOException; 24 import java.nio.file.Path; 25 26 /** 27 * Utility methods for manipulating AOSP annotations. 28 */ 29 public final class Annotations { 30 Annotations()31 private Annotations() { 32 } 33 34 /** 35 * Add android.compat.annotation.UnsupportedAppUsage annotations to the body declarations 36 * specified in the supplied file. 37 * 38 * <p>The supplied file is a JSON file consisting of a top level array containing objects of the 39 * following structure: 40 * <pre>{@code 41 * { 42 * "@location": "<body declaration location>", 43 * "maxTargetSdk": <int>|<placeholder>, 44 * "trackingBug": <long>|<placeholder>, 45 * "expectedSignature": <string>, 46 * "publicAlternatives": <string>, 47 * } 48 * }</pre> 49 * 50 * <p>Where: 51 * <ul> 52 * <li>{@code <body declaration location>} is in the format expected by 53 * {@link BodyDeclarationLocators#fromStringForm(String)}.</li> 54 * <li>{@code <int>} and {@code <long>} are numbers that are inserted into the source as literal 55 * primitive values.</li> 56 * <li>{@code <string>} is a quoted JSON string that is inserted into the source as a literal 57 * string.</li> 58 * <li>{@code <placeholder>} is a quoted JSON string that is inserted into the source as if it 59 * was a constant expression. It is used to reference constants in annotation values, e.g. 60 * {@code android.compat.annotation.UnsupportedAppUsage.VERSION_CODES.P}.</li> 61 * </ul> 62 * 63 * <p>See external/icu/tools/srcgen/unsupported-app-usage.json for an example. 64 * 65 * @param unsupportedAppUsagePath the location of the file. 66 * @return the {@link Processor}. 67 */ addUnsupportedAppUsage(Path unsupportedAppUsagePath)68 public static AddAnnotation addUnsupportedAppUsage(Path unsupportedAppUsagePath) { 69 AnnotationClass annotationClass = new AnnotationClass( 70 "android.compat.annotation.UnsupportedAppUsage") 71 .addProperty("maxTargetSdk", int.class) 72 .addProperty("trackingBug", long.class) 73 .addProperty("implicitMember", String.class) 74 .addProperty("expectedSignature", String.class) 75 .addProperty("publicAlternatives", String.class); 76 try { 77 return AddAnnotation.fromJsonFile(annotationClass, unsupportedAppUsagePath); 78 } catch (IOException e) { 79 throw new IllegalStateException("Could not read JSON from " + unsupportedAppUsagePath, e); 80 } 81 } 82 addFlaggedApi(Path flaggedApiPath)83 public static AddAnnotation addFlaggedApi(Path flaggedApiPath) { 84 AnnotationClass annotationClass = new AnnotationClass( 85 "android.annotation.FlaggedApi") 86 .addProperty("value", Placeholder.class); 87 try { 88 return AddAnnotation.fromJsonFile(annotationClass, flaggedApiPath); 89 } catch (IOException e) { 90 throw new IllegalStateException("Could not read JSON from " + flaggedApiPath, e); 91 } 92 } 93 } 94