Handling unknown enum values

[gcatanese]

When an unknown enum value is found in the JSON payload (API response, webhook request) the deserialization throws an exception. This PR makes the deserialization logic more robust to be able to handle:

• unknown enum values
• unknown Terminal API Notification Events

The Mustache templates have been update to set the attribute as null, instead of throwing an IllegalArgumentException.

Unit tests have been added to verify the deserialization code.

Implementation Details

When parsing a JSON payload and encountering unknown enumsm we have 2 options:

1. strict validation throwing IllegalArgumentException if the value is unknown
2. don't fail and ignore, hence set the value as null

We have adopted the latter as it allows us to be resilient when new enums appear in the API responses.

We have also decided to keep case-sensitivity when checking enum values, this is how OpenAPI defines enums.

[gemini-code-assist]

Summary of Changes

Hello @gcatanese, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly improves the resilience of the API client by implementing a more robust deserialization strategy for enum values, preventing crashes when unexpected data is received. It also includes minor structural enhancements to the LegalEntity model for better management of its associated capabilities.

Highlights

• Robust Deserialization: Modified the deserialization logic for numerous enum types across various API models. Previously, encountering an unknown enum value in a JSON payload would throw an IllegalArgumentException, halting processing. Now, the system will log a warning message detailing the unexpected value and supported options, and then set the corresponding attribute to null, allowing for more graceful handling of unforeseen data.
• API Model Updates: Updated a large number of API model classes to incorporate java.util.Arrays and java.util.logging.Logger imports, and added Logger instances to enum definitions to support the new warning-based error handling.
• LegalEntity Capabilities Management: Refactored the LegalEntity model to provide more flexible handling of its capabilities map. The capabilities parameter was removed from the JsonCreator constructor, and new methods (capabilities(Map<String, LegalEntityCapability> capabilities) and putCapabilitiesItem(String key, LegalEntityCapability capabilitiesItem)) were added for programmatic management of capabilities. A setCapabilities method with @JsonInclude(value = JsonInclude.Include.USE_DEFAULTS) was also introduced.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[gcatanese]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant improvement in deserialization robustness by handling unknown enum values gracefully across numerous model classes. Instead of throwing an exception, the new implementation logs a warning and sets the enum field to null, preventing crashes from unexpected API responses. The changes are extensive and consistently applied, which is great. Consider adding metrics to monitor the occurrence of unexpected enum values to ensure that the API is used correctly and that integrations are not relying on undocumented enum values.

[Kwok-he-Chu]

Approved, note that this change does not handle caseInsensitivity comparisons when looping over all enum values. Developers will have to handle the null-case as well