fix(docs): DSPX-2409 replace SDK README code example with working code

[marythought]

Fixed API References

• ❌ Removed incorrect import: import io.opentdf.platform.sdk.Reader; (non-existent class)
• ✅ Added correct import: import io.opentdf.platform.sdk.TDF;
• ✅ Fixed Reader usage: Changed Reader reader = ... → TDF.Reader reader = ... (Reader is a nested class within TDF)

Complete Working Example

• Fixed imports to use file-based I/O with FileChannel (required for SeekableByteChannel)
• Added complete end-to-end example: create TDF → encrypt to file → decrypt from file → write plaintext
• Proper resource management with try-with-resources
• Proper exception handling with throws Exception
• Working example that can be copied and pasted directly

Quickstart Alignment

Replaced generic placeholders with actual quickstart values:

• platformEndpoint: localhost:8080 (was https://your.cluster/)
• clientId: opentdf (was myClient)
• clientSecret: secret (was token)
• kasUrl: http://localhost:8080/kas (new)
• dataAttribute: https://opentdf.io/attr/department/value/finance (was attr1, attr2)

Documentation Enhancements

• Added link to SDK Quickstart Guide at the top
• Added links to Creating TDFs and Managing policy
• Changed header from "Quick Start Example" to "Example code"
• Added note about hosted versions vs local development

Added Configuration Documentation

• Configuration Values table with defaults and descriptions

• Prerequisites section with setup instructions:

  1. Follow OpenTDF Quickstart to start the platform
  2. Create OAuth client in Keycloak
  3. Grant client entitlements to the department attribute

• Expected Output section:
  TDF created successfully
  Successfully created and decrypted TDF

• Note that output.txt contains the decrypted plaintext: Hello, world!

Automated Testing

Created READMETest.java that validates code blocks:

• ✅ Required imports present (SDK, SDKBuilder, Config)
• ❌ Non-existent Reader import not used
• ✅ TDF.Reader used correctly instead of standalone Reader
• ✅ Proper API usage (sdk.loadTDF, sdk.createTDF)
• ✅ Matching braces and parentheses
• ✅ Proper exception handling

Prevents future API changes from breaking README examples.

[gemini-code-assist]

Summary of Changes

Hello @marythought, 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 README.md for the OpenTDF Java SDK by replacing the existing, non-functional code example with a complete, verified, and production-ready end-to-end example for TDF creation and decryption. It also enhances the documentation with detailed configuration, prerequisites, and links to further resources, while introducing an automated test suite to ensure the continued accuracy and functionality of the README's code examples.

Highlights

• API Reference Fixes: Corrected the Reader class import and usage in the example code, replacing a non-existent class with io.opentdf.platform.sdk.TDF.Reader for proper functionality.
• Complete Working Example: Introduced a full end-to-end Java example for TDF creation and decryption, including proper file I/O with FileChannel, try-with-resources for resource management, and robust exception handling.
• Quickstart Alignment: Updated example configuration placeholders (e.g., platformEndpoint, clientId, kasUrl) to use specific values consistent with the OpenTDF quickstart guide.
• Documentation Enhancements: Added new links to the SDK Quickstart Guide, 'Creating TDFs', and 'Managing policy' documentation, updated section headers, and included notes on hosted versions versus local development.
• Configuration Documentation: Provided a detailed table of configuration values with defaults and descriptions, a 'Prerequisites' section with setup instructions, and an 'Expected Output' section for the example.
• Automated Testing: Implemented READMETest.java to automatically validate the syntax and correctness of Java code blocks within the README.md file, ensuring documentation accuracy and preventing future regressions.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• README.md
  • The main Java code example was completely rewritten to demonstrate a full TDF encryption and decryption flow, using FileChannel for I/O and try-with-resources for resource management.
  • Corrected the import for the Reader class from io.opentdf.platform.sdk.Reader to io.opentdf.platform.sdk.TDF and updated its usage to TDF.Reader.
  • Replaced generic placeholder values for platformEndpoint, clientId, clientSecret, kasUrl, and dataAttribute with values consistent with the OpenTDF quickstart.
  • Added a new 'Configuration Values' table, a 'Prerequisites' section, and an 'Expected Output' section to guide users.
  • Incorporated new links to the SDK Quickstart Guide, 'Creating TDFs', and 'Managing policy' documentation.
  • The header 'Quick Start Example' was changed to 'Example code'.
• sdk/src/test/java/io/opentdf/platform/sdk/READMETest.java
  • A new JUnit test file was added to programmatically extract and validate Java code blocks from README.md.
  • The test checks for correct imports (e.g., SDK, SDKBuilder, Config, TDF), proper TDF.Reader usage, correct API calls (sdk.loadTDF, sdk.createTDF), class structure, exception handling, and matching braces/parentheses.
  • This test ensures that the documentation's code examples remain syntactically correct and aligned with the SDK's API.

Activity

• The author, marythought, has proactively addressed documentation accuracy and maintainability by completely overhauling the primary code example in README.md to be a functional, end-to-end demonstration.
• Comprehensive documentation sections for configuration, prerequisites, and expected output have been added to improve user guidance.
• A new automated test (READMETest.java) has been implemented to continuously validate the correctness of Java code blocks within the README.md, thereby preventing future documentation rot.

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 by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

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 pull request 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 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. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

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]

Code Review

This pull request significantly improves the README.md by replacing an outdated code example with a complete, working one, and adding valuable context like configuration details and prerequisites. The introduction of READMETest.java to validate the README's code examples is an excellent addition that will help keep the documentation synchronized with the code. I have a couple of minor suggestions for the new test file to improve its robustness and adherence to best practices.

[github-actions]

X-Test Failure Report

✅ js-main
✅ js-v0.12.0
✅ go-main
✅ go-v0.12.0

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud