1 // Copyright 2022 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 package com.google.api.generator.gapic.model; 16 17 import com.google.api.generator.engine.ast.CommentStatement; 18 import com.google.api.generator.engine.ast.LineComment; 19 import com.google.api.generator.gapic.utils.JavaStyle; 20 import com.google.auto.value.AutoValue; 21 import com.google.common.base.Preconditions; 22 23 // TODO: alicejli edit RegionTag to match other languages 24 /** 25 * This model represents a code sample region tag. Matching region start and end region tag comments 26 * are used to determine the boundaries of code snippets to be used in documentation. 27 */ 28 @AutoValue 29 public abstract class RegionTag { apiShortName()30 public abstract String apiShortName(); 31 apiVersion()32 public abstract String apiVersion(); 33 serviceName()34 public abstract String serviceName(); 35 rpcName()36 public abstract String rpcName(); 37 overloadDisambiguation()38 public abstract String overloadDisambiguation(); 39 isAsynchronous()40 public abstract Boolean isAsynchronous(); 41 builder()42 public static Builder builder() { 43 return new AutoValue_RegionTag.Builder() 44 .setApiVersion("") 45 .setApiShortName("") 46 .setOverloadDisambiguation("") 47 .setIsAsynchronous(false); 48 } 49 toBuilder()50 public abstract RegionTag.Builder toBuilder(); 51 52 /** 53 * Helper method to easily update region tag apiVersion. 54 * 55 * @param apiVersion String to replace region tag apiVersion 56 * @return RegionTag with updated apiVersion 57 */ withApiVersion(String apiVersion)58 public final RegionTag withApiVersion(String apiVersion) { 59 return toBuilder().setApiVersion(apiVersion).build(); 60 } 61 62 /** 63 * Helper method to easily update region tag apiShortName. 64 * 65 * @param apiShortName String to replace region tag apiShortName 66 * @return RegionTag with updated apiShortName 67 */ withApiShortName(String apiShortName)68 public final RegionTag withApiShortName(String apiShortName) { 69 return toBuilder().setApiShortName(apiShortName).build(); 70 } 71 72 /** 73 * Helper method to easily update region tag overloadDisambiguation. 74 * 75 * @param overloadDisambiguation String to replace region tag overloadDisambiguation 76 * @return RegionTag with updated overloadDisambiguation 77 */ withOverloadDisambiguation(String overloadDisambiguation)78 public final RegionTag withOverloadDisambiguation(String overloadDisambiguation) { 79 return toBuilder().setOverloadDisambiguation(overloadDisambiguation).build(); 80 } 81 82 @AutoValue.Builder 83 public abstract static class Builder { setApiVersion(String apiVersion)84 public abstract Builder setApiVersion(String apiVersion); 85 setApiShortName(String apiShortName)86 public abstract Builder setApiShortName(String apiShortName); 87 setServiceName(String serviceName)88 public abstract Builder setServiceName(String serviceName); 89 setRpcName(String rpcName)90 public abstract Builder setRpcName(String rpcName); 91 setOverloadDisambiguation(String overloadDisambiguation)92 public abstract Builder setOverloadDisambiguation(String overloadDisambiguation); 93 setIsAsynchronous(Boolean isAsynchronous)94 public abstract Builder setIsAsynchronous(Boolean isAsynchronous); 95 apiVersion()96 abstract String apiVersion(); 97 apiShortName()98 abstract String apiShortName(); 99 serviceName()100 abstract String serviceName(); 101 rpcName()102 abstract String rpcName(); 103 overloadDisambiguation()104 abstract String overloadDisambiguation(); 105 autoBuild()106 abstract RegionTag autoBuild(); 107 build()108 public final RegionTag build() { 109 setApiVersion(sanitizeAttributes(apiVersion())); 110 setApiShortName(sanitizeAttributes(apiShortName())); 111 setServiceName(sanitizeAttributes(serviceName())); 112 setRpcName(sanitizeAttributes(rpcName())); 113 setOverloadDisambiguation(sanitizeAttributes(overloadDisambiguation())); 114 return autoBuild(); 115 } 116 sanitizeAttributes(String attribute)117 private final String sanitizeAttributes(String attribute) { 118 return JavaStyle.toUpperCamelCase(attribute.replaceAll("[^a-zA-Z0-9]", "")); 119 } 120 } 121 122 public enum RegionTagRegion { 123 START, 124 END 125 } 126 127 /** 128 * Method to generate region tag comment text 129 * 130 * @return region tag comment text 131 */ generate()132 public String generate() { 133 Preconditions.checkState(!apiShortName().isEmpty(), "apiShortName can't be empty"); 134 Preconditions.checkState(!serviceName().isEmpty(), "serviceName can't be empty"); 135 Preconditions.checkState(!rpcName().isEmpty(), "rpcName can't be empty"); 136 137 String rt = apiShortName() + "_"; 138 if (!apiVersion().isEmpty()) { 139 rt = rt + apiVersion() + "_"; 140 } 141 rt = rt.toLowerCase() + "generated_" + serviceName() + "_" + rpcName(); 142 // TODO: @alicejli overloadDisambiguation will need to be updated to match other languages 143 if (!overloadDisambiguation().isEmpty()) { 144 rt = rt + "_" + overloadDisambiguation(); 145 } 146 if (isAsynchronous()) { 147 rt = rt + "_async"; 148 } else { 149 rt = rt + "_sync"; 150 } 151 152 return rt; 153 } 154 generateTag( RegionTagRegion regionTagRegion, String regionTagContent)155 public static CommentStatement generateTag( 156 RegionTagRegion regionTagRegion, String regionTagContent) { 157 return CommentStatement.withComment( 158 LineComment.withComment("[" + regionTagRegion.name() + " " + regionTagContent + "]")); 159 } 160 } 161