UrlBuilder

Utility class for constructing syntactically correct HTTP URLs using a fluent method-chaining API. It strives simply to be more robust than manually constructing URLs by string concatenation.

Made with ❤️ by Widen.

Requirements

• Java 8 or higher

Features

• Automatic slash management in paths. Slashes will be de-duped or added as necessary when using addPathSegment
• Automatic URL encoding for both path segments (preserving slashes) and query parameters
  • RFC 3986 compliant encoders:
    • PathSegmentEncoder for path segments (allows @, :, sub-delimiters unencoded)
    • QueryParameterEncoder for query parameters (stricter encoding)
  • Backward compatibility:
    • LegacyEncoder for v2.x-compatible encoding
    • Use usingLegacyEncoding() to enable v2.x behavior for both path and query encoding
  • Custom encoders supported via usingPathEncoder(Encoder) and usingQueryEncoder(Encoder)
  • NoEncodingEncoder passes text through unchanged
• Options for generation of fully-qualified, hostname relative, or protocol relative URLs
• Fluent method-chaining API
• More examples in the test suite:
  • UrlBuilderTest - general usage
  • UrlBuilderParsingTest - URL parsing
  • UrlBuilderPathTest - path handling
  • UrlBuilderQueryParamsTest - query parameters
  • UrlBuilderPortSslTest - port and SSL
  • UrlBuilderModesTest - output modes

Installation

Gradle

implementation("com.widen:urlbuilder:{version}")

Maven

<dependency>
    <groupId>com.widen</groupId>
    <artifactId>urlbuilder</artifactId>
    <version>{version}</version>
</dependency>

Usage

Basic URL Construction

new UrlBuilder("my.host.com", "foo").addPathSegment("bar").addParameter("a", "b").toString()
// produces: http://my.host.com/foo/bar?a=b

Automatic URL Encoding

new UrlBuilder("my.host.com", "foo & bar").addParameter("1&2", "3&4").addParameter("a", "b&c").toString()
// produces: http://my.host.com/foo%20%26%20bar?1%262=3%264&a=b%26c

Parsing Existing URLs

new UrlBuilder("https://example.com/path/to/resource?existing=param")
    .addParameter("new", "value")
    .toString()
// produces: https://example.com/path/to/resource?existing=param&new=value

SSL/HTTPS

new UrlBuilder("my.host.com", "secure/path").usingSsl().toString()
// produces: https://my.host.com/secure/path

Output Modes

UrlBuilder builder = new UrlBuilder("my.host.com", "foo");

// Fully qualified (default)
builder.modeFullyQualified().toString()
// produces: http://my.host.com/foo

// Protocol relative
builder.modeProtocolRelative().toString()
// produces: //my.host.com/foo

// Hostname relative
builder.modeHostnameRelative().toString()
// produces: /foo

Converting to URI/URL

UrlBuilder builder = new UrlBuilder("my.host.com", "path");

URI uri = builder.toURI();
URL url = builder.toURL();

S3 Flavored UrlBuilder

S3UrlBuilder provides specialized functionality for building S3 URLs.

Features

• expireIn and expireAt for time-bombing S3 links
• All bucket reference methods supported:
  • virtual bucket (http://bucket.example.com/key.txt)
  • bucket in path (https://s3.amazonaws.com/bucket.example.com/key.txt)
  • hostname (http://bucket.example.com.s3.amazonaws.com/key.txt)
• withAttachmentFilename(String filename) generates required Content-Disposition header for browser file download prompt

Examples

// Basic S3 URL with bucket in path
S3UrlBuilder.create("my-bucket", "path/to/file.txt")
    .inRegion("us-west-2")
    .usingBucketInPath()
    .toString()
// produces: http://s3.us-west-2.amazonaws.com/my-bucket/path/to/file.txt

// Signed S3 URL with expiration
S3UrlBuilder.create("my-bucket", "private/file.txt")
    .inRegion("us-east-1")
    .usingCredentials("AKIAIOSFODNN7EXAMPLE", "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY")
    .expireIn(1, TimeUnit.HOURS)
    .usingSsl()
    .toString()

// Virtual bucket hosting
S3UrlBuilder.create("my-bucket", "file.txt")
    .usingBucketVirtualHost()
    .toString()
// produces: http://my-bucket/file.txt

// Force download with custom filename
S3UrlBuilder.create("my-bucket", "documents/report-2024-q1.pdf")
    .inRegion("us-east-1")
    .withAttachmentFilename("Quarterly Report.pdf")
    .toString()

CloudFront Flavored UrlBuilder

CloudfrontUrlBuilder provides specialized functionality for building CloudFront URLs.

Features

• expireIn and expireAt for time-bombing CloudFront links
• Signed URL support with private key authentication

Examples

PrivateKey privateKey = CloudfrontPrivateKeyUtils.loadPrivateKey(pemFileInputStream);

// Signed CloudFront URL with expiration
new CloudfrontUrlBuilder("d1234.cloudfront.net", "videos/movie.mp4", "APKAEIBAERJR2EXAMPLE", privateKey)
    .expireIn(2, TimeUnit.HOURS)
    .toString()

// CloudFront URL with attachment filename
new CloudfrontUrlBuilder("d1234.cloudfront.net", "files/document.pdf", "APKAEIBAERJR2EXAMPLE", privateKey)
    .expireAt(new Date(System.currentTimeMillis() + 86400000))
    .withAttachmentFilename("download.pdf")
    .toString()

License

Licensed under the Apache Version 2.0 license. See the license file for details.