anxkhn opened a new pull request, #3651:
URL: https://github.com/apache/parquet-java/pull/3651
### Rationale for this change
The class-level Javadoc of the public abstract class `PrimitiveStringifier`
(`parquet-column/src/main/java/org/apache/parquet/schema/PrimitiveStringifier.java`)
documents the wrong exception type. It states:
> The overloaded methods not implemented for the related types throw
> `{@link OperationNotSupportedException}`.
That `{@link}` resolves to `javax.naming.OperationNotSupportedException`,
which is
the only reason the `import javax.naming.OperationNotSupportedException;`
exists in
the file. Two problems follow from this:
1. Every `stringify(...)` overload that is not implemented for a type
actually
throws `java.lang.UnsupportedOperationException`, and each method's own
`@throws` tag already documents `UnsupportedOperationException`. So the
class-level contract contradicts every per-method contract in the same
file.
2. `javax.naming.OperationNotSupportedException` is a checked exception
(`extends NamingException extends Exception`). The unchecked
`stringify(...)`
methods cannot declare or throw it, so the documented behavior is
impossible
and would mislead a caller into catching the wrong exception type.
### What changes are included in this PR?
A documentation-only change in one file:
- Point the class Javadoc `{@link}` at
`java.lang.UnsupportedOperationException`
(no import needed), so the class contract matches the six per-method
`@throws`
tags and the actual `throw` statements.
- Remove the now-unused `import
javax.naming.OperationNotSupportedException;`,
which existed solely to satisfy the incorrect link.
No behavioral change. Net diff is one import line removed and one word
changed in
the Javadoc.
### Are these changes tested?
This is a Javadoc/import-only change with no runtime behavior change, so no
new
test is added. It was validated locally on `parquet-column` (JDK 21, Maven
3.9):
- `mvn -pl parquet-column -Dspotless.check.skip=true -DskipTests compile`
succeeds,
confirming the removed `javax.naming` import was unused.
- `mvn -pl parquet-column javadoc:javadoc` succeeds with no "reference not
found"
warning for `PrimitiveStringifier`; the generated HTML now links the class
description to `java.lang.UnsupportedOperationException` and contains no
`javax.naming` reference.
- `mvn -pl parquet-column spotless:check` succeeds (0 files need
reformatting).
- `mvn -pl parquet-column -Dtest=TestPrimitiveStringifier test` passes
(13 tests, 0 failures), confirming no behavioral change.
### Are there any user-facing changes?
No. This only corrects Javadoc and removes a dead import. There is no API or
behavior change.
---
## Notes for the ship step (not part of the PR body)
- Title uses `MINOR:` because there is no filed GitHub issue. This is
explicitly
sanctioned by `.github/PULL_REQUEST_TEMPLATE.md` ("or simply use the title
below
if it is a minor issue: MINOR: ${SUMMARY}") and matches recent master
history
(e.g. "MINOR: Fix error message in SimpleGroup.add() for binary (#3385)").
- Do NOT uncomment the template's "Closes #${GITHUB_ISSUE_ID}" line: there
is no
issue to close.
- Rebase again onto `origin/master` right before pushing if upstream has
advanced.
- Suggested PR branch name for the fork at ship time (the local `patch-1` is
just
a placeholder): `fix/primitivestringifier-javadoc-link`.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
