Skip to content

MINOR: Fix PrimitiveStringifier class Javadoc to link UnsupportedOperationException#3651

Open
anxkhn wants to merge 1 commit into
apache:masterfrom
anxkhn:patch-1
Open

MINOR: Fix PrimitiveStringifier class Javadoc to link UnsupportedOperationException#3651
anxkhn wants to merge 1 commit into
apache:masterfrom
anxkhn:patch-1

Conversation

@anxkhn

@anxkhn anxkhn commented Jul 8, 2026

Copy link
Copy Markdown

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 (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.

…ationException

The class-level Javadoc of PrimitiveStringifier stated that the overloaded
stringify(...) methods not implemented for the related types throw
{@link OperationNotSupportedException}. That link resolved to the checked
javax.naming.OperationNotSupportedException, which these unchecked methods
cannot throw, and it contradicted every method's own @throws tag. In fact all
overloads throw java.lang.UnsupportedOperationException.

Point the class Javadoc at UnsupportedOperationException and drop the now-unused
javax.naming import. Documentation-only, no behavioral change.

@nastra nastra left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants