[BUG][JAVA] Field named 'java' shadows package namespace causing compilation failure in v7.18.0+

[janisz]

Bug Report Checklist

• Have you provided a full/minimal spec to reproduce the issue?
• Have you validated the input using an OpenAPI validator?
• Have you tested with the latest master to confirm the issue still exists?
• Have you searched for related issues/PRs?
• What's the actual output vs expected output?
• [] [Optional] Sponsorship to speed up the bug fix or feature request (example)

Description

When an OpenAPI schema contains a field named java, the generated Java code fails to compile in versions 7.18.0 and later. The issue is caused by using fully-qualified names like java.util.Locale.ROOT which get shadowed by instance fields named java.

openapi-generator version

7.18.0, 7.19.0, 7.25.0, and current master

OpenAPI declaration file content or url

openapi: 3.0.0
info:
  title: Minimal Reproduction
  version: 1.0.0
paths: {}
components:
  schemas:
    LanguageComponent:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        java:
          $ref: '#/components/schemas/JavaComponent'
    JavaComponent:
      type: object
      properties:
        util:
          type: string

Generation Details

openapi-generator-cli generate \
  -g java \
  --library okhttp-gson \
  -i spec.yaml \
  -o ./generated

Steps to reproduce

1. Save the above OpenAPI spec to spec.yaml
2. Run the generation command
3. Try to compile the generated code with mvn compile
4. Observe compilation failure

Related issues/PRs

• [BUG] Missing reserved words in Java and CSharp #16277 - Missing reserved words in Java and CSharp
• PR [Java] Use Fully Qualified Name for java.util.Locale in Generated Classes #22342 (commit 149fdcb) - Introduced the regression
• PR [Java] Add missing Locale to String.format() invocations #21871 (commit babb3e2) - Original addition of Locale parameter

Suggest a fix

Root Cause: Commit 149fdcb (PR #22342) removed import java.util.Locale; and changed all occurrences to use the fully-qualified name java.util.Locale.ROOT. When a field is named java, it shadows the java.* package namespace, causing compilation failures.

Affected versions: 7.18.0 through 7.25.0 (and master)

Previously working: 7.16.0-7.17.0 (used import java.util.Locale; + Locale.ROOT)

Error Message:

[ERROR] non-static variable java cannot be referenced from a static context
[ERROR] cannot find symbol
  symbol:   variable util
  location: variable java of type JavaComponent

Generated Code (Broken):

package org.openapitools.client.model;

// No import for Locale (removed in commit 149fdcb61f6)

public class LanguageComponent {
  private JavaComponent java;  // Field shadows java.* package

  public static void validateJsonElement(JsonElement jsonElement) throws IOException {
    if (jsonElement == null) {
      if (!LanguageComponent.openapiRequiredFields.isEmpty()) {
        // BUG: 'java' refers to the field, not the package!
        throw new IllegalArgumentException(String.format(
          java.util.Locale.ROOT,  // <-- Compilation error
          "The required field(s) %s in LanguageComponent is not found",
          LanguageComponent.openapiRequiredFields.toString()
        ));
      }
    }
  }
}

Proposed Fix: Revert to using imports. Add import java.util.Locale; and use Locale.ROOT:

package org.openapitools.client.model;

import java.util.Locale;  // Add back the import

public class LanguageComponent {
  private JavaComponent java;

  public static void validateJsonElement(JsonElement jsonElement) throws IOException {
    if (jsonElement == null) {
      if (!LanguageComponent.openapiRequiredFields.isEmpty()) {
        throw new IllegalArgumentException(String.format(
          Locale.ROOT,  // Use short name - no conflict with field
          "The required field(s) %s in LanguageComponent is not found",
          LanguageComponent.openapiRequiredFields.toString()
        ));
      }
    }
  }
}

Why this works: Locale is a class name, not a field name, so it doesn't conflict with the java field.

Files to modify:

• modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/pojo.mustache
• modules/openapi-generator/src/main/resources/Java/libraries/okhttp-gson/model.mustache
• Similar files in other Java libraries (jersey2, jersey3, native, feign, etc.)

Alternative solutions:

1. Mark java as a reserved word (breaking change for existing users)
2. Use static import: import static java.util.Locale.ROOT;

Real-world impact: This affects the stackrox/jenkins-plugin where the StackRox API contains ScannerV1LanguageComponent with a java field.

Workaround (for affected users):

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-antrun-plugin</artifactId>
  <version>3.1.0</version>
  <executions>
    <execution>
      <phase>process-sources</phase>
      <goals><goal>run</goal></goals>
      <configuration>
        <target>
          <replaceregexp
              file="${project.basedir}/target/generated-sources/.../LanguageComponent.java"
              match="(package .*;)"
              replace="\1&#10;&#10;import java.util.Locale;"
              byline="false"/>
          <replaceregexp
              file="${project.basedir}/target/generated-sources/.../LanguageComponent.java"
              match="java\.util\.Locale\.ROOT"
              replace="Locale.ROOT"
              byline="true"
              flags="g"/>
        </target>
      </configuration>
    </execution>
  </executions>
</plugin>

Regression timeline:

• v7.14.0 and earlier: No Locale specified (incorrect but no shadowing)
• v7.16.0-v7.17.0: Used Locale.ROOT with import ✅ (correct, no shadowing)
• v7.18.0+: Uses java.util.Locale.ROOT without import ❌ (breaks with java field)

The irony is that commit 149fdcb was trying to avoid naming conflicts by using fully-qualified names, but actually created a new class of conflicts (field shadowing).

[wing328]

thanks for reporting the issue

cc @Chrimle who made the change (149fdcb)

[Picazsoo]

Hi @janisz, No need for the regex post-processing. You should be able to rename the colliding field with --name-mappings:

openapi-generator-cli generate -g java --library okhttp-gson \
  -i spec.yaml -o ./generated \
  --name-mappings java=javaField

Same thing works via the Maven plugin (<nameMappings>) or addNameMapping("java", "javaField"). That stops java from shadowing the package without touching the generated code.

That workaround is manual though, so it won't stop this happening again. And it can pop up with other stuff too. Anything writing java.util.X, java.time.X, etc. breaks if a field is named java. Switching to a plain import doesn't help, it just moves the collision to locale.

If the solution above is not satisfactory, then I'd suggest just reserving java in AbstractJavaCodegen. It reuses the same escaping as name-mappings, so a java field becomes _java automatically for everyone.

It would be a breaking change for anyone with a java field today, but it's a compile error so it's obvious and trivial to fix.

[Picazsoo]

Just to make it clear @janisz, I am not saying that my proposed solution is the correct one. Your issue is not automatically invalidated by me providing a possible workaround. But if you feel like the suggested solution is satisfactory, then feel free to keep the issue closed.

[janisz]

Thanks! It worked and it is pretty clean (much better than my patch). So I think issue could be closed especially java is not a popular filed name.