starred/pkl
1
0
Fork 0
mirror of https://github.com/apple/pkl.git synced 2026-09-02 17:37:16 +02:00
Code Issues 198 Packages Projects Releases 10 Wiki Activity

[PR #759] [MERGED] Polish external reader API/implementation #717

New Issue
Closed
opened 2025-12-30 01:26:21 +01:00 by adam · 0 comments
adam commented 2025-12-30 01:26:21 +01:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/apple/pkl/pull/759
Author: @odenix
Created: 10/31/2024
Status: ✅ Merged
Merged: 10/31/2024
Merged by: @bioball

Base: main ← Head: polish-reader

📝 Commits (1)

  • 598d98d Polish external reader API/implementation

📊 Changes

14 files changed (+107 additions, -86 deletions)

View changed files

📝 pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliCommand.kt (+5 -6)
📝 pkl-core/src/main/java/org/pkl/core/EvaluatorBuilder.java (+3 -4)
📝 pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderMessagePackDecoder.java (+1 -1)
📝 pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderMessagePackEncoder.java (+1 -1)
📝 pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderMessages.java (+2 -1)
📝 pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderProcess.java (+31 -12)
📝 pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderProcessImpl.java (+52 -46)
📝 pkl-core/src/main/java/org/pkl/core/messaging/MessageTransports.java (+2 -1)
📝 pkl-core/src/main/java/org/pkl/core/messaging/Messages.java (+2 -7)
📝 pkl-core/src/main/java/org/pkl/core/module/ModuleKeys.java (+2 -2)
📝 pkl-core/src/main/java/org/pkl/core/resource/ExternalResourceResolver.java (+1 -1)
📝 pkl-core/src/main/java/org/pkl/core/resource/ResourceReaders.java (+1 -1)
📝 pkl-core/src/main/java/org/pkl/core/util/Readers.java (+3 -1)
📝 pkl-server/src/main/kotlin/org/pkl/server/Server.kt (+1 -2)

📄 Description

Things I noticed but didn't address in this PR:

  • many APIs are missing Javadoc
  • libraries shouldn't log directly to std out/err (see ExternalReaderProcessImpl)
  • some ExternalReaderProcessException messages are externalized, others aren't
  • ExternalReaderProcessException is a checked exception
    • it's not clear to me what Pkl's policy on unchecked vs. checked exceptions is
  • new Random().nextLong() is expensive and has poor randomness (Random should be reused or replaced with counter)
  • deprecation of ModuleKeyFactories.closeQuietly in favor of org.pkl.core.util.Readers.closeQuietly turns package org.pkl.core.util into a public API
    • private packages keep leaking into public APIs
  • org.pkl.core.module.ResourceReaders API is (too) tightly coupled to reader protocol via ModuleReaderSpec
  • ExternalReaderProcess is a leaky abstraction
    • only partially implements the reader protocol
    • exposes its MessageTransport
    • interface name implies that all implementations spawn a process (unnecessary requirement?)
  • msgpack is now a hard dependency of pkl-core, pkl-config-java, etc.
    • might be safer to make it an optional dependency

IMHO the external reader API/implementation needs more work.

Changes:

  • keep implementation classes internal to their packages
  • make classes final if possible
  • make namespace classes non-instantiable
  • throw IllegalStateException instead of ExternalReaderProcessException for use after close
    • common convention already used by HttpClient etc.
    • programming errors should be signaled with unchecked exceptions
  • use private instead of public lock object
  • polish Javadoc
  • delete commented out code
  • don't use star import for importing a single class

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/apple/pkl/pull/759 **Author:** [@odenix](https://github.com/odenix) **Created:** 10/31/2024 **Status:** ✅ Merged **Merged:** 10/31/2024 **Merged by:** [@bioball](https://github.com/bioball) **Base:** `main` ← **Head:** `polish-reader` --- ### 📝 Commits (1) - [`598d98d`](https://github.com/apple/pkl/commit/598d98d12b636a881df46c3232eb34b14e52f4ba) Polish external reader API/implementation ### 📊 Changes **14 files changed** (+107 additions, -86 deletions) <details> <summary>View changed files</summary> 📝 `pkl-commons-cli/src/main/kotlin/org/pkl/commons/cli/CliCommand.kt` (+5 -6) 📝 `pkl-core/src/main/java/org/pkl/core/EvaluatorBuilder.java` (+3 -4) 📝 `pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderMessagePackDecoder.java` (+1 -1) 📝 `pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderMessagePackEncoder.java` (+1 -1) 📝 `pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderMessages.java` (+2 -1) 📝 `pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderProcess.java` (+31 -12) 📝 `pkl-core/src/main/java/org/pkl/core/externalreader/ExternalReaderProcessImpl.java` (+52 -46) 📝 `pkl-core/src/main/java/org/pkl/core/messaging/MessageTransports.java` (+2 -1) 📝 `pkl-core/src/main/java/org/pkl/core/messaging/Messages.java` (+2 -7) 📝 `pkl-core/src/main/java/org/pkl/core/module/ModuleKeys.java` (+2 -2) 📝 `pkl-core/src/main/java/org/pkl/core/resource/ExternalResourceResolver.java` (+1 -1) 📝 `pkl-core/src/main/java/org/pkl/core/resource/ResourceReaders.java` (+1 -1) 📝 `pkl-core/src/main/java/org/pkl/core/util/Readers.java` (+3 -1) 📝 `pkl-server/src/main/kotlin/org/pkl/server/Server.kt` (+1 -2) </details> ### 📄 Description Things I noticed but didn't address in this PR: * many APIs are missing Javadoc * libraries shouldn't log directly to std out/err (see `ExternalReaderProcessImpl`) * some `ExternalReaderProcessException` messages are externalized, others aren't * `ExternalReaderProcessException` is a checked exception - it's not clear to me what Pkl's policy on unchecked vs. checked exceptions is * `new Random().nextLong()` is expensive and has poor randomness (Random should be reused or replaced with counter) * deprecation of `ModuleKeyFactories.closeQuietly` in favor of `org.pkl.core.util.Readers.closeQuietly` turns package `org.pkl.core.util` into a public API - private packages keep leaking into public APIs * `org.pkl.core.module.ResourceReaders` API is (too) tightly coupled to reader protocol via `ModuleReaderSpec` * `ExternalReaderProcess` is a leaky abstraction - only partially implements the reader protocol - exposes its `MessageTransport` - interface name implies that all implementations spawn a process (unnecessary requirement?) * msgpack is now a hard dependency of pkl-core, pkl-config-java, etc. - might be safer to make it an optional dependency IMHO the external reader API/implementation needs more work. Changes: - keep implementation classes internal to their packages - make classes final if possible - make namespace classes non-instantiable - throw IllegalStateException instead of ExternalReaderProcessException for use after close - common convention already used by HttpClient etc. - programming errors should be signaled with unchecked exceptions - use private instead of public lock object - polish Javadoc - delete commented out code - don't use star import for importing a single class --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2025-12-30 01:26:21 +01:00
adam closed this issue 2025-12-30 01:26:21 +01:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
duplicate
enhancement
good first issue
help wanted
pull-request
Mirrored from GitHub Pull Request
No labels pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/pkl#717