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