Replace java.net.URL with alternative, e.g. java.net.URI

[aSemy]

Is your feature request related to a problem? Please describe

Dokka Generator uses java.net.URL in the configuration.

dokka/core/src/main/kotlin/configuration.kt

Lines 226 to 230 in 3fc8b83

	interface SourceLinkDefinition : Serializable {
	val localDirectory: String
	val remoteUrl: URL
	val remoteLineSuffix: String?
	}

dokka/core/src/main/kotlin/configuration.kt

Lines 250 to 255 in 3fc8b83

	interface ExternalDocumentationLink : Serializable {
	val url: URL
	val packageListUrl: URL
	companion object
	}

java.net.URL has a number of drawbacks and unexpected behaviours.

• The hashcode is not serialized consistently, which affects Gradle caching java.net.URL serialization depends on hashCode which creates cache misses gradle/gradle#24979
• URL.hashCode() is blocking
• .equals() is not performant
• In Java 20 the URL constructor is deprecated

  The java.net.URL constructors are deprecated. Developers are encouraged to use java.net.URI to parse or construct a URL.

Describe the solution you'd like

Here are some suggestions:

1. Replace all usages of java.net.URL with java.net.URI

2. Replace all usages of java.net.URL with String, and annotate it with @Language("http-url-reference") so IntelliJ recognises it as a URL

3. Create a custom class named something like WebUrl or HttpLink

   class Website(private val value: String)

4. Use another library's URL, e.g. ui.ktor.http.Url

Describe alternatives you've considered

Dokkatoo can work around this and use an alternative, as it 'hides' the Dokka configuration from Gradle.

Ideally Dokka would also be updated, for consistency.

Additional context

See also

• https://stackoverflow.com/questions/75908405/getting-around-the-deprecation-of-java-net-url
• https://stackoverflow.com/questions/2348399/why-does-java-net-urls-hashcode-resolve-the-host-to-an-ip

  The IP resolution behavior of URL.equals and URL.hashcode is a trap for inexperienced Java programmers, even though it is clearly documented.

• https://stackoverflow.com/questions/1306290/i-know-that-java-net-url-tries-to-resolve-the-url-does-java-net-uri-do-the-same

Are you willing to provide a PR?

Sure thing

(cc @martinbonnin)

[whyoleg]

Exploration regarding removal of deprecated URL constructor: 521d9e5