Merge branch 'master' into py2-sunset

src/main/java/com/google/api/codegen/config/GapicInterfaceConfig.java

@@ -15,6 +15,7 @@
 package com.google.api.codegen.config;
 
 import com.google.api.codegen.CollectionConfigProto;
+import com.google.api.codegen.DeprecatedCollectionConfigProto;
 import com.google.api.codegen.InterfaceConfigProto;
 import com.google.api.codegen.MethodConfigProto;
 import com.google.api.codegen.RetryParamsDefinitionProto;
@@ -193,6 +194,8 @@ static GapicInterfaceConfig createInterfaceConfig(
         }
         resourcesBuilder.add((SingleResourceNameConfig) resourceName);
       }
+    } else {
+      addDeprecatedResources(diagCollector, resourcesBuilder, interfaceConfigProto, language);
     }
     ImmutableSet<SingleResourceNameConfig> singleResourceNames = resourcesBuilder.build();
 
@@ -288,6 +291,23 @@ private static ImmutableMap<String, GapicMethodConfig> createMethodConfigMap(
     }
   }
 
+  /** Add deprecated resource definitions into singleResources. */
+  private static void addDeprecatedResources(
+      DiagCollector diagCollector,
+      ImmutableSet.Builder<SingleResourceNameConfig> singleResources,
+      InterfaceConfigProto interfaceConfigProto,
+      TargetLanguage targetLanguage) {
+    for (DeprecatedCollectionConfigProto deprecatedResource :
+        interfaceConfigProto.getDeprecatedCollectionsList()) {
+      // We can safely assign null here; wedon't care about assigned proto file
+      // for deprecated resource names
+      SingleResourceNameConfig deprecatedResourceConfig =
+          SingleResourceNameConfig.createDeprecatedSingleResourceName(
+              diagCollector, deprecatedResource, null, targetLanguage);
+      singleResources.add(deprecatedResourceConfig);
+    }
+  }
+
   /** Returns the GapicMethodConfig for the given method. */
   @Override
   public GapicMethodConfig getMethodConfig(MethodModel method) {

src/main/java/com/google/api/codegen/config/SingleResourceNameConfig.java

@@ -16,6 +16,7 @@
 
 import com.google.api.codegen.CollectionConfigProto;
 import com.google.api.codegen.CollectionLanguageOverridesProto;
+import com.google.api.codegen.DeprecatedCollectionConfigProto;
 import com.google.api.codegen.common.TargetLanguage;
 import com.google.api.codegen.util.Name;
 import com.google.api.pathtemplate.PathTemplate;
@@ -82,6 +83,31 @@ public static SingleResourceNameConfig createSingleResourceName(
     return builder.build();
   }
 
+  @Nullable
+  public static SingleResourceNameConfig createDeprecatedSingleResourceName(
+      DiagCollector diagCollector,
+      DeprecatedCollectionConfigProto deprecatedResource,
+      @Nullable ProtoFile file,
+      TargetLanguage language) {
+
+    // Entity names of resource names parsed from proto annotations are in upper camel case.
+    String upperCamelEntityName = Name.anyLower(deprecatedResource.getEntityName()).toUpperCamel();
+
+    // Reconstruct a CollectionConfigProto as specified in gapic config v1
+    CollectionConfigProto resourceV1 =
+        CollectionConfigProto.newBuilder()
+            .setEntityName(upperCamelEntityName)
+            .setNamePattern(deprecatedResource.getNamePattern())
+            .build();
+    SingleResourceNameConfig resourceConfigV1 =
+        createSingleResourceName(diagCollector, resourceV1, file, language);
+
+    // If a SingleResourceNameConfig is created, mark it as deprecated too.
+    return resourceConfigV1 == null
+        ? null
+        : resourceConfigV1.toBuilder().setDeprecated(true).build();
+  }
+
   /** Returns the name pattern for the resource name config. */
   public abstract String getNamePattern();
 
@@ -110,8 +136,11 @@ public ResourceNameType getResourceNameType() {
     return ResourceNameType.SINGLE;
   }
 
+  /** Whether the resource name will be removed in the annotation world. */
+  public abstract boolean getDeprecated();
+
   public static SingleResourceNameConfig.Builder newBuilder() {
-    return new AutoValue_SingleResourceNameConfig.Builder();
+    return new AutoValue_SingleResourceNameConfig.Builder().setDeprecated(false);
   }
 
   public String getUnqualifiedEntityId() {
@@ -134,6 +163,8 @@ public abstract static class Builder {
 
     public abstract Builder setAssignedProtoFile(ProtoFile val);
 
+    public abstract Builder setDeprecated(boolean val);
+
     public abstract SingleResourceNameConfig build();
   }
 }

src/main/java/com/google/api/codegen/transformer/PathTemplateTransformer.java

@@ -224,7 +224,8 @@ public List<FormatResourceFunctionView> generateFormatResourceFunctions(
               .pathTemplateName(namer.getPathTemplateName(interfaceConfig, resourceNameConfig))
               .pathTemplateGetterName(
                   namer.getPathTemplateNameGetter(interfaceConfig, resourceNameConfig))
-              .pattern(resourceNameConfig.getNamePattern());
+              .pattern(resourceNameConfig.getNamePattern())
+              .isResourceNameDeprecated(resourceNameConfig.getDeprecated());
       List<ResourceIdParamView> resourceIdParams = new ArrayList<>();
       for (String var : resourceNameConfig.getNameTemplate().vars()) {
         ResourceIdParamView param =
@@ -263,6 +264,7 @@ public List<ParseResourceFunctionView> generateParseResourceFunctions(InterfaceC
                     namer.getPathTemplateNameGetter(interfaceConfig, resourceNameConfig))
                 .entityNameTypeName(namer.getResourceTypeName(resourceNameConfig))
                 .entityNameParamName(namer.getEntityNameParamName(resourceNameConfig))
+                .isResourceNameDeprecated(resourceNameConfig.getDeprecated())
                 .outputResourceId(var);
         functions.add(function.build());
       }

src/main/java/com/google/api/codegen/viewmodel/FormatResourceFunctionView.java

@@ -33,8 +33,11 @@ public abstract class FormatResourceFunctionView {
 
   public abstract String pattern();
 
+  /** True iff this resource name will cease to exist in the proto annotation world. */
+  public abstract boolean isResourceNameDeprecated();
+
   public static Builder newBuilder() {
-    return new AutoValue_FormatResourceFunctionView.Builder();
+    return new AutoValue_FormatResourceFunctionView.Builder().isResourceNameDeprecated(false);
   }
 
   @AutoValue.Builder
@@ -53,6 +56,8 @@ public abstract static class Builder {
 
     public abstract Builder pattern(String val);
 
+    public abstract Builder isResourceNameDeprecated(boolean val);
+
     public abstract FormatResourceFunctionView build();
   }
 }

src/main/java/com/google/api/codegen/viewmodel/ParseResourceFunctionView.java

@@ -32,8 +32,11 @@ public abstract class ParseResourceFunctionView {
 
   public abstract String outputResourceId();
 
+  /** True iff this resource name will cease to exist in the proto annotation world. */
+  public abstract boolean isResourceNameDeprecated();
+
   public static Builder newBuilder() {
-    return new AutoValue_ParseResourceFunctionView.Builder();
+    return new AutoValue_ParseResourceFunctionView.Builder().isResourceNameDeprecated(false);
   }
 
   @AutoValue.Builder
@@ -52,6 +55,8 @@ public abstract static class Builder {
 
     public abstract Builder outputResourceId(String val);
 
+    public abstract Builder isResourceNameDeprecated(boolean val);
+
     public abstract ParseResourceFunctionView build();
   }
 }

src/main/proto/com/google/api/codegen/config.proto

@@ -161,6 +161,14 @@ message InterfaceConfigProto {
   // A list of resource collection configurations.
   repeated CollectionConfigProto collections = 10;
 
+  // A list of configurations for deprecated resource collections.
+  //
+  // This field is introduced to avoid breaking changes in client surface and 
+  // make the migration to proto annoations smoother. The generator will continue
+  // to generate resource name classes or helper functions for these resources,
+  // and mark the as deprecated.
+  repeated DeprecatedCollectionConfigProto deprecated_collections = 11;
+
   // A list of method configurations.
   repeated MethodConfigProto methods = 20;
 
@@ -203,6 +211,15 @@ message CollectionConfigProto {
   repeated CollectionLanguageOverridesProto language_overrides = 3;
 }
 
+message DeprecatedCollectionConfigProto {
+  // The pattern of the deprecated resource name.
+  string name_pattern = 1;
+
+  // The entity name of the deprecated resource name.
+  string entity_name = 2;
+}
+
+
 message CollectionLanguageOverridesProto {
   // The language of the generated code.
   string language = 1;

src/main/proto/com/google/api/codegen/v2/config_v2.proto

@@ -97,6 +97,14 @@ message InterfaceConfigProto {
   // A list of resource collection configurations.
   repeated CollectionConfigProto collections = 10;
 
+  // A list of configurations for deprecated resource collections.
+  //
+  // This field is introduced to avoid breaking changes in client surface and 
+  // make the migration to proto annoations smoother. The generator will continue
+  // to generate resource name classes or helper functions for these resources,
+  // and mark the as deprecated.
+  repeated DeprecatedCollectionConfigProto deprecated_collections = 11;
+
   // A list of method configurations.
   repeated MethodConfigProto methods = 20;
 
@@ -132,6 +140,14 @@ message CollectionConfigProto {
   repeated CollectionLanguageOverridesProto language_overrides = 3;
 }
 
+message DeprecatedCollectionConfigProto {
+  // The pattern of the deprecated resource name.
+  string name_pattern = 1;
+
+  // The entity name of the deprecated resource name.
+  string entity_name = 2;
+}
+
 message CollectionLanguageOverridesProto {
   // The language of the generated code.
   string language = 1;

src/main/resources/com/google/api/codegen/nodejs/main.snip

@@ -369,6 +369,9 @@
 
 @private createResourceFunction(function, apiName)
   /**
+  @if function.isResourceNameDeprecated
+    {@""} * @@deprecated Multi-pattern resource names will have unified formatting and parsing helper functions. This helper function will be deleted in the next major version.
+  @end
    * Return a fully-qualified {@function.entityName} resource name string.
    *
    @join param : function.resourceIdParams
@@ -385,6 +388,9 @@
 
 @private createMatchFunction(function, apiName)
   /**
+  @if function.isResourceNameDeprecated
+    {@""} * @@deprecated Multi-pattern resource names will have unified formatting and parsing helper functions. This helper function will be deleted in the next major version.
+  @end
    * Parse the {@function.entityNameParamName} from a {@function.entityName} resource.
    *
    * @@param {String} {@function.entityNameParamName}

src/main/resources/com/google/api/codegen/py/main.snip

@@ -61,7 +61,9 @@
             @join function : api.formatResourceFunctions
                 @@classmethod
                 def {@function.name}(cls, {@createResourceFunctionParams(function.resourceIdParams)}):
-                    """Return a fully-qualified {@function.entityName} string."""
+                    """DEPRECATED. Return a fully-qualified {@function.entityName} string."""
+                    warnings.warn('Resource name helper functions are deprecated.',
+                        PendingDeprecationWarning, stacklevel=1)
                     return google.api_core.path_template.expand(
                         '{@function.pattern}',
                         {@createRenderParams(function.resourceIdParams)}

src/main/resources/com/google/api/codegen/ruby/main.snip

@@ -280,6 +280,10 @@
 
 @private createResourceFunction(function)
   @# Returns a fully-qualified {@function.entityName} resource name string.
+  @if function.isResourceNameDeprecated
+    @# @@deprecated Multi-pattern resource names will have unified creation and parsing helper functions.
+    @# This helper function will be deleted in the next major version.
+  @end
   @join param : function.resourceIdParams
     @# @@param {@param.docName} [String]
   @end

src/test/java/com/google/api/codegen/gapic/testdata/py/python_library.baseline

@@ -1202,7 +1202,9 @@ class LibraryServiceClient(object):
 
     @classmethod
     def archived_book_path(cls, archive_path, book_id):
-        """Return a fully-qualified archived_book string."""
+        """DEPRECATED. Return a fully-qualified archived_book string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'archives/{archive_path}/books/{book_id=**}',
             archive_path=archive_path,
@@ -1211,7 +1213,9 @@ class LibraryServiceClient(object):
 
     @classmethod
     def book_path(cls, shelf_id, book_id):
-        """Return a fully-qualified book string."""
+        """DEPRECATED. Return a fully-qualified book string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'shelves/{shelf_id}/books/{book_id}',
             shelf_id=shelf_id,
@@ -1220,15 +1224,19 @@ class LibraryServiceClient(object):
 
     @classmethod
     def folder_path(cls, folder):
-        """Return a fully-qualified folder string."""
+        """DEPRECATED. Return a fully-qualified folder string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'folders/{folder}',
             folder=folder,
         )
 
     @classmethod
     def location_path(cls, project, location):
-        """Return a fully-qualified location string."""
+        """DEPRECATED. Return a fully-qualified location string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'projects/{project}/locations/{location}',
             project=project,
@@ -1237,15 +1245,19 @@ class LibraryServiceClient(object):
 
     @classmethod
     def project_path(cls, project):
-        """Return a fully-qualified project string."""
+        """DEPRECATED. Return a fully-qualified project string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'projects/{project}',
             project=project,
         )
 
     @classmethod
     def project_book_path(cls, project, book):
-        """Return a fully-qualified project_book string."""
+        """DEPRECATED. Return a fully-qualified project_book string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'projects/{project}/books/{book}',
             project=project,
@@ -1254,7 +1266,9 @@ class LibraryServiceClient(object):
 
     @classmethod
     def shelf_path(cls, shelf_id):
-        """Return a fully-qualified shelf string."""
+        """DEPRECATED. Return a fully-qualified shelf string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'shelves/{shelf_id}',
             shelf_id=shelf_id,
@@ -4345,7 +4359,9 @@ class MyProtoClient(object):
 
     @classmethod
     def return_path(cls, shelf, book, return_):
-        """Return a fully-qualified return string."""
+        """DEPRECATED. Return a fully-qualified return string."""
+        warnings.warn('Resource name helper functions are deprecated.',
+            PendingDeprecationWarning, stacklevel=1)
         return google.api_core.path_template.expand(
             'shelves/{shelf}/books/{book}/returns/{return}',
             shelf=shelf,