ドキュメント

§Play 2.8 移行ガイド

このガイドは、Play 2.7からPlay 2.8への移行を対象としています。Play 2.6からアップグレードする場合は、Play 2.7移行ガイドを参照してください。また、Akka 2.5から2.6への移行にはPlay 2.8に影響を与える変更が複数含まれているため、Akka 2.5から2.6への移行ガイドを読むことをお勧めします。

§移行方法

sbtを開始する前に、以下のアップグレードを必ず行ってください。

§Playのアップデート

project/plugins.sbtでPlayのバージョン番号を更新します。

addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.8.x")

2.8.xの "x" は、使用するPlayのマイナーバージョン（例えば2.8.0）です。

§sbtのアップグレード

Play 2.8は依然としてsbt 0.13をサポートしていますが、sbt 1を使用することをお勧めします。この新しいバージョンはサポートされており、アクティブにメンテナンスされています。更新するには、project/build.propertiesを変更して、以下のようにします。

sbt.version=1.3.10

この記事の執筆時点では、1.3.10がsbt 1.xファミリの最新バージョンですが、より新しいバージョンも使用できる場合があります。Playのマイナーバージョンのリリースノートとsbtのリリースノートで詳細を確認してください。

§APIの変更

Play 2.8には、複数のAPI変更が含まれています。通常どおり、削除する前に既存のAPIを非推奨にするというポリシーに従っています。このセクションでは、これらの変更について詳しく説明します。

§SSLEngineProviderがSSLContextを可視化

HTTPSを設定する場合、SSL証明書を完全に構成する必要がある場合は、play.server.SSLEngineProviderをオーバーライドできます。Play 2.8.0より前は、プロバイダーはSSLEngineのみを可視化していました。サードパーティのライブラリとの統合を改善するために、SSLContextも可視化する必要があるようになりました。詳細については、ConfiguringHttpsページをご覧ください。

§Scala 2.11のサポートが終了

Play 2.8はScala 2.12と2.13をサポートしますが、サポートが終了した2.11はサポートしません。

§プロジェクトでscalaVersionを設定する

ScalaとJavaの両方のユーザーは、Scala 2.12または2.13を使用するようにsbtを設定する必要があります。プロジェクトにScalaコードがない場合でも、Play自体はScalaを使用するため、適切なScalaライブラリを使用するように設定する必要があります。

sbtでScalaバージョンを設定するには、scalaVersionキーを設定するだけです。例：

scalaVersion := "2.13.13"

単一のプロジェクトビルドを使用している場合、この設定はbuild.sbt内の独自の行に配置できます。ただし、マルチプロジェクトビルドを使用している場合は、各プロジェクトでscalaバージョン設定を設定する必要があります。通常、マルチプロジェクトビルドでは、すべてのプロジェクトで共有される共通設定があり、これが設定を配置するのに最適な場所です。例：

def commonSettings = Seq(
  scalaVersion := "2.13.13"
)

val projectA = (project in file("projectA"))
  .enablePlugins(PlayJava)
  .settings(commonSettings)

val projectB = (project in file("projectB"))
  .enablePlugins(PlayJava)
  .settings(commonSettings)

§ファイル提供メソッドのfilenameパラメータの型が変更

Java APIのok(File content, ...)（および同様のメソッド）や、JavaのStatusHeaderとScalaのStatusクラスのsendFile、sendPath、sendResourceなどのファイルを提供するメソッドでは、filenameパラメータの型が変更されました。Scala APIでは、プレーンなStringを使用する代わりに、filenameパラメーター関数に対してOption[String]を戻り値の型として使用するようになりました。Java APIでは、パラメーターの型がOptional<String>に変更されました。
このAPIの変更は、Content-Dispositionヘッダーにファイル名を含めたくない場合にNone / Optional.empty()を渡せるという事実をより適切に反映しています。

§Java APIのHeadersクラスは不変

play.mvc.Http.Headersクラスは不変になりました。いくつかのメソッドが非推奨になり、新しいメソッドに置き換えられました。

非推奨のメソッド 新しいメソッド
toMap() asMap()
addHeader(String name, String value) adding(String name, String value)
addHeader(String name, List<String> values) adding(String name, List<String> values)
remove(String name) removing(String name)

古い非推奨のメソッドは、元の変更されたHeadersオブジェクトを返すのに対し、新しいメソッドは常に新しいオブジェクトを返し、元のオブジェクトは変更されないことに注意してください。

§非推奨のAPIが削除されました

以前のバージョンで非推奨になった多くのAPIがPlay 2.8で削除されました。それらをまだ使用している場合は、Play 2.8にアップグレードする前に新しいAPIに移行することをお勧めします。移行に関する注意については、JavadocとScaladocを確認してください。詳細については、Play 2.7の移行ガイドも参照してください。

§Java API

Play 2.7では、play.mvc.Http.Contextを非推奨にし、play.mvc.Http.RequestHeaderまたはplay.mvc.Http.Requestを直接使用することをお勧めしました。Http.Contextは削除されました。アプリケーションがそれに依存している場合は、Play 2.7の移行ガイドの指示を読む必要があります。

§Cache APIの変更

§構成の変更

このセクションでは、構成の変更と非推奨について説明します。

§ObjectMapperシリアル化の変更

Play 2.8はAkka Jacksonシリアル化のサポートを採用し、Akkaによって提供されるデフォルトを使用します。変更点の1つは、Java Time型がどのようにレンダリングされるかです。Play 2.7まで、それらはタイムスタンプとしてレンダリングされていましたが、パフォーマンスが向上していましたが、現在はISO-8601（rfc3339）形式（yyyy-MM-dd'T'HH:mm:ss.SSSZ）を使用してレンダリングされます。

古いタイムスタンプのデフォルト形式を使用する必要がある場合は、application.confに次の構成を追加します。

akka.serialization.jackson.play.serialization-features {
  WRITE_DATES_AS_TIMESTAMPS = on
  WRITE_DURATIONS_AS_TIMESTAMPS = on
}

Playが提供するObjectMapperのインスタンス（Json#newDefaultMapperまたはGuice管理のplay.core.ObjectMapperProviderを使用）には、JsonNodeへのJacksonデシリアライザーのスタック効率の高い実装が含まれています。すでにカスタムデシリアライザーを使用してjsonペイロードをJsonNodeに読み込んでいる場合は、2つのオプションがあります。

  1. 設定を使用して、Playのplay.utils.JacksonJsonNodeModuleをObjectMapperから無効にできます。
akka.serialization.jackson.play {
  jackson-modules = ${akka.serialization.jackson.jackson-modules}
  ##   Play's default settings concatenate "akka.serialization.jackson.jackson-modules" 
  ##      with "play.utils.JacksonJsonNodeModule" 
  ## jackson-modules = ${akka.serialization.jackson.jackson-modules} ["play.utils.JacksonJsonNodeModule"]
}
  1. さらに進んで、バインドするplay.core.ObjectMapperModule Guiceモジュールを完全に無効にできます。
    ObjectMapper を Provider<ObjectMapper> に変更する必要があります。次に、独自の
    com.example.ObjectMapperModule を作成し、そのバインディングを提供する必要があります。
play.modules.disabled += "play.core.ObjectMapperModule"
play.modules.enabled += "com.example.ObjectMapperModule"

§akka.actor.default-dispatcher.fork-join-executor のオーバーライドを削除しました

Play が akka.actor.default-dispatcher.fork-join-executor の下で持っていたオーバーライドは、Akka の新しく改善されたデフォルトを使用するために削除されました。

詳細については、Akka の移行ガイドにあるデフォルトディスパッチの変更に関するセクションを参照してください。

§Akka Streams における IOSource および FileIO の変更

FileIO.toPath、StreamConverters.fromInputStream、および StreamConverters.fromOutputStream に関する Akka Streams のエラー処理方法に関連する変更があります。詳細については、Akka の移行ガイドにあるこれらの変更に関するセクションを参照してください。

§構成のロードに関する変更

Play 2.7 まで、構成をロードする際、ユーザーがいくつかのプロパティを提供した場合、Play はデフォルトのJava システムプロパティを考慮していませんでした。現在、システムプロパティは常に考慮されるため、カスタムプロパティを定義している場合でも、application.conf ファイルでそれらを参照できます。たとえば、下記のコードのようにPlay を埋め込む場合、userProperties とシステムプロパティの両方が使用されます。

import java.util.Properties

import play.api.mvc.Results
import play.core.server.AkkaHttpServer
import play.core.server.ServerConfig
import play.api.routing.sird._

class MyApp {
  def main(args: Array[String]): Unit = {
    // Define some user properties here
    val userProperties = new Properties()
    userProperties.setProperty("my.property", "some value")

    val serverConfig = ServerConfig(properties = userProperties)

    val server = AkkaHttpServer.fromRouterWithComponents(serverConfig) { components => {
      case GET(p"/hello") => components.defaultActionBuilder {
        Results.Ok
      }
    }}
  }
}

システムプロパティはユーザー定義のプロパティを上書きすることに注意してください。

§SSL接続のデバッグ

Play 2.7 まで、Play と Play-WS の両方が、内部の JSSE デバッグ設定のドキュメント化されていない変更に依存するデバッグシステムを備えた ssl-config のバージョンを使用していました。これらは通常、起動時に javax.net.debug および java.security.debug システムプロパティを使用して設定されます。

デバッグシステムは削除され、新しいシステムに直接的な相関関係がないデバッグフラグは非推奨となり、新しい構成はssl-config のドキュメントに記載されています。

§I18n の動作の変更

言語のマッチングの動作が、RFC 4647 を満たすようになりました。

§例

conf/application.conf ファイル

play.i18n.langs = [ "fr", "fr-FR", "en", "en-US" ]

ユーザーの accept-language

en-GB
§変更前

ユーザーの accept-language en-GB は conf のいずれにも一致しません。Play アプリは、ユーザーの意向に反してフランス語のページを返します。

§変更後

ユーザーの accept-language en-GB は en に一致します。Play アプリは英語のページを返します。

§一般化されたサーバーバックエンド構成

Play には 2 つの サーバーバックエンド が付属しています。

これまで、両方のバックエンドに適用される設定があり、結果的に重複している場合でも、これらの構成は別々に保持していました。
Play 2.8 では、このような重複したサーバーバックエンド構成を一般化し始め、play.server.* の直下に移動します。

§Redirect HTTPS フィルターの excludePaths 構成が変更されました

Redirect HTTPS フィルターの play.filters.https.excludePaths 構成には、URI ではなくパスのリストが含まれるようになりました。つまり、クエリパラメータはもう関係ありません。リストに /foo が含まれている場合、リクエスト /foo?abc=xyz も除外されるようになります。Play 2.8 より前は、リクエストの URI (パス + クエリパラメータ) がリストと照合されていたため、リダイレクトから除外するには、リクエストの URI を正確に追加する必要がありました。

§デフォルトの変更

Play によって使用される一部のデフォルト値が変更されており、それがアプリケーションに影響を与える可能性があります。このセクションでは、デフォルトの変更について詳しく説明します。

§ファイルを処理する際、Content-Disposition: inline ヘッダーが送信されなくなりました

Scala API または Java API を介してファイルを処理する場合、Play はデフォルトで Content-Disposition ヘッダーを自動的に生成し、クライアントに送信します。

ただし、Play 2.8 以降では、計算されたヘッダーが正確に Content-Disposition: inline になる場合 (デフォルトである inline = true を渡し、ファイル名を null にした場合)、Play は自動的に送信しなくなります。これは、RFC 6266 セクション 4.2 によると、コンテンツをインラインでレンダリングするのがデフォルトであるためです。

したがって、すべてのブラウザが仕様を遵守しており、このヘッダーを特別な方法で扱うのではなく、ヘッダーが送信されていないかのようにインラインでコンテンツをレンダリングするため、この変更はまったく影響しないはずです。

ただし、この正確なヘッダーを送信したい場合は、Scala または Java の Result クラスの withHeader(s) メソッドを使用して送信できます。

§依存関係グラフの変更

Play 2.7.0 まで、"com.typesafe.play" %% "play-test" アーティファクトには、Akka HTTP と Netty サーバーバックエンドの両方が含まれていました。これにより、テストの動作が不安定になり、クラスパスの並べ替え方によっては、実稼働コードとは異なるサーバーが使用される可能性がありました。Play 2.8 では、play-test は代わりに play-server に依存するようになり、テストはアプリケーションが使用するのと同じサーバープロバイダーを使用します。何らかの理由でテストにプロバイダーを追加する必要がある場合は、Akka HTTP または Netty サーバーの依存関係を "test" の依存関係として追加することでそれを行うことができます。たとえば、次のようになります。

libraryDependencies += akkaHttpServer % "test" // Use nettyServer if you want the Netty Server backend

§更新されたライブラリ

独自のライブラリ (play-json、play-ws、twirl、cachecontrol など) の新しいバージョンへの更新に加えて、他の多くの重要な依存関係が最新バージョンに更新されました。

次: Play 2.7

このドキュメントにエラーを見つけましたか？このページのソースコードはこちらにあります。 ドキュメントのガイドラインを読んだ後、プルリクエストを遠慮なく送信してください。質問や共有するアドバイスがありますか？コミュニティフォーラムにアクセスして、コミュニティとの会話を開始してください。