Compilation Error: java.util.Map needs to be fully qualified when domain class is called Map

[NetzwergX]

@jakarta.annotation.Generated("com.microsoft.kiota")
public class Map implements AdditionalDataHolder, Parsable {

    /**
     * Stores additional data not described in the OpenAPI description found when deserializing. Can be used for serialization as well.
     */
    private Map<String, Object> additionalData;

    // ...

}

If the domain class for an endpoint is called Map (see above), the compilation fails due to the clash with the import java.util.Map. In those cases, the generated code is trivially fixed by removing the import and fully qualifying all instances where Map refers to java.util.Map:

Swagger config to try this out:

• https://esi.evetech.net/_latest/swagger.json?datasource=tranquility (look at the sovereignty/map endpoint)

[baywet]

Hi @NetzwergX
Thank you for using kiota and for reaching out.
This is typically handled in kiota by adding to the list of reserved names instead.
Is this something you'd like to submit a pull request for provided some guidance?

[NetzwergX]

@baywet Thanks for pointing out the reserved names list. I am willing to provide a PR if I have a sufficient understand of what is going on.

What exactly is the effect of adding the class, e.g. Map, there? Would this lead to java.util.Map no longer being imported but always being referred to by FQN?

[baywet]

Not exactly, the result is that name cannot be used anymore for generated symbols (class names, enum names, enum members....).
Every time a symbol should be "Map", it'll instead be "Map_escaped" or something along those lines depending on language conventions.

[NetzwergX]

I wonder if thats the desired solution when we look at where this converges. There are several dozens of imports declared in the generated code files.

• I could provide a PR for just Map. This would solve this issue. It has two rather severe drawbacks, though. First of all, having the domain object called Map is quite desirable. Second, it would not solve all the other instances where a domain object is generated that has a name that clashes with some import.
• I could provide a PR for all classes that are currently imported -- at least the ones I can find out about. This would take care of all possible domain names, but it would also severely restrict which domain names are valid. It also wouldn't really be future-proof, because when a new import is added in the future because the generated code is changed, that would need to be added as well.

The last point is also a problem for evolution overall and applies to the reserved classes list in general. Say today I generate a client that uses a name as domain object class name that ends up being on the reserved names list in some future version. This would make all code generated in the future, where that class name is escaped incompatible with the current code.

So overall, it seems a more robust solution would be highly desirable. And that is actually possible without too much effort. There are in general two approaches that can be used.

• The easiest solution would be not to import anything at all and always use the FQN, which is guaranteed to be unique, to refer to any type in the generated source. This is a backwards compatible change and would be quite robust to changes in required types in the future. It has the disadvantage of making the generated source code files more verbose, though. Which only affects human-readability to some extend, but is irrelevant once compiled to bytecode.
• The somewhat smarter solution would be to track all simple names and FQNs during generation and to disambiguate them while generating the code. I don't know how the Kiota generator works and how much effort this would be, but I have implemented this in the past to some extend. Suffice to say, this is a magnitude more complex to implement than the first offered solution.

From a robustness perspective, especially wrt. forwards- and backwards compatibility (of the generated api and model), it seems to me that dealing with this on the side of the source generator and by disambiguating the class names while generating is the preferable option. It also ensures that future evolution of the generated code does not require synced changes in the reserved words list, making changes less error-prone.

Personally, I'd go with just using FQNs everywhere when referring to types. Its the simplest to implement, offers all the advantages (robustness, forward- and backward compatibility both wrt. the generated source and evolution of the generated code) and has the only drawback of being more verbose on the source level.

Let me know what your thoughts are on this topic.

[baywet]

Thank you for the additional information.

We've been through this topic with dotnet #5020, #4796 and many more. The solution depends a lot on the internals of the compiler. FQNs often seems like a more favorable approach until you start having symbol names that match namespace segments...

The easiest to implement solution, with the least impact to existing clients that would potentially be refreshed, is the reserved names approach. We can always adjust later on based on people's feedback.

From looking at this list here are the types that would need to be added f not already present:

• Map
• HashMap
• Collection
• RequestAdapter
• RequestInformation
• RequestOption
• HttpMethod
• Parsable
• AdditionalDataHolder
• Objects
• InputStream
• SerializationWriter
• ParseNode
• Parsable
• ParsableFactory
• BackingStoreFactory
• BackingStoreFactorySingleton
• BackingStore
• BackedModel
• BigDecimal
• QueryParameters
• ParseNodeHelper
• MultipartBody
• UntypedNode

We're talking about ~30 reserved names, and we're not expecting this list to grow by much in the future.

Let us know if you have any additional comments or questions.

[baywet]

authored #5184