Add backcompat stubs for optional header params

changelog/@unreleased/pr-967.v2.yml

@@ -0,0 +1,7 @@
+type: improvement
+improvement:
+  description: When optional header params are added, Retrofit and Jersey generated
+    code now includes deprecated methods without these headers - similar to those
+    generated when optional query params are added.
+  links:
+  - https://github.com/palantir/conjure-java/pull/967

conjure-java-core/src/main/java/com/palantir/conjure/java/services/JerseyServiceGenerator.java

@@ -186,19 +186,65 @@ private MethodSpec generateServiceMethod(
     /** Provides a linear expansion of optional query arguments to improve Java back-compat. */
     private List<MethodSpec> generateCompatibilityBackfillServiceMethods(
             EndpointDefinition endpointDef, TypeMapper returnTypeMapper, TypeMapper argumentTypeMapper) {
+        List<ArgumentDefinition> headerArgs = new ArrayList<>();
         List<ArgumentDefinition> queryArgs = new ArrayList<>();
 
         for (ArgumentDefinition arg : endpointDef.getArgs()) {
+            if (arg.getParamType().accept(ParameterTypeVisitor.IS_HEADER)
+                    && arg.getType().accept(DefaultableTypeVisitor.INSTANCE)) {
+                headerArgs.add(arg);
+            }
             if (arg.getParamType().accept(ParameterTypeVisitor.IS_QUERY)
                     && arg.getType().accept(DefaultableTypeVisitor.INSTANCE)) {
                 queryArgs.add(arg);
             }
         }
 
+        if (!headerArgs.isEmpty()) {
+            // ensure the correct ordering of parameters by creating the complete sorted parameter list
+            List<ParameterSpec> sortedParams = createServiceMethodParameters(endpointDef, argumentTypeMapper, false);
+            List<ArgumentDefinition> sortedArgs = sortedParams.stream()
+                    .map(param -> endpointDef.getArgs().stream()
+                            .filter(arg -> arg.getArgName().get().equals(param.name))
+                            .findFirst())
+                    .filter(Optional::isPresent)
+                    .map(Optional::get)
+                    .collect(Collectors.toList());
+
+            Optional<ArgumentDefinition> firstParameterAfterLastHeader = Optional.empty();
+            for (int i = 0; i < sortedArgs.size(); i++) {
+                ArgumentDefinition arg = sortedArgs.get(i);
+                boolean isOptionalHeaderArg = arg.getParamType().accept(ParameterTypeVisitor.IS_HEADER)
+                        && arg.getType().accept(DefaultableTypeVisitor.INSTANCE);
+                if (isOptionalHeaderArg) {
+                    if (i < (sortedArgs.size() - 1)) {
+                        firstParameterAfterLastHeader = Optional.of(sortedArgs.get(i + 1));
+                    } else {
+                        firstParameterAfterLastHeader = Optional.empty();
+                    }
+                }
+            }
+
+            if (!firstParameterAfterLastHeader.isPresent()
+                    || firstParameterAfterLastHeader.get().getType().accept(DefaultableTypeVisitor.INSTANCE)) {
+                // The last optional header is not followed by a non-optional parameter, so we can't guarantee
+                // uniqueness of signatures if we generate backfill methods for headers.
+                headerArgs = ImmutableList.of();
+            }
+        }
+
         List<MethodSpec> alternateMethods = new ArrayList<>();
-        for (int i = 0; i < queryArgs.size(); i++) {
-            alternateMethods.add(createCompatibilityBackfillMethod(
-                    endpointDef, returnTypeMapper, argumentTypeMapper, queryArgs.subList(i, queryArgs.size())));
+        for (int j = 0; j <= headerArgs.size(); j++) {
+            for (int i = 0; i <= queryArgs.size(); i++) {
+                List<ArgumentDefinition> extraHeaderArgs = headerArgs.subList(j, headerArgs.size());
+                List<ArgumentDefinition> extraQueryArgs = queryArgs.subList(i, queryArgs.size());
+                List<ArgumentDefinition> extraArgs = new ArrayList<>(extraHeaderArgs);
+                extraArgs.addAll(extraQueryArgs);
+                if (!extraArgs.isEmpty()) {
+                    alternateMethods.add(createCompatibilityBackfillMethod(
+                            endpointDef, returnTypeMapper, argumentTypeMapper, extraArgs));
+                }
+            }
         }
 
         return alternateMethods;

conjure-java-core/src/main/java/com/palantir/conjure/java/services/Retrofit2ServiceGenerator.java

@@ -201,23 +201,32 @@ private HttpPath replaceEncodedPathArgs(HttpPath httpPath) {
     private List<MethodSpec> generateCompatibilityBackfillServiceMethods(
             EndpointDefinition endpointDef, TypeMapper returnTypeMapper, TypeMapper argumentTypeMapper) {
         Set<ArgumentName> encodedPathArgs = extractEncodedPathArgs(endpointDef.getHttpPath());
+        List<ArgumentDefinition> headerArgs = new ArrayList<>();
         List<ArgumentDefinition> queryArgs = new ArrayList<>();
 
         for (ArgumentDefinition arg : endpointDef.getArgs()) {
+            if (arg.getParamType().accept(ParameterTypeVisitor.IS_HEADER)
+                    && arg.getType().accept(DefaultableTypeVisitor.INSTANCE)) {
+                headerArgs.add(arg);
+            }
             if (arg.getParamType().accept(ParameterTypeVisitor.IS_QUERY)
                     && arg.getType().accept(DefaultableTypeVisitor.INSTANCE)) {
                 queryArgs.add(arg);
             }
         }
 
         List<MethodSpec> alternateMethods = new ArrayList<>();
-        for (int i = 0; i < queryArgs.size(); i++) {
-            alternateMethods.add(createCompatibilityBackfillMethod(
-                    endpointDef,
-                    returnTypeMapper,
-                    argumentTypeMapper,
-                    encodedPathArgs,
-                    queryArgs.subList(i, queryArgs.size())));
+        for (int j = 0; j <= headerArgs.size(); j++) {
+            for (int i = 0; i <= queryArgs.size(); i++) {
+                List<ArgumentDefinition> extraHeaderArgs = headerArgs.subList(j, headerArgs.size());
+                List<ArgumentDefinition> extraQueryArgs = queryArgs.subList(i, queryArgs.size());
+                List<ArgumentDefinition> extraArgs = new ArrayList<>(extraHeaderArgs);
+                extraArgs.addAll(extraQueryArgs);
+                if (!extraArgs.isEmpty()) {
+                    alternateMethods.add(createCompatibilityBackfillMethod(
+                            endpointDef, returnTypeMapper, argumentTypeMapper, encodedPathArgs, extraArgs));
+                }
+            }
         }
 
         return alternateMethods;

conjure-java-core/src/test/java/com/palantir/conjure/java/TestBase.java

@@ -56,7 +56,7 @@ protected static void validateGeneratorOutput(List<Path> files, Path outputDir,
                 Files.deleteIfExists(output);
                 Files.copy(file, output);
             }
-            assertThat(readFromFile(file)).isEqualTo(readFromFile(output));
+            assertThat(readFromFile(file)).describedAs(output.toString()).isEqualTo(readFromFile(output));
         }
     }
 }

conjure-java-core/src/test/resources/example-service.yml

@@ -224,6 +224,21 @@ services:
             type: optional<rid>
             param-type: query
 
+      testOptionalHeaderParam:
+        http: POST /test-optional-header-param
+        args:
+          query: string
+          maybeHeader:
+            type: optional<string>
+            param-type: header
+            param-id: MaybeHeader
+          implicit:
+            type: rid
+            param-type: query
+          maybeQuery:
+            type: optional<rid>
+            param-type: query
+
       testBoolean:
         http: GET /boolean
         returns: boolean