JAX-RS Client の WebTarget.queryParam() の仕様にハマったのでメモ。

問題点

WebTarget.queryParam() の仕様はこちらです。
WebTarget に対してクエリパラメータを設定するというメソッドです。

このメソッド、URIエンコードについて注意点があります。

URIテンプレートは {} で囲んだ部分にパスパラメータを突っ込んでくれるという機能ですが、よく考えるとちょっと問題があります。
それはクエリパラメータ値に "{" や "}" 自体を含めることができない、という問題です。"{", "}" ともにパスパラメータとして解釈されるためですね。

これを避けるためには、"{" や "}" を URIエンコードしなければなりません。それぞれ %7b, %7d にすれば良いということです。

が、JerseyやRESTEasyなどの実装では本メソッドは上記の通り URI エンコードをする動作なので、そのままもう一度URIエンコードされると %257b, %257d に変換されてしまうはずです。つまり { や } が使えないのでは、、、？

回避方法

Jersey 実装ではこれを回避するために URI エンコードを二重に実施しないようになっています。具体的には % の後ろに16進文字(0-9a-fA-F)が２個連続している場合は % をエンコードしないというルールです。なので、{, } をそのままエンコードしても大丈夫です。

また逆に考えると、たまたま % の後ろに16進文字が２個連続していたら % は URL エンコードしてくれないということでもあります。

従って、常に自分で URIエンコードしてから queryParam() を呼ぶようにしたほうがよいということです。

他の実装がどうなっているかは知りません。RESTEasy のコードをちょっと見た感じでは % は一切エンコードしないようになっていたみたいです。

当然ですが、上記動作は JAX-RS の仕様からは読み取れないです(実装依存)。なので一応動作確認してから使いましょう。