ひだまりソケットは壊れない

ソフトウェア開発に関する話を書きます。 最近は主に Android アプリ、Windows アプリ (UWP アプリ)、Java 関係です。

まじめなことを書くつもりでやっています。 適当なことは 「一角獣は夜に啼く」 に書いています。

Java EE 技術から EE4J (Jakarta EE) 技術に移行する

2017 年に発表された Java EE の Eclipse Foundation への移管。 移管されたプロジェクトをまとめるルートプロジェクトの名前は Eclipse Enterprise for Java (EE4J) で、Java EE に相当するプラットフォームの名前は Jakarta EE となっている *1

EE4J には JAX-RSJSON Processing (JSON-P) などの Java EE の一部として使われていたプロジェクトも移管されている。 これらを単体で使う場合も今後は EE4J のものを使っていくべきだろう。 (古いリポジトリの方は更新されないだろうので。)

EE4J 傘下になってからの最初のリリースがぼちぼちなされていたりして、そろそろ EE4J の方に移行できるようになってきているので、移行について調べたことをまとめておく。

EE4J の各プロジェクト

EE4J 傘下のプロジェクトについては EE4J プロジェクトページ からリンクがあるので、それを辿ると見つけられる。 例えば JAX-RS のページや JSON-P のページは下記である。

EE4J 各プロジェクトの Maven リポジトリ

EE4J への移管に伴って、多くのプロジェクトの API や参照実装 (Reference Implementation; RI) の Maven リポジトリのグループ ID やアーティファクト ID が変更されている。 API については下記ページにまとめられている。

見た感じでは、javax という部分が jakarta に変更されている模様 *2

参照実装についてはプロジェクトごとに異なるようである。

例えば、JSON-P の参照実装については下記のように書かれており、org.glassfish:javax.json から org.glassfish:jakarta.json に変更されていることがわかる。

The main API jar file is now located at jakarta.json:jakarta.json-api and the main RI jar file is now located at org.glassfish:jakarta.json.

JSON Processing (JSON-P)

一方で、JAX-RS の参照実装である Jersery については、バージョン 2.28 が最初の Jakarta EE 実装としてリリースされているが、特にグループ ID やアーティファクト ID の変更はないようである。

ソースコードの変更は必要か?

Maven アーティファクトの名前が変わってはいつつも、API 自体に変更はない。 Java EE 時代の最後の API を使っているソースコードであれば、そのまま EE4J の最初のリリースに移行できるはず。

This is common for every Jakarta EE project this release: it was required not to provide any changes in API and functionality to ensure the compatibility between last Java EE and initial Jakarta EE releases.

Jersey 2.28 has been released | Jan's Blog

*1:EE4J と Jakarta EE の名前の使い方などは Jakarta EE の FAQ に書かれている。 が、これを読んでも正直なところ EE4J と Jakarta EE の使い分けがいまいちわからない……。

*2:正式な名前変更のルールについてはどこかで言及されているのかもわからないが、見つけられていない。

JAX-RS のリソースから送出された例外の扱い

JAX-RS のリソースのメソッドから例外が送出された場合の挙動についてちゃんと把握していなかったので調べた。

前提知識 : JAX-RS について

JAX-RS は、RESTful Web API を提供するための JavaAPI。 もともとは Java EE の一部。 現在は Eclipse Foundation に移管されて EE4J プロジェクトの一部 (Jakarta EE の一部) となっている。

JAX-RS のリソースから送出された例外の扱いについて

今回は JAX-RS 2.1 の仕様を参照する。

3.3.4 節に書かれている。

3.3.4 Exceptions

A resource method, sub-resource method or sub-resource locator may throw any checked or unchecked exception. An implementation MUST catch all exceptions and process them in the following order:

  • 1. Instances of WebApplicationException and its subclasses MUST be mapped to a response as follows. If the response property of the exception does not contain an entity and an exception mapping provider (see Section 4.4) is available for WebApplicationException or the corresponding subclass, an implementation MUST use the provider to create a new Response instance, otherwise the response property is used directly. The resulting Response instance is then processed according to Section 3.3.3.
  • 2. If an exception mapping provider (see Section 4.4) is available for the exception or one of its superclasses, an implementation MUST use the provider whose generic type is the nearest superclass of the exception to create a Response instance that is then processed according to Section 3.3.3. If the exception mapping provider throws an exception while creating a Response then return a server error (status code 500) response to the client.
  • 3. Unchecked exceptions and errors that have not been mapped MUST be re-thrown and allowed to propagate to the underlying container.
  • 4. Checked exceptions and throwables that have not been mapped and cannot be thrown directly MUST be wrapped in a container-specific exception that is then thrown and allowed to propagate to the underlying container. Servlet-based implementations MUST use ServletException as the wrapper. JAX-WS Provider-based implementations MUST use WebServiceException as the wrapper.

Note: Items 3 and 4 allow existing container facilities (e.g. a Servlet filter or error pages) to be used to handle the error if desired.

Exception mapping provider による変換

上記の説明の中に、「exception mapping provider」 というものが出てくる。 詳細は 4.4 節に書かれている。

4.4 Exception Mapping Providers

Exception mapping providers map a checked or runtime exception to an instance of Response. An exception mapping provider implements the ExceptionMapper<T> interface and may be annotated with @Provider for automatic discovery.

When a resource class or provider method throws an exception for which there is an exception mapping provider, the matching provider is used to obtain a Response instance. The resulting Response is processed as if a web resource method had returned the Response, see Section 3.3.3. In particular, a mapped Response MUST be processed using the ContainerResponse filter chain defined in Chapter 6.

When choosing an exception mapping provider to map an exception, an implementation MUST use the provider whose generic type is the nearest superclass of the exception. If two or more exception providers are applicable, the one with the highest priority MUST be chosen as described in Section 4.1.3.

To avoid a potentially infinite loop, a single exception mapper must be used during the processing of a request and its corresponding response. JAX-RS implementations MUST NOT attempt to map exceptions thrown while processing a response previously mapped from an exception. Instead, this exception MUST be processed as described in steps 3 and 4 in Section 3.3.4.

すなわち、リソースメソッドなどから送出された例外を変換して Response オブジェクトを生成する機能を提供するものである。

Exception mapping provider は複数登録することができる。 例外が送出されると、対応する exception mapping provider が選択され、Response が生成されて、それがレスポンスとして使用される。 対応する exception mapping provider がない場合、非検査例外だとそのまま再送出されるし、検査例外だとコンテナに応じた非検査例外にラップされて送出されるとのこと。

WebApplicationException について

基本的には上に書いた通りの例外ハンドリングがなされるが、リソースメソッドなどから送出された例外が WebApplicationException の場合は、exception mapping provider を通らないことがある。 3.3.4 節の箇条書きの 1 つめがそれである。

WebApplicationExceptionresponse プロパティがエンティティを持っていない場合で、対応する exception mapping provider が存在する場合には exception mapping provider による Response 生成がなされる。 それ以外の場合は WebApplicationExceptionresponse プロパティの値がそのままレスポンスとして使われる。

サンプルコード

JAX-RS の参照実装である Jersey を使った Kotlin のサンプルコード。

import org.glassfish.jersey.jdkhttp.JdkHttpServerFactory
import org.glassfish.jersey.server.ResourceConfig
import javax.ws.rs.GET
import javax.ws.rs.Path
import javax.ws.rs.WebApplicationException
import javax.ws.rs.core.Response
import javax.ws.rs.core.UriBuilder
import javax.ws.rs.ext.ExceptionMapper

@Path("exceptions")
class MyResource {
    @GET
    @Path("re")
    fun re() {
        // RuntimeException なので対応する MyExceptionMapper で変換される。
        throw RuntimeException("RuntimeException")
    }

    @GET
    @Path("wae-without-entity")
    fun waeWithoutEntity() {
        // エンティティのない WebApplicationException なので MyExceptionMapper で変換される。
        throw WebApplicationException("WebApplicationException with response not containing entity",
            Response.status(Response.Status.BAD_REQUEST).build())
    }

    @GET
    @Path("wae-with-entity")
    fun waeWithEntity() {
        // エンティティを持つ WebApplicationException なので MyExceptionMapper で変換されない。
        throw WebApplicationException("WebApplicationException with response containing entity",
            Response.status(Response.Status.BAD_REQUEST).entity("Entity").build())
    }
}

class MyExceptionMapper : ExceptionMapper<Throwable> {
    override fun toResponse(exception: Throwable): Response {
        println(exception)
        return Response.status(Response.Status.BAD_REQUEST).entity("$exception").build()
    }
}

fun main() {
    val baseUri = UriBuilder.fromUri("http://localhost/").port(9998).build()
    val config = ResourceConfig(MyResource::class.java, MyExceptionMapper::class.java)
    JdkHttpServerFactory.createHttpServer(baseUri, config)
}

ビルドコードは以下のような感じで動くはず。 (Gradle。)

plugins {
    id 'org.jetbrains.kotlin.jvm' version '1.3.11'
}

repositories {
    mavenCentral()
}

dependencies {
    compile "org.jetbrains.kotlin:kotlin-stdlib-jdk8"

    compileOnly "javax.ws.rs:javax.ws.rs-api:2.1"

    compile "org.glassfish.jersey.containers:jersey-container-jdk-http:2.27"
    compile "org.glassfish.jersey.inject:jersey-hk2:2.27"

    // JDK 9 以降は下記が必要。
    // See : https://stackoverflow.com/questions/43574426/how-to-resolve-java-lang-noclassdeffounderror-javax-xml-bind-jaxbexception-in-j
    compile "javax.xml.bind:jaxb-api:2.2.11"
    compile "javax.activation:activation:1.1.1"
}

compileKotlin {
    kotlinOptions.jvmTarget = "1.8"
}
compileTestKotlin {
    kotlinOptions.jvmTarget = "1.8"
}

JerseyTest で Servlet のリソースを扱う JAX-RS 部品のユニットテストを行う方法

要約

前提知識 : ServletJAX-RS

Jakarta EE (旧 Java EE) における HTTP サーバーアプリケーションのための API として有名なもの *1ServletJAX-RS がある。 これらは依存関係にはなく、Servlet 単体でも JAX-RS 単体でも使用できる。

一方で、JAX-RSServlet コンテナ内で実行し、JAX-RS コンポーネントServletコンポーネントをインジェクトするというような使い方もできる。

In a product that also supports the Servlet specification, implementations MUST support JAX-RS applications that are packaged as a Web application. See Section 2.3.2 for more information Web application packaging.

JAX-RS: Java™ API for RESTful Web Services version 2.1 (11. Environments - 11.2.1 Servlets)

The @Context annotation can be used to indicate a dependency on a Servlet-defined resource. A Servlet-based implementation MUST support injection of the following Servlet-defined types: ServletConfig, ServletContext, HttpServletRequest and HttpServletResponse.

JAX-RS: Java™ API for RESTful Web Services version 2.1 (11. Environment - 11.1 Servlet Container)

Servlet のリソースを扱う JAX-RS コンポーネントユニットテストする方法 (JerseyTest を使用)

JAX-RS コンポーネントユニットテストする方法は様々あるだろうが、個人的には JAX-RS の参照実装である Jersey のテストフレームワークを使う方法に親しみがある。

Jersey のテストフレームワークJerseyTest というクラスを提供しており、これを継承してテストクラスを作ると簡単に JAX-RS コンポーネントのテストを記述できる。

public class SimpleTest extends JerseyTest {
    // SimpleResource という JAX-RS リソースをテストしたい場合は、
    // それを ResourceConfig に渡してテスト用の Application を作ればよい。
    @Override
    protected Application configure() {
        return new ResourceConfig(SimpleResource.class);
    }

    // テストメソッド 
    @Test
    public void test() {
        final String responseContent = target("simple").request().get(String.class);
        assertEquals("Hello World!", responseContent);
    }
}

問題 : 単に JerseyTest を継承してテストクラスを定義するだけだと Servlet リソースが扱われない

上のようなテストコードを書いた場合、基本的には問題なくテストが動く。 しかし、SimpleResourceServlet のリソースを扱っている場合 (@ContextHttpServletRequest をインジェクトしている場合など) には、期待通りに動かない。

なぜなら、(おそらく) デフォルトで選択されるテストコンテナは Servlet をサポートしておらず、Servlet のリソースのインジェクトが行われないからである。

解決策 : Servlet をサポートしているテストコンテナを利用する

テストコンテナの決まり方については、ドキュメントに下記のように書かれている。

A test container is selected based on various inputs. JerseyTest#getTestContainerFactory() is always executed, so if you override it and provide your own version of TestContainerFactory, nothing else will be considered. Setting a system variable TestProperties#CONTAINER_FACTORY has similar effect. This way you may defer the decision on which containers you want to run your tests from the compile time to the test execution time. Default implementation of TestContainerFactory looks for container factories on classpath. If more than one instance is found and there is a Grizzly test container factory among them, it will be used; if not, a warning will be logged and the first found factory will be instantiated.

Chapter 26. Jersey Test Framework

一番簡単な方法は JerseyTest#getTestContainerFactory() をオーバーライドすることだろう。

Servlet をサポートしているテストコンテナもドキュメントに書かれている。

Second factory is GrizzlyWebTestContainerFactory that is Servlet-based and supports Servlet deployment context for tested applications. This factory can be useful when testing more complex Servlet-based application deployments.

Chapter 26. Jersey Test Framework

GrizzlyWebTestContainerFactory を使えばよい。 ちなみに GrizzlyWebTestContainerFactoryDeploymentContext として ServletDeploymentContext を求めるので、その点は注意が必要である。

ということで、下記のようなテストクラスを書けば Servlet のリソースを扱う JAX-RSユニットテストを記述できる。

import org.glassfish.jersey.server.ResourceConfig;
import org.glassfish.jersey.servlet.ServletContainer;
import org.glassfish.jersey.test.JerseyTest;
import org.glassfish.jersey.test.ServletDeploymentContext;
import org.glassfish.jersey.test.grizzly.GrizzlyWebTestContainerFactory;
import org.glassfish.jersey.test.spi.TestContainerException;
import org.glassfish.jersey.test.spi.TestContainerFactory;

public class CookieSessionResponseFilterTest extends JerseyTest {

    private TestContainerFactory testContainerFactory;

    /**
     * テスト用のコンテナを生成するメソッドをオーバーライド。
     *
     * ここで {@link GrizzlyWebTestContainerFactory} を指定することで、サーブレットベースのアプリケーションのテストが可能となる。
     */
    @Override
    protected TestContainerFactory getTestContainerFactory() throws TestContainerException {
        // こういう感じで同じインスタンスを返す必要があるのかはよくわからないが
        // JerseyTest の実装がそういう感じになっているのでそれに合わせている。
        if (testContainerFactory == null) {
            testContainerFactory = new GrizzlyWebTestContainerFactory();
        }
        return testContainerFactory;
    }

    /**
     * テスト用のコンテナにデプロイする内容。
     *
     * {@link GrizzlyWebTestContainerFactory} を使うためには {@link ServletDeploymentContext} を返す必要がある。
     */
    @Override
    protected ServletDeploymentContext configureDeployment() {
        ServletContainer jaxRsServlet = ;
        return ServletDeploymentContext
                // JAX-RS コンポーネントは `ServletContainer` に包んでやる。
                .forServlet(new ServletContainer(configure()))
                // Servlet フィルタの追加も可能。
                .addFilter(TestServletFilter.class, TestServletFilter.class.getSimpleName())
                .build();
    }

    // SimpleResource という JAX-RS リソースをテストしたい場合は、
    // それを ResourceConfig に渡してテスト用の Application を作ればよい。
    // {@link #configureDeployment()} をオーバーライドしたらこのメソッドを
    // オーバーライドしなくても良いはず (configureDeployment 内に書けばよいはず) だが、
    // 一応オーバーライドして {@link #configureDeployment()} から呼ぶようにした。
    @Override
    protected ResourceConfig configure() {
        return new ResourceConfig(SimpleResource.class);
    }

    // テストメソッド 
    @Test
    public void test() {
        final String responseContent = target("simple").request().get(String.class);
        assertEquals("Hello World!", responseContent);
    }
}

自分でテストコンテナのファクトリを書いても良い

上ではもともと Jersey のテストフレームワークに用意されている GrizzlyWebTestContainerFactory を利用したが、独自に TestContainerFactory を実装しても良い。 サーブレットを複数含むテストを書きたい場合などにはそうする必要がありそうである。 (そもそもそういうテストを書く必要がある設計にすべきではないという気もするが。)

JerseyTestでHttpServletRequestを使いたい - Chonaso's Commentary』 が参考になる。 (実際に自分で書いたらわりと手を入れる必要はあったが。)

おわり

まとめると、下記のとおり。

  • Jersey のテストフレームワークが便利。
  • Servlet のリソースも含めてテストしたい場合には GrizzlyWebTestContainerFactory を使用すると良い。

とはいえ、JAX-RSServlet のリソースを扱う必要がある場面は非常に限定的であるはずで、JAX-RSAPI だけで完結できる場面ではそうすべきである。 その方がテストも書きやすいし移植性も高い。 複数の API 仕様の知識 (JAX-RS の知識も Servelt の知識も必要) を求めることもなくなるので、開発者に対しても優しいはずである。

仕事で触っているコードには JAX-RS の中で Servlet のリソースを扱っているものがわりとあるのだが、少しずつ JAX-RSAPI に置き換えていきたい。

*1:これ以外にあるのかどうかは知らない。

読んだ: Java エンジニア養成読本

2014 年 12 月に発売された 『Java エンジニア養成読本 [現場で役立つ最新知識、満載!]』 を読みました。 これだけを読んで Java がわかるわけではないけど、歴史から Java EE、周辺技術に至るまで説明されていて、Java 初心者が全体を俯瞰するのに良さそうだと思いました!

内容紹介

本書は、複数の著者による共著になっています。

まず、巻頭記事がきしださんによる 「誰も教えてくれない Java の世界」。 Java の歴史や、Java のエディション (Java SE、EE、ME について)、JDKJREJCP、JSR の紹介や各種 IDE や有名なフレームワークの紹介など、Java を使い始めてみたけど世界観がよくわからない、という人に役立つ情報が凝縮されています。 「お前に Sun が救えるか」 といったネタも紹介されています。

続く特集 1 が irof さんによる 「Java 入門」。 もちろん Java の構文の細かいところまでは説明されていませんが、クラス定義についてや例外処理、標準ライブラリについてのプラクティスなどが紹介されています。

特集 2 は bitter_fox さんによる 「Java SE 8 時代のデータ処理入門」。 Java SE 8 で導入されたラムダ式や Stream API について説明されます。 私もここら辺のことはまだ詳しくは知らなかったのでためになりました。

特集 3 はキクタローさんによる 「現場で役立つ Java EE」。 Java 初心者にとっては Java EE とは何者なのか良くわからない存在だと思いますが、この特集を読むことでなんとなく何者であるかはわかると思います。 Java EE と一口に言ってもその技術要素は多岐に渡りますが、この特集では ServletJSFJAX-RSJPACDIEJB といったわりと良く使われる技術要素について主に説明されます。 私も JSFEJB については詳しくなかったので、本書を読んで勉強になりました。

特集 4 は渡辺さんによる 「現場で役立つチーム開発入門」。 Git や MavenJUnit によるテストや Jenkins といった、開発現場で良く使われている周辺技術が説明されます。

最後に 「イマドキの Java 受託開発の現場で求められる知識」 というタイトルで、提案や設計について、「web 開発の現場では Java の知識だけでなく、HTML や CSS、JS の知識なども必要である」 みたいな話や、テストやデプロイについて説明されます。

感想

Java 初心者が Java を使った web アプリケーション開発について学ぶのにちょうど良い書籍になっていると思います。 もちろん、前半は web アプリケーション開発とは関係なく Java について学べますし、Java を使うなら (web アプリケーション開発をするつもりがなくても) 読むと良いでしょう。

文体がいいのか構成がいいのかムックという本の形態が良いのかわかりませんが、技術書としては読みやすかったです。

既に Java について深い造詣があるならこの本を読む必要はないと思います *1 が、これから Java を使っていきたい人や最近 Java を学び始めた人は、この本を早い段階で呼んでおくと後々の学習が捗ると思います。 Java の良書はいろいろありますが、重量級なものも多いですので、まずは軽く本書から読んでみる、というのをオススメします。

あなたと Java エンジニア養成読本、今すぐ購入!

Kindle 版もあるようですよ!

Javaエンジニア養成読本 [現場で役立つ最新知識、満載!] (Software Design plus)

Javaエンジニア養成読本 [現場で役立つ最新知識、満載!] (Software Design plus)

Javaエンジニア養成読本[現場で役立つ最新知識、満載!]

Javaエンジニア養成読本[現場で役立つ最新知識、満載!]

*1:Java 8 周りはまだ、ということであれば 「Java SE 8 時代のデータ処理入門」 は役立つでしょう

JAX-RS アプリケーションの 404 Not Found のカスタマイズ (リソースが見つからない場合)

JAX-RS アプリケーションでリソースが見つからない場合に表示される 404 Not Found のレスポンスの内容を変更したい場合にどうすればいいか、という話。

リソースが見つからない場合: NotFoundException が投げられる

まずは、そもそもの話として、リソースが見つからなかった場合に内部的にどういう処理が行われているのか見てみます。

JAX-RS 2.0 のドキュメントを見ると、3.7.2 節 「Request Matching」 において、リソースクラスやリソースメソッドの選択について書かれています。 そこには、リクエストにマッチするリソースクラスがなかった場合の処理として、次のように書かれていました。

(d) If E is empty then no matching resource can be found, the algorithm terminates and an implementation MUST generate a
NotFoundException (404 status) and no entity

マッチするリソースクラスが存在しない場合、NotFoundException が投げられるようです。 マッチするリソースメソッドがなかった場合も、同様に NotFoundException が投げられると書かれています。

例外をレスポンスにマッピングする: ExceptionMappter<T>

さて、内部的には例外が発生していることがわかりましたので、その例外をうまく扱いたいところです。

JAX-RS には、例外をレスポンスにマッピングする Exception Mapping Provider という仕組みがあります。 JAX-RS 2.0 のドキュメントの 4.4 節 「Exception Mapping Providers」 に次のように書かれています。

Exception mapping providers map a checked or runtime exception to an instance of
Response. An exception mapping provider implements the ExceptionMapper<T>
interface and may be annotated with @Provider for automatic discovery. When choosing an exception mapping provider to map an exception, an implementation MUST use the provider whose generic type is the nearest superclass of the exception

NotFoundException を適当なレスポンスにマッピングするための Exception Mappging Provider を書くことで、リソースが見つからない場合の 404 Not Found をカスタマイズできます。 (もちろん、リソースが見つからない場合のエラー以外にも適用できます。)

サンプルコード

カスタマイズ前

以下のように、JAX-RS 実装として Jersey を使用し、Grizzly 上で JAX-RS アプリケーションを動かしているとします。

// 必要な import 文
import java.net.URI;
import javax.ws.rs.core.UriBuilder;
import org.glassfish.grizzly.http.server.HttpServer;
import org.glassfish.jersey.grizzly2.httpserver.GrizzlyHttpServerFactory;
import org.glassfish.jersey.server.ResourceConfig;

// 処理
URI baseUri = UriBuilder.fromUri("http://localhost/").port(10082).build();
ResourceConfig config = new ResourceConfig();
HttpServer server = GrizzlyHttpServerFactory.createHttpServer(baseUri, config);

上のコードでは、リソースクラスを 1 個も登録していないので、ブラウザで http://localhost:10082/ にアクセスしても 404 Not Found が返ってきます。 (ページ自体は真っ白。)

カスタマイズ後

以下のような Exception Mapping Provider を書いてみます。 単に 「404 Not Found!!!」 という文字列を表示するだけのレスポンスです。

import javax.ws.rs.NotFoundException;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.Response.Status;
import javax.ws.rs.ext.ExceptionMapper;
import javax.ws.rs.ext.Provider;

@Provider
public class NotFoundExceptionMapper implements ExceptionMapper<NotFoundException> {

    @Override
    public Response toResponse(NotFoundException exception) {
        return Response.status(Status.NOT_FOUND).entity("404 Not Found!!!").build();
    }

}

そして、以下のように ResourceConfig に登録します。

URI baseUri = UriBuilder.fromUri("http://localhost/").port(10082).build();
ResourceConfig config = new ResourceConfig();
config.register(NotFoundExceptionMapper.class);
HttpServer server = GrizzlyHttpServerFactory.createHttpServer(baseUri, config);

これで、リソースが見つからなかった場合にカスタマイズされた 「404 Not Found!!!」 という文字列が返されるようになります。