Java : URL - API使用例

URL (Java SE 17 & JDK 17) の使用例まとめです。
だいたいのメソッドを網羅済みです。
API仕様のおともにどうぞ。


概要

URLクラスは、Uniform Resource Locator (ユニフォーム・リソース・ロケータ)、つまりWorld Wide Web上の「リソース」へのポインタを表します。

クラス構成

final var url = new URL("https://example.com/java/index.html");
System.out.println(url); // "https://example.com/java/index.html"
System.out.println(url.getProtocol()); // "https"
System.out.println(url.getHost()); // "example.com"
System.out.println(url.getPath()); // "/java/index.html"

備考

  • URLクラス自体がエスケープ処理を行うことはありません。
  • 関連するクラスとしてURIクラスがあります。
    Java API 使用例 : URI」も参考にしていただけたら幸いです。

コンストラクタ

URL (String spec)

String表現からURLオブジェクトを生成します。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1); // "http://www.example.com/docs/resource1.html"

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2); // "https://example.com/index.html?query#fragment"

final var url3 = new URL("file:///~/calendar");
System.out.println(url3); // "file:/~/calendar"

final var url4 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url4); // "jar:file:/home/xxx/sample.jar!/sample.txt"
// エスケープはされません。
final var url1 = new URL("http://example.com/a b c/");
System.out.println(url1); // "http://example.com/a b c/"

final var url2 = new URL("http://example.com/a%20b%20c/");
System.out.println(url2); // "http://example.com/a%20b%20c/"
//new URL("aaa://example.com/"); // MalformedURLException: unknown protocol: aaa
//new URL("sample/a/index.html#28"); // MalformedURLException: no protocol: sample/a/index.html#28
//new URL("../../demo/b/index.html"); // MalformedURLException: no protocol: ../../demo/b/index.html
//new URL("/aaa/index.html"); // MalformedURLException: no protocol: /aaa/index.html

URL (String protocol, String host, int port, String file)

指定されたprotocol、host、port番号、およびfileから、URLオブジェクトを作成します。

final var url1 = new URL("http", "example.com", 80, "/aaa/index.html");
System.out.println(url1); // "http://example.com:80/aaa/index.html"

final var url2 = new URL("http", "192.168.1.1", -1, "");
System.out.println(url2); // "http://192.168.1.1"

final var url3 = new URL("http", "[0:0:0:0:0:0:0:1]", -1, "");
System.out.println(url3); // "http://[0:0:0:0:0:0:0:1]"
final var url1 = new URL("https", "example.com", 443, "/index.html");
System.out.println(url1); // "https://example.com:443/index.html"

final var url2 = new URL("file", "", -1, "/~/calendar");
System.out.println(url2); // "file:/~/calendar"

final var url3 = new URL("jar", "", -1, "/home/xxx/sample.jar!/sample.txt");
System.out.println(url3); // "jar:/home/xxx/sample.jar!/sample.txt"
// エスケープはされません。
final var url1 = new URL("http", "example.com", -1, "/a b c/");
System.out.println(url1); // "http://example.com/a b c/"

final var url2 = new URL("http", "example.com", -1, "/a%20b%20c/");
System.out.println(url2); // "http://example.com/a%20b%20c/"
//new URL("aaaa", "example.com", -1, ""); // "MalformedURLException: unknown protocol: aaaa"

URL (String protocol, String host, int port, String file, URLStreamHandler handler)

指定されたprotocol、host、port番号、file、およびhandlerから、URLオブジェクトを作成します。

handler を null にした場合は、URL(String protocol, String host, int port, String file) と同等となります。
そのパターンの使用例はそちらをご参照ください。

class DummyURLStreamHandler extends URLStreamHandler {
    @Override
    protected URLConnection openConnection(URL u) {
        System.out.println("openConnection! : " + u);
        return new URLConnection(u) {
            @Override
            public void connect() {
                System.out.println("connect!");
            }
        };
    }
}

final var url = new URL("http", "example.com", -1, "/index.html", new DummyURLStreamHandler());
System.out.println(url); // "http://example.com/index.html"

final var connection = url.openConnection();
connection.connect();

// 結果
// ↓
//openConnection! : http://example.com/index.html
//connect!

URL (String protocol, String host, String file)

指定されたprotocol名、host名、およびfile名からURLを作成します。

final var url1 = new URL("http", "example.com", "/aaa/index.html");
System.out.println(url1); // "http://example.com/aaa/index.html"

final var url2 = new URL("http", "192.168.1.1", "");
System.out.println(url2); // "http://192.168.1.1"

final var url3 = new URL("http", "[0:0:0:0:0:0:0:1]", "");
System.out.println(url3); // "http://[0:0:0:0:0:0:0:1]"
final var url1 = new URL("https", "example.com", "/index.html");
System.out.println(url1); // "https://example.com/index.html"

final var url2 = new URL("file", "", "/~/calendar");
System.out.println(url2); // "file:/~/calendar"

final var url3 = new URL("jar", "", "file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url3); // "jar:file:/home/xxx/sample.jar!/sample.txt"
// エスケープはされません。
final var url1 = new URL("http", "example.com", "/a b c/");
System.out.println(url1); // "http://example.com/a b c/"

final var url2 = new URL("http", "example.com", "/a%20b%20c/");
System.out.println(url2); // "http://example.com/a%20b%20c/"
//new URL("aaaa", "example.com", ""); // "MalformedURLException: unknown protocol: aaaa"

URL (URL context, String spec)

指定されたコンテキスト内の指定された仕様で構文解析することによって、URLを生成します。

context を null にした場合は、URL(String spec) と同等となります。
そのパターンの使用例はそちらをご参照ください。

context をベースとして URI.resolve のような解決をします。

final var context = new URL("http://example.com/");

final var url1 = new URL(context, "sample/a/index.html#28");
System.out.println(url1); // "http://example.com/sample/a/index.html#28"

final var url2 = new URL(context, "../../demo/b/index.html");
System.out.println(url2); // "http://example.com/../../demo/b/index.html"

final var url3 = new URL(context, "/aaa/index.html");
System.out.println(url3); // "http://example.com/aaa/index.html"
final var context = new URL("http://example.com/xxx/yyy/zzz/");

final var url1 = new URL(context, "sample/a/index.html#28");
System.out.println(url1); // "http://example.com/xxx/yyy/zzz/sample/a/index.html#28"

final var url2 = new URL(context, "../../demo/b/index.html");
System.out.println(url2); // "http://example.com/xxx/demo/b/index.html"

final var url3 = new URL(context, "/aaa/index.html");
System.out.println(url3); // "http://example.com/aaa/index.html"
final var context = new URL("http://example.com/index.html");

final var url1 = new URL(context, "");
System.out.println(url1); // "http://example.com/index.html"

final var url2 = new URL(context, "#fragment");
System.out.println(url2); // "http://example.com/index.html#fragment"

final var url3 = new URL(context, "?query");
System.out.println(url3); // "http://example.com/?query"

final var url4 = new URL(context, "//www.example.com");
System.out.println(url4); // "http://www.example.com"

final var url5 = new URL(context, "file:///~/calendar");
System.out.println(url5); // "file:/~/calendar"

final var url6 = new URL(context, "https://www.example.com/ccc.html");
System.out.println(url6); // "https://www.example.com/ccc.html"
final var context = new URL("http://example.com/index.html?aaa#bbb");

final var url1 = new URL(context, "");
System.out.println(url1); // "http://example.com/index.html?aaa#bbb"

final var url2 = new URL(context, "#fragment");
System.out.println(url2); // "http://example.com/index.html?aaa#fragment"

final var url3 = new URL(context, "?query");
System.out.println(url3); // "http://example.com/?query"

final var url4 = new URL(context, "//www.example.com");
System.out.println(url4); // "http://www.example.com"

final var url5 = new URL(context, "file:///~/calendar");
System.out.println(url5); // "file:/~/calendar"

final var url6 = new URL(context, "https://www.example.com/ccc.html");
System.out.println(url6); // "https://www.example.com/ccc.html"
final var context = new URL("file:///~/calendar");

final var url1 = new URL(context, "#fragment");
System.out.println(url1); // "file:/~/calendar#fragment"

final var url2 = new URL(context, "?query");
System.out.println(url2); // "file:/~/?query"

final var url3 = new URL(context, "//www.example.com");
System.out.println(url3); // "file://www.example.com"

final var url4 = new URL(context, "https://www.example.com/ccc.html");
System.out.println(url4); // "https://www.example.com/ccc.html"

URL (URL context, String spec, URLStreamHandler handler)

指定されたコンテキスト内の指定されたハンドラで、指定された仕様を構文解析してURLを生成します。

handler を null にした場合は、URL(URL context, String spec) と同等となります。
そのパターンの使用例はそちらをご参照ください。

class DummyURLStreamHandler extends URLStreamHandler {
    @Override
    protected URLConnection openConnection(URL u) {
        System.out.println("openConnection! : " + u);
        return new URLConnection(u) {
            @Override
            public void connect() {
                System.out.println("connect!");
            }
        };
    }
}

final var url = new URL(null, "http://example.com", new DummyURLStreamHandler());
System.out.println(url); // "http://example.com"

final var connection = url.openConnection();
connection.connect();

// 結果
// ↓
//openConnection! : http://example.com
//connect!

メソッド

boolean equals (Object obj)

このURLと別のオブジェクトとが等しいかどうかを比較します。

final var url1 = new URL("http://example.com/docs/resource1.html");
final var url2 = new URL("http://example.com/docs/resource1.html");

System.out.println(url1 != url2); // true
System.out.println(url1.equals(url2)); // true
// 大文字・小文字の区別はしません。
final var url1 = new URL("http://example.com/");
final var url2 = new URL("HTTP://EXAMPLE.COM/");

System.out.println(url1.equals(url2)); // true
final var url1 = new URL("http://example.com/a");
final var url2 = new URL("http://example.com/b");

System.out.println(url1.equals(url2)); // false
// IPアドレスで一致していればtrueとなります。
final var url1 = new URL("http://example.com");
final var url2 = new URL("http://www.example.com");

System.out.println(url1.equals(url2)); // true

String getAuthority ()

このURLの機関部分を取得します。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.getAuthority()); // "www.example.com"
System.out.println(url1.getHost()); // "www.example.com"

// ホストは、ユーザ情報とポートを含みません。
final var url2 = new URL("http://user-a@example.com:80/");
System.out.println(url2.getAuthority()); // "user-a@example.com:80"
System.out.println(url2.getHost()); // "example.com"

final var url3 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url3.getAuthority()); // "example.com"
System.out.println(url3.getHost()); // "example.com"

final var url4 = new URL("file:///~/calendar");
System.out.println(url4.getAuthority()); // ""
System.out.println(url4.getHost()); // ""

final var url5 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url5.getAuthority()); // null
System.out.println(url5.getHost()); // ""

final Object getContent ()

このURLのコンテンツを取得します。

※どの Content-Type がなんのクラスを返すのか…そのあたりの仕様を見つけられていません。
とりあえず text/html は InputStream を返すようです。
疑問点が解決したら更新するかもです。

final var url = new URL("http://example.com");
final var content = url.getContent();

if (content instanceof InputStream inputStream) {
    try (final var reader = new BufferedReader(new InputStreamReader(inputStream))) {
        reader.lines().forEach(System.out::println);
    }
}

// 結果
// ↓
//<!doctype html>
//<html>
//<head>
//    <title>Example Domain</title>
// ...
//</html>

final Object getContent (Class<?>[] classes)

このURLのコンテンツを取得します。

final var url = new URL("http://example.com");
final Class<?>[] classes = {InputStream.class};

final var content = url.getContent(classes);
if (content instanceof InputStream inputStream) {
    try (final var reader = new BufferedReader(new InputStreamReader(inputStream))) {
        reader.lines().forEach(System.out::println);
    }
}

// 結果
// ↓
//<!doctype html>
//<html>
//<head>
//    <title>Example Domain</title>
// ...
//</html>

int getDefaultPort ()

このURLに関連するプロトコルのデフォルトのポート番号を取得します。

このメソッドの使用例は、getPort() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

String getFile ()

このURLのファイル名を取得します。

getPath との違いはクエリー部分を含むかどうかです。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.getFile()); // "/docs/resource1.html"
System.out.println(url1.getPath()); // "/docs/resource1.html"

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2.getFile()); // "/index.html?query"
System.out.println(url2.getPath()); // "/index.html"

final var url3 = new URL("http://user-a@example.com:80/");
System.out.println(url3.getFile()); // "/"
System.out.println(url3.getPath()); // "/"

final var url4 = new URL("file:///~/calendar");
System.out.println(url4.getFile()); // "/~/calendar"
System.out.println(url4.getPath()); // "/~/calendar"

final var url5 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url5.getFile()); // "file:/home/xxx/sample.jar!/sample.txt"
System.out.println(url5.getPath()); // "file:/home/xxx/sample.jar!/sample.txt"

String getHost ()

該当する場合、このURLのホスト名を取得します。

このメソッドの使用例は、getAuthority() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

String getPath ()

このURLのパス部分を取得します。

このメソッドの使用例は、getFile() にまとめて記載しました。
そちらのAPI使用例をご参照ください。

int getPort ()

このURLのポート番号を取得します。

final var uri1 = new URL("http://example.com/");
System.out.println(uri1.getDefaultPort()); // 80
System.out.println(uri1.getPort()); // -1

final var uri2 = new URL("http://example.com:9999/");
System.out.println(uri2.getDefaultPort()); // 80
System.out.println(uri2.getPort()); // 9999

final var uri3 = new URL("https://example.com/");
System.out.println(uri3.getDefaultPort()); // 443
System.out.println(uri3.getPort()); // -1

final var uri4 = new URL("ftp://example.com/");
System.out.println(uri4.getDefaultPort()); // 21
System.out.println(uri4.getPort()); // -1

final var uri5 = new URL("file:///~/calendar");
System.out.println(uri5.getDefaultPort()); // -1
System.out.println(uri5.getPort()); // -1

final var uri6 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(uri6.getDefaultPort()); // -1
System.out.println(uri6.getPort()); // -1

String getProtocol ()

このURLのプロトコル名を取得します。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.getProtocol()); // "http"

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2.getProtocol()); // "https"

final var url3 = new URL("file:///~/calendar");
System.out.println(url3.getProtocol()); // "file"

final var url4 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url4.getProtocol()); // "jar"

String getQuery ()

このURLのクエリー部分を取得します。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.getQuery()); // null

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2.getQuery()); // "query"

final var url3 = new URL("https://example.com/index.html?aaa&bbb&ccc");
System.out.println(url3.getQuery()); // "aaa&bbb&ccc"

final var url4 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url4.getQuery()); // null

String getRef ()

このURLのアンカー(「参照」とも呼ばれる)を取得します。

アンカーはURIでいうフラグメントのことです。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.getRef()); // null

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2.getRef()); // "fragment"

final var url3 = new URL("https://example.com/#aaaa");
System.out.println(url3.getRef()); // "aaaa"

final var url4 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url4.getRef()); // null

String getUserInfo ()

このURLのユーザー情報部分を取得します。

final var url1 = new URL("http://example.com/");
System.out.println(url1.getUserInfo()); // null

final var url2 = new URL("http://user-a@example.com:80/");
System.out.println(url2.getUserInfo()); // "user-a"

int hashCode ()

ハッシュ表のインデックス付けに適したint値を作成します。

final var url1 = new URL("http://example.com/");
final var url2 = new URL("http://example.com/");

System.out.println(url1 != url2); // true
System.out.println(url1.hashCode()); // 1575608617
System.out.println(url2.hashCode()); // 1575608617
// 大文字・小文字の区別はしません。
final var url1 = new URL("http://example.com/");
final var url2 = new URL("HTTP://EXAMPLE.COM/");

System.out.println(url1.hashCode()); // 1575608617
System.out.println(url2.hashCode()); // 1575608617
final var url1 = new URL("http://example.com/a");
final var url2 = new URL("http://example.com/b");

System.out.println(url1.hashCode()); // 1575610124
System.out.println(url2.hashCode()); // 1575610125
// IPアドレスで一致していればハッシュ・コードも同じになります。
final var url1 = new URL("http://example.com");
final var url2 = new URL("http://www.example.com");

System.out.println(url1.equals(url2)); // true
System.out.println(url1.hashCode()); // 1575608570
System.out.println(url2.hashCode()); // 1575608570

URLConnection openConnection ()

URLが参照するリモート・オブジェクトへの接続を表すURLConnectionインスタンスを返します。

final var url = new URL("http://example.com");

final var connection = url.openConnection();
System.out.println(connection.getContentType()); // "text/html; charset=UTF-8"

try (final var reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
    reader.lines().forEach(System.out::println);
}

// 結果
// ↓
//<!doctype html>
//<html>
//<head>
//    <title>Example Domain</title>
// ...
//</html>

URLConnection openConnection (Proxy proxy)

openConnection()と同じですが、指定されたプロキシを介して接続が行われます。プロキシをサポートしないプロトコル・ハンドラは、プロキシ・パラメータを無視し、通常の接続を作成します。

final var url = new URL("http://example.com");
final var proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy.example.com", 8080));

final var connection = url.openConnection(proxy);
System.out.println(connection.getContentType()); // "text/html; charset=UTF-8"

try (final var reader = new BufferedReader(new InputStreamReader(connection.getInputStream()))) {
    reader.lines().forEach(System.out::println);
}

// 結果
// ↓
//<!doctype html>
//<html>
//<head>
//    <title>Example Domain</title>
// ...
//</html>

final InputStream openStream ()

このURLへの接続を開き、その接続から読み込むためのInputStreamを返します。

final var url = new URL("http://example.com");
try (final var reader = new BufferedReader(new InputStreamReader(url.openStream()))) {
    reader.lines().forEach(System.out::println);
}

// 結果
// ↓
//<!doctype html>
//<html>
//<head>
//    <title>Example Domain</title>
// ...
//</html>

boolean sameFile (URL other)

フラグメント・コンポーネント以外の2つのURLを比較します。

final var url1 = new URL("http://example.com/");
final var url2 = new URL("http://example.com/");

System.out.println(url1 != url2); // true
System.out.println(url1.sameFile(url2)); // true
// 参照(フラグメント)は除外して比較されます。
final var url1 = new URL("http://example.com/#aaa");
final var url2 = new URL("http://example.com/#bbb");

System.out.println(url1.sameFile(url2)); // true
// クエリが違えば不一致。
final var url1 = new URL("http://example.com/?aaa");
final var url2 = new URL("http://example.com/?bbb");

System.out.println(url1.sameFile(url2)); // false
// 大文字・小文字の区別はしません。
final var url1 = new URL("http://example.com/");
final var url2 = new URL("HTTP://EXAMPLE.COM/");

System.out.println(url1.sameFile(url2)); // true
final var url1 = new URL("http://example.com/a");
final var url2 = new URL("http://example.com/b");

System.out.println(url1.sameFile(url2)); // false
// IPアドレスで一致していればtrueです。
final var url1 = new URL("http://example.com/");
final var url2 = new URL("http://www.example.com/");

System.out.println(url1.sameFile(url2)); // true

static void setURLStreamHandlerFactory (URLStreamHandlerFactory fac)

アプリケーションのURLStreamHandlerFactoryを設定します。

class DummyURLStreamHandler extends URLStreamHandler {
    @Override
    protected URLConnection openConnection(URL u) {
        System.out.println("openConnection! : " + u);
        return new URLConnection(u) {
            @Override
            public void connect() {
                System.out.println("connect!");
            }
        };
    }
}

URL.setURLStreamHandlerFactory(protocol -> {
    System.out.println("createURLStreamHandler! : " + protocol);
    return new DummyURLStreamHandler();
});

final var url = new URL("http://example.com/");
final var connection = url.openConnection();
connection.connect();

// 結果
// ↓
//createURLStreamHandler! : http
//openConnection! : http://example.com/
//connect!

String toExternalForm ()

このURLの文字列表現を構築します。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.toExternalForm()); // "http://www.example.com/docs/resource1.html"

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2.toExternalForm()); // "https://example.com/index.html?query#fragment"

final var url3 = new URL("file:///~/calendar");
System.out.println(url3.toExternalForm()); // "file:/~/calendar"

final var url4 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url4.toExternalForm()); // "jar:file:/home/xxx/sample.jar!/sample.txt"

String toString ()

このURLの文字列表現を構築します。

結果は toExternalForm() と同じになります。
API使用例は toExternalForm のメソッドをご参照ください。

結果は同じ。ならどちらを使ったほうがよいのか…

外部サイトですが参考までに。
Is there a semantic difference between toExternalForm and toString on java.net.URL? - Stack Overflow

URI toURI ()

このURLと等価なURIを返します。

final var url1 = new URL("http://www.example.com/docs/resource1.html");
System.out.println(url1.toURI()); // "http://www.example.com/docs/resource1.html"

final var url2 = new URL("https://example.com/index.html?query#fragment");
System.out.println(url2.toURI()); // "https://example.com/index.html?query#fragment"

final var url3 = new URL("file:///~/calendar");
System.out.println(url3.toURI()); // "file:/~/calendar"

final var url4 = new URL("jar:file:/home/xxx/sample.jar!/sample.txt");
System.out.println(url4.toURI()); // "jar:file:/home/xxx/sample.jar!/sample.txt"
final var url1 = new URL("http://example.com/a b c/");
//url1.toURI(); // URISyntaxException

// エスケープ例
final var url2 = new URL("http://example.com/a%20b%20c/");
System.out.println(url2.toURI()); // "http://example.com/a%20b%20c/"
System.out.println(url2.toURI().getPath()); // "/a b c/"

関連記事

  • API 使用例
ページの先頭へ