Deprecated Java URL Constructors

Problem Statement

Java 20 deprecated all public constructors of java.net.URL. Developers encounter compiler warnings when using these deprecated constructors and need migration strategies. The core issues are:

1. How to replace new URL(protocol, host, file)
2. Replacement patterns for other constructors like:
   • new URL(String spec)
   • new URL(URL context, String spec) (relative URL resolution)
3. Challenges when converting file paths to URLs

Without proper migration, code becomes incompatible with future Java versions and may throw IllegalArgumentException in specific cases.

Why Deprecation Occurred

URL constructors were deprecated due to:

• Lack of standardized escaping of URL components
• Inconsistent behavior in edge cases
• Better alternatives available through java.net.URI and java.nio.file.Path

Official Rationale

"To construct a URL, the URI::toURL alternative should instead be preferred. To construct a file based URL, Path::toURI should be used prior to URI::toURL."
– Oracle: JDK 20 Deprecation Notice

Replacement Strategies

Basic URL Construction

❌ Deprecated approach

URL url = new URL("https", "example.com", "/resources/data.json");

✅ Recommended replacement

URI uri = new URI("https", "example.com", "/resources/data.json", null);
URL url = uri.toURL();

1. Simple String to URL Conversion

Anti-Pattern

// Throws deprecation warning
URL url = new URL("https://api.example.com/v2/data");

✅ Recommended Solution

URI uri = new URI("https://api.example.com/v2/data");
URL url = uri.toURL();

2. Relative URL Resolution

Anti-Pattern

URL base = new URL("https://base.example.com/path/");
URL resolved = new URL(base, "resource"); // Deprecated

✅ Recommended Solution

URI baseUri = new URI("https://base.example.com/path/");
URI resolvedUri = baseUri.resolve("resource");  // Key difference
URL resolved = resolvedUri.toURL();

// Produces: https://base.example.com/path/resource

3. File Path Handling

File paths require special attention due to platform differences in path formats:

Unreliable Approach

URL fileUrl = new URL("file:/Users/name/data.txt");

✅ Robust Solution

Path path = Path.of("/Users/name/data.txt");
URI uri = path.toUri();  // Creates 'file:///Users/name/data.txt'
URL url = uri.toURL();

Common Pitfalls and Solutions

Handling Special Characters

URLs containing spaces or special characters must be properly encoded:

Problem

// Fails with IllegalArgumentException due to space
URI uri = new URI("https://example.com/file with space.txt");

✅ Safe Encoding

String safeUrl = "https://example.com/file%20with%20space.txt";
URI uri = new URI(safeUrl);  // Explicitly encoded first

Why File Paths Need Special Treatment

File URIs require explicit conversions:

• Direct string substitution (new URI("file:///path")) fails with Windows paths and spaces
• Path.toUri() handles:
  • Platform-specific separators
  • Character encoding
  • Drive letters (Windows)
  • Relative path resolution

Debugging IllegalArgumentException

Cause typically includes:

1. Invalid URI syntax in input string
2. Improper relative path resolution
3. Missing URI components for multi-argument constructors

Resolution strategy:

try {
    URI uri = new URI("invalid uri");
} catch (URISyntaxException e) {
    // Examine e.getMessage() for syntax violations
    // Fix invalid characters or missing components
}

Migration Reference Table

Original	Replacement
new URL(str)	new URI(str).toURL()
new URL(context, relative)	context.toURI().resolve(relative).toURL()
new URL(proto, host, file)	new URI(proto, host, file, null).toURL()
new URL(filePath)	Path.of(filePath).toUri().toURL()

Conclusion

Migrate deprecated URL constructors using:

1. URI for standard URL construction
2. URI.resolve() for relative paths
3. Path.toUri() for file references

These strategies ensure forward compatibility, proper URL encoding, and cross-platform file path handling. The URI API provides more standards-compliant URL management compared to legacy URL constructors.