-```
-
-
-## リバースルーティングと公開アセットへのフィンガープリント
-
-
-[sbt-web](https://github.com/sbt/sbt-web) は、例えば以下のビルドファイルのように、高度に設定可能なアセットパイプラインの概念を Play に持ち込みました:
-
-```scala
-pipelineStages := Seq(rjs, digest, gzip)
-```
-
-
-上記の場合、RequireJs オプティマイザ (`sbt-rjs`), ダイジェスト (`sbt-digest`) と、続けて圧縮 (`sbt-gzip`) が順序付けられます。多くの sbt タスクとは異なり、これらのタスクは宣言された順序で、ひとつずつ実行されます。
-
-
-アセットのフィンガープリントにより、ブラウザに対して提供する静的なアセットのキャッシュを積極的に指示することができます。結果として、次にサイトを訪れるユーザはより少ないアセットのダウンロードを要求することになり、ユーザ体験が向上します。Rails も [アセットのフィンガープリント](http://railsguides.jp/asset_pipeline.html#%E3%83%95%E3%82%A3%E3%83%B3%E3%82%AC%E3%83%BC%E3%83%97%E3%83%AA%E3%83%B3%E3%83%88%E3%81%A8%E6%B3%A8%E6%84%8F%E7%82%B9) の利点を述べています。
-
-
-はじめに、上記した `pipelineStages` と、必要なプラグインを `plugins.sbt` に `addSbtPlugin` で宣言します。続いて、バージョン管理するアセットを Play に宣言する必要があります。以下の route ファイルでは、すべてのアセットをバージョン管理するよう宣言しています:
-
-```scala
-GET /assets/*file controllers.Assets.versioned(path="/public", file: Asset)
-```
-
-
-> `file: Asset` と書くことで `file` がアセットであると示していることを確認してください。
-
-
-それから、例えば `scala.html` ビューでリバースルーターを使います:
-
-```html
-
-```
-
-
-アセットフィンガープリントの利用を強く推奨します。
-
-
-## Etag サポート
-
-
-`Assets` コントローラは、自動的に **ETag** HTTP ヘッダを管理します。ETag の値 (`sbt-digest` がアセットパイプラインで使われている場合) は、ダイジェストまたはリソース名および最終更新日付から生成されます。リソースが JAR ファイルに組み込まれている場合は、その JAR ファイルの最終更新日付が使用されます。
-
-
-Web ブラウザがこの **ETag** を指定してリクエストを行った場合、サーバは **304 NotModified** で応答することができます。
-
-
-## Gzip サポート
-
-
-名前が同じで `gz` 拡張子を持つリソースが見つかった場合、`Assets` コントローラは後者のリソース、そして以下の HTTP ヘッダを提供します:
-
-```
-Content-Encoding: gzip
-```
-
-
-gzip ファイルを生成するには、ビルドに `sbt-gzip` プラグインを取り込み、`pipelineStages` において適切に宣言している必要があります。
-
-
-## `Cache-Control` 命令の追加
-
-
-通常のキャッシュ目的であれば、ETag で十分です。特定のリソース用に独自の `Cache-Control` ヘッダを指定したい場合は、`application.conf` ファイルに指定することができます。例えば:
-
-```
-# Assets configuration
-# ~~~~~
-"assets.cache./public/stylesheets/bootstrap.min.css"="max-age=3600"
-```
-
-
-## 管理アセット
-
-
-Play 2.3 から、管理アセットは [sbt-web](https://github.com/sbt/sbt-web#sbt-web) ベースのプラグインで処理されるようになりました。2.3 より前の Play には、管理アセットの処理として CoffeeScript, LESS, JavaScript Lint (ClosureCompiler) そして RequireJS による最適化がバンドルされていました。以降の節では、sbt-web と 2.2 同等の機能を達成する方法について記述します。とは言え、徐々に sbt-web で多くのプラグインが使えるようになっていくため、Play はこのアセット処理技術に制限されていないことに注意してください。[sbt-web](https://github.com/sbt/sbt-web#sbt-web) プロジェクトを確認して、利用できるより多くのプラグインについて学んでください。
-
-
-多くのプラグインが sbt-web の [js-engine plugin](https://github.com/sbt/sbt-js-engine) を使います。js-engine は、素晴らしい [Trireme](https://github.com/apigee/trireme#trireme) プロジェクトによって JVM 上でも、またはより良いパフォーマンスのために直接 [Node.js](https://nodejs.org/) 上でも Node API で書かれたプラグインを実行することができます。これらのツールは開発サイクルにおいてのみ使用され、Play アプリケーションの実行時には関与しないことに注目してください。Node.js がインストール済みであれば、以下の環境変数を宣言することを推奨します。Unix で `SBT_OPTS` をどこかに定義している場合、以下のように指定することができます:
-
-```bash
-export SBT_OPTS="$SBT_OPTS -Dsbt.jse.engineType=Node"
-```
-
-
-上記の宣言は、あらゆる sbt-web プラグインの実行時に Node.js が使われることを保証します。
diff --git a/manual/detailedTopics/assets/AssetsCoffeeScript.md b/manual/detailedTopics/assets/AssetsCoffeeScript.md
deleted file mode 100644
index ba8f6033..00000000
--- a/manual/detailedTopics/assets/AssetsCoffeeScript.md
+++ /dev/null
@@ -1,72 +0,0 @@
-
-
-# CoffeeScript を使う
-
-
-[CoffeeScript](http://coffeescript.org/) は、小さくかつエレガントな言語で、JavaScript へコンパイルされます。CoffeeScript は、JavaScript コードを書くためのより良い構文を提供しています。
-
-
-Play では、コンパイルされるアセットは `app/assets` ディレクトリに定義しなければなりません。このアセットはビルドプロセスによって操作され、CoffeeScript ソースは通常の JavaScript ファイルにコンパイルされます。生成された JavaScript ファイルは標準的なリソースとして、他の管理されないアセットと同じように `public/` フォルダに配布されるので、一度コンパイルされればこれらのリソースの使い方に違いはありません。
-
-
-例えば、 `app/assets/javascripts/main.coffee` という CoffeeScript ソースファイルは `public/javascripts/main.js` にある通常の JavaScript リソースとして利用できるようになります。
-
-
-CoffeeScript ソースファイルは `assets` コマンドの実行時や、開発モードでの動作中にブラウザでページを更新すると自動的にコンパイルされます。あらゆるコンパイルエラーはブラウザに表示されます:
-
-[[images/coffeeError.png]]
-
-
-## ディレクトリ構造
-
-
-以下は、CoffeeScript を使うプロジェクトのレイアウト例です:
-
-```
-app
- └ assets
- └ javascripts
- └ main.coffee
-```
-
-
-以下の構文で、コンパイルされた JavaScript ファイルをテンプレートから使うことができます:
-
-```html
-
@@ -229,11 +229,11 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-coffeescript" % "1.0.0")
Coffeescript options have changed. The new options are:
-* `sourceMaps` When set, generates sourceMap files. Defaults to `true`.
+* `sourceMap` When set, generates sourceMap files. Defaults to `true`.
- `CoffeeScriptKeys.sourceMaps := true`
+ `CoffeeScriptKeys.sourceMap := true`
-* `bare` When set, generates JavaScript without the [top-level function safety wrapper](http://coffeescript.org/#lexical-scope). Defaults to `false`.
+* `bare` When set, generates JavaScript without the [top-level function safety wrapper](https://coffeescript.org/#lexical-scope). Defaults to `false`.
`CoffeeScriptKeys.bare := false`
@@ -354,7 +354,7 @@ mainModule | By default, 'main' is used as the module.
modules | The json array of modules.
optimize | The name of the optimizer, defaults to uglify2.
paths | RequireJS path mappings of module ids to a tuple of the build path and production path. By default all WebJar libraries are made available from a CDN and their mappings can be found here (unless the cdn is set to None).
-preserveLicenseComments | Whether to preserve comments or not. Defaults to false given source maps (see http://requirejs.org/docs/errors.html#sourcemapcomments).
+preserveLicenseComments | Whether to preserve comments or not. Defaults to false given source maps (see https://requirejs.org/docs/errors.html#sourcemapcomments).
webJarCdns | CDNs to be used for locating WebJars. By default "org.webjars" is mapped to "jsdelivr".
webJarModuleIds | A sequence of webjar module ids to be used.
@@ -492,7 +492,7 @@ The WS API has changed slightly, and `WS.client` now returns an instance of `WSC
There are various changes included for Anorm in this new release.
-For improved type safety, type of query parameter must be visible, so that it [can be properly converted](https://github.com/playframework/playframework/blob/master/documentation/manual/scalaGuide/main/sql/ScalaAnorm.md#edge-cases). Now using `Any` as parameter value, explicitly or due to erasure, leads to compilation error `No implicit view available from Any => anorm.ParameterValue`.
+For improved type safety, type of query parameter must be visible, so that it [[can be properly converted|ScalaAnorm#edge-cases]]. Now using `Any` as parameter value, explicitly or due to erasure, leads to compilation error `No implicit view available from Any => anorm.ParameterValue`.
```scala
// Wrong
@@ -580,7 +580,7 @@ The session timeout configuration item, `session.maxAge`, used to be an integer,
## Java JUnit superclasses
-The Java `WithApplication`, `WithServer` and `WithBrowser` JUnit test superclasses have been modified to define an `@Before` annotated method. This means, previously where you had to explicitly start a fake application by defining:
+The Java `WithApplication`, `WithServer` and `WithBrowser` JUnit test superclasses have been modified to define an `@Before` annotated method. This means, previously where you had to explicitly start an application by defining:
```java
@Before
@@ -589,11 +589,11 @@ public void setUp() {
}
```
-Now you don't need to. If you need to provide a custom fake application, you can do so by overriding the `provideFakeApplication` method:
+Now you don't need to. If you need to provide a custom application, you can do so by overriding the `provideFakeApplication` method:
```java
@Override
-protected FakeApplication provideFakeApplication() {
+protected Application provideFakeApplication() {
return Helpers.fakeApplication(Helpers.inMemoryDatabase());
}
```
diff --git a/manual/releases/release23/index.toc b/manual/releases/release23/index.toc
new file mode 100644
index 00000000..867c341b
--- /dev/null
+++ b/manual/releases/release23/index.toc
@@ -0,0 +1,2 @@
+Highlights23:What's new?
+Migration23:Migration Guide
diff --git a/manual/releases/Highlights24.md b/manual/releases/release24/Highlights24.md
similarity index 94%
rename from manual/releases/Highlights24.md
rename to manual/releases/release24/Highlights24.md
index 843a4204..fe4e6b65 100644
--- a/manual/releases/Highlights24.md
+++ b/manual/releases/release24/Highlights24.md
@@ -1,4 +1,4 @@
-
+
# What's new in Play 2.4
This page highlights the new features of Play 2.4. If you want learn about the changes you need to make to migrate to Play 2.4, check out the [[Play 2.4 Migration Guide|Migration24]].
@@ -15,7 +15,7 @@ A long term strategy for Play is to remove Play's dependence on global state. P
* More interesting deployment scenarios are possible, such as multiple Play instances in a single JVM, or embedding a lightweight Play application.
* The application lifecycle becomes easier to follow and reason about.
-Removing Play's global state is however a big task that will require some disruptive changes to the way Play applications are written. The approach we are taking to do this is to do as much as possible in Play 2.4 while maintaining backwards compatibility. For a time, many of Play's APIs will support both methods that rely on require global state and methods that don't rely on global state, allowing you to migrate your application to not depend on global state incrementally, rather than all at once when you uprgade to Play 2.4.
+Removing Play's global state is however a big task that will require some disruptive changes to the way Play applications are written. The approach we are taking to do this is to do as much as possible in Play 2.4 while maintaining backwards compatibility. For a time, many of Play's APIs will support both methods that rely on require global state and methods that don't rely on global state, allowing you to migrate your application to not depend on global state incrementally, rather than all at once when you upgrade to Play 2.4.
The first step to removing global state is to make it such that Play components have their dependencies provided to them, rather than looking them up statically. This means providing out of the box support for dependency injection.
@@ -48,9 +48,9 @@ You can read about these new APIs here:
It is now straightforward to embed a Play application. Play 2.4 provides both APIs to start and stop a Play server, as well as routing DSLs for Java and Scala so that routes can be embedded directly in code.
-In Java, see [[Embedding Play|JavaEmbeddingPlay]] as well as information about the [[Routing DSL|JavaRoutingDsl]].
+In Java, see [[Embedding Play|ScalaEmbeddingPlayAkkaHttp]] as well as information about the [[Routing DSL|JavaRoutingDSL]].
-In Scala, see [[Embedding Play|ScalaEmbeddingPlay]] as well as information about the [[String Interpolating Routing DSL|ScalaSirdRouter]].
+In Scala, see [[Embedding Play|ScalaEmbeddingPlayAkkaHttp]] as well as information about the [[String Interpolating Routing DSL|ScalaSirdRouter]].
## Aggregated reverse routers
@@ -87,7 +87,7 @@ return promise(() -> longComputation())
## Maven/sbt standard layout
-Play will now let you use either its default layout or the directory layout that is the default for Maven and SBT projects. See the [[Anatomy of a Play application|Anatomy]] page for more details.
+Play will now let you use either its default layout or the directory layout that is the default for Maven and sbt projects. See the [[Anatomy of a Play application|Anatomy]] page for more details.
## Anorm
diff --git a/manual/experimental/ReactiveStreamsIntegration.md b/manual/releases/release24/ReactiveStreamsIntegration.md
similarity index 83%
rename from manual/experimental/ReactiveStreamsIntegration.md
rename to manual/releases/release24/ReactiveStreamsIntegration.md
index f7f03e73..a9dbc059 100644
--- a/manual/experimental/ReactiveStreamsIntegration.md
+++ b/manual/releases/release24/ReactiveStreamsIntegration.md
@@ -1,9 +1,9 @@
-
+
# Reactive Streams integration (experimental)
> **Play experimental libraries are not ready for production use**. APIs may change. Features may not work properly.
-[Reactive Streams](http://www.reactive-streams.org/) is a new standard that gives a common API for asynchronous streams. Play 2.4 introduces some wrappers to convert Play's [[Iteratees and Enumerators|Iteratees]] into Reactive Streams objects. This means that Play can integrate with other software that supports Reactive Streams, e.g. [Akka Streams](http://doc.akka.io/docs/akka-stream-and-http-experimental/current/), [RxJava](https://github.com/ReactiveX/RxJavaReactiveStreams) and [others](http://www.reactive-streams.org/announce-1.0.0#implementations).
+[Reactive Streams](http://www.reactive-streams.org/) is a new standard that gives a common API for asynchronous streams. Play 2.4 introduces some wrappers to convert Play's [[Iteratees and Enumerators|Iteratees]] into Reactive Streams objects. This means that Play can integrate with other software that supports Reactive Streams, e.g. [Akka Streams](https://doc.akka.io/docs/akka/2.4.3/scala/stream/index.html), [RxJava](https://github.com/ReactiveX/RxJavaReactiveStreams) and [others](http://www.reactive-streams.org/announce-1.0.0#implementations).
The purpose of the API is:
@@ -31,7 +31,7 @@ Include the Reactive Streams integration library into your project.
libraryDependencies += "com.typesafe.play" %% "play-streams-experimental" % "%PLAY_VERSION%"
```
-All access to the module is through the [`Streams`](api/scala/play/api/libs/streams/Streams$.html) object.
+All access to the module is through the `Streams` object.
Here is an example that adapts a `Future` into a single-element `Publisher`.
@@ -40,12 +40,10 @@ val fut: Future[Int] = Future { ... }
val pubr: Publisher[Int] = Streams.futureToPublisher(fut)
```
-See the `Streams` object's [API documentation](api/scala/play/api/libs/streams/Streams$.html) for more information.
+See the `Streams` object's API documentation for more information.
For more examples you can look at the code used by the experimental [[Akka HTTP server backend|AkkaHttpServer]]. Here are the main files where you can find examples:
-
-
* [ModelConversion](https://github.com/playframework/playframework/blob/2.4.x/framework/src/play-akka-http-server/src/main/scala/play/core/server/akkahttp/ModelConversion.scala)
* [AkkaStreamsConversion](https://github.com/playframework/playframework/blob/2.4.x/framework/src/play-akka-http-server/src/main/scala/play/core/server/akkahttp/AkkaStreamsConversion.scala)
* [AkkaHttpServer](https://github.com/playframework/playframework/blob/2.4.x/framework/src/play-akka-http-server/src/main/scala/play/core/server/akkahttp/AkkaHttpServer.scala)
diff --git a/manual/releases/release24/index.toc b/manual/releases/release24/index.toc
new file mode 100644
index 00000000..c24236b1
--- /dev/null
+++ b/manual/releases/release24/index.toc
@@ -0,0 +1,3 @@
+Highlights24:What's new?
+!migration24:Migration Guides
+ReactiveStreamsIntegration:Reactive Streams integration (experimental)
\ No newline at end of file
diff --git a/manual/releases/migration24/Anorm.md b/manual/releases/release24/migration24/Anorm.md
similarity index 98%
rename from manual/releases/migration24/Anorm.md
rename to manual/releases/release24/migration24/Anorm.md
index 846f6d9a..a876b29c 100644
--- a/manual/releases/migration24/Anorm.md
+++ b/manual/releases/release24/migration24/Anorm.md
@@ -1,4 +1,4 @@
-
+
# Anorm
Anorm has been pulled out of the core of Play into a separately managed project that can have its own lifecycle. To add a dependency on it, use:
@@ -192,4 +192,4 @@ Binary and large data can also be used as parameters:
- **Joda Time**: New conversions for Joda `Instant` or `DateTime`, from `Long`, `Date` or `Timestamp` column.
- Parses text column as `UUID` value: `SQL("SELECT uuid_as_text").as(scalar[UUID].single)`.
-- Passing `None` for a nullable parameter is deprecated, and typesafe `Option.empty[T]` must be use instead.
\ No newline at end of file
+- Passing `None` for a nullable parameter is deprecated, and typesafe `Option.empty[T]` must be use instead.
diff --git a/manual/releases/migration24/GlobalSettings.md b/manual/releases/release24/migration24/GlobalSettings.md
similarity index 94%
rename from manual/releases/migration24/GlobalSettings.md
rename to manual/releases/release24/migration24/GlobalSettings.md
index ef96552f..8fae2e8a 100644
--- a/manual/releases/migration24/GlobalSettings.md
+++ b/manual/releases/release24/migration24/GlobalSettings.md
@@ -1,4 +1,4 @@
-
+
# Removing `GlobalSettings`
If you are keen to use dependency injection, we are recommending that you move out of your `GlobalSettings` implementation class as much code as possible. Ideally, you should be able to refactor your code so that it is possible to eliminate your `GlobalSettings` class altogether.
@@ -9,7 +9,7 @@ Next follows a method-by-method guide for refactoring your code. Because the API
## Scala
-* `GlobalSettings.beforeStart` and `GlobalSettings.onStart`: Anything that needs to happen on start up should now be happening in the constructor of a dependency injected class. A class will perform its initialisation when the dependency injection framework loads it. If you need eager initialisation (because you need to execute some code *before* the application is actually started), [[define an eager binding|ScalaDependencyInjection#Eager-bindings]].
+* `GlobalSettings.beforeStart` and `GlobalSettings.onStart`: Anything that needs to happen on start up should now be happening in the constructor of a dependency injected class. A class will perform its initialization when the dependency injection framework loads it. If you need eager initialization (because you need to execute some code *before* the application is actually started), [[define an eager binding|ScalaDependencyInjection#Eager-bindings]].
* `GlobalSettings.onStop`: Add a dependency to [`ApplicationLifecycle`](api/scala/play/api/inject/ApplicationLifecycle.html) on the class that needs to register a stop hook. Then, move the implementation of your `GlobalSettings.onStop` method inside the `Future` passed to the `ApplicationLifecycle.addStopHook`. Read [[Stopping/cleaning-up|ScalaDependencyInjection#Stopping/cleaning-up]] for more information.
@@ -49,13 +49,13 @@ Also, mind that if your `Global` class is mixing the `WithFilters` trait, you sh
## Java
-* `GlobalSettings.beforeStart` and `GlobalSettings.onStart`: Anything that needs to happen on start up should now be happening in the constructor of a dependency injected class. A class will perform its initialisation when the dependency injection framework loads it. If you need eager initialisation (for example, because you need to execute some code *before* the application is actually started), [[define an eager binding|JavaDependencyInjection#Eager-bindings]].
+* `GlobalSettings.beforeStart` and `GlobalSettings.onStart`: Anything that needs to happen on start up should now be happening in the constructor of a dependency injected class. A class will perform its initialization when the dependency injection framework loads it. If you need eager initialization (for example, because you need to execute some code *before* the application is actually started), [[define an eager binding|JavaDependencyInjection#Eager-bindings]].
* `GlobalSettings.onStop`: Add a dependency to [`ApplicationLifecycle`](api/java/play/inject/ApplicationLifecycle.html) on the class that needs to register a stop hook. Then, move the implementation of your `GlobalSettings.onStop` method inside the `Promise` passed to the `ApplicationLifecycle.addStopHook`. Read [[Stopping/cleaning-up|JavaDependencyInjection#Stopping/cleaning-up]] for more information.
* `GlobalSettings.onError`: Create a class that inherits from [`HttpErrorHandler`](api/java/play/http/HttpErrorHandler.html), and move the implementation of your `GlobalSettings.onError` inside the `HttpErrorHandler.onServerError` method. Read [[Error Handling|JavaErrorHandling]] for more information.
-* `GlobalSettings.onRequest`: Create a class that inherits from [`DefaultHttpRequestHandler`](api/java/play/http/DefaultHttpRequestHandler.html), and move the implementation of your `GlobalSettings.onRequest` method inside the `DefaultHttpRequestHandler.createAction` method. Read [[Request Handlers|JavaHttpRequestHandlers]] for more information.
+* `GlobalSettings.onRequest`: Create a class that inherits from [`DefaultHttpRequestHandler`](api/java/play/http/DefaultHttpRequestHandler.html), and move the implementation of your `GlobalSettings.onRequest` method inside the `DefaultHttpRequestHandler.createAction` method. Read [[Request Handlers|JavaActionCreator]] for more information.
* `GlobalSettings.onRouteRequest`: There is no simple migration for this method when using the Java API. If you need this, you will have to keep your Global class around for a little longer.
@@ -79,4 +79,4 @@ if(statusCode == play.mvc.Http.Status.BAD_REQUEST) {
* `GlobalSettings.onLoadConfig`: Specify all configuration in your config file or create your own ApplicationLoader (see [[GuiceApplicationBuilder.loadConfig|JavaDependencyInjection#Advanced:-Extending-the-GuiceApplicationLoader]]).
-* `GlobalSettings.filters`: Create a class that inherits from [`HttpFilters`](api/java/play/http/HttpFilters.html), and provide an implementation for `HttpFilter.filters`. Read [[Http Filters|JavaHttpFilters]] for more information.
\ No newline at end of file
+* `GlobalSettings.filters`: Create a class that inherits from [`HttpFilters`](api/java/play/http/HttpFilters.html), and provide an implementation for `HttpFilter.filters`. Read [[Http Filters|JavaHttpFilters]] for more information.
diff --git a/manual/releases/migration24/Migration24.md b/manual/releases/release24/migration24/Migration24.md
similarity index 82%
rename from manual/releases/migration24/Migration24.md
rename to manual/releases/release24/migration24/Migration24.md
index e9f4e2fe..cae28fe0 100644
--- a/manual/releases/migration24/Migration24.md
+++ b/manual/releases/release24/migration24/Migration24.md
@@ -1,8 +1,14 @@
-
+
# Play 2.4 Migration Guide
This is a guide for migrating from Play 2.3 to Play 2.4. If you need to migrate from an earlier version of Play then you must first follow the [[Play 2.3 Migration Guide|Migration23]].
+As well as the information contained on this page, there are is more detailed migration information for some topics:
+
+- [[Migrating GlobalSettings|GlobalSettings]]
+- [[Migrating Plugins to Modules|PluginsToModules]]
+- [[Migrating Anorm|Anorm]]
+
## Java 8 support
The support for Java 6 and Java 7 was dropped and Play 2.4 now requires Java 8. This decision was made based on the fact that [Java 7 reached its End-of-Life in April 2015](https://www.java.com/en/download/faq/java_7.xml). Also, Java 8 enables clean APIs and has better support for functional programming style. If you try to use Play 2.4 with Java 6/7, you will get an error like below:
@@ -13,7 +19,7 @@ java.lang.UnsupportedClassVersionError: play/runsupport/classloader/ApplicationC
A [java.lang.UnsupportedClassVersionError](https://docs.oracle.com/javase/8/docs/api/java/lang/UnsupportedClassVersionError.html) means that reading a Java class file with an older version of Java than the class file was compiled with is unsupported.
-> **Note:** Scala 2.10 does not have full support to all Java 8 language features, like static methods on interfaces. If your project has Java code using these new features present in Java 8, upgrade to use Scala 2.11.6+. See [sbt docs](http://www.scala-sbt.org/0.13/docs/Howto-Scala.html) to learn how to set `scalaVersion` to your project.
+> **Note:** Scala 2.10 does not have full support to all Java 8 language features, like static methods on interfaces. If your project has Java code using these new features present in Java 8, upgrade to use Scala 2.11.6+. See [sbt docs](https://www.scala-sbt.org/0.13/docs/Howto-Scala.html) to learn how to set `scalaVersion` to your project.
## Build changes
@@ -24,7 +30,7 @@ The following steps need to be taken to update your sbt build before you can loa
Update the Play version number in `project/plugins.sbt` to upgrade Play:
```scala
-addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "%PLAY_VERSION%")
+addSbtPlugin("com.typesafe.play" % "sbt-plugin" % "2.4.0") // Set to latest version of Play 2.4
```
### sbt upgrade
@@ -37,12 +43,9 @@ sbt.version=0.13.8
### Specs2 support in a separate module
-If you were previously using Play's specs2 support, you now need to explicitly add a dependency on that to your project. Additionally, specs2 now requires `scalaz-stream` which isn't available on maven central or any other repositories that sbt uses by default, so you need to add the `scalaz-stream` repository as a resolver:
-
+If you were previously using Play's specs2 support, you now need to explicitly add a dependency on that to your project:
```scala
libraryDependencies += specs2 % Test
-
-resolvers += "scalaz-bintray" at "https://dl.bintray.com/scalaz/releases"
```
If you are using a .scala build file, you will need to add the following import `import play.sbt.PlayImport._`
@@ -68,13 +71,13 @@ Eclipse support can be setup with as little as one extra line to import the plug
IntelliJ is now able to import sbt projects natively, so we recommend using that instead. Alternatively, the sbt-idea plugin can be manually installed and used, instructions can be found [here](https://github.com/mpeltonen/sbt-idea).
-### Play SBT plugin API
+### Play sbt plugin API
-All classes in the SBT plugin are now in the package `play.sbt`, this is particularly pertinent if using `.scala` files to configure your build. You will need to import identifiers from `play.sbt.PlayImport` to use play provided configuration elements.
+All classes in the sbt plugin are now in the package `play.sbt`, this is particularly pertinent if using `.scala` files to configure your build. You will need to import identifiers from `play.sbt.PlayImport` to use play provided configuration elements.
#### `playWatchService` renamed
-The SBT setting key `playWatchService` has been renamed to `fileWatchService`.
+The sbt setting key `playWatchService` has been renamed to `fileWatchService`.
Also the corresponding class has changed. To set the FileWatchService to poll every two seconds, use it like this:
```scala
@@ -169,7 +172,7 @@ If you wish to switch to the injected generator, add the following to your build
routesGenerator := InjectedRoutesGenerator
```
-By default Play will automatically handle the wiring of this router for you using Guice, but depending in the DI approach you're taking, you may be able to customise it.
+By default Play will automatically handle the wiring of this router for you using Guice, but depending in the DI approach you're taking, you may be able to customize it.
The injected routes generator also supports the `@` operator on routes, but it has a slightly different meaning (since everything is injected), if you prefix a controller with `@`, instead of that controller being directly injected, a JSR 330 `Provider` for that controller will be injected. This can be used, for example, to eliminate circular dependency issues, or if you want a new action instantiated per request.
@@ -185,13 +188,13 @@ While Play 2.4 won't force you to use the dependency injected versions of compon
| ------- | --------| -------- |
| [`Lang`](api/scala/play/api/i18n/Lang$.html) | [`Langs`](api/scala/play/api/i18n/Langs.html) | |
| [`Messages`](api/scala/play/api/i18n/Messages$.html) | [`MessagesApi`](api/scala/play/api/i18n/MessagesApi.html) | Using one of the `preferred` methods, you can get a [`Messages`](api/scala/play/api/i18n/Messages.html) instance. |
-| [`DB`](api/scala/play/api/db/DB$.html) | [`DBApi`](api/scala/play/api/db/DBApi.html) or better, [`Database`](api/scala/play/api/db/Database.html) | You can get a particular database using the `@NamedDatabase` annotation. |
-| [`Cache`](api/scala/play/api/cache/Cache$.html) | [`CacheApi`](api/scala/play/api/cache/CacheApi.html) or better | You can get a particular cache using the `@NamedCache` annotation. |
-| [`Cached` object](api/scala/play/api/cache/Cached$.html) | [`Cached` instance](api/scala/play/api/cache/Cached.html) | Use an injected instance instead of the companion object. You can use the `@NamedCache` annotation. |
+| `DB` | [`DBApi`](api/scala/play/api/db/DBApi.html) or better, [`Database`](api/scala/play/api/db/Database.html) | You can get a particular database using the `@NamedDatabase` annotation. |
+| `Cache` | [`CacheApi`](api/scala/play/api/cache/CacheApi.html) or better | You can get a particular cache using the `@NamedCache` annotation. |
+| `Cached` object | [`Cached` instance](api/scala/play/api/cache/Cached.html) | Use an injected instance instead of the companion object. You can use the `@NamedCache` annotation. |
| [`Akka`](api/scala/play/api/libs/concurrent/Akka$.html) | N/A | No longer needed, just declare a dependency on `ActorSystem` |
-| [`WS`](api/scala/play/api/libs/ws/WS$.html) | [`WSClient`](api/scala/play/api/libs/ws/WSClient.html) | |
-| [`Crypto`](api/scala/play/api/libs/Crypto$.html) | [`Crypto`](api/scala/play/api/libs/Crypto.html) | |
-| [`GlobalSettings`](api/scala/play/api/GlobalSettings.html) | [`HttpErrorHandler`](api/scala/play/api/http/HttpErrorHandler.html), [`HttpRequestHandler`](api/scala/play/api/http/HttpRequestHandler.html), and [`HttpFilters`](api/scala/play/api/http/HttpFilters.html)| Read the details in the [[GlobalSettings|Migration24#GlobalSettings]] section below. |
+| `WS` | [`WSClient`](api/scala/play/api/libs/ws/WSClient.html) | |
+| `Crypto` | `Crypto` | |
+| `GlobalSettings` | [`HttpErrorHandler`](api/scala/play/api/http/HttpErrorHandler.html), [`HttpRequestHandler`](api/scala/play/api/http/HttpRequestHandler.html), and [`HttpFilters`](api/scala/play/api/http/HttpFilters.html)| Read the details in the [[GlobalSettings|Migration24#GlobalSettings]] section below. |
#### Java
@@ -199,21 +202,21 @@ While Play 2.4 won't force you to use the dependency injected versions of compon
| ------- | --------| -------- |
| [`Lang`](api/java/play/i18n/Lang.html) | [`Langs`](api/java/play/i18n/Langs.html) | Instances of `Lang` objects are still fine to use |
| [`Messages`](api/java/play/i18n/Messages.html) | [`MessagesApi`](api/java/play/i18n/MessagesApi.html) | Using one of the `preferred` methods, you can get a `Messages` instance, and you can then use `at` to get messages for that lang. |
-| [`DB`](api/java/play/db/DB.html) | [`DBApi`](api/java/play/db/DBApi.html) or better, [`Database`](api/java/play/db/Database.html) | You can get a particular database using the [`@NamedDatabase`](api/java/play/db/NamedDatabase.html) annotation. |
+| `DB` | [`DBApi`](api/java/play/db/DBApi.html) or better, [`Database`](api/java/play/db/Database.html) | You can get a particular database using the [`@NamedDatabase`](api/java/play/db/NamedDatabase.html) annotation. |
| [`JPA`](api/java/play/db/jpa/JPA.html) | [`JPAApi`](api/java/play/db/jpa/JPAApi.html) | |
-| [`Cache`](api/java/play/cache/Cache.html) | [`CacheApi`](api/java/play/cache/CacheApi.html) | You can get a particular cache using the [`@NamedCache`](api/java/play/cache/NamedCache.html) annotation. |
+| `Cache` | [`CacheApi`](api/java/play/cache/CacheApi.html) | You can get a particular cache using the [`@NamedCache`](api/java/play/cache/NamedCache.html) annotation. |
| [`Akka`](api/java/play/libs/Akka.html) | N/A | No longer needed, just declare a dependency on `ActorSystem` |
| [`WS`](api/java/play/libs/ws/WS.html) | [`WSClient`](api/java/play/libs/ws/WSClient.html) | |
-| [`Crypto`](api/java/play/libs/Crypto.html) | [`Crypto`](api/java/play/libs/Crypto.html) | The old static methods have been removed, an instance can statically be accessed using `play.Play.application().injector().instanceOf(Crypto.class)` |
-| [`GlobalSettings`](api/java/play/GlobalSettings.html) | [`HttpErrorHandler`](api/java/play/http/HttpErrorHandler.html), [`HttpRequestHandler`](api/java/play/http/HttpRequestHandler.html), and [`HttpFilters`](api/java/play/http/HttpFilters.html)| Read the details in the [[GlobalSettings|Migration24#GlobalSettings]] section below. |
+| `Crypto` | `Crypto` | The old static methods have been removed, an instance can statically be accessed using `play.Play.application().injector().instanceOf(Crypto.class)` |
+| `GlobalSettings` | [`HttpErrorHandler`](api/java/play/http/HttpErrorHandler.html), [`HttpRequestHandler`](api/java/play/http/HttpRequestHandler.html), and [`HttpFilters`](api/java/play/http/HttpFilters.html)| Read the details in the [[GlobalSettings|Migration24#GlobalSettings]] section below. |
### GlobalSettings
-If you are keen to use dependency injection, we are recommending that you move out of your `GlobalSettings` implementation class as much code as possible. Read the [[`GlobalSettings` migration documentation|GlobalSettings]] for the glory details.
+If you are keen to use dependency injection, we are recommending that you move out of your `GlobalSettings` implementation class as much code as possible. Read the [[`GlobalSettings` migration documentation|GlobalSettings]] for the gory details.
## `Plugin` deprecated
-Both Java [`play.Plugin`](api/java/play/Plugin.html) and Scala [`play.api.Plugin`](api/scala/play/api/Plugin.html) types have been deprecated. Read [[migrating Plugin to Module|PluginsToModules]] to update your code to use [`play.api.inject.Module`](api/scala/play/api/inject/Module.html).
+Both Java `play.Plugin` and Scala `play.api.Plugin` types have been deprecated. Read [[migrating Plugin to Module|PluginsToModules]] to update your code to use [`play.api.inject.Module`](api/scala/play/api/inject/Module.html).
## Configuration changes
@@ -264,7 +267,7 @@ akka {
}
```
-In particular, you might want to try the [default Akka settings](http://doc.akka.io/docs/akka/2.3.11/general/configuration.html#listing-of-the-reference-configuration):
+In particular, you might want to try the [default Akka settings](https://doc.akka.io/docs/akka/2.3.11/general/configuration.html#listing-of-the-reference-configuration):
```
akka {
@@ -292,7 +295,7 @@ play.http.requestHandler = "play.http.DefaultHttpRequestHandler"
### Logging
-Logging is now configured solely via [logback configuration files](http://logback.qos.ch/manual/configuration.html).
+Logging is now configured solely via [logback configuration files](https://logback.qos.ch/manual/configuration.html).
## JDBC connection pool
@@ -342,7 +345,7 @@ Additionally, Java actions may now declare a `BodyParser.Of.maxLength` value tha
## JSON API changes
-The semantics of JSON lookups have changed slightly. `JsUndefined` has been removed from the `JsValue` type hierarchy and all lookups of the form `jsv \ foo` or `jsv(bar)` have been moved to [`JsLookup`](api/scala/play/api/libs/json/JsLookup.html). They now return a [`JsLookupResult`](api/scala/play/api/libs/json/JsLookupResult.html) instead of a `JsValue`.
+The semantics of JSON lookups have changed slightly. `JsUndefined` has been removed from the `JsValue` type hierarchy and all lookups of the form `jsv \ foo` or `jsv(bar)` have been moved to `JsLookup`. They now return a `JsLookupResult` instead of a `JsValue`.
If you have code of the form
@@ -356,7 +359,7 @@ the following code is equivalent, if you know the property exists:
val v: JsValue = (json \ "foo" \ "bar").get
```
-If you don't know the property exists, we recommend using pattern matching or the methods on [`JsLookupResult`](api/scala/play/api/libs/json/JsLookupResult.html) to safely handle the `JsUndefined` case, e.g.
+If you don't know the property exists, we recommend using pattern matching or the methods on `JsLookupResult` to safely handle the `JsUndefined` case, e.g.
```scala
val vOpt: Option[JsValue] = (json \ "foo" \ "bar").toOption
@@ -364,7 +367,7 @@ val vOpt: Option[JsValue] = (json \ "foo" \ "bar").toOption
### JsLookup
-All JSON traversal methods have been moved to the [`JsLookup`](api/scala/play/api/libs/json/JsLookup.html) class, which is implicitly applied to all values of type `JsValue` or `JsLookupResult`. In addition to the `apply`, `\`, and `\\` methods, the `head`, `tail`, and `last` methods have been added for JSON arrays. All methods except `\\` return a [`JsLookupResult`](api/scala/play/api/libs/json/JsLookupResult.html), a wrapper for `JsValue` that helps with handling undefined values.
+All JSON traversal methods have been moved to the `JsLookup` class, which is implicitly applied to all values of type `JsValue` or `JsLookupResult`. In addition to the `apply`, `\`, and `\\` methods, the `head`, `tail`, and `last` methods have been added for JSON arrays. All methods except `\\` return a `JsLookupResult`, a wrapper for `JsValue` that helps with handling undefined values.
The methods `as[A]`, `asOpt[A]`, `validate[A]` also exist on `JsLookup`, so code like the below should require no source changes:
@@ -405,23 +408,23 @@ implicit val optionStringReads: Reads[Option[String]] = Reads.optionWithNull[Str
## Testing changes
-[`FakeRequest`](api/java/play/test/FakeRequest.html) has been replaced by [`RequestBuilder`](api/java/play/mvc/Http.RequestBuilder.html).
+`FakeRequest` has been replaced by [`RequestBuilder`](api/java/play/mvc/Http.RequestBuilder.html).
The reverse ref router used in Java tests has been removed. Any call to `Helpers.call` that was passed a ref router can be replaced by a call to `Helpers.route` which takes either a standard reverse router reference or a `RequestBuilder`.
## Java TimeoutExceptions
-If you use the Java API, the [`F.Promise`](api/java/play/libs/F.Promise.html) class now throws unchecked [`F.PromiseTimeoutException`s](api/java/play/libs/F.PromiseTimeoutException.html) instead of Java's checked [`TimeoutException`s](http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeoutException.html). The `TimeoutExceptions`s which were previously used were not properly declared with the `throws` keyword. Rather than changing the API to use the `throws` keyword, which would mean users would have to declare `throws` on their methods, the exception was changed to a new unchecked type instead. See [#1227](https://github.com/playframework/playframework/pull/1227) for more information.
+If you use the Java API, the `F.Promise` class now throws unchecked [`F.PromiseTimeoutException`s](api/java/play/libs/F.PromiseTimeoutException.html) instead of Java's checked [`TimeoutException`s](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeoutException.html). The `TimeoutExceptions`s which were previously used were not properly declared with the `throws` keyword. Rather than changing the API to use the `throws` keyword, which would mean users would have to declare `throws` on their methods, the exception was changed to a new unchecked type instead. See [#1227](https://github.com/playframework/playframework/pull/1227) for more information.
| Old API | New API | Comments |
| ------- | --------| -------- |
-| [`TimeoutException`](http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeoutException.html) | [`F.PromiseTimeoutException`](api/java/play/libs/F.PromiseTimeoutException.html) | |
+| [`TimeoutException`](https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/TimeoutException.html) | [`F.PromiseTimeoutException`](api/java/play/libs/F.PromiseTimeoutException.html) | |
## WS client
`WSRequestHolder` has been renamed to `WSRequest` in [Scala](api/scala/play/api/libs/ws/WSRequest.html) and [Java](api/java/play/libs/ws/WSRequest.html). The previous `WSRequest` class has been removed out as it was only used internally to WS for OAuth functionality.
-WS has upgraded from AsyncHttpClient 1.8.x to 1.9.x, which includes a number of breaking changes if using or configuring that library directly. Please see the [AsyncHttpClient Migration Guide](https://github.com/AsyncHttpClient/async-http-client/blob/master/MIGRATION.md) for more details. The upgrade to AsyncHttpClient 1.9.x enables Server Name Indication (SNI) in HTTPS -- this solves a number of problems with HTTPS based CDNs such as Cloudflare which depend heavily on SNI.
+WS has upgraded from AsyncHttpClient 1.8.x to 1.9.x, which includes a number of breaking changes if using or configuring that library directly. Please see the [AsyncHttpClient Migration Guide](https://github.com/AsyncHttpClient/async-http-client/blob/2.0/MIGRATION.md) for more details. The upgrade to AsyncHttpClient 1.9.x enables Server Name Indication (SNI) in HTTPS -- this solves a number of problems with HTTPS based CDNs such as Cloudflare which depend heavily on SNI.
Configuration settings for WS have changed:
@@ -450,9 +453,9 @@ Due to the recent spate of TLS vulnerabilities, there has been more activity to
## Crypto APIs
-Play 2.4's AES encryption now uses [initialization vectors](http://en.wikipedia.org/wiki/Initialization_vector) to randomize each encryption. The Play encryption format has been changed to add support for initialization vectors.
+Play 2.4's AES encryption now uses [initialization vectors](https://en.wikipedia.org/wiki/Initialization_vector) to randomize each encryption. The Play encryption format has been changed to add support for initialization vectors.
-The full name of the new AES transformation used by Play 2.4 is `AES/CTR/NoPadding`. The old transformation was `AES/ECB/PKCS5Padding`. The [`CTR`](http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29) mode is much more secure than the `ECB` mode. As before, you can override Play's encryption transformation by setting the `play.crypto.aes.transformation` configuration option. In Play 2.4, any [transformation supported by your JRE](http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Cipher) can be used, including transformations that use an initialization vector.
+The full name of the new AES transformation used by Play 2.4 is `AES/CTR/NoPadding`. The old transformation was `AES/ECB/PKCS5Padding`. The [`CTR`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29) mode is much more secure than the `ECB` mode. As before, you can override Play's encryption transformation by setting the `play.crypto.aes.transformation` configuration option. In Play 2.4, any [transformation supported by your JRE](https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#Cipher) can be used, including transformations that use an initialization vector.
Play 2.4 uses a new encryption format, but it can read data encrypted by earlier versions of Play. However, earlier versions of Play **will not** be able to read data encrypted by Play 2.4. If your Play 2.4 application needs to produce data in the old format then you may want to copy the algorithm from the [Play 2.3 Crypto code](https://github.com/playframework/playframework/blob/2.3.6/framework/src/play/src/main/scala/play/api/libs/Crypto.scala#L187-L277).
@@ -464,7 +467,7 @@ Old format | _hex(cipher(plaintext))_ | writes | reads | | reads
New format I | "1-" + _base64(cipher(plaintext))_ | | | writes | reads
New format II | "2-" + _base64(iv + cipher(plaintext, iv))_ | | | writes | reads
-Usage of the [Java Crypto API](api/java/play/libs/Crypto.html) remains the same even though the output is different:
+Usage of the Java Crypto API remains the same even though the output is different:
```java
import play.libs.Crypto;
@@ -473,7 +476,7 @@ String enc = Crypto.encryptAES(orig);
String dec = Crypto.decryptAES(enc);
```
-Usage of the [Scala Crypto API](api/scala/play/api/libs/Crypto.html) is also the same:
+Usage of the Scala Crypto API is also the same:
```scala
import play.api.libs.Crypto
@@ -535,7 +538,7 @@ The API should be backward compatible with your code using Play 2.3 so there is
## Distribution
-Previously, Play added all the resources to the the `conf` directory in the distribution, but didn't add the `conf` directory to the classpath. Now Play adds the `conf` directory to the classpath by default.
+Previously, Play added all the resources to the `conf` directory in the distribution, but didn't add the `conf` directory to the classpath. Now Play adds the `conf` directory to the classpath by default.
This can be turned off by setting `PlayKeys.externalizeResources := false`, which will cause no `conf` directory to be created in the distribution, and it will not be on the classpath. The contents of the applications `conf` directory will still be on the classpath by virtue of the fact that it's included in the applications jar file.
@@ -563,7 +566,7 @@ serverLoading in Debian := SystemV
The mysterious `OrderedExecutionContext` had [[been retained|Migration22#Concurrent-F.Promise-execution]] in Play for several versions in order to support legacy applications. It was rarely used and has now been removed. If you still need the `OrderedExecutionContext` for some reason, you can create your own implementation based on the [Play 2.3 source](https://github.com/playframework/playframework/blob/2.3.x/framework/src/play/src/main/scala/play/core/j/OrderedExecutionContext.scala). If you haven't heard of this class, then there's nothing you need to do.
-### SubProject Assets
+### Subproject Assets
Any assets in sub projects are now by default placed into /lib/[subproject] to allow files with the same name in the root project / different subprojects without causing them to interfere with each other.
diff --git a/manual/releases/migration24/PluginsToModules.md b/manual/releases/release24/migration24/PluginsToModules.md
similarity index 77%
rename from manual/releases/migration24/PluginsToModules.md
rename to manual/releases/release24/migration24/PluginsToModules.md
index 2b79e7b9..dd03c28d 100644
--- a/manual/releases/migration24/PluginsToModules.md
+++ b/manual/releases/release24/migration24/PluginsToModules.md
@@ -1,7 +1,9 @@
-
+
# Migrating Plugin to Module
-If you have implemented a Play plugin, please consider migrating your implementation to use [`play.api.inject.Module`](api/scala/play/api/inject/Module.html), instead of the deprecated Java [`play.Plugin`](api/java/play/Plugin.html) or Scala [`play.api.Plugin`](api/scala/play/api/Plugin.html) types.
+> **Note:** The deprecated `play.Plugin` system is removed as of 2.5.x.
+
+If you have implemented a Play plugin, please consider migrating your implementation to use [`play.api.inject.Module`](api/scala/play/api/inject/Module.html), instead of the deprecated Java `play.Plugin` or Scala `play.api.Plugin` types.
The main difference between the old `Plugin` API, and the new one using `Module`, is that with the latter we are going to fully embrace Dependency Injection (DI) - you can read [[here|Highlights24#Dependency-Injection]] to understand why Play became opinionated about DI.
@@ -13,26 +15,25 @@ With the old `Plugin` API, you were required to provide a `play.plugins` file co
Start by creating a class that inherits from `play.api.inject.Module`, and provide an implementation for the `bindings` method. In this method you should wire types to concrete implementation so that components provided by your module can be injected in users' code, or in other modules. Next follows an example.
-In Java
+In Java:
@[module-decl](code24/MyModule.java)
-In Scala
+In Scala:
@[module-decl](code24/MyModule.scala)
-
Note that if a component you are defining requires another component, you should simply add the required component as a constructor's dependency, prepending the constructor with the `@javax.inject.Inject` annotation. The DI framework will then take care of the rest.
-> Note that if a component B requires A, then B will be initialized only after A is initialized.
+> **Note:** if a component B requires A, then B will be initialized only after A is initialized.
Next follows an example of a component named `MyComponentImpl` requiring the `ApplicationLifecycle` component.
-In Java
+In Java:
@[components-decl](code24/MyComponent.java)
-In Scala
+In Scala:
@[components-decl](code24/MyComponent.scala)
@@ -45,8 +46,9 @@ play.modules.enabled += "my.module.MyModule"
```
If you are working on a library that will be used by other projects (including sub projects), add the above line in your `reference.conf` file (if you don't have a `reference.conf` yet, create one and place it under `src/main/resources`). Otherwise, if it's in an end Play project, it should be in `application.conf`.
+If it's and end Play project, you could also create a class called `Module` and put it in the root package (the "app" directory).
-> Note: If you are working on a library, it is highly discouraged to use `play.modules.disabled` to disable modules, as it can lead to undetermistic results when modules are loaded by the application (see [this issue](https://github.com/playframework/play-slick/issues/245) for reasons on why you should not touch `play.modules.disabled`). In fact, `play.modules.disabled` is intended for end users to be able to override what modules are enabled by default.
+> **Note:** If you are working on a library, it is highly discouraged to use `play.modules.disabled` to disable modules, as it can lead to nondeterministic results when modules are loaded by the application (see [this issue](https://github.com/playframework/play-slick/issues/245) for reasons on why you should not touch `play.modules.disabled`). In fact, `play.modules.disabled` is intended for end users to be able to override what modules are enabled by default.
### Compile-time DI
diff --git a/manual/releases/migration24/code24/MyComponent.java b/manual/releases/release24/migration24/code24/MyComponent.java
similarity index 83%
rename from manual/releases/migration24/code24/MyComponent.java
rename to manual/releases/release24/migration24/code24/MyComponent.java
index 0d984014..52fb21fd 100644
--- a/manual/releases/migration24/code24/MyComponent.java
+++ b/manual/releases/release24/migration24/code24/MyComponent.java
@@ -1,5 +1,5 @@
/*
- * Copyright (C) 2009-2015 Typesafe Inc. (not supported anymore; use `List` instead) | `Validatable
user form
+ +@request.flash.get("success").getOrElse("") + +@helper.form(action = routes.UserController.userPost()) { + @helper.CSRF.formField + @helper.inputText(userForm("name")) + @helper.inputText(userForm("age")) + +} +``` + +must contain a CSRF token in the request. In the Scala API, this is done by importing `play.api.test.CSRFTokenHelper._`, which enriches `play.api.test.FakeRequest` with the `withCSRFToken` method: + +```scala +import play.api.test.CSRFTokenHelper._ + +class UserControllerSpec extends PlaySpec with GuiceOneAppPerTest { + "UserController GET" should { + + "render the index page from the application" in { + val controller = app.injector.instanceOf[UserController] + val request = FakeRequest().withCSRFToken + val result = controller.userGet().apply(request) + + status(result) mustBe OK + contentType(result) mustBe Some("text/html") + } + } +} +``` + +In the Java API, this is done by calling `CSRFTokenHelper.addCSRFToken` on a `play.mvc.Http.RequestBuilder` instance: + +``` +requestBuilder = CSRFTokenHelper.addCSRFToken(requestBuilder); +``` + +### Disabling Default Filters + +The simplest way to disable the default filters is to set the list of filters manually in `application.conf`: + +``` +play.filters.enabled=[] +``` + +This may be useful if you have functional tests that you do not want to go through the default filters. + +If you want to remove all filter classes, you can disable it through the `disablePlugins` mechanism: + +``` +lazy val root = project.in(file(".")).enablePlugins(PlayScala).disablePlugins(PlayFilters) +``` + +or by replacing `EnabledFilters`: + +``` +play.http.filters=play.api.http.NoHttpFilters +``` + +If you are writing functional tests involving `GuiceApplicationBuilder` and you want to disable default filters, then you can disable all or some of the filters through configuration by using `configure`: + +```scala +GuiceApplicationBuilder().configure("play.http.filters" -> "play.api.http.NoHttpFilters") +``` + +## Compile Time Default Filters + +If you are using compile time dependency injection, then the default filters are resolved at compile time, rather than through runtime. + +This means that the `BuiltInComponents` trait now contains an `httpFilters` method which is left abstract: + +```scala +trait BuiltInComponents { + + /** A user defined list of filters that is appended to the default filters */ + def httpFilters: Seq[EssentialFilter] +} +``` + +The default list of filters is defined in `play.filters.HttpFiltersComponents`: + +```scala +trait HttpFiltersComponents + extends CSRFComponents + with SecurityHeadersComponents + with AllowedHostsComponents { + + def httpFilters: Seq[EssentialFilter] = Seq(csrfFilter, securityHeadersFilter, allowedHostsFilter) +} +``` + +In most cases you will want to mixin HttpFiltersComponents and append your own filters: + +```scala +class MyComponents(context: ApplicationLoader.Context) + extends BuiltInComponentsFromContext(context) + with play.filters.HttpFiltersComponents { + + lazy val loggingFilter = new LoggingFilter() + override def httpFilters = { + super.httpFilters :+ loggingFilter + } +} +``` + +If you want to filter elements out of the list, you can do the following: + +```scala +class MyComponents(context: ApplicationLoader.Context) + extends BuiltInComponentsFromContext(context) + with play.filters.HttpFiltersComponents { + override def httpFilters = { + super.httpFilters.filterNot(_.getClass == classOf[CSRFFilter]) + } +} +``` + +### Disabling Compile Time Default Filters + +To disable the default filters, mixin `play.api.NoHttpFiltersComponents`: + +```scala +class MyComponents(context: ApplicationLoader.Context) + extends BuiltInComponentsFromContext(context) + with NoHttpFiltersComponents + with AssetsComponents { + + lazy val homeController = new HomeController(controllerComponents) + lazy val router = new Routes(httpErrorHandler, homeController, assets) +} +``` + +## JWT Support + +Play's cookie encoding has been switched to use JSON Web Token (JWT) under the hood. JWT comes with a number of advantages, notably automatic signing with HMAC-SHA-256, and support for automatic "not before" and "expires after" date checks which ensure the session cookie cannot be reused outside of a given time window. + +More information is available under [[Configuring the Session Cookie|SettingsSession]] page. + +### Fallback Cookie Support + +Play's cookie encoding uses a "fallback" cookie encoding mechanism that reads in JWT encoded cookies, then attempts reading a URL encoded cookie if the JWT parsing fails, so you can safely migrate existing session cookies to JWT. This functionality is in the `FallbackCookieDataCodec` trait and leveraged by `DefaultSessionCookieBaker` and `DefaultFlashCookieBaker`. + +### Legacy Support + +Using JWT encoded cookies should be seamless, but if you want, you can revert back to URL encoded cookie encoding by switching to `play.api.mvc.LegacyCookiesModule` in application.conf file: + +``` +play.modules.disabled+="play.api.mvc.CookiesModule" +play.modules.enabled+="play.api.mvc.LegacyCookiesModule" +``` + +### Custom CookieBakers + +If you have custom cookies being used in Play, using the `CookieBaker[T]` trait, then you will need to specify what kind of encoding you want for your custom cookie baker. + +The `encode` and `decode` methods that `Map[String, String]` to and from the format found in the browser have been extracted into `CookieDataCodec`. There are three implementations: `FallbackCookieDataCodec`, `JWTCookieDataCodec`, or `UrlEncodedCookieDataCodec`, which respectively represent URL-encoded with an HMAC, or a JWT, or a "read signed or JWT, write JWT" codec. + +You will also need to provide a `JWTConfiguration` case class, using the `JWTConfigurationParser` with the path to your configuration, or use `JWTConfiguration()` for the defaults. + + +```scala +@Singleton +class UserInfoCookieBaker @Inject()(service: UserInfoService, + val secretConfiguration: SecretConfiguration) + extends CookieBaker[UserInfo] with JWTCookieDataCodec { + + override val COOKIE_NAME: String = "userInfo" + + override val isSigned = true + + override def emptyCookie: UserInfo = new UserInfo() + + override protected def serialize(userInfo: UserInfo): Map[String, String] = service.encrypt(userInfo) + + override protected def deserialize(data: Map[String, String]): UserInfo = service.decrypt(data) + + override val path: String = "/" + + override val jwtConfiguration: JWTConfiguration = JWTConfigurationParser() +} +``` + +## Deprecated Futures methods + +The following `play.libs.concurrent.Futures` static methods have been deprecated: + +* `timeout(A value, long amount, TimeUnit unit)` +* `timeout(final long delay, final TimeUnit unit)` +* `delayed(Supplier supplier, long delay, TimeUnit unit, Executor executor)` + +A dependency injected instance of `Futures` should be used instead: + +```java +class MyClass { + @Inject + public MyClass(play.libs.concurrent.Futures futures) { + this.futures = futures; + } + + CompletionStage` heading from `Hello World!` to `Hello @name!
`.
+
+The end result will be:
+
+@[](code/javaguide/hello/helloName.scala.html)
+
+In the browser, enter the following URL and pass in any name as a query parameter to the hello method: . Play responds with a helpful compilation error that lets you know that the render method in the return value requires a typed parameter:
+
+[[images/hello-error.png]]
+
+To fix the compilation error, modify the `hello` action method in `HomeController` so that the it includes the `name` parameter when rendering the view:
+
+Java
+:
+@[hello-world-hello-correct-action](code/javaguide/hello/HelloController.java)
+
+Scala
+:
+@[hello-world-hello-correct-action](code/scalaguide/hello/HelloController.scala)
+
+Save the file and refresh the browser. The page should display a customized greeting similar to the following:
+
+[[images/hello-name.png]]
+
+## Summary
+
+Thanks for trying our tutorial. You learned how to use an action method, routes, Twirl template, and input parameter to create a customized Hello World greeting! You experienced how template compilation makes it easier to identify and fix problems and how auto-reloading saves time.
+
+This was just a simple example to get you started. Let's now see other official examples and tutorials from the community.
diff --git a/manual/tutorial/PlayApplicationOverview.md b/manual/tutorial/PlayApplicationOverview.md
new file mode 100644
index 00000000..f3858831
--- /dev/null
+++ b/manual/tutorial/PlayApplicationOverview.md
@@ -0,0 +1,51 @@
+
+
+# Play Application Overview
+
+This tutorial is implemented as a simple Play application that we can examine to start learning about Play. Let's first look at what happens at runtime. When you enter
+ */
+package javaguide.hello;
+
+import play.mvc.*;
+
+public class HelloController extends Controller {
+
+ // #hello-world-index-action
+ public Result index() {
+ // ###replace: ok(views.html.index.render());
+ return ok(javaguide.hello.html.index.render());
+ }
+ // #hello-world-index-action
+
+ // #hello-world-hello-action
+ public Result hello() {
+ // ###replace: return ok(views.html.hello.render());
+ return ok(javaguide.hello.html.hello.render());
+ }
+ // #hello-world-hello-action
+
+ /*
+ //#hello-world-hello-error-action
+ public Result hello(String name) {
+ return ok(views.html.hello.render());
+ }
+ //#hello-world-hello-error-action
+ */
+
+ // #hello-world-hello-correct-action
+ public Result hello(String name) {
+ // ###replace: return ok(views.html.hello.render(name));
+ return ok(javaguide.hello.html.helloName.render(name));
+ }
+ // #hello-world-hello-correct-action
+}
diff --git a/manual/tutorial/code/javaguide/hello/hello.scala.html b/manual/tutorial/code/javaguide/hello/hello.scala.html
new file mode 100644
index 00000000..87e2b7f2
--- /dev/null
+++ b/manual/tutorial/code/javaguide/hello/hello.scala.html
@@ -0,0 +1,9 @@
+@* #hello-world-page *@
+@main("Hello") {
+
+
+ Hello World
+
+
+}
+@* #hello-world-page *@
\ No newline at end of file
diff --git a/manual/tutorial/code/javaguide/hello/helloName.scala.html b/manual/tutorial/code/javaguide/hello/helloName.scala.html
new file mode 100644
index 00000000..e894a33a
--- /dev/null
+++ b/manual/tutorial/code/javaguide/hello/helloName.scala.html
@@ -0,0 +1,9 @@
+@(name: String)
+@main("Hello") {
+
+
+ Hello, @name
+
+
+}
+@* #hello-world-page *@
\ No newline at end of file
diff --git a/manual/tutorial/code/javaguide/hello/index.scala.html b/manual/tutorial/code/javaguide/hello/index.scala.html
new file mode 100644
index 00000000..15a6e995
--- /dev/null
+++ b/manual/tutorial/code/javaguide/hello/index.scala.html
@@ -0,0 +1,3 @@
+@main("Hello") {
+ Index view
+}
\ No newline at end of file
diff --git a/manual/tutorial/code/javaguide/hello/main.scala.html b/manual/tutorial/code/javaguide/hello/main.scala.html
new file mode 100644
index 00000000..e4385b6c
--- /dev/null
+++ b/manual/tutorial/code/javaguide/hello/main.scala.html
@@ -0,0 +1,11 @@
+@(title: String)(content: play.twirl.api.Html)
+
+
+
+
+ @title
+
+
+ @content
+
+
diff --git a/manual/tutorial/code/routes b/manual/tutorial/code/routes
new file mode 100644
index 00000000..d18b32d5
--- /dev/null
+++ b/manual/tutorial/code/routes
@@ -0,0 +1,11 @@
+# #hello-world-index-route
+GET / controllers.HomeController.index
+# #hello-world-index-route
+
+# #hello-world-hello-route
+GET /hello controllers.HomeController.hello
+# #hello-world-hello-route
+
+# #hello-world-hello-name-route
+# ###insert: GET /hello controllers.HomeController.hello(name: String)
+# #hello-world-hello-name-route
\ No newline at end of file
diff --git a/manual/tutorial/code/scalaguide/hello/HelloController.scala b/manual/tutorial/code/scalaguide/hello/HelloController.scala
new file mode 100644
index 00000000..1f49d4d3
--- /dev/null
+++ b/manual/tutorial/code/scalaguide/hello/HelloController.scala
@@ -0,0 +1,47 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package scalaguide.hello {
+ import play.api.mvc._
+ import javax.inject.Inject
+
+ package views {
+
+ import play.twirl.api.Html
+
+ object html {
+ def index(): Html = Html("Index page")
+ def hello(): Html = Html("Hello page")
+ def hello(name: String): Html = Html(s"Hello $name")
+ }
+ }
+
+ class HelloController @Inject()(val controllerComponents: ControllerComponents) extends BaseController {
+
+ //#hello-world-index-action
+ def index = Action {
+ Ok(views.html.index())
+ }
+ //#hello-world-index-action
+
+ //#hello-world-hello-action
+ def hello = Action {
+ Ok(views.html.hello())
+ }
+ //#hello-world-hello-action
+
+ /*
+ //#hello-world-hello-error-action
+ def hello(name: String) = Action {
+ Ok(views.html.hello())
+ }
+ //#hello-world-hello-error-action
+ */
+
+ //#hello-world-hello-correct-action
+ def hello(name: String) = Action {
+ Ok(views.html.hello(name))
+ }
+ //#hello-world-hello-correct-action
+ }
+}
diff --git a/manual/tutorial/images/hello-error.png b/manual/tutorial/images/hello-error.png
new file mode 100644
index 00000000..381fde2a
Binary files /dev/null and b/manual/tutorial/images/hello-error.png differ
diff --git a/manual/tutorial/images/hello-name.png b/manual/tutorial/images/hello-name.png
new file mode 100644
index 00000000..7e6c1659
Binary files /dev/null and b/manual/tutorial/images/hello-name.png differ
diff --git a/manual/tutorial/images/hello-page.png b/manual/tutorial/images/hello-page.png
new file mode 100644
index 00000000..d9009833
Binary files /dev/null and b/manual/tutorial/images/hello-page.png differ
diff --git a/manual/tutorial/images/play-request-response.png b/manual/tutorial/images/play-request-response.png
new file mode 100644
index 00000000..03d8b946
Binary files /dev/null and b/manual/tutorial/images/play-request-response.png differ
diff --git a/manual/tutorial/images/play-stack.png b/manual/tutorial/images/play-stack.png
new file mode 100644
index 00000000..b4728d5f
Binary files /dev/null and b/manual/tutorial/images/play-stack.png differ
diff --git a/manual/tutorial/index.toc b/manual/tutorial/index.toc
new file mode 100644
index 00000000..b86d9e6b
--- /dev/null
+++ b/manual/tutorial/index.toc
@@ -0,0 +1,4 @@
+HelloWorldTutorial: Hello World Tutorial
+PlayApplicationOverview: Play Application Overview
+ImplementingHelloWorld: Implementing Hello World
+Tutorials:Play Tutorials
\ No newline at end of file
diff --git a/manual/working/commonGuide/Modules.md b/manual/working/commonGuide/Modules.md
new file mode 100644
index 00000000..e9a1f52b
--- /dev/null
+++ b/manual/working/commonGuide/Modules.md
@@ -0,0 +1,22 @@
+
+# Extending Play with modules
+
+At its core, Play is a very lightweight HTTP server, providing mechanisms for serving HTTP requests, but not much else. Additional functionality in Play is provided through the use of Play modules.
+
+## What is a module?
+
+There is no strict definition in Play of what a module is or isn't - a module could be just a library that provides some helper methods to help you do something, or it could be a full framework providing complex functionality such as user management. Some modules are built in to Play, others are written and maintained by members of the Play community.
+
+Some modules provide components - objects that represent resources, for example a database connection. These objects may have a lifecycle and need to be started and stopped when the application starts and stops, and they may hold some state such as a cache. Play provides a variety of mechanisms for accessing and using these components. Components are not only provided by modules, they may be provided by the application themselves.
+
+## Accessing modules
+
+One of the earliest decisions that you need to make when starting a new Play project is how you will access the components provided by modules. Components are accessed through the use of a dependency injection mechanism, where rather than having your components look up other components in the system, your components declare what other components they need, and the system injects those components into your components.
+
+At its core, Play is agnostic to any particular form of dependency injection, however out of the box Play provides and we recommend that you use [Guice](https://github.com/google/guice). The remainder of this documentation will assume that this is the decision that you have made, however there will be examples of how to integrate with other dependency injection mechanisms.
+
+You can read more about dependency injection in [[Scala|ScalaDependencyInjection]] or [[Java|JavaDependencyInjection]].
+
+## Community modules
+
+Play has a list of [[community-developed modules|ModuleDirectory]] that may provide functionality you need or serve as examples of how to write a module.
diff --git a/manual/working/commonGuide/assets/Assets.md b/manual/working/commonGuide/assets/Assets.md
new file mode 100644
index 00000000..06a336fa
--- /dev/null
+++ b/manual/working/commonGuide/assets/Assets.md
@@ -0,0 +1,11 @@
+
+# Static assets
+
+This section covers serving your application’s static resources such as JavaScript, CSS and images.
+
+- [[Working with public assets|AssetsOverview]]
+- [[Using CoffeeScript|AssetsCoffeeScript]]
+- [[Using LESS CSS|AssetsLess]]
+- [[Using Sass|AssetsSass]]
+- [[Using JSHint|AssetsJSHint]]
+- [[Using RequireJs|RequireJS-support]]
diff --git a/manual/working/commonGuide/assets/AssetsCoffeeScript.md b/manual/working/commonGuide/assets/AssetsCoffeeScript.md
new file mode 100644
index 00000000..04e15a53
--- /dev/null
+++ b/manual/working/commonGuide/assets/AssetsCoffeeScript.md
@@ -0,0 +1,39 @@
+
+# Using CoffeeScript
+
+[CoffeeScript](https://coffeescript.org/) is a small and elegant language that compiles into JavaScript. It provides a nice syntax for writing JavaScript code.
+
+Compiled assets in Play must be defined in the `app/assets` directory. They are handled by the build process and CoffeeScript sources are compiled into standard JavaScript files. The generated JavaScript files are distributed as standard resources into the same `public/` folder as other unmanaged assets, meaning that there is no difference in the way you use them once compiled.
+
+For example a CoffeeScript source file `app/assets/javascripts/main.coffee` will be available as a standard JavaScript resource, at `public/javascripts/main.js`.
+
+CoffeeScript sources are compiled automatically during an `assets` command, or when you refresh any page in your browser while you are running in development mode. Any compilation errors will be displayed in your browser:
+
+[[images/coffeeError.png]]
+
+## Layout
+
+Here is an example layout for using CoffeeScript in your projects:
+
+```
+app
+ └ assets
+ └ javascripts
+ └ main.coffee
+```
+
+You can use the following syntax to use the compiled JavaScript file in your template:
+
+```html
+
+```
+
+Note the `lib/requirejs/require.js` path. The `lib` folder denotes the extracted WebJar assets, the `requirejs` folder corresponds to the WebJar artifactId, and the `require.js` refers to the required asset at the root of the WebJar. To clarify, the `requirejs` webjar dependency is declared at your build file like:
+
+```scala
+libraryDependencies += "org.webjars" % "requirejs" % "2.2.0"
+```
+
+## How are public assets packaged?
+
+During the build process, the contents of the `public` folder are processed and added to the application classpath.
+
+When you package your application, all assets for the application, including all sub projects, are aggregated into a single jar, in `target/my-first-app-1.0.0-assets.jar`. This jar is included in the distribution so that your Play application can serve them. This jar can also be used to deploy the assets to a CDN or reverse proxy.
+
+## The Assets controller
+
+Play comes with a built-in controller to serve public assets. By default, this controller provides caching, ETag, gzip and compression support. There are two different styles that the Assets controller supports: the first is to use Play's configuration, and the second is to use pass the assets path directly to the controller.
+
+### Binding the Assets components
+
+If you are using runtime dependency injection, Play already provides bindings in the `AssetsModule`, which is loaded by default. (If you are not using assets, you can disable this module by adding the configuration `play.modules.disabled += controllers.AssetsModule`.). The bindings there make `Assets` class injectable.
+
+If you are using components traits to do compile-time dependency injection, you should mix in `controllers.AssetsComponents`. Then the controller will be available as `assets: Assets`. You do not need to construct the controller yourself.
+
+### Using assets with configuration
+
+For the most common case where you only have one place where assets are centrally located, you can use configuration to specify the location:
+
+```
+play.assets {
+ path = "/public"
+ urlPrefix = "/assets"
+}
+```
+
+And use the `Assets.at` method with one parameter:
+
+```scala
+Assets.at(file: String)
+```
+
+Then in routes:
+
+@[assets-configured-path](code/configured.assets.routes)
+
+### Passing the assets path directly
+
+The `Assets` controller also defines an `at` action with two parameters:
+
+```scala
+Assets.at(path: String, file: String)
+```
+
+The `path` parameter must be fixed and defines the directory managed by the action. The `file` parameter is usually dynamically extracted from the request path.
+
+Here is the typical mapping of the `Assets` controller in your `conf/routes` file:
+
+@[assets-wildcard](code/common.assets.routes)
+
+Note that we define the `*file` dynamic part that will match the `.*` regular expression. So for example, if you send this request to the server:
+
+```
+GET /assets/javascripts/jquery.js
+```
+
+The router will invoke the `Assets.at` action with the following parameters:
+
+```
+controllers.Assets.at("/public", "javascripts/jquery.js")
+```
+
+To route to a single static file, both the path and file have to be specified:
+
+@[assets-single-static-file](code/common.assets.routes)
+
+## Reverse routing for public assets
+
+As for any controller mapped in the routes file, a reverse controller is created in `controllers.routes.Assets`. You use this to reverse the URL needed to fetch a public resource. For example, from a template:
+
+```html
+
+```
+
+In `DEV` mode this will by default produce the following result:
+
+```html
+
+```
+
+If your app is not running in `DEV` mode **and** a `jquery.min.js` or `jquery-min.js` file exists then by default the minified file will be used instead:
+
+```html
+
+```
+
+This makes debugging of JavaScript files easier during development. Of course this not only works for JavaScript files but for any file extension.
+If you don't want Play to automatically resolve the `.min.*` or `-min.*` files, regardless of the mode your application is running in, you can set `play.assets.checkForMinified = false` in your `application.conf` (or to `true` to always resolve the min file, even in `DEV` mode).
+
+Note that we don’t specify the first `folder` parameter when we reverse the route. This is because our routes file defines a single mapping for the `Assets.at` action, where the `folder` parameter is fixed. So it doesn't need to be specified.
+
+However, if you define two mappings for the `Assets.at` action, like this:
+
+@[assets-two-mappings](code/common.assets.routes)
+
+You will then need to specify both parameters when using the reverse router:
+
+```html
+
+
+```
+
+## Reverse routing and fingerprinting for public assets
+
+[sbt-web](https://github.com/sbt/sbt-web) brings the notion of a highly configurable asset pipeline to Play e.g. in your build file:
+
+```scala
+pipelineStages := Seq(rjs, digest, gzip)
+```
+
+The above will order the RequireJs optimizer ([sbt-rjs](https://github.com/sbt/sbt-rjs)), the digester ([sbt-digest](https://github.com/sbt/sbt-digest)) and then compression ([sbt-gzip](https://github.com/sbt/sbt-gzip)). Unlike many sbt tasks, these tasks will execute in the order declared, one after the other.
+
+In essence asset fingerprinting permits your static assets to be served with aggressive caching instructions to a browser. This will result in an improved experience for your users given that subsequent visits to your site will result in less assets requiring to be downloaded. Rails also describes the benefits of [asset fingerprinting](https://guides.rubyonrails.org/asset_pipeline.html#what-is-fingerprinting-and-why-should-i-care-questionmark).
+
+The above declaration of `pipelineStages` and the requisite `addSbtPlugin` declarations in your `plugins.sbt` for the plugins you require are your start point. You must then declare to Play what assets are to be versioned.
+
+There are two ways obtain the real path of a fingerprinted asset. The first way uses static state and supports the same style as normal reverse routing. It does so by looking up assets metadata that's set by a running Play application. The second way is to use configuration and inject an AssetsFinder to find your asset.
+
+### Using reverse routing and static state
+
+If you plan to use the reverse router with static state, the following routes file entry declares that all assets are to be versioned:
+
+```scala
+GET /assets/*file controllers.Assets.versioned(path="/public", file: Asset)
+```
+
+> **Note:** Make sure you indicate that `file` is an asset by writing `file: Asset`.
+
+You then use the reverse router, for example within a `scala.html` view:
+
+```html
+
+```
+
+The downside of this approach is that it requires special logic that converts the `Asset` from the path you passed in to the final minified path with a digest. It's also more difficult to unit test, since there's no component you can mock to define the path.
+
+### Using configuration and AssetsFinder
+
+You can also define your paths in configuration, and inject an `AssetsFinder` into your controller to get the final path. In your configuration set up the assets `path` (the directory containing assets) and the `urlPrefix` (the prefix to the URL in your application):
+
+```
+play.assets {
+ path = "/public"
+ urlPrefix = "/assets"
+}
+```
+
+In your routes file you can define a route as follows:
+
+@[assets-configured-path-versioned](code/configured.assets.routes)
+
+(you should not use the `: Asset` type annotation here)
+
+Then you can pass an `AssetsFinder` to your template and use that to get the final path:
+
+```html
+@(assetsFinder: AssetsFinder)
+
+
+```
+
+The advantage to this approach is that it requires no static state to set up. That means you can unit test your controllers and templates without a running application by simply passing an instance of `AssetsFinder`. That makes it simple to mock for a unit test by simply implementing the abstract methods that return `String`s.
+
+Using the `AssetsFinder` approach also makes it easy to run multiple self-contained applications at once in the same classloader, since it uses no static state. This can also be helpful for testing.
+
+The `AssetsFinder` interface also works in cases where fingerprinting is not used. It returns the original asset if a fingerprinted and/or minified asset cannot be found.
+
+## Etag support
+
+The `Assets` controller automatically manages **ETag** HTTP Headers. The ETag value is generated from the digest (if `sbt-digest` is being used in the asset pipeline) or otherwise the resource name and the file’s last modification date. If the resource file is embedded into a file, the JAR file’s last modification date is used.
+
+When a web browser makes a request specifying this **Etag** then the server can respond with **304 NotModified**.
+
+## Gzip support
+
+If a resource with the same name but using a `.gz` suffix is found then the `Assets` controller will also serve the latter and add the following HTTP header:
+
+```
+Content-Encoding: gzip
+```
+
+Including the `sbt-gzip` plugin in your build and declaring its position in the `pipelineStages` is all that is required to generate gzip files.
+
+## Additional `Cache-Control` directive
+
+Using Etag is usually enough for the purposes of caching. However if you want to specify a custom `Cache-Control` header for a particular resource, you can specify it in your `application.conf` file. For example:
+
+```
+# Assets configuration
+# ~~~~~
+play.assets.cache."/public/stylesheets/bootstrap.min.css"="max-age=3600"
+```
+
+You can also use partial paths to specify a custom `Cache-Control` for all the assets that are under that path, for example:
+
+```
+# Assets configuration
+# ~~~~~
+play.assets.cache."/public/stylesheets/"="max-age=100"
+play.assets.cache."/public/javascripts/"="max-age=200"
+```
+
+And Play will use `max-age=200` for all assets under `/public/javascripts` (like `/public/javascripts/main.js`) and `max-age=100` to all assets under `/public/stylesheets` (like `/public/stylesheets/main.css`).
+
+### How the additional directives are applied
+
+Play sorts the `Cache-Control` directives lexicographically and later from more specific to less specific. For example, given the following configuration:
+
+```
+# Assets configuration
+# ~~~~~
+play.assets.cache."/public/stylesheets/"="max-age=101"
+play.assets.cache."/public/stylesheets/layout/"="max-age=102"
+play.assets.cache."/public/stylesheets/app/"="max-age=103"
+play.assets.cache."/public/stylesheets/layout/main.css"="max-age=103"
+
+play.assets.cache."/public/javascripts/"="max-age=201"
+play.assets.cache."/public/javascripts/app/"="max-age=202"
+play.assets.cache."/public/javascripts/app/main.js"="max-age=203"
+```
+
+The directives will be sorted and applied in the following order:
+
+```
+play.assets.cache."/public/javascripts/app/main.js"="max-age=203"
+play.assets.cache."/public/javascripts/app/"="max-age=202"
+play.assets.cache."/public/javascripts/"="max-age=201"
+
+play.assets.cache."/public/stylesheets/app/"="max-age=103"
+play.assets.cache."/public/stylesheets/layout/main.css"="max-age=103"
+play.assets.cache."/public/stylesheets/layout/"="max-age=102"
+play.assets.cache."/public/stylesheets/"="max-age=101"
+```
+
+> **Note:** a configuration like `play.assets.cache."/public/stylesheets"="max-age=101"` will match both `public/stylesheets.css` and `public/stylesheets/main.css`, so you may want to add a trailing `/` to better differentiate directories, for example `play.assets.cache."/public/stylesheets/"="max-age=101"`.
+
+## Managed assets
+
+Starting with Play 2.3 managed assets are processed by [sbt-web](https://github.com/sbt/sbt-web#sbt-web) based plugins. Prior to 2.3 Play bundled managed asset processing in the form of CoffeeScript, LESS, JavaScript linting (ClosureCompiler) and RequireJS optimization. The following sections describe sbt-web and how the equivalent 2.2 functionality can be achieved. Note though that Play is not limited to this asset processing technology as many plugins should become available to sbt-web over time. Please check-in with the [sbt-web](https://github.com/sbt/sbt-web#sbt-web) project to learn more about what plugins are available.
+
+Many plugins use sbt-web's [js-engine plugin](https://github.com/sbt/sbt-js-engine). js-engine is able to execute plugins written to the Node API either within the JVM via the excellent [Trireme](https://github.com/apigee/trireme#trireme) project, or directly on [Node.js](https://nodejs.org/) for superior performance. Note that these tools are used during the development cycle only and have no involvement during the runtime execution of your Play application. If you have Node.js installed then you are encouraged to declare the following environment variable. For Unix, if `SBT_OPTS` has been defined elsewhere then you can:
+
+```bash
+export SBT_OPTS="$SBT_OPTS -Dsbt.jse.engineType=Node"
+```
+
+The above declaration ensures that Node.js is used when executing any sbt-web plugin.
+
+## Range requests support
+
+`Assets` controller automatically supports part of [RFC 7233](https://tools.ietf.org/html/rfc7233) which defines how range requests and partial responses works. The `Assets` controller will delivery a `206 Partial Content` if a satisfiable `Range` header is present in the request. It will also returns a `Accept-Ranges: bytes` for all assets delivery.
+
+> **Note:** Besides the fact that some parsing is done to better handle multiple ranges, `multipart/byteranges` is not fully supported yet.
+
+You can also return `206 Partial Content` when delivering files without using the `Assets` controller:
+
+### Scala version
+
+@[range-request](code/assets/controllers/RangeRequestController.scala)
+
+### Java version
+
+@[range-request](code/assets/controllers/JavaRangeRequestController.java)
+
+Both examples will delivery just part of the video file, according to the requested range.
diff --git a/manual/working/commonGuide/assets/AssetsSass.md b/manual/working/commonGuide/assets/AssetsSass.md
new file mode 100644
index 00000000..00f6cb1d
--- /dev/null
+++ b/manual/working/commonGuide/assets/AssetsSass.md
@@ -0,0 +1,95 @@
+
+# Using Sass
+
+[Sass](http://sass-lang.com/) is a dynamic stylesheet language. It allows considerable flexibility in the way you write CSS files including support for variables, mixins and more.
+
+Compilable assets in Play are typically defined in the `app/assets` directory. They are handled by the build process, and Sass sources are compiled into standard CSS files. The generated CSS files are distributed as standard resources into the same `public/` folder as the unmanaged assets, meaning that there is no difference in the way you use them once compiled.
+
+For example, Sass source file `app/assets/stylesheets/main.scss` will be available as standard CSS resource, at `public/stylesheets/main.css`.
+
+Sass sources are compiled automatically during an `assets` command, or when you refresh any page in your browser while you are running in development mode. Any compilation errors will be displayed in your browser:
+
+[[images/sassError.png]]
+
+## Working with partial Sass source files
+
+Any Sass file (`*.scss`/`*.sass`) will automatically be compiled. The Sass plugin will automatically determine which Sass syntax is being used (indented or not) based on the filename. A file who's name starts with an `_` will not be compiled separately. However, such files can be included in other Sass files by using the standard Sass import feature.
+
+## Layout
+
+Below an example layout for using Sass in your project is given:
+
+```
+app
+ └ assets
+ └ stylesheets
+ └ main.scss
+ └ utils
+ └ _reset.scss
+ └ _layout.scss
+```
+
+Given the following `main.scss` source:
+
+```scss
+@import "utils/reset";
+@import "utils/layout";
+
+h1 {
+ color: red;
+}
+```
+
+The Sass file outlined above, will be compiled into `public/stylesheets/main.css`. Hence, this file can be used in your template as any regular public asset:
+
+```html
+
+```
+
+## Mixing Sass and web-jars
+
+[WebJars](https://www.webjars.org) enable us to depend on client libraries without pulling all dependencies into our own code base manually.
+
+Compass is a library containing all sorts of reusable functions and mixins for Sass. Unfortunately, this library is targeted towards the Ruby implementation of Sass. There is a number of useful mixins that can be extracted from it. Fortunately, these mixins are wrapped in a web-jar.
+
+To include these compass mixins in your project is as easy as including the web-jar dependency in your library dependencies. For example, within a `build.sbt` file:
+
+```scala
+libraryDependencies += "org.webjars.bower" % "compass-mixins" % "0.12.7"
+```
+
+sbt-web will automatically extract WebJars into a `lib` directory relative to your asset's target directory. Therefore to use the Compass mixins you can import the mixins by:
+
+```scss
+@import "lib/compass-mixins/lib/compass";
+
+table.ellipsed-table {
+ tr td {
+ max-width: 100px;
+ @include ellipsis();
+ }
+}
+```
+
+The same idea can be used to include other Sass libraries, for instance the [official Sass port of bootstrap](https://github.com/twbs/bootstrap-sass). To include the WebJar use:
+
+```scala
+libraryDependencies += "org.webjars.bower" % "bootstrap-sass" % "3.3.6"
+```
+
+Then to use it in your project, you can use:
+
+```scss
+@import "lib/bootstrap-sass/assets/stylesheets/bootstrap";
+```
+
+## Enablement and Configuration
+
+Sass compilation is enabled by simply adding the sbt-sassify plugin to your plugins.sbt file when using the `PlayJava` or `PlayScala` plugins:
+
+```scala
+addSbtPlugin("org.irundaia.sbt" % "sbt-sassify" % "1.4.11")
+```
+
+The plugin's default configuration should normally be sufficient. However please refer to the [plugin's documentation](https://github.com/irundaia/sbt-sassify#options) for information on how it may be configured as well as its latest version.
+
diff --git a/manual/working/commonGuide/assets/RequireJS-support.md b/manual/working/commonGuide/assets/RequireJS-support.md
new file mode 100644
index 00000000..44f69f26
--- /dev/null
+++ b/manual/working/commonGuide/assets/RequireJS-support.md
@@ -0,0 +1,40 @@
+
+# RequireJS
+
+According to [RequireJS](https://requirejs.org/)' website
+
+> RequireJS is a JavaScript file and module loader. It is optimized for in-browser use, but it can be used in other JavaScript environments... Using a modular script loader like RequireJS will improve the speed and quality of your code.
+
+What this means in practice is that one can use [RequireJS](https://requirejs.org/) to modularize your JavaScript. RequireJS achieves this by implementing a semi-standard API called [Asynchronous Module Definition](http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition) (other similar ideas include [CommonJS](http://www.commonjs.org/) ). Using AMD makes it is possible to resolve and load javascript modules on the _client side_ while allowing server side _optimization_. For server side optimization module dependencies may be minified and combined using [UglifyJS 2](https://github.com/mishoo/UglifyJS2#uglifyjs-2).
+
+By convention RequireJS expects a main.js file to bootstrap its module loader.
+
+## Deployment
+
+The RequireJS optimizer shouldn't generally kick-in until it is time to perform a deployment i.e. by running the `start`, `stage` or `dist` tasks.
+
+If you're using WebJars with your build then the RequireJS optimizer plugin will also ensure that any JavaScript resources referenced from within a WebJar are automatically referenced from the [jsdelivr](https://www.jsdelivr.com) CDN. In addition if any `.min.js` file is found then that will be used in place of `.js`. An added bonus here is that there is no change required to your html!
+
+## Enablement and Configuration
+
+RequireJS optimization is enabled by simply adding the plugin to your plugins.sbt file when using the `PlayJava` or `PlayScala` plugins:
+
+```scala
+addSbtPlugin("com.typesafe.sbt" % "sbt-rjs" % "1.0.9")
+```
+
+To add the plugin to the asset pipeline you can declare it as follows (assuming just the one plugin for the pipeline - add others into the sequence such as digest and gzip as required):
+
+```scala
+pipelineStages := Seq(rjs)
+```
+
+A standard build profile for the RequireJS optimizer is provided and should suffice for most projects. However please refer to the [plugin's documentation](https://github.com/sbt/sbt-rjs#sbt-rjs) for information on how it may be configured.
+
+Note that RequireJS performs a lot of work and while it works when executed in-JVM under Trireme, you will be best to use Node.js as the js-engine from a performance perspective. For convenience you can set the `sbt.jse.engineType` property in `SBT_OPTS`. For example on Unix:
+
+```bash
+export SBT_OPTS="$SBT_OPTS -Dsbt.jse.engineType=Node"
+```
+
+Please refer to the [plugin's documentation](https://github.com/sbt/sbt-rjs#sbt-rjs) for information on how it may be configured.
diff --git a/manual/working/commonGuide/assets/code/CommonAssets.scala b/manual/working/commonGuide/assets/code/CommonAssets.scala
new file mode 100644
index 00000000..729e5001
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/CommonAssets.scala
@@ -0,0 +1,8 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package common.assets
+
+package object controllers {
+ type Assets = _root_.controllers.Assets
+}
diff --git a/manual/working/commonGuide/assets/code/ConfiguredAssets.scala b/manual/working/commonGuide/assets/code/ConfiguredAssets.scala
new file mode 100644
index 00000000..a7489ffc
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/ConfiguredAssets.scala
@@ -0,0 +1,8 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package configured.assets
+
+package object controllers {
+ type Assets = _root_.controllers.Assets
+}
diff --git a/manual/working/commonGuide/assets/code/assets/controllers/JavaRangeRequestController.java b/manual/working/commonGuide/assets/code/assets/controllers/JavaRangeRequestController.java
new file mode 100644
index 00000000..12d4eea6
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/assets/controllers/JavaRangeRequestController.java
@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package assets.controllers;
+
+import play.mvc.*;
+
+import java.io.File;
+
+public class JavaRangeRequestController extends Controller {
+
+ // #range-request
+ public Result video(Long videoId) {
+ File videoFile = getVideoFile(videoId);
+ return RangeResults.ofFile(videoFile);
+ }
+ // #range-request
+
+ private File getVideoFile(Long videoId) {
+ return new File("video.mp4");
+ }
+}
diff --git a/manual/working/commonGuide/assets/code/assets/controllers/RangeRequestController.scala b/manual/working/commonGuide/assets/code/assets/controllers/RangeRequestController.scala
new file mode 100644
index 00000000..40153f53
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/assets/controllers/RangeRequestController.scala
@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package assets.controllers
+
+import java.io.File
+import javax.inject.Inject
+
+import play.api.mvc._
+
+class RangeRequestController @Inject()(c: ControllerComponents) extends AbstractController(c) {
+
+ // #range-request
+ def video(videoId: Long) = Action { implicit request =>
+ val videoFile = getVideoFile(videoId)
+ RangeResult.ofFile(videoFile, request.headers.get(RANGE), Some("video/mp4"))
+ }
+ // #range-request
+
+ private def getVideoFile(videoId: Long) = new File("video.mp4")
+}
diff --git a/manual/working/commonGuide/assets/code/common.assets.routes b/manual/working/commonGuide/assets/code/common.assets.routes
new file mode 100644
index 00000000..9502fda6
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/common.assets.routes
@@ -0,0 +1,13 @@
+#assets-wildcard
+GET /assets/*file controllers.Assets.at(path="/public", file)
+#assets-wildcard
+
+#assets-single-static-file
+GET /favicon.ico controllers.Assets.at(path="/public", file="favicon.ico")
+#assets-single-static-file
+
+#assets-two-mappings
+GET /javascripts/*file controllers.Assets.at(path="/public/javascripts", file)
+GET /images/*file controllers.Assets.at(path="/public/images", file)
+#assets-two-mappings
+
diff --git a/manual/working/commonGuide/assets/code/configured.assets.routes b/manual/working/commonGuide/assets/code/configured.assets.routes
new file mode 100644
index 00000000..898d3e24
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/configured.assets.routes
@@ -0,0 +1,7 @@
+#assets-configured-path
+GET /assets/*file controllers.Assets.at(file)
+#assets-configured-path
+
+#assets-configured-path-versioned
+GET /assets/*file controllers.Assets.versioned(file)
+#assets-configured-path-versioned
diff --git a/manual/detailedTopics/assets/images/ClosureError.png b/manual/working/commonGuide/assets/images/ClosureError.png
similarity index 100%
rename from manual/detailedTopics/assets/images/ClosureError.png
rename to manual/working/commonGuide/assets/images/ClosureError.png
diff --git a/manual/detailedTopics/assets/images/coffeeError.png b/manual/working/commonGuide/assets/images/coffeeError.png
similarity index 100%
rename from manual/detailedTopics/assets/images/coffeeError.png
rename to manual/working/commonGuide/assets/images/coffeeError.png
diff --git a/manual/detailedTopics/assets/images/lessError.png b/manual/working/commonGuide/assets/images/lessError.png
similarity index 100%
rename from manual/detailedTopics/assets/images/lessError.png
rename to manual/working/commonGuide/assets/images/lessError.png
diff --git a/manual/working/commonGuide/assets/images/sassError.png b/manual/working/commonGuide/assets/images/sassError.png
new file mode 100644
index 00000000..b62d40f6
Binary files /dev/null and b/manual/working/commonGuide/assets/images/sassError.png differ
diff --git a/manual/working/commonGuide/assets/index.toc b/manual/working/commonGuide/assets/index.toc
new file mode 100644
index 00000000..41643251
--- /dev/null
+++ b/manual/working/commonGuide/assets/index.toc
@@ -0,0 +1,7 @@
+Assets:Static assets
+AssetsOverview:Working with public assets
+AssetsCoffeeScript:Using CoffeeScript
+AssetsLess:Using LESS CSS
+AssetsSass:Using Sass
+AssetsJSHint:Using JSHint
+RequireJS-support:Using RequireJs
\ No newline at end of file
diff --git a/manual/working/commonGuide/build/AggregatingReverseRouters.md b/manual/working/commonGuide/build/AggregatingReverseRouters.md
new file mode 100644
index 00000000..6b677c5e
--- /dev/null
+++ b/manual/working/commonGuide/build/AggregatingReverseRouters.md
@@ -0,0 +1,14 @@
+
+# Aggregating reverse routers
+
+In some situations you want to share reverse routers between sub projects that are not dependent on each other.
+
+For example, you might have a `web` sub project, and an `api` sub project. These sub projects may have no dependence on each other, except that the `web` project wants to render links to the `api` project (for making AJAX calls), while the `api` project wants to render links to the `web` (rendering the web link for a resource in JSON). In this situation, it would be convenient to use the reverse router, but since these projects don't depend on each other, you can't.
+
+Play's routes compiler offers a feature that allows a common dependency to generate the reverse routers for projects that depend on it so that the reverse routers can be shared between those projects. This is configured using the `aggregateReverseRoutes` sbt configuration item, like this:
+
+@[content](code/aggregate.sbt)
+
+In this setup, the reverse routers for `api` and `web` will be generated as part of the `common` project. Meanwhile, the forwards routers for `api` and `web` will still generate forwards routers, but not reverse routers, because their reverse routers have already been generated in the `common` project which they depend on, so they don't need to generate them.
+
+> Note that the `common` project has a type of `Project` explicitly declared. This is because there is a recursive reference between it and the `api` and `web` projects, through the `dependsOn` method and `aggregateReverseRoutes` setting, so the Scala type checker needs an explicit type somewhere in the chain of recursion.
diff --git a/manual/working/commonGuide/build/Build.md b/manual/working/commonGuide/build/Build.md
new file mode 100644
index 00000000..96d36c6d
--- /dev/null
+++ b/manual/working/commonGuide/build/Build.md
@@ -0,0 +1,14 @@
+
+# The build system
+
+This section gives details about Play's build system.
+
+- [[Overview of the build system|BuildOverview]]
+- [[About sbt settings|sbtSettings]]
+- [[Manage application dependencies|sbtDependencies]]
+- [[Working with sub-projects|sbtSubProjects]]
+- [[Play enhancer|PlayEnhancer]]
+- [[Aggregating reverse routers|AggregatingReverseRouters]]
+- [[Improving Compilation Times|CompilationSpeed]]
+- [[Cookbook|sbtCookbook]]
+- [[Debugging your build|sbtDebugging]]
diff --git a/manual/working/commonGuide/build/BuildOverview.md b/manual/working/commonGuide/build/BuildOverview.md
new file mode 100644
index 00000000..fa63e0db
--- /dev/null
+++ b/manual/working/commonGuide/build/BuildOverview.md
@@ -0,0 +1,81 @@
+
+# Overview of the build system
+
+The Play build system uses [sbt](https://www.scala-sbt.org/), a high-performance integrated build for Scala and Java projects. Using `sbt` as our build tool brings certain requirements to play which are explained on this page.
+
+## Understanding sbt
+
+sbt functions quite differently to many traditional build tasks. Fundamentally, sbt is a task engine. Your build is represented as a tree of task dependencies that need to be executed, for example, the `compile` task depends on the `sources` task, which depends on the `sourceDirectories` task and the `sourceGenerators` task, and so on.
+
+sbt breaks typical build executions up into very fine grained tasks, and any task at any point in the tree can be arbitrarily redefined in your build. This makes sbt very powerful, but also requires a shift in thinking if you've come from other build tools that break your build up into very coarsely grained tasks.
+
+The documentation here describes Play's usage of sbt at a very high level. As you start to use sbt more in your project, it is recommended that you follow the [sbt tutorial](https://www.scala-sbt.org/0.13/tutorial/index.html) to get an understanding for how sbt fits together. Another resource that many people have found useful is [this series of blog posts](https://jazzy.id.au/2015/03/03/sbt-task-engine.html).
+
+## Play application directory structure
+
+Most people get started with Play using on of our [example templates](https://playframework.com/download#examples), or with the `sbt new` command, which generally produce a directory structure like this:
+
+- `/`: The root folder of your application
+- `/README`: A text file describing your application that will get deployed with it.
+- `/app`: Where your application code will be stored.
+- `/build.sbt`: The [sbt](https://www.scala-sbt.org/) settings that describe building your application.
+- `/conf`: Configuration files for your application
+- `/project`: Further build description information
+- `/public`: Where static, public assets for your application are stored.
+- `/test`: Where your application's test code will be stored.
+
+For now, we are going to concern ourselves with the `/build.sbt` file and the `/project` directory.
+
+> **Tip**: See the complete [[anatomy of a Play application here|Anatomy]].
+
+## The `/build.sbt` file.
+
+An sbt build file for Play generally looks something like this:
+
+@[default](code/build.sbt)
+
+The `name` line defines the name of your application and it will be the same as the name of your application's root directory, `/`. In sbt this is derived from the argument that you gave to the `sbt new` command.
+
+The `version` line provides the version of your application which is used as part of the name for the artifacts your build will produce.
+
+The `libraryDependencies` line specifies the libraries that your application depends on. You can see more details about [how to manage your dependencies in the sbt docs](https://www.scala-sbt.org/0.13/docs/Library-Management.html).
+
+Finally, you need to enable an sbt plugin on your project to "Play-ify" it. This adds support for Play-specific features such as the twirl compiler and the routes compiler, and adds the necessary Play libraries to build your project and run the server. Generally you should use one of the following Play plugins for a Play application:
+ - `PlayScala`: a standard Play Scala project.
+ - `PlayJava`: a standard Play Java project, with the [[forms|JavaForms]] module.
+ - `PlayMinimalJava`: a minimal Play Java project, without forms support.
+
+### Using scala for building
+
+sbt is also able to construct the build requirements from scala files inside your project's `project` folder. The recommended practice is to use `build.sbt` but there are times when using scala directly is required. If you find yourself, perhaps because you're migrating an older project, then here are a few useful imports:
+
+```scala
+import sbt._
+import Keys._
+import play.sbt._
+import Play.autoImport._
+import PlayKeys._
+```
+
+The line indicating `autoImport` is the correct means of importing an sbt plugin's automatically declared properties. Along the same lines, if you're importing an sbt-web plugin then you might well:
+
+```scala
+import com.typesafe.sbt.less.autoImport._
+import LessKeys._
+```
+
+## The `/project` directory
+
+Everything related to building your project is kept in the `/project` directory underneath your application directory. This is an [sbt](https://www.scala-sbt.org/) requirement. Inside that directory, there are two files:
+
+- `/project/build.properties`: This is a marker file that declares the sbt version used.
+- `/project/plugins.sbt`: sbt plugins used by the project build including Play itself.
+
+## Play plugin for sbt (`/project/plugins.sbt`)
+
+The Play console and all of its development features like live reloading are implemented via an sbt plugin. It is registered in the `/project/plugins.sbt` file:
+
+```scala
+addSbtPlugin("com.typesafe.play" % "sbt-plugin" % playVersion) // where version is the current Play version, i.e. "%PLAY_VERSION%"
+```
+> **Note**: `build.properties` and `plugins.sbt` must be manually updated when you are changing the play version.
diff --git a/manual/working/commonGuide/build/CompilationSpeed.md b/manual/working/commonGuide/build/CompilationSpeed.md
new file mode 100644
index 00000000..68cf1550
--- /dev/null
+++ b/manual/working/commonGuide/build/CompilationSpeed.md
@@ -0,0 +1,20 @@
+
+# Improving Compilation Times
+
+Compilation speed can be improved by following some guidelines that are also good engineering practice:
+
+## Use subprojects/modularize
+
+This is something like bulkheads for incremental compilation in addition to the other benefits of modularization. It minimizes the size of cycles, makes inter-dependencies explicit, and allows you to work with a subset of the code when desired. It also allows sbt to compile independent modules in parallel.
+
+## Annotate return types of public methods
+
+This makes compilation faster as it reduces the need for type inference and for accuracy helps address corner cases in incremental compilation arising from inference across source file boundaries.
+
+## Avoid large cycles between source files
+
+Cycles tend to result in larger recompilations and/or more steps. In sbt 0.13.0+ (Play 2.2+), this is less of a problem.
+
+## Minimize inheritance
+
+A public API change in a source file typically requires recompiling all descendents.
diff --git a/manual/working/commonGuide/build/PlayEnhancer.md b/manual/working/commonGuide/build/PlayEnhancer.md
new file mode 100644
index 00000000..1d94335b
--- /dev/null
+++ b/manual/working/commonGuide/build/PlayEnhancer.md
@@ -0,0 +1,52 @@
+
+# Play enhancer
+
+The [Play enhancer](https://github.com/playframework/play-enhancer) is an sbt plugin that generates getters and setters for Java beans, and rewrites the code that accesses those fields to use the getters and setters.
+
+## Motivation
+
+One common criticism of Java is that simple things require a lot of boilerplate code. One of the biggest examples of this is encapsulating fields - it is considered good practice to encapsulate the access and mutation of fields in methods, as this allows future changes such as validation and generation of the data. In Java, this means making all your fields private, and then writing getters and setters for each field, a typical overhead of 6 lines of code per field.
+
+Furthermore, many libraries, particularly libraries that use reflection to access properties of objects such as ORMs, require classes to be implemented in this way, with getters and setters for each field.
+
+The Play enhancer provides a convenient alternative to manually implementing getters and setters. It implements some post processing on the compiled byte code for your classes, this is commonly referred to as byte code enhancement. For every public field in your classes, Play will automatically generate a getter and setter, and then will rewrite the code that uses these fields to use the getters and setters instead.
+
+### Drawbacks
+
+Using byte code enhancement to generating getters and setters is not without its drawbacks however. Here are a few:
+
+* Byte code enhancement is opaque, you can't see the getters and setters that are generated, so when things go wrong, it can be hard to debug and understand what is happening. Byte code enhancement is ofter described as being "magic" for this reason.
+* Byte code enhancement can interfere with the operation of some tooling, such as IDEs, as they will be unaware of the eventual byte code that gets used. This can cause problems such as tests failing when run in an IDE because they depend on byte code enhancement, but the IDE isn't running the byte code enhancer when it compiles your source files.
+* Existing Java developers that are new to your codebase will not expect getters and setters to be generated, this can cause confusion.
+
+Whether you use the Play enhancer or not in your projects is up to you, if you do decide to use it the most important thing is that you understand what the enhancer does, and what the drawbacks may be.
+
+## Setting up
+
+To enable the byte code enhancer, simply add the following line to your `project/plugins.sbt` file:
+
+@[plugins.sbt](code/enhancer.sbt)
+
+The Play enhancer should be enabled for all your projects. If you want to disable the Play enhancer for a particular project, you can do that like so in your `build.sbt` file:
+
+@[disable-project](code/enhancer.sbt)
+
+In some situations, it may not be possible to disable the enhancer plugin, an example of this is using Play's ebean plugin, which requires the enhancer to ensure that getters and setters are generated before it does its byte code enhancement. If you don't want to generate getters and setters in that case, you can use the `playEnhancerEnabled` setting:
+
+@[disable-enhancement](code/enhancer.sbt)
+
+## Operation
+
+The enhancer looks for all fields on Java classes that:
+
+* are public
+* are non static
+* are non final
+
+For each of those fields, it will generate a getter and a setter if they don't already exist. If you wish to provide a custom getter or setter for a field, this can be done by just writing it, the Play enhancer will simply skip the generation of the getter or setter if it already exists.
+
+## Configuration
+
+If you want to control exactly which files get byte code enhanced, this can be done by configuring the `sources` task scoped to the `playEnhancerGenerateAccessors` and `playEnhancerRewriteAccessors` tasks. For example, to only enhance the java sources in the models package, you might do this:
+
+@[select-generate](code/enhancer.sbt)
diff --git a/manual/detailedTopics/build/code/aggregate.sbt b/manual/working/commonGuide/build/code/aggregate.sbt
similarity index 85%
rename from manual/detailedTopics/build/code/aggregate.sbt
rename to manual/working/commonGuide/build/code/aggregate.sbt
index 29739126..200a1846 100644
--- a/manual/detailedTopics/build/code/aggregate.sbt
+++ b/manual/working/commonGuide/build/code/aggregate.sbt
@@ -1,3 +1,7 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
//#content
lazy val common: Project = (project in file("common"))
.enablePlugins(PlayScala)
diff --git a/manual/detailedTopics/build/code/build.sbt b/manual/working/commonGuide/build/code/build.sbt
similarity index 62%
rename from manual/detailedTopics/build/code/build.sbt
rename to manual/working/commonGuide/build/code/build.sbt
index 8dd14ba5..f9b828c4 100644
--- a/manual/detailedTopics/build/code/build.sbt
+++ b/manual/working/commonGuide/build/code/build.sbt
@@ -1,3 +1,7 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
//#default
name := "foo"
@@ -6,8 +10,8 @@ version := "1.0-SNAPSHOT"
libraryDependencies ++= Seq(
jdbc,
anorm,
- cache
+ ehcache
)
lazy val root = (project in file(".")).enablePlugins(PlayScala)
-//#default
\ No newline at end of file
+//#default
diff --git a/manual/working/commonGuide/build/code/common.build.routes b/manual/working/commonGuide/build/code/common.build.routes
new file mode 100644
index 00000000..a351deb6
--- /dev/null
+++ b/manual/working/commonGuide/build/code/common.build.routes
@@ -0,0 +1,5 @@
+#assets-routes
+GET /index controllers.admin.HomeController.index()
+
+GET /assets/*file controllers.Assets.at(path="/public/lib/myadmin", file)
+#assets-routes
diff --git a/manual/working/commonGuide/build/code/cookbook.sbt b/manual/working/commonGuide/build/code/cookbook.sbt
new file mode 100644
index 00000000..2275618b
--- /dev/null
+++ b/manual/working/commonGuide/build/code/cookbook.sbt
@@ -0,0 +1,25 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
+//#compiler-options
+scalacOptions += "-feature"
+//#compiler-options
+
+//#add-assets
+unmanagedResourceDirectories in Assets += baseDirectory.value / "pictures"
+//#add-assets
+
+//#disable-scaladoc
+sources in (Compile, doc) := Seq.empty
+publishArtifact in (Compile, packageDoc) := false
+//#disable-scaladoc
+
+//#ivy-logging
+ivyLoggingLevel := UpdateLogging.Quiet
+//#ivy-logging
+
+//#fork-parallel-test
+parallelExecution in Test := true
+fork in Test := false
+//#fork-parallel-test
diff --git a/manual/working/commonGuide/build/code/dependencies.sbt b/manual/working/commonGuide/build/code/dependencies.sbt
new file mode 100644
index 00000000..e0c5170f
--- /dev/null
+++ b/manual/working/commonGuide/build/code/dependencies.sbt
@@ -0,0 +1,36 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
+//#single-dep
+libraryDependencies += "org.apache.derby" % "derby" % "10.13.1.1"
+//#single-dep
+
+//#single-dep-test
+libraryDependencies += "org.apache.derby" % "derby" % "10.13.1.1" % "test"
+//#single-dep-test
+
+//#multi-deps
+libraryDependencies ++= Seq(
+ "org.apache.derby" % "derby" % "10.13.1.1",
+ "org.hibernate" % "hibernate-entitymanager" % "5.2.10.Final"
+)
+//#multi-deps
+
+//#explicit-scala-version-dep
+libraryDependencies += "org.scala-stm" % "scala-stm_2.11" % "0.8"
+//#explicit-scala-version-dep
+
+//#auto-scala-version-dep
+libraryDependencies += "org.scala-stm" %% "scala-stm" % "0.8"
+//#auto-scala-version-dep
+
+//#resolver
+resolvers += "sonatype snapshots".at("https://oss.sonatype.org/content/repositories/snapshots/")
+//#resolver
+
+//#local-maven-repos
+resolvers += (
+ "Local Maven Repository".at(s"file:///${Path.userHome.absolutePath}/.m2/repository")
+)
+//#local-maven-repos
diff --git a/manual/detailedTopics/build/code/enhancer.sbt b/manual/working/commonGuide/build/code/enhancer.sbt
similarity index 73%
rename from manual/detailedTopics/build/code/enhancer.sbt
rename to manual/working/commonGuide/build/code/enhancer.sbt
index 4fee31cd..569678ac 100644
--- a/manual/detailedTopics/build/code/enhancer.sbt
+++ b/manual/working/commonGuide/build/code/enhancer.sbt
@@ -1,5 +1,9 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
//#plugins.sbt
-addSbtPlugin("com.typesafe.sbt" % "sbt-play-enhancer" % "1.1.0")
+addSbtPlugin("com.typesafe.sbt" % "sbt-play-enhancer" % "1.2.2")
//#plugins.sbt
//#disable-project
diff --git a/manual/working/commonGuide/build/code/javaguide/common/build/controllers/AssetsBuilder.java b/manual/working/commonGuide/build/code/javaguide/common/build/controllers/AssetsBuilder.java
new file mode 100644
index 00000000..0c4f6f0d
--- /dev/null
+++ b/manual/working/commonGuide/build/code/javaguide/common/build/controllers/AssetsBuilder.java
@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+// #assets-builder
+// ###replace: package controllers.admin;
+package javaguide.common.build.controllers;
+
+import play.api.mvc.*;
+import controllers.AssetsMetadata;
+import play.api.http.HttpErrorHandler;
+
+import javax.inject.Inject;
+
+// ###replace: public class AssetsBuilder extends controllers.Assets {
+class Assets extends controllers.Assets {
+
+ @Inject
+ public Assets(HttpErrorHandler errorHandler, AssetsMetadata meta) {
+ super(errorHandler, meta);
+ }
+
+ public Action at(String path, String file) {
+ boolean aggressiveCaching = true;
+ return super.at(path, file, aggressiveCaching);
+ }
+}
+// #assets-builder
diff --git a/manual/working/commonGuide/build/code/javaguide/common/build/controllers/HomeController.java b/manual/working/commonGuide/build/code/javaguide/common/build/controllers/HomeController.java
new file mode 100644
index 00000000..b334176d
--- /dev/null
+++ b/manual/working/commonGuide/build/code/javaguide/common/build/controllers/HomeController.java
@@ -0,0 +1,14 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+// ###replace: package controllers.admin;
+package javaguide.common.build.controllers;
+
+import play.mvc.Controller;
+import play.mvc.Result;
+
+public class HomeController extends Controller {
+ public Result index() {
+ return ok("admin");
+ }
+}
diff --git a/manual/working/commonGuide/build/code/runhook.sbt b/manual/working/commonGuide/build/code/runhook.sbt
new file mode 100644
index 00000000..b66171b8
--- /dev/null
+++ b/manual/working/commonGuide/build/code/runhook.sbt
@@ -0,0 +1,66 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
+// You can't define objects at the root level of an sbt file, so we do it inside a def
+def Grunt(base: File) = {
+ //#grunt-before-started
+ import play.sbt.PlayRunHook
+ import sbt._
+ import scala.sys.process.Process
+
+ object Grunt {
+ def apply(base: File): PlayRunHook = {
+
+ object GruntProcess extends PlayRunHook {
+
+ override def beforeStarted(): Unit = {
+ Process("grunt dist", base).run
+ }
+ }
+
+ GruntProcess
+ }
+ }
+ //#grunt-before-started
+ Grunt(base)
+}
+
+//#grunt-build-sbt
+PlayKeys.playRunHooks += Grunt(baseDirectory.value)
+//#grunt-build-sbt
+
+def Grunt2(base: File) = {
+ //#grunt-watch
+ import play.sbt.PlayRunHook
+ import sbt._
+ import java.net.InetSocketAddress
+ import scala.sys.process.Process
+
+ object Grunt {
+ def apply(base: File): PlayRunHook = {
+
+ object GruntProcess extends PlayRunHook {
+
+ var watchProcess: Option[Process] = None
+
+ override def beforeStarted(): Unit = {
+ Process("grunt dist", base).run
+ }
+
+ override def afterStarted(addr: InetSocketAddress): Unit = {
+ watchProcess = Some(Process("grunt watch", base).run)
+ }
+
+ override def afterStopped(): Unit = {
+ watchProcess.map(p => p.destroy())
+ watchProcess = None
+ }
+ }
+
+ GruntProcess
+ }
+ }
+ //#grunt-watch
+ Grunt(base)
+}
diff --git a/manual/working/commonGuide/build/code/scalaguide/common/build/controllers/SubProjectAssets.scala b/manual/working/commonGuide/build/code/scalaguide/common/build/controllers/SubProjectAssets.scala
new file mode 100644
index 00000000..f6c44fbe
--- /dev/null
+++ b/manual/working/commonGuide/build/code/scalaguide/common/build/controllers/SubProjectAssets.scala
@@ -0,0 +1,9 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package scalaguide.common.build
+
+package object controllers {
+ type AssetsBuilder = _root_.controllers.AssetsBuilder
+ type Assets = _root_.controllers.Assets
+}
diff --git a/manual/working/commonGuide/build/code/scalaguide/common/build/controllers/SubProjectsAssetsBuilder.scala b/manual/working/commonGuide/build/code/scalaguide/common/build/controllers/SubProjectsAssetsBuilder.scala
new file mode 100644
index 00000000..1ab0b1c7
--- /dev/null
+++ b/manual/working/commonGuide/build/code/scalaguide/common/build/controllers/SubProjectsAssetsBuilder.scala
@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package common.build.controllers {
+
+ //#assets-builder
+ import javax.inject._
+
+ import play.api.http.HttpErrorHandler
+
+ class Assets @Inject()(
+ errorHandler: HttpErrorHandler,
+ assetsMetadata: controllers.AssetsMetadata
+ ) extends controllers.AssetsBuilder(errorHandler, assetsMetadata)
+ //#assets-builder
+
+ package admin {
+ //#admin-home-controller
+ //###insert: package controllers.admin
+
+ import play.api.mvc._
+ import javax.inject.Inject
+
+ class HomeController @Inject()(val controllerComponents: ControllerComponents) extends BaseController {
+
+ def index = Action { implicit request =>
+ Ok("admin")
+ }
+ }
+ //#admin-home-controller
+ }
+}
diff --git a/manual/detailedTopics/build/images/ivy-report.png b/manual/working/commonGuide/build/images/ivy-report.png
similarity index 100%
rename from manual/detailedTopics/build/images/ivy-report.png
rename to manual/working/commonGuide/build/images/ivy-report.png
diff --git a/manual/working/commonGuide/build/index.toc b/manual/working/commonGuide/build/index.toc
new file mode 100644
index 00000000..ddbf4739
--- /dev/null
+++ b/manual/working/commonGuide/build/index.toc
@@ -0,0 +1,10 @@
+Build:Contents
+BuildOverview:Overview of the build system
+sbtSettings:About sbt settings
+sbtDependencies:Manage application dependencies
+sbtSubProjects:Working with sub-projects
+PlayEnhancer:Play enhancer
+AggregatingReverseRouters:Aggregating reverse routers
+CompilationSpeed:Improving Compilation Times
+sbtCookbook:Cookbook
+sbtDebugging:Debugging your build
diff --git a/manual/working/commonGuide/build/sbtCookbook.md b/manual/working/commonGuide/build/sbtCookbook.md
new file mode 100644
index 00000000..d585e369
--- /dev/null
+++ b/manual/working/commonGuide/build/sbtCookbook.md
@@ -0,0 +1,72 @@
+
+# sbt Cookbook
+
+## Hooking into Play's dev mode
+
+When Play runs in dev mode, that is, when using `sbt run`, it's often useful to hook into this to start up additional processes that are required for development. This can be done by defining a `PlayRunHook`, which is a trait with the following methods:
+
+ * `beforeStarted(): Unit` - called before the play application is started, but after all "before run" tasks have been completed.
+ * `afterStarted(addr: InetSocketAddress): Unit` - called after the play application has been started.
+ * `afterStopped(): Unit` - called after the play process has been stopped.
+
+Now let's say you want to build a Web application with `grunt` before the application is started. First, you need to create a Scala object in the `project/` directory to extend `PlayRunHook`. Let's name it `Grunt.scala`:
+
+@[grunt-before-started](code/runhook.sbt)
+
+Now you can register this hook in `build.sbt`:
+
+@[grunt-build-sbt](code/runhook.sbt)
+
+This will execute the `grunt dist` command in `baseDirectory` before the application is started whenever you run `sbt run`.
+
+Now we want to modify our run hook to execute the `grunt watch` command to observe changes and rebuild the Web application when they happen, so we'll modify the `Grunt.scala` file we created before:
+
+@[grunt-watch](code/runhook.sbt)
+
+Now when the application is started using `sbt run`, `grunt watch` will be executed to rerun the grunt build whenever files change.
+
+## Add compiler options
+
+For example, you may want to add the feature flag to have details on feature warnings:
+
+```
+[info] Compiling 1 Scala source to ~/target/scala-2.10/classes...
+[warn] there were 1 feature warnings; re-run with -feature for details
+```
+
+Simply add `-feature` to the `scalacOptions` attribute:
+
+@[compiler-options](code/cookbook.sbt)
+
+## Add additional asset directory
+
+For example you can add the `pictures` folder to be included as an additional asset directory:
+
+@[add-assets](code/cookbook.sbt)
+
+This will allow you to use `routes.Assets.at` with this folder.
+
+## Disable documentation
+
+To speed up compilation you can disable documentation generation:
+
+@[disable-scaladoc](code/cookbook.sbt)
+
+The first line will disable documentation generation and the second one will avoid to publish the documentation artifact.
+
+## Configure ivy logging level
+
+By default `ivyLoggingLevel` is set on `UpdateLogging.DownloadOnly`. You can change this value with:
+
+ * `UpdateLogging.Quiet` only displays errors
+ * `UpdateLogging.Full` logs the most
+
+For example if you want to only display errors:
+
+@[ivy-logging](code/cookbook.sbt)
+
+## Fork and parallel execution in test
+
+By default parallel execution is disabled and fork is enabled. You can change this behavior by setting `parallelExecution in Test` and/or `fork in Test`:
+
+@[fork-parallel-test](code/cookbook.sbt)
diff --git a/manual/detailedTopics/build/SBTDebugging.md b/manual/working/commonGuide/build/sbtDebugging.md
similarity index 50%
rename from manual/detailedTopics/build/SBTDebugging.md
rename to manual/working/commonGuide/build/sbtDebugging.md
index 9929c5cb..8d083dfc 100644
--- a/manual/detailedTopics/build/SBTDebugging.md
+++ b/manual/working/commonGuide/build/sbtDebugging.md
@@ -1,55 +1,25 @@
-
-
# Debugging your build
--->
-# ビルドをデバッグする
-
-sbt を思い通りに動かすのに手こずっているのであれば、ビルドのデバッグを支援するために sbt が提供している組み込みユーティリティをいくつか使う必要があるのかもしれません。
-
-## 依存性のデバッグ
-
-sbt はデフォルトで、どの依存性が他の依存性に取り込まれているかを示す依存性ツリー、そして複数の依存性が要求されたときに sbt がどのようにしてバージョンを選択しているかを表示するコンフリクト解決テーブルを含む、すべての依存性のレポートを生成します。
-
-このレポートは、XSL をサポートしているブラウザでは XML から HTML に変換できるようにする XSL スタイルシートを伴った XML ファイルとして生成されます。これをサポートしているブラウザには Firefox と Safari が含まれますが、注目すべきことに Chrome が含まれていません。
-
-このレポートはプロジェクトの `target/resolution-cache/reports` ディレクトリ内にプロジェクトのスコープごとに生成されており、例えば `com.example-my-first-app_2.11-compile.xml` のように `organization-projectId_scalaVersion-scope.xml` という名前が付けられています。このレポートは Firefox で開くと以下のように見えます:
+The reports can be found in the `target/scala-2.12/resolution-cache/reports/` directory of your project, one is generated for each scope in your project, and are named `organization-projectId_scalaVersion-scope.xml`, for example, `com.example-my-first-app_2.11-compile.xml`. When opened in Firefox, this report looks something like this:
[[images/ivy-report.png]]
-
-## 設定のデバッグ
-
-sbt は、ビルドを理解し、なにかおかしくなったところを解決するために使うことのできる便利なコマンドをいくつか提供しています。
-
-### show コマンド
-
-show コマンドはあらゆる sbt タスクの戻り値を表示します。例えば、あるソースファイルがコンパイルされるかどうかよく分からない場合、`show sources` を実行して sbt がそれをソースに含めているかどうか見ることができます:
```
[my-first-app] $ show sources
@@ -61,15 +31,9 @@ show コマンドはあらゆる sbt タスクの戻り値を表示します。
my-first-app/target/scala-2.11/src_managed/main/controllers/routes.java)
```
-
-上記の出力はスクリーンにぴったり収まるように整形されていますが、実行したタスクが長いリストを返す場合は、その内容を理解するためにエディタにコピーする必要があるかもしれません。
-
-例えば `test:sources` や `compile:sources` のように、タスクに特定のスコープを指定したり、`my-project/compile:sources` のように特定のプロジェクトを指定することもできます。また、あるタスクが他のタスクのスコープとなっている別の場合は、そのスコープを指定することもできます。例えばプロジェクトの jar ファイルにパッケージされるものをすべて表示するには、`packageBin` タスクをスコープとする `mappings` タスクを表示します:
```
[my-first-app] $ show compile:packageBin::mappings
@@ -79,15 +43,9 @@ You can also specify a task a particular scope, eg `test:sources` or `compile:so
...
```
-
-### inspect コマンド
-
-inspect コマンドは、タスクが何に依存しているか、何から依存されているか、どこに定義されているか、などの詳細情報を提供します。これは `show` コマンドと同じように使うことができます:
```
[my-first-app] $ inspect managedSources
@@ -105,20 +63,11 @@ inspect コマンドは、タスクが何に依存しているか、何から依
...
```
-
-ここでは `managedSources` コマンドを調査し、このタスクはファイルのシーケンスを提供すること、`Sources generated by the build` という説明文を持つことが分かります。`sourceGenerators` タスクに依存していること、`sources` タスクから依存されていることも確認できます。どこに定義されているかを確認することもできて、この場合は sbt のデフォルトタスク定義の 185 行目です。
-
-### inspect tree コマンド
-
-inspect tree コマンドは、あるタスクのタスクツリー全体を表示します。`unmanagedSources` タスクのタスクツリーを調査した場合、以下のように表示されます:
```
[my-first-app] $ inspect tree unmanagedSources
@@ -138,25 +87,13 @@ inspect tree コマンドは、あるタスクのタスクツリー全体を表
[info] +-*/*:excludeFilter = sbt.HiddenFileFilter$@49e479da
```
-
-ここでは、どのファイルを含める、あるいは除外するかを判断するフィルタを含め、プロジェクト内にあるソースを発見するために sbt が使うタスクツリー全体が表示されています。`inspect tree` コマンドは、ビルドのある部分がどのように構築されていてのかよく分からず、それらがどのように組み合わさるのかを解明したい場合に特に便利で、これによりさらに詳しく調べていくことができます。
-
-## インクリメンタルコンパイルのデバッグ
-
-人々が Play に持っている共通の問題は、期待していないときに Play が再コンパイルし、再ロードすることです。多くの場合、これはソースジェネレータまたは IDE がなんらかの事情で Play クラスパスの要素を更新し、再ロードを強制することで引き起こされます。このような問題を解決するために、compile タスクのデバッグログを見ることができます。sbt はタスクを実行すると、それを表示するしないに関わらずログ出力をすべてキャプチャするので、必要な場合は後から調査することができます。これは `last` コマンドを使って調査することができます。
-
-さて、ここで `compile` を実行して、あるファイルを再コンパイルする必要があったとしましょう:
```
[my-first-app] $ compile
@@ -164,10 +101,7 @@ So, let's say you `compile`, and a file needs to be recompiled:
[success] Total time: 1 s, completed 07/04/2015 1:28:43 PM
```
-
-`last compile` を実行すると、compile コマンドの実行中に起こったことの完全なデバッグログを取得できます。大量のダンプが出力されますが、興味があるのは以下に示す最初の部分だけです:
```
[my-first-app] $ last compile
@@ -187,7 +121,4 @@ You can get a full debug log of what happened during the compile command by runn
[debug] external source: Set()
```
-
-これは、`my-first-app/app/controllers/Application.scala` が変更されたために再コンパイルが引き起こされたことを伝えています。
\ No newline at end of file
diff --git a/manual/working/commonGuide/build/sbtDependencies.md b/manual/working/commonGuide/build/sbtDependencies.md
new file mode 100644
index 00000000..9e0b0ccb
--- /dev/null
+++ b/manual/working/commonGuide/build/sbtDependencies.md
@@ -0,0 +1,64 @@
+
+# Managing library dependencies
+
+> **Note:** Some sections of this page were copied from the sbt manual, specifically from the [Library Dependencies](https://www.scala-sbt.org/0.13/docs/Library-Dependencies.html) page. You can refer to that page for a more detailed and updated version of the information here.
+
+## Unmanaged dependencies
+
+Most people end up using managed dependencies - which allows for fine-grained control, but unmanaged dependencies can be simpler when starting out.
+
+Unmanaged dependencies work like this: create a `lib/` directory in the root of your project and then add jar files to that directory. They will automatically be added to the application classpath. There's not much else to it.
+
+There's nothing to add to `build.sbt` to use unmanaged dependencies, although you could change a configuration key if you'd like to use a directory different than `lib`.
+
+## Managed dependencies
+
+Play uses [Apache Ivy](http://ant.apache.org/ivy/) (via sbt) to implement managed dependencies, so if you're familiar with Maven or Ivy, you are already used to managed dependencies.
+
+Most of the time you can simply list your dependencies in the `build.sbt` file.
+
+Declaring a dependency looks like this (defining `group`, `artifact` and `revision`):
+
+@[single-dep](code/dependencies.sbt)
+
+Or like this, with an optional `configuration`:
+
+@[single-dep-test](code/dependencies.sbt)
+
+Multiple dependencies can be added either by multiple declarations like the above, or you can provide a Scala sequence:
+
+@[multi-deps](code/dependencies.sbt)
+
+Of course, sbt (via Ivy) has to know where to download the module. If your module is in one of the default repositories sbt comes with then this will just work.
+
+### Getting the right Scala version with `%%`
+
+If you use `groupID %% artifactID % revision` rather than `groupID % artifactID % revision` (the difference is the double `%%` after the `groupID`), sbt will add your project's Scala version to the artifact name. This is just a shortcut. You could write this without the `%%`:
+
+@[explicit-scala-version-dep](code/dependencies.sbt)
+
+Assuming the `scalaVersion` for your build is `2.11.1`, the following is identical (note the double `%%` after `"org.scala-tools"`):
+
+@[auto-scala-version-dep](code/dependencies.sbt)
+
+The idea is that many dependencies are compiled for multiple Scala versions, and you'd like to get the one that matches your project to ensure binary compatibility.
+
+### Resolvers
+
+sbt uses the standard Maven2 repository and the Typesafe Releases () repositories by default. If your dependency isn't on one of the default repositories, you'll have to add a resolver to help Ivy find it.
+
+Use the `resolvers` setting key to add your own resolver. For example:
+
+@[resolver](code/dependencies.sbt)
+
+sbt can search your local Maven repository if you add it as a repository:
+
+@[local-maven-repos](code/dependencies.sbt)
+
+## Handling conflicts between dependencies
+
+sbt has extensive documentation about how to manage conflict between your dependencies:
+
+[sbt: Dependencies Conflict Management](https://www.scala-sbt.org/0.13/docs/Library-Management.html#Conflict+Management)
+
+You can also use [sbt-dependency-graph](https://github.com/jrudolph/sbt-dependency-graph) to have a better visualization of your dependency tree. See also our page about [[debugging sbt|sbtDebugging]] common problems.
diff --git a/manual/working/commonGuide/build/sbtSettings.md b/manual/working/commonGuide/build/sbtSettings.md
new file mode 100644
index 00000000..6eb211d8
--- /dev/null
+++ b/manual/working/commonGuide/build/sbtSettings.md
@@ -0,0 +1,20 @@
+
+# About sbt Settings
+
+## About sbt settings
+
+The `build.sbt` file defines settings for your project. You can also define your own custom settings for your project, as described in the [sbt documentation](https://www.scala-sbt.org). In particular, it helps to be familiar with the [settings](https://www.scala-sbt.org/release/docs/Getting-Started/More-About-Settings) in sbt.
+
+To set a basic setting, use the `:=` operator:
+
+```scala
+confDirectory := "myConfFolder"
+```
+
+## Default settings for Java applications
+
+Play defines a default set of settings suitable for Java-based applications. To enable them add the `PlayJava` plugin via your project's enablePlugins method. These settings mostly define the default imports for generated templates e.g. importing `java.lang.*` so types like `Long` are the Java ones by default instead of the Scala ones. `play.Project.playJavaSettings` also imports `java.util.*` so that the default collection library will be the Java one.
+
+## Default settings for Scala applications
+
+Play defines a default set of settings suitable for Scala-based applications. To enable them add the `PlayScala` plugin via your project's enablePlugins method. These default settings define the default imports for generated templates (such as internationalized messages, and core APIs).
diff --git a/manual/working/commonGuide/build/sbtSubProjects.md b/manual/working/commonGuide/build/sbtSubProjects.md
new file mode 100644
index 00000000..84055358
--- /dev/null
+++ b/manual/working/commonGuide/build/sbtSubProjects.md
@@ -0,0 +1,248 @@
+
+# Working with sub-projects
+
+A complex project is not necessarily composed of a single Play application. You may want to split a large project into several smaller applications, or even extract some logic into a standard Java or Scala library that has nothing to do with a Play application.
+
+It will be helpful to read the [sbt documentation on multi-project builds](https://www.scala-sbt.org/release/docs/Getting-Started/Multi-Project). Sub-projects can be fully defined in the parent project's build file, although here we put sub-projects' settings in their own build file.
+
+## Adding a simple library sub-project
+
+You can make your application depend on a simple library project. Just add another sbt project definition in your `build.sbt` file:
+
+```
+name := "my-first-application"
+
+version := "1.0"
+
+lazy val myFirstApplication = (project in file("."))
+ .enablePlugins(PlayScala)
+ .aggregate(myLibrary)
+ .dependsOn(myLibrary)
+
+lazy val myLibrary = project
+```
+
+The lowercased `project` on the last line is a Scala Macro which will use the name of the val it is being assigned to in order to determine the project's name and folder.
+
+The `myFirstApplication` project declares the base project. If you don't have any sub projects, this is already implied, however when declaring sub projects, it's usually required to declare it so that you can ensure that it aggregates (that is, runs things like compile/test etc on the sub projects when run in the base project) and depends on (that is, adds the sub projects to the main projects classpath) the sub projects.
+
+The above example defines a sub-project in the application’s `myLibrary` folder. This sub-project is a standard sbt project, using the default layout:
+
+```
+myProject
+ └ build.sbt
+ └ app
+ └ conf
+ └ public
+ └ myLibrary
+ └ build.sbt
+ └ src
+ └ main
+ └ java
+ └ scala
+```
+
+`myLibrary` has its own `build.sbt` file, this is where it can declare its own settings, dependencies etc.
+
+When you have a sub-project enabled in your build, you can focus on this project and compile, test or run it individually. Just use the `projects` command in the Play console prompt to display all projects:
+
+```
+[my-first-application] $ projects
+[info] In file:/Volumes/Data/gbo/myFirstApp/
+[info] * my-first-application
+[info] my-library
+```
+
+The default project is the one whose variable name comes first alphabetically. You may make your main project by making its variable name aaaMain. To change the current project use the `project` command:
+
+```
+[my-first-application] $ project my-library
+[info] Set current project to my-library
+>
+```
+
+When you run your Play application in dev mode, the dependent projects are automatically recompiled, and if something cannot compile you will see the result in your browser:
+
+[[subprojectError.png]]
+
+## Sharing common variables and code
+
+If you want your sub projects and root projects to share some common settings or code, then these can be placed in a Scala file in the `project` directory of the root project. For example, in `project/Common.scala` you might have:
+
+```scala
+import sbt._
+import Keys._
+
+object Common {
+ val settings: Seq[Setting[_]] = Seq(
+ organization := "com.example",
+ version := "1.2.3-SNAPSHOT"
+ )
+
+ val fooDependency = "com.foo" %% "foo" % "2.4"
+}
+```
+
+Then in each of your `build.sbt` files, you can reference anything declared in the file:
+
+```scala
+name := "my-sub-module"
+
+Common.settings
+
+libraryDependencies += Common.fooDependency
+```
+
+One thing to note is that if you have a mix of Play and non-Play projects, you may need to share Play configuration explicitly. For example, you may want to share the `InjectedRoutesGenerator` and specs2 for every Play project:
+
+```scala
+object Common {
+
+ val playSettings = settings ++ Seq(
+ routesGenerator := InjectedRoutesGenerator,
+ libraryDependencies += specs2 % Test,
+ resolvers += "scalaz-bintray" at "https://dl.bintray.com/scalaz/releases"
+ )
+}
+```
+
+And in the sub-project's `build.sbt` file, you would have the following:
+
+```scala
+Common.playSettings
+```
+
+## Splitting your web application into several parts
+
+As a Play application is just a standard sbt project with a default configuration, it can depend on another Play application. You can make any sub module a Play application by adding the `PlayJava` or `PlayScala` plugins, depending on whether your project is a Java or Scala project, in its corresponding `build.sbt` file.
+
+> **Note:** In order to avoid naming collision, make sure your controllers, including the Assets controller in your subprojects are using a different name space than the main project. For example, controllers in the `admin` module should have the fully qualified package name of `admin.MyController`.
+
+## Splitting the route file
+
+It's also possible to split the route file into smaller pieces. This is a very handy feature if you want to create a robust, reusable multi-module play application.
+
+### Consider the following build configuration
+
+`build.sbt`:
+
+```scala
+name := "myproject"
+
+lazy val admin = (project in file("modules/admin")).enablePlugins(PlayScala)
+
+lazy val main = (project in file("."))
+ .enablePlugins(PlayScala).dependsOn(admin).aggregate(admin)
+```
+
+`modules/admin/build.sbt`
+
+```scala
+name := "myadmin"
+
+libraryDependencies ++= Seq(
+ "mysql" % "mysql-connector-java" % "5.1.41",
+ jdbc,
+ anorm
+)
+```
+
+### Project structure
+
+```
+build.sbt
+app
+ └ controllers
+ └ models
+ └ views
+conf
+ └ application.conf
+ └ routes
+modules
+ └ admin
+ └ build.sbt
+ └ conf
+ └ admin.routes
+ └ app
+ └ controllers
+ └ models
+ └ views
+project
+ └ build.properties
+ └ plugins.sbt
+```
+
+> **Note:** Configuration and route file names must be unique in the whole project structure. Particularly, there must be only one `application.conf` file and only one `routes` file. To define additional routes or configuration in sub-projects, use sub-project-specific names. For instance, the route file in `admin` is called `admin.routes`. To use a specific set of settings in development mode for a sub project, it would be even better to put these settings into the build file, e.g. `PlayKeys.devSettings += ("play.http.router", "admin.Routes")`.
+
+`conf/routes`:
+
+```
+GET /index controllers.HomeController.index()
+
+-> /admin admin.Routes
+
+GET /assets/*file controllers.Assets.at(path="/public", file)
+```
+
+`modules/admin/conf/admin.routes`:
+
+@[assets-routes](code/common.build.routes)
+
+> **Note:** Resources are served from a unique classloader, and thus resource path must be relative from project classpath root.
+> Subprojects resources are generated in `target/web/public/main/lib/{module-name}`, so the resources are accessible from `/public/lib/{module-name}` when using `play.api.Application#resources(uri)` method, which is what the `Assets.at` method does.
+
+### Assets and controller classes should be all defined in the `controllers.admin` package
+
+Java
+: @[assets-builder](code/javaguide/common/build/controllers/AssetsBuilder.java)
+
+Scala
+: @[assets-builder](code/scalaguide/common/build/controllers/SubProjectsAssetsBuilder.scala)
+
+And a controller:
+
+Java
+: @[](code/javaguide/common/build/controllers/HomeController.java)
+
+Scala
+: @[admin-home-controller](code/scalaguide/common/build/controllers/SubProjectsAssetsBuilder.scala)
+
+
+### Reverse routing in ```admin```
+
+in case of a regular controller call:
+
+
+```
+controllers.admin.routes.HomeController.index
+```
+
+and for `Assets`:
+
+```
+controllers.admin.routes.Assets.at("...")
+```
+
+### Through the browser
+
+```
+http://localhost:9000/index
+```
+
+triggers
+
+```
+controllers.HomeController.index
+```
+
+and
+
+```
+http://localhost:9000/admin/index
+```
+
+triggers
+
+```
+controllers.admin.HomeController.index
+```
diff --git a/manual/detailedTopics/build/subprojectError.png b/manual/working/commonGuide/build/subprojectError.png
similarity index 100%
rename from manual/detailedTopics/build/subprojectError.png
rename to manual/working/commonGuide/build/subprojectError.png
diff --git a/manual/working/commonGuide/configuration/ApplicationSecret.md b/manual/working/commonGuide/configuration/ApplicationSecret.md
new file mode 100644
index 00000000..7f19ecd1
--- /dev/null
+++ b/manual/working/commonGuide/configuration/ApplicationSecret.md
@@ -0,0 +1,74 @@
+
+# The Application Secret
+
+Play uses a secret key for a number of things, including:
+
+* Signing session cookies and CSRF tokens
+* Built in encryption utilities
+
+It is configured in `application.conf`, with the property name `play.http.secret.key`, and defaults to `changeme`. As the default suggests, it should be changed for production.
+
+> When started in prod mode, if Play finds that the secret is not set, or if it is set to `changeme`, Play will throw an error.
+
+## Best practices
+
+Anyone that can get access to the secret will be able to generate any session they please, effectively allowing them to log in to your system as any user they please. Hence it is strongly recommended that you do not check your application secret into source control. Rather, it should be configured on your production server. This means that it is considered bad practice to put the production application secret in `application.conf`.
+
+One way of configuring the application secret on a production server is to pass it as a system property to your start script. For example:
+
+```bash
+/path/to/yourapp/bin/yourapp -Dplay.http.secret.key='QCY?tAnfk?aZ?iwrNwnxIlR6CTf:G3gf:90Latabg@5241AB`R5W:1uDFN];Ik@n'
+```
+
+This approach is very simple, and we will use this approach in the Play documentation on running your app in production mode as a reminder that the application secret needs to be set. In some environments however, placing secrets in command line arguments is not considered good practice. There are two ways to address this.
+
+### Environment variables
+
+The first is to place the application secret in an environment variable. In this case, we recommend you place the following configuration in your `application.conf` file:
+
+ play.http.secret.key="changeme"
+ play.http.secret.key=${?APPLICATION_SECRET}
+
+The second line in that configuration sets the secret to come from an environment variable called `APPLICATION_SECRET` if such an environment variable is set, otherwise, it leaves the secret unchanged from the previous line.
+
+This approach works particularly well for cloud based deployment scenarios, where the normal practice is to set passwords and other secrets via environment variables that can be configured through the API for that cloud provider.
+
+### Production configuration file
+
+Another approach is to create a `production.conf` file that lives on the server, and includes `application.conf`, but also overrides any sensitive configuration, such as the application secret and passwords.
+
+For example:
+
+ include "application"
+
+ play.http.secret.key="QCY?tAnfk?aZ?iwrNwnxIlR6CTf:G3gf:90Latabg@5241AB`R5W:1uDFN];Ik@n"
+
+Then you can start Play with:
+
+```bash
+/path/to/yourapp/bin/yourapp -Dconfig.file=/path/to/production.conf
+```
+
+## Generating an application secret
+
+Play provides a utility that you can use to generate a new secret. Run `playGenerateSecret` in the Play console. This will generate a new secret that you can use in your application. For example:
+
+```
+[my-first-app] $ playGenerateSecret
+[info] Generated new secret: QCYtAnfkaZiwrNwnxIlR6CTfG3gf90Latabg5241ABR5W1uDFNIkn
+[success] Total time: 0 s, completed 28/03/2014 2:26:09 PM
+```
+
+## Updating the application secret in application.conf
+
+Play also provides a convenient utility for updating the secret in `application.conf`, should you want to have a particular secret configured for development or test servers. This is often useful when you have encrypted data using the application secret, and you want to ensure that the same secret is used every time the application is run in dev mode.
+
+To update the secret in `application.conf`, run `playUpdateSecret` in the Play console:
+
+```
+[my-first-app] $ playUpdateSecret
+[info] Generated new secret: B4FvQWnTp718vr6AHyvdGlrHBGNcvuM4y3jUeRCgXxIwBZIbt
+[info] Updating application secret in /Users/jroper/tmp/my-first-app/conf/application.conf
+[info] Replacing old application secret: play.http.secret.key="changeme"
+[success] Total time: 0 s, completed 28/03/2014 2:36:54 PM
+```
diff --git a/manual/working/commonGuide/configuration/ConfigFile.md b/manual/working/commonGuide/configuration/ConfigFile.md
new file mode 100644
index 00000000..62be519c
--- /dev/null
+++ b/manual/working/commonGuide/configuration/ConfigFile.md
@@ -0,0 +1,430 @@
+
+# Configuration file syntax and features
+
+> The configuration file used by Play is based on the [Typesafe config library](https://github.com/typesafehub/config).
+
+The configuration file of a Play application must be defined in `conf/application.conf`. It uses the [HOCON format](https://github.com/typesafehub/config/blob/master/HOCON.md).
+
+As well as the `application.conf` file, configuration comes from a couple of other places.
+
+* Default settings are loaded from any `reference.conf` files found on the classpath. Most Play JARs include a `reference.conf` file with default settings. Settings in `application.conf` will override settings in `reference.conf` files.
+* It's also possible to set configuration using system properties. System properties override `application.conf` settings.
+
+The idiomatic way to use Config is to to have all configuration keys defined somewhere, either in `reference.conf` or `application.conf`. If the key does not have a reasonable default value, it is usually set to `null` to signify "no value".
+
+## Specifying an alternative configuration file
+
+At runtime, the default `application.conf` is loaded from the classpath. System properties can be used to force a different config source:
+
+* `config.resource` specifies a resource name including the extension, i.e. `application.conf` and not just `application`
+* `config.file` specifies a filesystem path, again it should include the extension, not be a basename
+
+These system properties specify a replacement for `application.conf`, not an addition. If you still want to use some values from the `application.conf` file then you can include the `application.conf` in your other `.conf` file by writing `include "application"` at the top of that file. After you've included the `application.conf`'s settings in your new `.conf` file you can then specify any settings that you want override.
+
+## Using from your controller
+
+The configuration can be available in your controller (or your component), to use the default settings or your custom one, thanks to Dependency Injection (in [[Scala|ScalaDependencyInjection]] or in [[Java|JavaDependencyInjection]]).
+
+Scala
+: @[dependency-injection](code/Configuration.scala)
+
+Java
+: @[dependency-injection](code/javaguide/configuration/MyController.java)
+
+## Using with Akka
+
+Akka will use the same configuration file as the one defined for your Play application. Meaning that you can configure anything in Akka in the `application.conf` file. In Play, Akka reads its settings from within the `play.akka` setting, not from the `akka` setting.
+
+## Using with the `run` command
+
+There are a couple of special things to know about configuration when running your application with the `run` command.
+
+### Extra `devSettings`
+
+You can configure extra settings for the `run` command in your `build.sbt`. These settings won't be used when you deploy your application.
+
+```
+PlayKeys.devSettings += "play.server.http.port" -> "8080"
+```
+
+### HTTP server settings in `application.conf`
+
+In `run` mode the HTTP server part of Play starts before the application has been compiled. This means that the HTTP server cannot access the `application.conf` file when it starts. If you want to override HTTP server settings while using the `run` command you cannot use the `application.conf` file. Instead, you need to either use system properties or the `devSettings` setting shown above. An example of a server setting is the HTTP port. Other server settings can be seen [[here|ProductionConfiguration#Server-configuration-options]].
+
+```
+> run -Dhttp.port=1234
+```
+
+There is also a specific *namespace* if you need to customize Akka configuration for development mode (the mode used with `run` command). You need to prefix your configuration in `PlayKeys.devSettings` with `play.akka.dev-mode`, for example:
+
+@[prefix-with-play-akka-dev-mode](code/build.sbt)
+
+This is specially useful if there is some conflict between the Akka ActorSystem used to run the development server and the ActorSystem used by the application itself.
+
+## HOCON Syntax
+
+HOCON has similarities to JSON; you can find the JSON spec at
+ ${application.home:-.}/logs/application.log
+
+ %date [%level] from %logger in %thread - %message%n%xException
+
+
+```
+
+Optionally use the async appender to wrap the `FileAppender`:
+```xml
+
+
+```
+
+Add the necessary appender(s) to the root:
+```xml
+
+
+```
+
+## Security Logging
+
+A security marker has been added for security related operations in Play, and failed security checks now log at WARN level, with the security marker set. This ensures that developers always know why a particular request is failing, which is important now that security filters are enabled by default in Play.
+
+The security marker also allows security failures to be triggered or filtered distinct from normal logging. For example, to disable all logging with the SECURITY marker set, add the following lines to the `logback.xml` file:
+
+```xml
+
+ SECURITY
+ DENY
+
+```
+
+In addition, log events using the security marker can also trigger a message to a Security Information & Event Management (SEIM) engine for further processing.
+
+## Using a custom application loader
+
+Note that when using a custom application loader that does not extend the default `GuiceApplicationLoader` (for example when using [[compile-time dependency injection|ScalaCompileTimeDependencyInjection]]), the `LoggerConfigurator` needs to be manually invoked to pick up your custom configuration. You can do this with code like the following:
+
+@[basicextended](../../scalaGuide/main/dependencyinjection/code/CompileTimeDependencyInjection.scala)
+
+## Custom configuration
+
+For any custom configuration, you will need to specify your own Logback configuration file.
+
+### Using a configuration file from project source
+
+You can provide a default logging configuration by providing a file `conf/logback.xml`.
+
+### Using an external configuration file
+
+You can also specify a configuration file via a System property. This is particularly useful for production environments where the configuration file may be managed outside of your application source.
+
+> **Note**: The logging system gives top preference to configuration files specified by system properties, secondly to files in the `conf` directory, and lastly to the default. This allows you to customize your application's logging configuration and still override it for specific environments or developer setups.
+
+#### Using `-Dlogger.resource`
+
+Specify a configuration file to be loaded from the classpath:
+
+```
+$ start -Dlogger.resource=prod-logger.xml
+```
+
+#### Using `-Dlogger.file`
+
+Specify a configuration file to be loaded from the file system:
+
+```
+$ start -Dlogger.file=/opt/prod/logger.xml
+```
+
+> **Note**: To see which file is being used, you can set a system property to debug it: `-Dlogback.debug=true`.
+
+### Examples
+
+Here's an example of configuration that uses a rolling file appender, as well as a separate appender for outputting an access log:
+
+```xml
+
+
+
+ ${application.home:-.}/logs/application.log
+
+
+ ${application.home:-.}/logs/application-log-%d{yyyy-MM-dd}.gz
+
+ 30
+
+
+ %date{yyyy-MM-dd HH:mm:ss ZZZZ} [%level] from %logger in %thread - %message%n%xException
+
+
+
+
+
+
+ SECURITY
+
+ DENY
+ ACCEPT
+
+ ${application.home:-.}/logs/security.log
+
+ %date [%level] [%marker] from %logger in %thread - %message%n%xException
+
+
+
+
+ ${application.home:-.}/logs/access.log
+
+
+ ${application.home:-.}/logs/access-log-%d{yyyy-MM-dd}.gz
+
+ 7
+
+
+ %date{yyyy-MM-dd HH:mm:ss ZZZZ} %message%n
+
+ false
+
+
+
+
+
+
+
+
+
+
+
+```
+
+This demonstrates a few useful features:
+
+- It uses `RollingFileAppender` which can help manage growing log files. See more [details here](https://logback.qos.ch/manual/appenders.html#SizeAndTimeBasedRollingPolicy).
+- It writes log files to a directory external to the application so they will not affected by upgrades, etc.
+- The `FILE` appender uses an expanded message format that can be parsed by third party log analytics providers such as Sumo Logic.
+- The `access` logger is routed to a separate log file using the `ACCESS_FILE` appender.
+- Any log messages sent with the "SECURITY" marker attached are logged to the `security.log` file using the [EvaluatorFilter](https://logback.qos.ch/manual/filters.html#evalutatorFilter) and the [OnMarkerEvaluator](https://logback.qos.ch/manual/appenders.html#OnMarkerEvaluator).
+- All loggers are set to a threshold of `INFO` which is a common choice for production logging.
+
+> **Note**: the `file` tag is optional and you can omit it if you want to avoid file renaming. See [Logback docs](https://logback.qos.ch/codes.html#renamingError) for more information.
+
+## Including Properties
+
+By default, only the property `application.home` is exported to the logging framework, meaning that files can be referenced relative to the Play application:
+
+```
+ ${application.home:-}/example.log
+```
+
+If you want to reference properties that are defined in the `application.conf` file, you can add `play.logger.includeConfigProperties=true` to your application.conf file. When the application starts, all properties defined in configuration will be available to the logger:
+
+```
+
+
+ context = ${my.property.defined.in.application.conf} %message%n
+
+
+```
+
+## Akka logging configuration
+
+Akka system logging can be done by changing the `akka` logger to INFO.
+
+```xml
+
+
+
+
+```
+
+> **NOTE**: `play.ws.cache.cacheManagerURI` is deprecated, use `play.ws.cache.cacheManagerResource` with a path on the classpath instead.
+
+## Debugging the Cache
+
+To see exactly what the HTTP caching layer in Play WS is doing, please add the following to `logback.xml`:
+
+```
+"
+```
+
+## Reference Configuration
+
+The reference configuration shows the default settings for Play WS Caching:
+
+@[](/confs/play-ahc-ws/reference.conf)
diff --git a/manual/working/commonGuide/configuration/WsSSL.md b/manual/working/commonGuide/configuration/WsSSL.md
new file mode 100644
index 00000000..0c2c3772
--- /dev/null
+++ b/manual/working/commonGuide/configuration/WsSSL.md
@@ -0,0 +1,44 @@
+
+# Configuring WS SSL
+
+[[Play WS|ScalaWS]] allows you to set up HTTPS completely from a configuration file, without the need to write code. It does this by layering the Java Secure Socket Extension (JSSE) with a configuration layer and with reasonable defaults.
+
+JDK 1.8 contains an implementation of JSSE which is [significantly more advanced](https://docs.oracle.com/javase/8/docs/technotes/guides/security/enhancements-8.html) than previous versions, and should be used if security is a priority.
+
+> **NOTE**: It is highly recommended (if not required) to use WS SSL with the
+unlimited strength java cryptography extension. You can download the policy files from Oracle's website at [Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files 8 Download](https://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html).
+
+## Table of Contents
+
+The Play WS configuration is based on [Typesafe SSLConfig](https://lightbend.github.io/ssl-config).
+
+For convenience, a table of contents to SSLConfig is provided:
+
+- [Quick Start to WS SSL](https://lightbend.github.io/ssl-config/WSQuickStart.html)
+- [Generating X.509 Certificates](https://lightbend.github.io/ssl-config/CertificateGeneration.html)
+- [Configuring Trust Stores and Key Stores](https://lightbend.github.io/ssl-config/KeyStores.html)
+- [Configuring Protocols](https://lightbend.github.io/ssl-config/Protocols.html)
+- [Configuring Cipher Suites](https://lightbend.github.io/ssl-config/CipherSuites.html)
+- [Configuring Certificate Validation](https://lightbend.github.io/ssl-config/CertificateValidation.html)
+- [Configuring Certificate Revocation](https://lightbend.github.io/ssl-config/CertificateRevocation.html)
+- [Configuring Hostname Verification](https://lightbend.github.io/ssl-config/HostnameVerification.html)
+- [Example Configurations](https://lightbend.github.io/ssl-config/ExampleSSLConfig.html)
+- [Using the Default SSLContext](https://lightbend.github.io/ssl-config/DefaultContext.html)
+- [Debugging SSL Connections](https://lightbend.github.io/ssl-config/DebuggingSSL.html)
+- [Loose Options](https://lightbend.github.io/ssl-config/LooseSSL.html)
+- [Testing SSL](https://lightbend.github.io/ssl-config/TestingSSL.html)
+
+> **NOTE**: The links below are relative to `Typesafe SSLConfig`, which uses the `ssl-config` as a prefix for ssl properties.
+> Play uses the `play.ws.ssl` prefix, so that, for instance the `ssl-config.loose.acceptAnyCertificate` becomes `play.ws.ssl.loose.acceptAnyCertificate` for your play `WSClient` configuration.
+
+## Further Reading
+
+JSSE is a complex product. For convenience, the JSSE materials are provided here:
+
+JDK 1.8:
+
+* [JSSE Reference Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html)
+* [JSSE Crypto Spec](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html#SSLTLS)
+* [SunJSSE Providers](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider)
+* [PKI Programmer's Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/certpath/CertPathProgGuide.html)
+* [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html)
diff --git a/manual/working/commonGuide/configuration/code/Configuration.scala b/manual/working/commonGuide/configuration/code/Configuration.scala
new file mode 100644
index 00000000..86ce74a7
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/Configuration.scala
@@ -0,0 +1,15 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+// With Play Scala
+
+object DependencyInjection {
+ //#dependency-injection
+ import javax.inject._
+ import play.api.Configuration
+
+ class MyController @Inject()(config: Configuration) {
+ // ...
+ }
+ //#dependency-injection
+}
diff --git a/manual/working/commonGuide/configuration/code/CustomAkkaHttpServer.scala b/manual/working/commonGuide/configuration/code/CustomAkkaHttpServer.scala
new file mode 100644
index 00000000..e23aa195
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/CustomAkkaHttpServer.scala
@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+//#custom-akka-http-server
+//###replace: package server
+package detailedtopics.configuration.customakkaserver
+
+import java.util.Random
+import play.core.server.AkkaHttpServer
+import play.core.server.AkkaHttpServerProvider
+import play.core.server.ServerProvider
+import akka.http.scaladsl.ConnectionContext
+import akka.http.scaladsl.model.HttpMethod
+import akka.http.scaladsl.settings.ParserSettings
+import akka.http.scaladsl.settings.ServerSettings
+
+/** A custom Akka HTTP server with advanced configuration. */
+class CustomAkkaHttpServer(context: AkkaHttpServer.Context) extends AkkaHttpServer(context) {
+ protected override def createParserSettings(): ParserSettings = {
+ val defaultSettings: ParserSettings =
+ super.createParserSettings()
+ defaultSettings.withCustomMethods(HttpMethod.custom("TICKLE"))
+ }
+ protected override def createServerSettings(
+ port: Int,
+ connectionContext: ConnectionContext,
+ secure: Boolean
+ ): ServerSettings = {
+ val defaultSettings: ServerSettings =
+ super.createServerSettings(port, connectionContext, secure)
+ defaultSettings.withWebsocketRandomFactory(() => new Random())
+ }
+}
+
+/** A factory that instantiates a CustomAkkaHttpServer. */
+class CustomAkkaHttpServerProvider extends ServerProvider {
+ def createServer(context: ServerProvider.Context) = {
+ val serverContext = AkkaHttpServer.Context.fromServerProviderContext(context)
+ new CustomAkkaHttpServer(serverContext)
+ }
+}
+//#custom-akka-http-server
diff --git a/manual/working/commonGuide/configuration/code/JavaLog4JLoggerConfigurator.java b/manual/working/commonGuide/configuration/code/JavaLog4JLoggerConfigurator.java
new file mode 100644
index 00000000..7d734b45
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/JavaLog4JLoggerConfigurator.java
@@ -0,0 +1,87 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+// #log4j2-class
+import com.typesafe.config.Config;
+import com.typesafe.config.ConfigFactory;
+import org.slf4j.ILoggerFactory;
+import play.Environment;
+import play.LoggerConfigurator;
+import play.Mode;
+import play.api.PlayException;
+
+import java.io.File;
+import java.net.URISyntaxException;
+import java.net.URL;
+import java.util.Collections;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Optional;
+
+// ###skip: 1
+/*
+import org.apache.logging.log4j.LogManager;
+import org.apache.logging.log4j.core.*;
+import org.apache.logging.log4j.core.config.Configurator;
+//###skip: 1
+*/
+
+public class JavaLog4JLoggerConfigurator implements LoggerConfigurator {
+
+ private ILoggerFactory factory;
+
+ @Override
+ public void init(File rootPath, Mode mode) {
+ Map properties = new HashMap<>();
+ properties.put("application.home", rootPath.getAbsolutePath());
+
+ String resourceName = "log4j2.xml";
+ URL resourceUrl = this.getClass().getClassLoader().getResource(resourceName);
+ configure(properties, Optional.ofNullable(resourceUrl));
+ }
+
+ @Override
+ public void configure(Environment env) {
+ Map properties =
+ LoggerConfigurator.generateProperties(env, ConfigFactory.empty(), Collections.emptyMap());
+ URL resourceUrl = env.resource("log4j2.xml");
+ configure(properties, Optional.ofNullable(resourceUrl));
+ }
+
+ @Override
+ public void configure(
+ Environment env, Config configuration, Map optionalProperties) {
+ // LoggerConfigurator.generateProperties enables play.logger.includeConfigProperties=true
+ Map properties =
+ LoggerConfigurator.generateProperties(env, configuration, optionalProperties);
+ URL resourceUrl = env.resource("log4j2.xml");
+ configure(properties, Optional.ofNullable(resourceUrl));
+ }
+
+ @Override
+ public void configure(Map properties, Optional config) {
+ try {
+ LoggerContext loggerContext = (LoggerContext) LogManager.getContext(false);
+ loggerContext.setConfigLocation(config.get().toURI());
+
+ factory = org.slf4j.impl.StaticLoggerBinder.getSingleton().getLoggerFactory();
+ } catch (URISyntaxException ex) {
+ throw new PlayException(
+ "log4j2.xml resource was not found",
+ "Could not parse the location for log4j2.xml resource",
+ ex);
+ }
+ }
+
+ @Override
+ public ILoggerFactory loggerFactory() {
+ return factory;
+ }
+
+ @Override
+ public void shutdown() {
+ LoggerContext loggerContext = (LoggerContext) LogManager.getContext();
+ Configurator.shutdown(loggerContext);
+ }
+}
+// #log4j2-class
diff --git a/manual/working/commonGuide/configuration/code/Log4j2LoggerConfigurator.scala b/manual/working/commonGuide/configuration/code/Log4j2LoggerConfigurator.scala
new file mode 100644
index 00000000..5cd83189
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/Log4j2LoggerConfigurator.scala
@@ -0,0 +1,86 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+//#log4j2-class
+import java.io.File
+import java.net.URI
+import java.net.URL
+
+//###skip: 1
+/*
+import play.api.{Mode, Configuration, Environment, LoggerConfigurator}
+
+import org.slf4j.ILoggerFactory
+
+import org.apache.logging.log4j.LogManager
+import org.apache.logging.log4j.core._
+import org.apache.logging.log4j.core.config.Configurator
+//###skip: 1
+ */
+
+import play.api.Mode
+import play.api.Configuration
+import play.api.Environment
+import play.api.LoggerConfigurator
+import org.slf4j.ILoggerFactory
+
+class Log4J2LoggerConfigurator extends LoggerConfigurator {
+
+ private var factory: ILoggerFactory = _
+
+ override def init(rootPath: File, mode: Mode): Unit = {
+ val properties = Map("application.home" -> rootPath.getAbsolutePath)
+ val resourceName = "log4j2.xml"
+ val resourceUrl = Option(this.getClass.getClassLoader.getResource(resourceName))
+ configure(properties, resourceUrl)
+ }
+
+ override def shutdown(): Unit = {
+ val context = LogManager.getContext().asInstanceOf[LoggerContext]
+ Configurator.shutdown(context)
+ }
+
+ override def configure(env: Environment): Unit = {
+ val properties = LoggerConfigurator.generateProperties(env, Configuration.empty, Map.empty)
+ val resourceUrl = env.resource("log4j2.xml")
+ configure(properties, resourceUrl)
+ }
+
+ override def configure(
+ env: Environment,
+ configuration: Configuration,
+ optionalProperties: Map[String, String]
+ ): Unit = {
+ // LoggerConfigurator.generateProperties enables play.logger.includeConfigProperties=true
+ val properties = LoggerConfigurator.generateProperties(env, configuration, optionalProperties)
+ val resourceUrl = env.resource("log4j2.xml")
+ configure(properties, resourceUrl)
+ }
+
+ override def configure(properties: Map[String, String], config: Option[URL]): Unit = {
+ val context = LogManager.getContext(false).asInstanceOf[LoggerContext]
+ context.setConfigLocation(config.get.toURI)
+
+ factory = org.slf4j.impl.StaticLoggerBinder.getSingleton.getLoggerFactory
+ }
+
+ override def loggerFactory: ILoggerFactory = factory
+}
+//#log4j2-class
+
+object Configurator {
+ def shutdown(context: Any): Unit = ???
+
+}
+
+object LogManager {
+ def getContext(): LoggerContext = ???
+
+ def getContext(b: Boolean): LoggerContext = ???
+
+}
+
+class LoggerContext {
+ def setConfigLocation(toURI: URI): Unit = ???
+
+}
diff --git a/manual/working/commonGuide/configuration/code/ThreadPools.scala b/manual/working/commonGuide/configuration/code/ThreadPools.scala
new file mode 100644
index 00000000..224297eb
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/ThreadPools.scala
@@ -0,0 +1,231 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package detailedtopics.configuration.threadpools
+
+import javax.inject.Inject
+
+import play.api.mvc._
+import play.api.test._
+import play.api._
+import com.typesafe.config.ConfigFactory
+import akka.actor.ActorSystem
+
+import scala.concurrent.ExecutionContext
+import scala.concurrent.Future
+import scala.concurrent.TimeoutException
+
+import org.specs2.execute.AsResult
+
+class ThreadPoolsSpec extends PlaySpecification {
+
+ "Play's thread pools" should {
+
+ "make a global thread pool available" in new WithApplication() {
+ val controller = app.injector.instanceOf[Samples]
+ contentAsString(controller.someAsyncAction(FakeRequest())) must startWith("The answer is 42")
+ }
+
+ "have a global configuration" in {
+ val config = """#default-config
+ akka {
+ actor {
+ default-dispatcher {
+ fork-join-executor {
+ # Settings this to 1 instead of 3 seems to improve performance.
+ parallelism-factor = 1.0
+
+ # @richdougherty: Not sure why this is set below the Akka
+ # default.
+ parallelism-max = 24
+
+ # Setting this to LIFO changes the fork-join-executor
+ # to use a stack discipline for task scheduling. This usually
+ # improves throughput at the cost of possibly increasing
+ # latency and risking task starvation (which should be rare).
+ task-peeking-mode = LIFO
+ }
+ }
+ }
+ }
+ #default-config """
+ val parsed = ConfigFactory.parseString(config)
+ val actorSystem = ActorSystem("test", parsed.getConfig("akka"))
+ actorSystem.terminate()
+ success
+ }
+
+ "use akka default thread pool configuration" in {
+ val config = """#akka-default-config
+ akka {
+ actor {
+ default-dispatcher {
+ # This will be used if you have set "executor = "fork-join-executor""
+ fork-join-executor {
+ # Min number of threads to cap factor-based parallelism number to
+ parallelism-min = 8
+
+ # The parallelism factor is used to determine thread pool size using the
+ # following formula: ceil(available processors * factor). Resulting size
+ # is then bounded by the parallelism-min and parallelism-max values.
+ parallelism-factor = 3.0
+
+ # Max number of threads to cap factor-based parallelism number to
+ parallelism-max = 64
+
+ # Setting to "FIFO" to use queue like peeking mode which "poll" or "LIFO" to use stack
+ # like peeking mode which "pop".
+ task-peeking-mode = "FIFO"
+ }
+ }
+ }
+ }
+ #akka-default-config """
+ val parsed = ConfigFactory.parseString(config)
+ val actorSystem = ActorSystem("test", parsed.getConfig("akka"))
+ actorSystem.terminate()
+ success
+ }
+
+ "allow configuring a custom thread pool" in runningWithConfig(
+ """#my-context-config
+ my-context {
+ fork-join-executor {
+ parallelism-factor = 20.0
+ parallelism-max = 200
+ }
+ }
+ #my-context-config """
+ ) { implicit app =>
+ val akkaSystem = app.actorSystem
+ //#my-context-usage
+ val myExecutionContext: ExecutionContext = akkaSystem.dispatchers.lookup("my-context")
+ //#my-context-usage
+ await(Future(Thread.currentThread().getName)(myExecutionContext)) must startWith("application-my-context")
+
+ //#my-context-explicit
+ Future {
+ // Some blocking or expensive code here
+ }(myExecutionContext)
+ //#my-context-explicit
+
+ {
+ //#my-context-implicit
+ implicit val ec = myExecutionContext
+
+ Future {
+ // Some blocking or expensive code here
+ }
+ //#my-context-implicit
+ }
+ success
+ }
+
+ "allow access to the application classloader" in new WithApplication() {
+ val myClassName = "java.lang.String"
+ //#using-app-classloader
+ val myClass = app.classloader.loadClass(myClassName)
+ //#using-app-classloader
+ }
+
+ "allow a synchronous thread pool" in {
+ val config =
+ ConfigFactory.parseString("""#highly-synchronous
+ akka {
+ actor {
+ default-dispatcher {
+ executor = "thread-pool-executor"
+ throughput = 1
+ thread-pool-executor {
+ fixed-pool-size = 55 # db conn pool (50) + number of cores (4) + housekeeping (1)
+ }
+ }
+ }
+ }
+ #highly-synchronous """)
+
+ val actorSystem = ActorSystem("test", config.getConfig("akka"))
+ actorSystem.terminate()
+ success
+ }
+
+ "allow configuring many custom thread pools" in runningWithConfig(
+ """ #many-specific-config
+ contexts {
+ simple-db-lookups {
+ executor = "thread-pool-executor"
+ throughput = 1
+ thread-pool-executor {
+ fixed-pool-size = 20
+ }
+ }
+ expensive-db-lookups {
+ executor = "thread-pool-executor"
+ throughput = 1
+ thread-pool-executor {
+ fixed-pool-size = 20
+ }
+ }
+ db-write-operations {
+ executor = "thread-pool-executor"
+ throughput = 1
+ thread-pool-executor {
+ fixed-pool-size = 10
+ }
+ }
+ expensive-cpu-operations {
+ fork-join-executor {
+ parallelism-max = 2
+ }
+ }
+ }
+ #many-specific-config """
+ ) { implicit app =>
+ val akkaSystem = app.actorSystem
+ //#many-specific-contexts
+ object Contexts {
+ implicit val simpleDbLookups: ExecutionContext = akkaSystem.dispatchers.lookup("contexts.simple-db-lookups")
+ implicit val expensiveDbLookups: ExecutionContext =
+ akkaSystem.dispatchers.lookup("contexts.expensive-db-lookups")
+ implicit val dbWriteOperations: ExecutionContext = akkaSystem.dispatchers.lookup("contexts.db-write-operations")
+ implicit val expensiveCpuOperations: ExecutionContext =
+ akkaSystem.dispatchers.lookup("contexts.expensive-cpu-operations")
+ }
+ //#many-specific-contexts
+ def test(context: ExecutionContext, name: String) = {
+ await(Future(Thread.currentThread().getName)(context)) must startWith("application-contexts." + name)
+ }
+ test(Contexts.simpleDbLookups, "simple-db-lookups")
+ test(Contexts.expensiveDbLookups, "expensive-db-lookups")
+ test(Contexts.dbWriteOperations, "db-write-operations")
+ test(Contexts.expensiveCpuOperations, "expensive-cpu-operations")
+ }
+
+ }
+
+ def runningWithConfig[T: AsResult](config: String)(block: Application => T) = {
+ val parsed: java.util.Map[String, Object] = ConfigFactory.parseString(config).root.unwrapped
+ running(_.configure(Configuration(ConfigFactory.parseString(config))))(block)
+ }
+}
+
+// since specs provides defaultContext, implicitly importing it doesn't work
+//#global-thread-pool
+class Samples @Inject()(components: ControllerComponents)(implicit ec: ExecutionContext)
+ extends AbstractController(components) {
+ def someAsyncAction = Action.async {
+ someCalculation()
+ .map { result =>
+ Ok(s"The answer is $result")
+ }
+ .recover {
+ case e: TimeoutException =>
+ InternalServerError("Calculation timed out!")
+ }
+ }
+
+ def someCalculation(): Future[Int] = {
+ Future.successful(42)
+ }
+}
+//#global-thread-pool
diff --git a/manual/working/commonGuide/configuration/code/application.conf b/manual/working/commonGuide/configuration/code/application.conf
new file mode 100644
index 00000000..2439072b
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/application.conf
@@ -0,0 +1,4 @@
+//#custom-akka-http-server-provider
+//###replace: play.server.provider = server.CustomAkkaHttpServerProvider
+#play.server.provider = server.CustomAkkaHttpServerProvider
+//#custom-akka-http-server-provider
diff --git a/manual/working/commonGuide/configuration/code/build.sbt b/manual/working/commonGuide/configuration/code/build.sbt
new file mode 100644
index 00000000..44afbec5
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/build.sbt
@@ -0,0 +1,12 @@
+//#play-ws-cache-deps
+libraryDependencies += ws
+libraryDependencies += ehcache
+//#play-ws-cache-deps
+
+//#prefix-with-play-akka-dev-mode
+PlayKeys.devSettings += "play.akka.dev-mode.akka.cluster.log-info" -> "off"
+//#prefix-with-play-akka-dev-mode
+
+//#custom-akka-http-server-provider
+PlayKeys.devSettings += "play.server.provider" -> "server.CustomAkkaHttpServerProvider"
+//#custom-akka-http-server-provider
diff --git a/manual/working/commonGuide/configuration/code/detailedtopics/ThreadPoolsJava.java b/manual/working/commonGuide/configuration/code/detailedtopics/ThreadPoolsJava.java
new file mode 100644
index 00000000..affad01d
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/detailedtopics/ThreadPoolsJava.java
@@ -0,0 +1,32 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package detailedtopics;
+
+import org.junit.Test;
+import play.Application;
+
+import static org.hamcrest.CoreMatchers.*;
+import static org.junit.Assert.*;
+import static play.test.Helpers.*;
+
+public class ThreadPoolsJava {
+
+ @Test
+ public void usingAppClassLoader() throws Exception {
+ final Application app = fakeApplication();
+ running(
+ app,
+ () -> {
+ String myClassName = "java.lang.String";
+ try {
+ // #using-app-classloader
+ Class myClass = app.classloader().loadClass(myClassName);
+ // #using-app-classloader
+ assertThat(myClass, notNullValue());
+ } catch (ClassNotFoundException e) {
+ throw new RuntimeException(e);
+ }
+ });
+ }
+}
diff --git a/manual/working/commonGuide/configuration/code/detailedtopics/httpec/MyController.java b/manual/working/commonGuide/configuration/code/detailedtopics/httpec/MyController.java
new file mode 100644
index 00000000..457d7dd6
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/detailedtopics/httpec/MyController.java
@@ -0,0 +1,39 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package detailedtopics.httpec;
+
+// #http-execution-context
+import play.libs.concurrent.HttpExecutionContext;
+import play.mvc.*;
+
+import javax.inject.Inject;
+import java.util.concurrent.CompletableFuture;
+import java.util.concurrent.CompletionStage;
+
+public class MyController extends Controller {
+
+ private HttpExecutionContext httpExecutionContext;
+
+ @Inject
+ public MyController(HttpExecutionContext ec) {
+ this.httpExecutionContext = ec;
+ }
+
+ public CompletionStage index() {
+ // Use a different task with explicit EC
+ return calculateResponse()
+ .thenApplyAsync(
+ answer -> {
+ // uses Http.Context
+ ctx().flash().put("info", "Response updated!");
+ return ok("answer was " + answer);
+ },
+ httpExecutionContext.current());
+ }
+
+ private static CompletionStage calculateResponse() {
+ return CompletableFuture.completedFuture("42");
+ }
+}
+// #http-execution-context
diff --git a/manual/working/commonGuide/configuration/code/javaguide/configuration/MyController.java b/manual/working/commonGuide/configuration/code/javaguide/configuration/MyController.java
new file mode 100644
index 00000000..48b532e9
--- /dev/null
+++ b/manual/working/commonGuide/configuration/code/javaguide/configuration/MyController.java
@@ -0,0 +1,22 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+// #dependency-injection
+// ###replace: package controllers
+package javaguide.configuration;
+
+import com.typesafe.config.Config;
+import play.mvc.Controller;
+
+import javax.inject.Inject;
+
+public class MyController extends Controller {
+
+ private final Config config;
+
+ @Inject
+ public MyController(Config config) {
+ this.config = config;
+ }
+}
+// #dependency-injection
diff --git a/manual/working/commonGuide/configuration/index.toc b/manual/working/commonGuide/configuration/index.toc
new file mode 100644
index 00000000..79ea380e
--- /dev/null
+++ b/manual/working/commonGuide/configuration/index.toc
@@ -0,0 +1,11 @@
+Configuration:Configuration
+ConfigFile:Configuration file syntax and features
+ApplicationSecret:Configuring the application secret
+SettingsSession:Configuring the session cookie
+SettingsJDBC:Configuring the JDBC connection pool
+ThreadPools:Configuring Play's thread pools
+SettingsAkkaHttp:Configuring Akka Http Server Backend
+SettingsNetty:Configuring Netty Server Backend
+SettingsLogger:Configuring logging
+WsSSL:Configuring WS SSL
+WsCache:Configuring WS Cache
\ No newline at end of file
diff --git a/manual/working/commonGuide/database/Databases.md b/manual/working/commonGuide/database/Databases.md
new file mode 100644
index 00000000..ac18893f
--- /dev/null
+++ b/manual/working/commonGuide/database/Databases.md
@@ -0,0 +1,7 @@
+
+# Databases
+
+This section covers a some topics related to working with databases in Play. There is language-specific documentation about working with databases in the [[Java|JavaDatabase]] and [[Scala|ScalaDatabase]] guides.
+
+- [[Using an in memory H2 database|Developing-with-the-H2-Database]]
+- [[Managing database evolutions|Evolutions]]
diff --git a/manual/detailedTopics/database/Developing-with-the-H2-Database.md b/manual/working/commonGuide/database/Developing-with-the-H2-Database.md
similarity index 68%
rename from manual/detailedTopics/database/Developing-with-the-H2-Database.md
rename to manual/working/commonGuide/database/Developing-with-the-H2-Database.md
index 1e0935c1..4939f1a2 100644
--- a/manual/detailedTopics/database/Developing-with-the-H2-Database.md
+++ b/manual/working/commonGuide/database/Developing-with-the-H2-Database.md
@@ -1,7 +1,13 @@
-
+
# H2 database
-The H2 in memory database is very convenient for development because your evolutions are run from scratch when play is restarted. If you are using anorm you probably need it to closely mimic your planned production database. To tell h2 that you want to mimic a particular database you add a parameter to the database url in your application.conf file, for example:
+> **Note:** From Play 2.6.x onwards you actually need to include the H2 Dependency on your own. To do this you just need to add the following to your build.sbt:
+>
+> ```
+> libraryDependencies += "com.h2database" % "h2" % "1.4.192"
+> ```
+
+The H2 in memory database is very convenient for development because your evolutions are run from scratch when play is restarted. If you are using Anorm, you probably need it to closely mimic your planned production database. To tell h2 that you want to mimic a particular database you add a parameter to the database url in your application.conf file, for example:
```
db.default.url="jdbc:h2:mem:play;MODE=MYSQL"
@@ -60,13 +66,15 @@ db.default.url="jdbc:h2:mem:play;MODE=MYSQL"
H2, by default, drops your in memory database if there are no connections to it anymore. You probably don't want this to happen. To prevent this add `DB_CLOSE_DELAY=-1` to the url (use a semicolon as a separator) eg: `jdbc:h2:mem:play;MODE=MYSQL;DB_CLOSE_DELAY=-1`
+> **Note:** Play's builtin JDBC Module will automatically add `DB_CLOSE_DELAY=-1`, however if you are using play-slick with evolutions you need to manually add `;DB_CLOSE_DELAY=-1` to your database url, else the evolution will be in a endless loop since the play application will restart after the evolutions are run, so that the applied evolutions will directly be lost.
+
## Caveats
H2, by default, creates tables with upper case names. Sometimes you don't want this to happen, for example when using H2 with Play evolutions in some compatibility modes. To prevent this add `DATABASE_TO_UPPER=FALSE` to the url (use a semicolon as a separator) eg: `jdbc:h2:mem:play;MODE=PostgreSQL;DB_CLOSE_DELAY=-1;DATABASE_TO_UPPER=FALSE`
## H2 Browser
-You can browse the contents of your database by typing `h2-browser` at the play console. An SQL browser will run in your web browser.
+You can browse the contents of your database by typing `h2-browser` at the [sbt shell](https://www.scala-sbt.org/0.13/docs/Howto-Interactive-Mode.html). An SQL browser will run in your web browser.
## H2 Documentation
diff --git a/manual/detailedTopics/evolutions/Evolutions.md b/manual/working/commonGuide/database/Evolutions.md
similarity index 79%
rename from manual/detailedTopics/evolutions/Evolutions.md
rename to manual/working/commonGuide/database/Evolutions.md
index a93c3819..8716e1d6 100644
--- a/manual/detailedTopics/evolutions/Evolutions.md
+++ b/manual/working/commonGuide/database/Evolutions.md
@@ -1,4 +1,4 @@
-
+
# Managing database evolutions
When you use a relational database, you need a way to track and organize your database schema evolutions. Typically there are several situations where you need a more sophisticated way to track your database schema changes:
@@ -9,12 +9,20 @@ When you use a relational database, you need a way to track and organize your da
## Enable evolutions
-Add `evolutions` into your dependencies list. For example, in `build.sbt`:
+Add `evolutions` and `jdbc` into your dependencies list. For example, in `build.sbt`:
```scala
-libraryDependencies += evolutions
+libraryDependencies ++= Seq(evolutions, jdbc)
```
+### Running evolutions using compile-time DI
+
+If you are using [[compile-time dependency injection|ScalaCompileTimeDependencyInjection]], you will need to mix in the `EvolutionsComponents` trait to your cake to get access to the `ApplicationEvolutions`, which will run the evolutions when instantiated. `EvolutionsComponents` requires `dbApi` to be defined, which you can get by mixing in `DBComponents` and `HikariCPComponents` (or `BoneCPComponents` if you are using BoneCP instead). Since `applicationEvolutions` is a lazy val supplied by `EvolutionsComponents`, you need to access that val to make sure the evolutions run. For example you could explicitly access it in your `ApplicationLoader`, or have an explicit dependency from another component.
+
+Your models will need an instance of `Database` to make connections to your database, which can be obtained from `dbApi.database`.
+
+@[compile-time-di-evolutions](code/CompileTimeDIEvolutions.scala)
+
## Evolutions scripts
Play tracks your database evolutions using several evolutions script. These scripts are written in plain old SQL and should be located in the `conf/evolutions/{database name}` directory of your application. If the evolutions apply to your default database, this path is `conf/evolutions/default`.
@@ -30,9 +38,9 @@ For example, take a look at this first evolution script that bootstrap a basic a
```
# Users schema
-
+
# --- !Ups
-
+
CREATE TABLE User (
id bigint(20) NOT NULL AUTO_INCREMENT,
email varchar(255) NOT NULL,
@@ -41,9 +49,9 @@ CREATE TABLE User (
isAdmin boolean NOT NULL,
PRIMARY KEY (id)
);
-
+
# --- !Downs
-
+
DROP TABLE User;
```
@@ -53,7 +61,7 @@ As you see you have to delimit the both Ups and Downs section by using comments
Evolutions are automatically activated if a database is configured in `application.conf` and evolution scripts are present. You can disable them by setting `play.evolutions.enabled=false`. For example when tests set up their own database you can disable evolutions for the test environment.
-When evolutions are activated, Play will check your database schema state before each request in DEV mode, or before starting the application in PROD mode. In DEV mode, if your database schema is not up to date, an error page will suggest that you synchronise your database schema by running the appropriate SQL script.
+When evolutions are activated, Play will check your database schema state before each request in DEV mode, or before starting the application in PROD mode. In DEV mode, if your database schema is not up to date, an error page will suggest that you synchronize your database schema by running the appropriate SQL script.
[[images/evolutions.png]]
@@ -64,6 +72,7 @@ If you agree with the SQL script, you can apply it directly by clicking on the
Evolutions can be configured both globally and per datasource. For global configuration, keys should be prefixed with `play.evolutions`. For per datasource configuration, keys should be prefixed with `play.evolutions.db.`, for example `play.evolutions.db.default`. The following configuration options are supported:
* `enabled` - Whether evolutions are enabled. If configured globally to be false, it disables the evolutions module altogether. Defaults to true.
+* `schema` - Database schema in which the generated evolution and lock tables will be saved to. No schema is set by default.
* `autocommit` - Whether autocommit should be used. If false, evolutions will be applied in a single transaction. Defaults to true.
* `useLocks` - Whether a locks table should be used. This must be used if you have many Play nodes that may potentially run evolutions, but you want to ensure that only one does. It will create a table called `play_evolutions_lock`, and use a `SELECT FOR UPDATE NOWAIT` or `SELECT FOR UPDATE` to lock it. This will only work for Postgres, Oracle, and MySQL InnoDB. It will not work for other databases. Defaults to false.
* `autoApply` - Whether evolutions should be automatically applied. In dev mode, this will cause both ups and downs evolutions to be automatically applied. In prod mode, it will cause only ups evolutions to be automatically applied. Defaults to false.
@@ -73,11 +82,11 @@ For example, to enable `autoApply` for all evolutions, you might set `play.evolu
## Synchronizing concurrent changes
-Now let’s imagine that we have two developers working on this project. Developer A will work on a feature that requires a new database table. So he will create the following `2.sql` evolution script:
+Now let’s imagine that we have two developers working on this project. Jamie will work on a feature that requires a new database table. So Jamie will create the following `2.sql` evolution script:
```
# Add Post
-
+
# --- !Ups
CREATE TABLE Post (
id bigint(20) NOT NULL AUTO_INCREMENT,
@@ -88,26 +97,26 @@ CREATE TABLE Post (
FOREIGN KEY (author_id) REFERENCES User(id),
PRIMARY KEY (id)
);
-
+
# --- !Downs
DROP TABLE Post;
```
-Play will apply this evolution script to Developer A’s database.
+Play will apply this evolution script to Jamie’s database.
-On the other hand, developer B will work on a feature that requires altering the User table. So he will also create the following `2.sql` evolution script:
+On the other hand, Robin will work on a feature that requires altering the User table. So Robin will also create the following `2.sql` evolution script:
```
# Update User
-
+
# --- !Ups
ALTER TABLE User ADD age INT;
-
+
# --- !Downs
ALTER TABLE User DROP age;
```
-Developer B finishes his feature and commits (let’s say they are using Git). Now developer A has to merge the his colleague’s work before continuing, so he runs git pull, and the merge has a conflict, like:
+Robin finishes the feature and commits (let’s say by using Git). Now Jamie has to merge Robin’s work before continuing, so Jamie runs git pull, and the merge has a conflict, like:
```
Auto-merging db/evolutions/2.sql
@@ -115,12 +124,12 @@ CONFLICT (add/add): Merge conflict in db/evolutions/2.sql
Automatic merge failed; fix conflicts and then commit the result.
```
-Each developer has created a `2.sql` evolution script. So developer A needs to merge the contents of this file:
+Each developer has created a `2.sql` evolution script. So Jamie needs to merge the contents of this file:
```
<<<<<<< HEAD
# Add Post
-
+
# --- !Ups
CREATE TABLE Post (
id bigint(20) NOT NULL AUTO_INCREMENT,
@@ -131,15 +140,15 @@ CREATE TABLE Post (
FOREIGN KEY (author_id) REFERENCES User(id),
PRIMARY KEY (id)
);
-
+
# --- !Downs
DROP TABLE Post;
=======
# Update User
-
+
# --- !Ups
ALTER TABLE User ADD age INT;
-
+
# --- !Downs
ALTER TABLE User DROP age;
>>>>>>> devB
@@ -149,10 +158,10 @@ The merge is really easy to do:
```
# Add Post and update User
-
+
# --- !Ups
ALTER TABLE User ADD age INT;
-
+
CREATE TABLE Post (
id bigint(20) NOT NULL AUTO_INCREMENT,
title varchar(255) NOT NULL,
@@ -162,16 +171,16 @@ CREATE TABLE Post (
FOREIGN KEY (author_id) REFERENCES User(id),
PRIMARY KEY (id)
);
-
+
# --- !Downs
ALTER TABLE User DROP age;
-
+
DROP TABLE Post;
```
-This evolution script represents the new revision 2 of the database, that is different of the previous revision 2 that developer A has already applied.
+This evolution script represents the new revision 2 of the database, that is different of the previous revision 2 that Jamie has already applied.
-So Play will detect it and ask developer A to synchronize his database by first reverting the old revision 2 already applied, and by applying the new revision 2 script:
+So Play will detect it and ask Jamie to synchronize the database by first reverting the old revision 2 already applied, and by applying the new revision 2 script:
## Inconsistent states
@@ -181,10 +190,10 @@ For example, the Ups script of this evolution has an error:
```
# Add another column to User
-
+
# --- !Ups
ALTER TABLE Userxxx ADD company varchar(255);
-
+
# --- !Downs
ALTER TABLE User DROP company;
```
@@ -205,10 +214,10 @@ But because your evolution script has errors, you probably want to fix it. So yo
```
# Add another column to User
-
+
# --- !Ups
ALTER TABLE User ADD company varchar(255);
-
+
# --- !Downs
ALTER TABLE User DROP company;
```
diff --git a/manual/working/commonGuide/database/code/CompileTimeDIEvolutions.scala b/manual/working/commonGuide/database/code/CompileTimeDIEvolutions.scala
new file mode 100644
index 00000000..aa15a6b7
--- /dev/null
+++ b/manual/working/commonGuide/database/code/CompileTimeDIEvolutions.scala
@@ -0,0 +1,26 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+//#compile-time-di-evolutions
+import play.api.ApplicationLoader.Context
+import play.api.BuiltInComponentsFromContext
+import play.api.db.Database
+import play.api.db.DBComponents
+import play.api.db.HikariCPComponents
+import play.api.db.evolutions.EvolutionsComponents
+import play.api.routing.Router
+import play.filters.HttpFiltersComponents
+
+class AppComponents(cntx: Context)
+ extends BuiltInComponentsFromContext(cntx)
+ with DBComponents
+ with EvolutionsComponents
+ with HikariCPComponents
+ with HttpFiltersComponents {
+ // this will actually run the database migrations on startup
+ applicationEvolutions
+
+ //###skip: 1
+ val router = Router.empty
+}
+//#compile-time-di-evolutions
diff --git a/manual/detailedTopics/evolutions/images/evolutions.png b/manual/working/commonGuide/database/images/evolutions.png
similarity index 100%
rename from manual/detailedTopics/evolutions/images/evolutions.png
rename to manual/working/commonGuide/database/images/evolutions.png
diff --git a/manual/detailedTopics/evolutions/images/evolutionsError.png b/manual/working/commonGuide/database/images/evolutionsError.png
similarity index 100%
rename from manual/detailedTopics/evolutions/images/evolutionsError.png
rename to manual/working/commonGuide/database/images/evolutionsError.png
diff --git a/manual/working/commonGuide/database/index.toc b/manual/working/commonGuide/database/index.toc
new file mode 100644
index 00000000..5aa80355
--- /dev/null
+++ b/manual/working/commonGuide/database/index.toc
@@ -0,0 +1,3 @@
+Databases:Databases
+Developing-with-the-H2-Database:Using an in memory H2 database
+Evolutions:Managing database evolutions
\ No newline at end of file
diff --git a/manual/working/commonGuide/filters/AllowedHostsFilter.md b/manual/working/commonGuide/filters/AllowedHostsFilter.md
new file mode 100644
index 00000000..abbe834f
--- /dev/null
+++ b/manual/working/commonGuide/filters/AllowedHostsFilter.md
@@ -0,0 +1,43 @@
+
+# Allowed hosts filter
+
+Play provides a filter that lets you configure which hosts can access your application. This is useful to prevent cache poisoning attacks. For a detailed description of how this attack works, see [this blog post](https://www.skeletonscribe.net/2013/05/practical-http-host-header-attacks.html). The filter introduces a whitelist of allowed hosts and sends a 400 (Bad Request) response to all requests with a host that do not match the whitelist.
+
+This is an important filter to use even in development, because DNS rebinding attacks can be used against a developer's instance of Play: see [Rails Webconsole DNS Rebinding](https://benmmurphy.github.io/blog/2016/07/11/rails-webconsole-dns-rebinding/) for an example of how short lived DNS rebinding can attack a server running on localhost.
+
+Note that if you are running a functional test against a Play application which has the AllowedHostsFilter, then `FakeRequest` and `Helpers.fakeRequest()` will create a request which already has `HOST` set to `localhost`.
+
+## Enabling the allowed hosts filter
+
+> **Note:** As of Play 2.6.x, the Allowed Hosts filter is included in Play's list of default filters that are applied automatically to projects. See [[the Filters page|Filters]] for more information.
+
+To enable the filter manually, add the allowed hosts filter to your filters in `application.conf`:
+
+```
+play.filters.enabled += play.filters.hosts.AllowedHostsFilter
+```
+
+## Configuring allowed hosts
+
+You can configure which hosts the filter allows using `application.conf`. See the Play filters [`reference.conf`](resources/confs/filters-helpers/reference.conf) to see the defaults.
+
+`play.filters.hosts.allowed` is a list of strings of the form `.example.com` or `example.com`. With a leading dot, the pattern will match example.com and all subdomains (`www.example.com`, `foo.example.com`, `foo.bar.example.com`, etc.). Without the leading dot it will just match the exact domain. If your application runs on a specific port, you can also include a port number, for instance `.example.com:8080`.
+
+You can use the `.` pattern to match all hosts (not recommended in production). Note that the filter also strips the dot character from the end of the host, so the `example.com` pattern will match `example.com.`
+
+An example configuration follows.
+
+```
+play.filters.hosts {
+ # Allow requests to example.com, its subdomains, and localhost:9000.
+ allowed = [".example.com", "localhost:9000"]
+}
+```
+
+## Testing
+
+Because the AllowedHostsFilter filter is added automatically, functional tests need to have the Host HTTP header added.
+
+If you are using `FakeRequest` or `Helpers.fakeRequest`, then the `Host` HTTP header is added for you automatically. If you are using `play.mvc.Http.RequestBuilder`, then you may need to add your own line to add the header manually:
+
+@[test-with-request-builder](code/javaguide/detailed/filters/FiltersTest.java)
diff --git a/manual/working/commonGuide/filters/CorsFilter.md b/manual/working/commonGuide/filters/CorsFilter.md
new file mode 100644
index 00000000..0f02c531
--- /dev/null
+++ b/manual/working/commonGuide/filters/CorsFilter.md
@@ -0,0 +1,41 @@
+
+# Cross-Origin Resource Sharing
+
+Play provides a filter that implements Cross-Origin Resource Sharing (CORS).
+
+CORS is a protocol that allows web applications to make requests from the browser across different domains. A full specification can be found [here](http://www.w3.org/TR/cors/).
+
+## Enabling the CORS filter
+
+To enable the CORS filter, add `play.filters.cors.CORSFilter` to `application.conf`:
+
+```
+play.filters.enabled += "play.filters.cors.CORSFilter"
+```
+
+## Configuring the CORS filter
+
+The filter can be configured from `application.conf`. For a full listing of configuration options, see the Play filters [`reference.conf`](resources/confs/filters-helpers/reference.conf).
+
+The available options include:
+
+* `play.filters.cors.pathPrefixes` - filter paths by a whitelist of path prefixes
+* `play.filters.cors.allowedOrigins` - allow only requests with origins from a whitelist (by default all origins are allowed)
+* `play.filters.cors.allowedHttpMethods` - allow only HTTP methods from a whitelist for preflight requests (by default all methods are allowed)
+* `play.filters.cors.allowedHttpHeaders` - allow only HTTP headers from a whitelist for preflight requests (by default all headers are allowed)
+* `play.filters.cors.exposedHeaders` - set custom HTTP headers to be exposed in the response (by default no headers are exposed)
+* `play.filters.cors.supportsCredentials` - disable/enable support for credentials (by default credentials support is enabled)
+* `play.filters.cors.preflightMaxAge` - set how long the results of a preflight request can be cached in a preflight result cache (by default 1 hour)
+* `play.filters.cors.serveForbiddenOrigins` - enable/disable serving requests with origins not in whitelist as non-CORS requests (by default they are forbidden)
+
+For example:
+
+```
+play.filters.cors {
+ pathPrefixes = ["/some/path", ...]
+ allowedOrigins = ["http://www.example.com", ...]
+ allowedHttpMethods = ["GET", "POST"]
+ allowedHttpHeaders = ["Accept"]
+ preflightMaxAge = 3 days
+}
+```
diff --git a/manual/working/commonGuide/filters/Filters.md b/manual/working/commonGuide/filters/Filters.md
new file mode 100644
index 00000000..13eb83cc
--- /dev/null
+++ b/manual/working/commonGuide/filters/Filters.md
@@ -0,0 +1,135 @@
+
+# Built-in HTTP filters
+
+Play provides several standard filters that can modify the HTTP behavior of your application. You can also write your own filters in either [[Java|JavaHttpFilters]] or [[Scala|ScalaHttpFilters]].
+
+- [[Configuring gzip encoding|GzipEncoding]]
+- [[Configuring security headers|SecurityHeaders]]
+- [[Configuring CORS|CorsFilter]]
+- [[Configuring allowed hosts|AllowedHostsFilter]]
+- [[Configuring Redirect HTTPS filter|RedirectHttpsFilter]]
+
+## Default Filters
+
+Play now comes with a default set of enabled filters, defined through configuration. If the property `play.http.filters` is null, then the default is now `play.api.http.EnabledFilters`, which loads up the filters defined by fully qualified class name in the `play.filters.enabled` configuration property.
+
+In Play itself, `play.filters.enabled` is an empty list. However, the filters library is automatically loaded in sbt as an AutoPlugin called `PlayFilters`, and will append the following values to the `play.filters.enabled` property:
+
+* `play.filters.csrf.CSRFFilter`
+* `play.filters.headers.SecurityHeadersFilter`
+* `play.filters.hosts.AllowedHostsFilter`
+
+This means that on new projects, CSRF protection ([[ScalaCsrf]] / [[JavaCsrf]]), [[SecurityHeaders]] and [[AllowedHostsFilter]] are all defined automatically.
+
+To append to the defaults list, use the `+=`:
+
+```
+play.filters.enabled+=MyFilter
+```
+
+If you have previously defined your own filters by extending `play.api.http.DefaultHttpFilters`, then you can also combine `EnabledFilters` with your own filters in code:
+
+Java
+: @[filters-combine-enabled-filters](code/javaguide/detailed/filters/Filters.java)
+
+Scala
+: @[filters-combine-enabled-filters](code/scalaguide/detailed/filters/ScalaFilters.scala)
+
+Otherwise, if you have a `Filters` class in the root or have `play.http.filters` defined explicitly, it will take precedence over the `EnabledFilters` functionality described below.
+
+### Testing Default Filters
+
+Because there are several filters enabled, functional tests may need to change slightly to ensure that all the tests pass and requests are valid. For example, a request that does not have a `Host` HTTP header set to `localhost` will not pass the AllowedHostsFilter and will return a 400 Forbidden response instead.
+
+#### Testing with AllowedHostsFilter
+
+Because the AllowedHostsFilter filter is added automatically, functional tests need to have the Host HTTP header added.
+
+If you are using `FakeRequest` or `Helpers.fakeRequest`, then the `Host` HTTP header is added for you automatically. If you are using `play.mvc.Http.RequestBuilder`, then you may need to add your own line to add the header manually:
+
+@[test-with-request-builder](code/javaguide/detailed/filters/FiltersTest.java)
+
+#### Testing with CSRFFilter
+
+Because the CSRFFilter filter is added automatically, tests that render a Twirl template that includes `CSRF.formField`, i.e.
+
+```html
+@(userForm: Form[UserData])(implicit request: RequestHeader, m: Messages)
+
+user form
+
+@request.flash.get("success").getOrElse("")
+
+@helper.form(action = routes.UserController.userPost()) {
+ @helper.CSRF.formField
+ @helper.inputText(userForm("name"))
+ @helper.inputText(userForm("age"))
+
+}
+```
+
+must contain a CSRF token in the request. In the Scala API, this is done by importing `play.api.test.CSRFTokenHelper._`, which enriches `play.api.test.FakeRequest` with the `withCSRFToken` method:
+
+@[test-with-withCSRFToken](code/scalaguide/detailed/filters/UserControllerSpec.scala)
+
+In the Java API, this is done by calling `CSRFTokenHelper.addCSRFToken` on a `play.mvc.Http.RequestBuilder` instance:
+
+@[test-with-addCSRFToken](code/javaguide/detailed/filters/FiltersTest.java)
+
+### Disabling Default Filters
+
+The simplest way to disable a filter is to add it to the `play.filters.disabled` list in `application.conf`:
+
+```
+play.filters.disabled+=play.filters.hosts.AllowedHostsFilter
+```
+
+This may be useful if you have functional tests that you do not want to go through the default filters.
+
+To remove the default filters, you can set the entire list manually:
+
+```
+play.filters.enabled=[]
+```
+
+If you want to remove all filter classes, you can disable it through the `disablePlugins` mechanism:
+
+```
+lazy val root = project.in(file(".")).enablePlugins(PlayScala).disablePlugins(PlayFilters)
+```
+
+If you are writing functional tests involving `GuiceApplicationBuilder`, then you can disable all filters in a test by calling `configure`:
+
+@[test-disabling-filters](code/scalaguide/detailed/filters/UserControllerSpec.scala)
+
+## Compile Time Default Filters
+
+If you are using compile time dependency injection, then the default filters are resolved at compile time, rather than through runtime.
+
+This means that the [`play.api.BuiltInComponents`](api/scala/play/api/BuiltInComponents.html) trait (for Scala) and [`play.BuiltInComponents`](api/java/play/BuiltInComponents.html) interface (for Java) now contains an `httpFilters` method which is left abstract. The default list of filters is defined in [`play.filters.HttpFiltersComponents`](api/scala/play/filters/HttpFiltersComponents.html) for Scala and [`play.filters.components.HttpFiltersComponents`](api/java/play/filters/components/HttpFiltersComponents.html) for Java. So, for most cases you will want to mixin `HttpFiltersComponents` and append your own filters:
+
+Java
+: @[appending-filters-compile-time-di](code/javaguide/detailed/filters/add/MyAppComponents.java)
+
+Scala
+: @[appending-filters-compile-time-di](code/scalaguide/detailed/filters/FiltersComponents.scala)
+
+If you want to filter elements out of the list, you can do the following:
+
+Java
+: @[removing-filters-compile-time-di](code/javaguide/detailed/filters/remove/MyAppComponents.java)
+
+Scala
+: @[removing-filters-compile-time-di](code/scalaguide/detailed/filters/FiltersComponents.scala)
+
+### Disabling Compile Time Default Filters
+
+To disable the default filters, mix in [`play.api.NoHttpFiltersComponents`](api/scala/play/api/NoHttpFiltersComponents.html) for Scala and [`play.filters.components.NoHttpFiltersComponents`](api/java/play/filters/components/NoHttpFiltersComponents.html) for Java:
+
+Java
+: @[remove-all-filters-compile-time-di](code/javaguide/detailed/filters/removeAll/MyAppComponents.java)
+
+Scala
+: @[remove-all-filters-compile-time-di](code/scalaguide/detailed/filters/FiltersComponents.scala)
+
+Both Scala [`play.api.NoHttpFiltersComponents`](api/scala/play/api/NoHttpFiltersComponents.html) and [`play.filters.components.NoHttpFiltersComponents`](api/java/play/filters/components/NoHttpFiltersComponents.html) have `httpFilters` method which returns an empty list of filters.
\ No newline at end of file
diff --git a/manual/working/commonGuide/filters/GzipEncoding.md b/manual/working/commonGuide/filters/GzipEncoding.md
new file mode 100644
index 00000000..a842a06e
--- /dev/null
+++ b/manual/working/commonGuide/filters/GzipEncoding.md
@@ -0,0 +1,45 @@
+
+# Configuring gzip encoding
+
+Play provides a gzip filter that can be used to gzip responses.
+
+## Enabling the gzip filter
+
+To enable the gzip filter, add the filter to `application.conf`:
+
+```
+play.filters.enabled += "play.filters.gzip.GzipFilter"
+```
+
+## Configuring the gzip filter
+
+The gzip filter supports a small number of tuning configuration options, which can be configured from `application.conf`. To see the available configuration options, see the Play filters [`reference.conf`](resources/confs/filters-helpers/reference.conf).
+
+## Controlling which responses are gzipped
+
+You can control which responses are and aren't gzipped based on their content types via `application.conf`:
+
+```
+play.filters.gzip {
+
+ contentType {
+
+ # If non empty, then a response will only be compressed if its content type is in this list.
+ whiteList = [ "text/*", "application/javascript", "application/json" ]
+
+ # The black list is only used if the white list is empty.
+ # Compress all responses except the ones whose content type is in this list.
+ blackList = []
+ }
+}
+```
+
+As a more flexible alternative you can use the `shouldGzip` parameter of the gzip filter itself, which accepts a function of a request header and a response header to a boolean.
+
+For example, the code below only gzips HTML responses:
+
+Scala
+: @[should-gzip](code/GzipEncoding.scala)
+
+Java
+: @[gzip-filter](code/detailedtopics/configuration/gzipencoding/CustomFilters.java)
diff --git a/manual/working/commonGuide/filters/RedirectHttpsFilter.md b/manual/working/commonGuide/filters/RedirectHttpsFilter.md
new file mode 100644
index 00000000..7ccbf556
--- /dev/null
+++ b/manual/working/commonGuide/filters/RedirectHttpsFilter.md
@@ -0,0 +1,55 @@
+
+# Redirect HTTPS Filter
+
+Play provides a filter which will redirect all HTTP requests to HTTPS automatically.
+
+## Enabling the HTTPS filter
+
+To enable the filter, add it to `play.filters.enabled`:
+
+```
+play.filters.enabled += play.filters.https.RedirectHttpsFilter
+```
+
+By default, the redirect only happens in Prod mode. To override this, set `play.filters.https.redirectEnabled = true`.
+
+## Determining Secure Requests
+
+The filter evaluates a request to be secure if `request.secure` is true.
+
+This logic depends on the [[trusted proxies|HTTPServer#configuring-trusted-proxies]] configured for Play's HTTP engine. Internally, `play.core.server.common.ForwardedHeaderHandler` and `play.api.mvc.request.RemoteConnection` determine between them whether an incoming request meets the criteria to be "secure", meaning that the request has gone through HTTPS at some point.
+
+When the filter is enabled, any request that is not secure is redirected.
+
+## Strict Transport Security
+
+The [Strict Transport Security](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) header is used to indicate when HTTPS should always be used, and is added to a secure request. The HSTS header is only added if the redirect is enabled.
+
+The default is "max-age=31536000; includeSubDomains", and can be set explicitly by adding the following to `application.conf`:
+
+```
+play.filters.https.strictTransportSecurity="max-age=31536000; includeSubDomains"
+```
+
+It is also possible to set `play.filters.https.strictTransportSecurity = null` to disable HSTS.
+
+Note that the `Strict-Transport-Security` header tells the browser to prefer HTTPS for *all requests to that hostname*, so if you enable the filter in dev mode, the header will affect other apps being developed with that hostname (e.g. `localhost:9000`). If you want to avoid this, either use a different host for each app in development (`app1:9000`, `app2:9000`, etc.) or disable HSTS completely in dev mode.
+
+## Redirect code
+
+The filter redirects using HTTP code 308, which is a permanent redirect that does not change the HTTP method according to [RFC 7238](https://tools.ietf.org/html/rfc7238). This will work with the vast majority of browsers, but you can change the redirect code if working with older browsers:
+
+```
+play.filters.https.redirectStatusCode = 301
+```
+
+## Custom HTTPS Port
+
+If the HTTPS server is on a custom port, then the redirect URL needs to be aware of it. If the port is specified:
+
+```
+play.filters.https.port = 9443
+```
+
+then the URL in the `Location` header will include the port specifically, e.g. `https://playframework.com:9443/some/url`.
+
diff --git a/manual/working/commonGuide/filters/SecurityHeaders.md b/manual/working/commonGuide/filters/SecurityHeaders.md
new file mode 100644
index 00000000..abb8ab15
--- /dev/null
+++ b/manual/working/commonGuide/filters/SecurityHeaders.md
@@ -0,0 +1,45 @@
+
+# Configuring Security Headers
+
+Play provides a security headers filter that can be used to configure some default headers in the HTTP response to mitigate security issues and provide an extra level of defense for new applications.
+
+## Enabling the security headers filter
+
+> **Note:** As of Play 2.6.x, the Security Headers filter is included in Play's list of default filters that are applied automatically to projects. See [[the Filters page|Filters]] for more information.
+
+To enable the security headers filter manually, add the security headers filter to your filters in `application.conf`:
+
+```
+play.filters.enabled += "play.filters.headers.SecurityHeadersFilter"
+```
+
+## Configuring the security headers
+
+Scaladoc is available in the [play.filters.headers](api/scala/play/filters/headers/index.html) package.
+
+The filter will set headers in the HTTP response automatically. The settings can be configured through the following settings in `application.conf`
+
+* `play.filters.headers.frameOptions` - sets [X-Frame-Options](https://developer.mozilla.org/en-US/docs/HTTP/X-Frame-Options), "DENY" by default.
+* `play.filters.headers.xssProtection` - sets [X-XSS-Protection](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection), "1; mode=block" by default.
+* `play.filters.headers.contentTypeOptions` - sets [X-Content-Type-Options](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options), "nosniff" by default.
+* `play.filters.headers.permittedCrossDomainPolicies` - sets [X-Permitted-Cross-Domain-Policies](https://www.adobe.com/devnet/articles/crossdomain_policy_file_spec.html), "master-only" by default.
+* `play.filters.headers.referrerPolicy` - sets [Referrer Policy](https://www.w3.org/TR/referrer-policy/), "origin-when-cross-origin, strict-origin-when-cross-origin" by default.
+* `play.filters.headers.contentSecurityPolicy` - sets [Content-Security-Policy](https://developers.google.com/web/fundamentals/security/csp/), "default-src 'self'" by default.
+
+Any of the headers can be disabled by setting a configuration value of `null`, for example:
+
+```
+play.filters.headers.frameOptions = null
+```
+
+For a full listing of configuration options, see the Play filters [`reference.conf`](resources/confs/filters-helpers/reference.conf).
+
+## Action-specific overrides
+
+Security headers may be overridden in specific actions using `withHeaders` on the result:
+
+@[allowActionSpecificHeaders](code/SecurityHeaders.scala)
+
+Any security headers not mentioned in `withHeaders` will use the usual configured values
+(if present) or the defaults. Action-specific security headers are ignored unless
+`play.filters.headers.allowActionSpecificHeaders` is set to `true` in the configuration.
diff --git a/manual/working/commonGuide/filters/code/GzipEncoding.scala b/manual/working/commonGuide/filters/code/GzipEncoding.scala
new file mode 100644
index 00000000..69e5bd1d
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/GzipEncoding.scala
@@ -0,0 +1,56 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package detailedtopics.configuration.gzipencoding
+
+import akka.stream.ActorMaterializer
+import play.api.test._
+
+class GzipEncoding extends PlaySpecification {
+
+ import javax.inject.Inject
+
+ import play.api.http.DefaultHttpFilters
+ import play.filters.gzip.GzipFilter
+
+ class Filters @Inject()(gzipFilter: GzipFilter) extends DefaultHttpFilters(gzipFilter)
+
+ "gzip filter" should {
+
+ "allow custom strategies for when to gzip (Scala)" in {
+
+ import play.api.mvc._
+ running() { app =>
+ implicit val mat = ActorMaterializer()(app.actorSystem)
+ def Action = app.injector.instanceOf[DefaultActionBuilder]
+
+ val filter =
+ //#should-gzip
+ new GzipFilter(
+ shouldGzip = (request, response) => response.body.contentType.exists(_.startsWith("text/html"))
+ )
+ //#should-gzip
+
+ header(CONTENT_ENCODING, filter(Action(Results.Ok("foo")))(gzipRequest).run()) must beNone
+ }
+ }
+
+ "allow custom strategies for when to gzip (Java)" in {
+
+ import play.api.mvc._
+ val app = play.api.inject.guice.GuiceApplicationBuilder().build()
+ running(app) {
+ implicit val mat = ActorMaterializer()(app.actorSystem)
+ def Action = app.injector.instanceOf[DefaultActionBuilder]
+
+ val filter = (new CustomFilters(mat)).getFilters.get(0)
+
+ header(CONTENT_ENCODING, filter(Action(Results.Ok("foo")))(gzipRequest).run()) must beNone
+ }
+ }
+
+ }
+
+ def gzipRequest = FakeRequest().withHeaders(ACCEPT_ENCODING -> "gzip")
+
+}
diff --git a/manual/working/commonGuide/filters/code/SecurityHeaders.scala b/manual/working/commonGuide/filters/code/SecurityHeaders.scala
new file mode 100644
index 00000000..435de7bf
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/SecurityHeaders.scala
@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package detailedtopics.configuration.securityheaders
+
+//#filters
+import javax.inject.Inject
+
+import play.api.http.DefaultHttpFilters
+import play.filters.headers.SecurityHeadersFilter
+import play.api.mvc.BaseController
+import play.api.mvc.ControllerComponents
+//#filters
+
+class SecurityHeaders @Inject()(val controllerComponents: ControllerComponents) extends BaseController {
+
+ def index = Action {
+ //#allowActionSpecificHeaders
+ Ok("Index").withHeaders(SecurityHeadersFilter.CONTENT_SECURITY_POLICY_HEADER -> "my page-specific header")
+ //#allowActionSpecificHeaders
+ }
+}
+
+object SecurityHeaders {
+ class Filters @Inject()(securityHeadersFilter: SecurityHeadersFilter)
+ extends DefaultHttpFilters(securityHeadersFilter)
+}
diff --git a/manual/working/commonGuide/filters/code/detailedtopics/configuration/gzipencoding/CustomFilters.java b/manual/working/commonGuide/filters/code/detailedtopics/configuration/gzipencoding/CustomFilters.java
new file mode 100644
index 00000000..edff7749
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/detailedtopics/configuration/gzipencoding/CustomFilters.java
@@ -0,0 +1,42 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package detailedtopics.configuration.gzipencoding;
+
+import akka.stream.Materializer;
+import play.mvc.EssentialFilter;
+import play.filters.gzip.GzipFilter;
+import play.filters.gzip.GzipFilterConfig;
+import play.http.HttpFilters;
+import play.mvc.Http;
+import play.mvc.Result;
+
+import javax.inject.Inject;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import java.util.function.BiFunction;
+
+public class CustomFilters implements HttpFilters {
+
+ private List filters;
+
+ @Inject
+ public CustomFilters(Materializer materializer) {
+ // #gzip-filter
+ GzipFilterConfig gzipFilterConfig = new GzipFilterConfig();
+ GzipFilter gzipFilter =
+ new GzipFilter(
+ gzipFilterConfig.withShouldGzip(
+ (BiFunction)
+ (req, res) -> res.body().contentType().orElse("").startsWith("text/html")),
+ materializer);
+ // #gzip-filter
+ filters = Collections.singletonList(gzipFilter.asJava());
+ }
+
+ @Override
+ public List getFilters() {
+ return filters;
+ }
+}
diff --git a/manual/working/commonGuide/filters/code/filters.sbt b/manual/working/commonGuide/filters/code/filters.sbt
new file mode 100644
index 00000000..94592fb2
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/filters.sbt
@@ -0,0 +1,7 @@
+//
+// Copyright (C) 2009-2019 Lightbend Inc.
+//
+
+//#content
+libraryDependencies += filters
+//#content
diff --git a/manual/working/commonGuide/filters/code/javaguide/detailed/filters/Filters.java b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/Filters.java
new file mode 100644
index 00000000..b5265233
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/Filters.java
@@ -0,0 +1,31 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package javaguide.detailed.filters;
+
+// #filters-combine-enabled-filters
+import play.api.http.EnabledFilters;
+import play.filters.cors.CORSFilter;
+import play.http.DefaultHttpFilters;
+import play.mvc.EssentialFilter;
+
+import javax.inject.Inject;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+public class Filters extends DefaultHttpFilters {
+
+ @Inject
+ public Filters(EnabledFilters enabledFilters, CORSFilter corsFilter) {
+ super(combine(enabledFilters.asJava().getFilters(), corsFilter.asJava()));
+ }
+
+ private static List combine(
+ List filters, EssentialFilter toAppend) {
+ List combinedFilters = new ArrayList<>(filters);
+ combinedFilters.add(toAppend);
+ return combinedFilters;
+ }
+}
+// #filters-combine-enabled-filters
diff --git a/manual/working/commonGuide/filters/code/javaguide/detailed/filters/FiltersTest.java b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/FiltersTest.java
new file mode 100644
index 00000000..efe00271
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/FiltersTest.java
@@ -0,0 +1,61 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package javaguide.detailed.filters;
+
+import org.junit.Test;
+import play.api.mvc.PlayBodyParsers;
+import play.api.test.CSRFTokenHelper;
+import play.core.j.JavaContextComponents;
+import play.mvc.Http;
+import play.mvc.Results;
+import play.routing.Router;
+import play.routing.RoutingDsl;
+import play.test.Helpers;
+import play.test.WithApplication;
+
+import static play.test.Helpers.GET;
+import static play.test.Helpers.POST;
+
+public class FiltersTest extends WithApplication {
+
+ @Test
+ public void testRequestBuilder() {
+ Router router =
+ new RoutingDsl(
+ instanceOf(play.mvc.BodyParser.Default.class),
+ instanceOf(JavaContextComponents.class))
+ .GET("/xx/Kiwi")
+ .routeTo(() -> Results.ok("success"))
+ .build();
+
+ // #test-with-request-builder
+ Http.RequestBuilder request =
+ new Http.RequestBuilder()
+ .method(GET)
+ .header(Http.HeaderNames.HOST, "localhost")
+ .uri("/xx/Kiwi");
+ // #test-with-request-builder
+
+ Helpers.routeAndCall(app, router, request, 10_000 /* 10 seconds */);
+ }
+
+ @Test
+ public void test() {
+ Router router =
+ new RoutingDsl(
+ instanceOf(play.mvc.BodyParser.Default.class),
+ instanceOf(JavaContextComponents.class))
+ .POST("/xx/Kiwi")
+ .routeTo(() -> Results.ok("success"))
+ .build();
+
+ // #test-with-addCSRFToken
+ Http.RequestBuilder request = new Http.RequestBuilder().method(POST).uri("/xx/Kiwi");
+
+ request = CSRFTokenHelper.addCSRFToken(request);
+ // #test-with-addCSRFToken
+
+ Helpers.routeAndCall(app, router, request, 10_000 /* 10 seconds */);
+ }
+}
diff --git a/manual/working/commonGuide/filters/code/javaguide/detailed/filters/add/MyAppComponents.java b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/add/MyAppComponents.java
new file mode 100644
index 00000000..caf44b5d
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/add/MyAppComponents.java
@@ -0,0 +1,37 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+ */
+package javaguide.detailed.filters.add;
+
+import javaguide.application.httpfilters.LoggingFilter;
+
+// #appending-filters-compile-time-di
+import play.ApplicationLoader;
+import play.BuiltInComponentsFromContext;
+import play.filters.components.HttpFiltersComponents;
+import play.mvc.EssentialFilter;
+import play.routing.Router;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class MyAppComponents extends BuiltInComponentsFromContext implements HttpFiltersComponents {
+
+ public MyAppComponents(ApplicationLoader.Context context) {
+ super(context);
+ }
+
+ @Override
+ public List httpFilters() {
+ List combinedFilters =
+ new ArrayList<>(HttpFiltersComponents.super.httpFilters());
+ combinedFilters.add(new LoggingFilter(materializer()));
+ return combinedFilters;
+ }
+
+ @Override
+ public Router router() {
+ return Router.empty(); // implement the router as needed
+ }
+}
+// #appending-filters-compile-time-di
diff --git a/manual/working/commonGuide/filters/code/javaguide/detailed/filters/remove/MyAppComponents.java b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/remove/MyAppComponents.java
new file mode 100644
index 00000000..55300d83
--- /dev/null
+++ b/manual/working/commonGuide/filters/code/javaguide/detailed/filters/remove/MyAppComponents.java
@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc.
+
+ Hello World
+
+
+ Hello, @name
+Index view
+} \ No newline at end of file diff --git a/manual/tutorial/code/javaguide/hello/main.scala.html b/manual/tutorial/code/javaguide/hello/main.scala.html new file mode 100644 index 00000000..e4385b6c --- /dev/null +++ b/manual/tutorial/code/javaguide/hello/main.scala.html @@ -0,0 +1,11 @@ +@(title: String)(content: play.twirl.api.Html) + + + + +
+```
+
+## Reverse routing and fingerprinting for public assets
+
+[sbt-web](https://github.com/sbt/sbt-web) brings the notion of a highly configurable asset pipeline to Play e.g. in your build file:
+
+```scala
+pipelineStages := Seq(rjs, digest, gzip)
+```
+
+The above will order the RequireJs optimizer ([sbt-rjs](https://github.com/sbt/sbt-rjs)), the digester ([sbt-digest](https://github.com/sbt/sbt-digest)) and then compression ([sbt-gzip](https://github.com/sbt/sbt-gzip)). Unlike many sbt tasks, these tasks will execute in the order declared, one after the other.
+
+In essence asset fingerprinting permits your static assets to be served with aggressive caching instructions to a browser. This will result in an improved experience for your users given that subsequent visits to your site will result in less assets requiring to be downloaded. Rails also describes the benefits of [asset fingerprinting](https://guides.rubyonrails.org/asset_pipeline.html#what-is-fingerprinting-and-why-should-i-care-questionmark).
+
+The above declaration of `pipelineStages` and the requisite `addSbtPlugin` declarations in your `plugins.sbt` for the plugins you require are your start point. You must then declare to Play what assets are to be versioned.
+
+There are two ways obtain the real path of a fingerprinted asset. The first way uses static state and supports the same style as normal reverse routing. It does so by looking up assets metadata that's set by a running Play application. The second way is to use configuration and inject an AssetsFinder to find your asset.
+
+### Using reverse routing and static state
+
+If you plan to use the reverse router with static state, the following routes file entry declares that all assets are to be versioned:
+
+```scala
+GET /assets/*file controllers.Assets.versioned(path="/public", file: Asset)
+```
+
+> **Note:** Make sure you indicate that `file` is an asset by writing `file: Asset`.
+
+You then use the reverse router, for example within a `scala.html` view:
+
+```html
+
+```
+
+The downside of this approach is that it requires special logic that converts the `Asset` from the path you passed in to the final minified path with a digest. It's also more difficult to unit test, since there's no component you can mock to define the path.
+
+### Using configuration and AssetsFinder
+
+You can also define your paths in configuration, and inject an `AssetsFinder` into your controller to get the final path. In your configuration set up the assets `path` (the directory containing assets) and the `urlPrefix` (the prefix to the URL in your application):
+
+```
+play.assets {
+ path = "/public"
+ urlPrefix = "/assets"
+}
+```
+
+In your routes file you can define a route as follows:
+
+@[assets-configured-path-versioned](code/configured.assets.routes)
+
+(you should not use the `: Asset` type annotation here)
+
+Then you can pass an `AssetsFinder` to your template and use that to get the final path:
+
+```html
+@(assetsFinder: AssetsFinder)
+
+
+```
+
+The advantage to this approach is that it requires no static state to set up. That means you can unit test your controllers and templates without a running application by simply passing an instance of `AssetsFinder`. That makes it simple to mock for a unit test by simply implementing the abstract methods that return `String`s.
+
+Using the `AssetsFinder` approach also makes it easy to run multiple self-contained applications at once in the same classloader, since it uses no static state. This can also be helpful for testing.
+
+The `AssetsFinder` interface also works in cases where fingerprinting is not used. It returns the original asset if a fingerprinted and/or minified asset cannot be found.
+
+## Etag support
+
+The `Assets` controller automatically manages **ETag** HTTP Headers. The ETag value is generated from the digest (if `sbt-digest` is being used in the asset pipeline) or otherwise the resource name and the file’s last modification date. If the resource file is embedded into a file, the JAR file’s last modification date is used.
+
+When a web browser makes a request specifying this **Etag** then the server can respond with **304 NotModified**.
+
+## Gzip support
+
+If a resource with the same name but using a `.gz` suffix is found then the `Assets` controller will also serve the latter and add the following HTTP header:
+
+```
+Content-Encoding: gzip
+```
+
+Including the `sbt-gzip` plugin in your build and declaring its position in the `pipelineStages` is all that is required to generate gzip files.
+
+## Additional `Cache-Control` directive
+
+Using Etag is usually enough for the purposes of caching. However if you want to specify a custom `Cache-Control` header for a particular resource, you can specify it in your `application.conf` file. For example:
+
+```
+# Assets configuration
+# ~~~~~
+play.assets.cache."/public/stylesheets/bootstrap.min.css"="max-age=3600"
+```
+
+You can also use partial paths to specify a custom `Cache-Control` for all the assets that are under that path, for example:
+
+```
+# Assets configuration
+# ~~~~~
+play.assets.cache."/public/stylesheets/"="max-age=100"
+play.assets.cache."/public/javascripts/"="max-age=200"
+```
+
+And Play will use `max-age=200` for all assets under `/public/javascripts` (like `/public/javascripts/main.js`) and `max-age=100` to all assets under `/public/stylesheets` (like `/public/stylesheets/main.css`).
+
+### How the additional directives are applied
+
+Play sorts the `Cache-Control` directives lexicographically and later from more specific to less specific. For example, given the following configuration:
+
+```
+# Assets configuration
+# ~~~~~
+play.assets.cache."/public/stylesheets/"="max-age=101"
+play.assets.cache."/public/stylesheets/layout/"="max-age=102"
+play.assets.cache."/public/stylesheets/app/"="max-age=103"
+play.assets.cache."/public/stylesheets/layout/main.css"="max-age=103"
+
+play.assets.cache."/public/javascripts/"="max-age=201"
+play.assets.cache."/public/javascripts/app/"="max-age=202"
+play.assets.cache."/public/javascripts/app/main.js"="max-age=203"
+```
+
+The directives will be sorted and applied in the following order:
+
+```
+play.assets.cache."/public/javascripts/app/main.js"="max-age=203"
+play.assets.cache."/public/javascripts/app/"="max-age=202"
+play.assets.cache."/public/javascripts/"="max-age=201"
+
+play.assets.cache."/public/stylesheets/app/"="max-age=103"
+play.assets.cache."/public/stylesheets/layout/main.css"="max-age=103"
+play.assets.cache."/public/stylesheets/layout/"="max-age=102"
+play.assets.cache."/public/stylesheets/"="max-age=101"
+```
+
+> **Note:** a configuration like `play.assets.cache."/public/stylesheets"="max-age=101"` will match both `public/stylesheets.css` and `public/stylesheets/main.css`, so you may want to add a trailing `/` to better differentiate directories, for example `play.assets.cache."/public/stylesheets/"="max-age=101"`.
+
+## Managed assets
+
+Starting with Play 2.3 managed assets are processed by [sbt-web](https://github.com/sbt/sbt-web#sbt-web) based plugins. Prior to 2.3 Play bundled managed asset processing in the form of CoffeeScript, LESS, JavaScript linting (ClosureCompiler) and RequireJS optimization. The following sections describe sbt-web and how the equivalent 2.2 functionality can be achieved. Note though that Play is not limited to this asset processing technology as many plugins should become available to sbt-web over time. Please check-in with the [sbt-web](https://github.com/sbt/sbt-web#sbt-web) project to learn more about what plugins are available.
+
+Many plugins use sbt-web's [js-engine plugin](https://github.com/sbt/sbt-js-engine). js-engine is able to execute plugins written to the Node API either within the JVM via the excellent [Trireme](https://github.com/apigee/trireme#trireme) project, or directly on [Node.js](https://nodejs.org/) for superior performance. Note that these tools are used during the development cycle only and have no involvement during the runtime execution of your Play application. If you have Node.js installed then you are encouraged to declare the following environment variable. For Unix, if `SBT_OPTS` has been defined elsewhere then you can:
+
+```bash
+export SBT_OPTS="$SBT_OPTS -Dsbt.jse.engineType=Node"
+```
+
+The above declaration ensures that Node.js is used when executing any sbt-web plugin.
+
+## Range requests support
+
+`Assets` controller automatically supports part of [RFC 7233](https://tools.ietf.org/html/rfc7233) which defines how range requests and partial responses works. The `Assets` controller will delivery a `206 Partial Content` if a satisfiable `Range` header is present in the request. It will also returns a `Accept-Ranges: bytes` for all assets delivery.
+
+> **Note:** Besides the fact that some parsing is done to better handle multiple ranges, `multipart/byteranges` is not fully supported yet.
+
+You can also return `206 Partial Content` when delivering files without using the `Assets` controller:
+
+### Scala version
+
+@[range-request](code/assets/controllers/RangeRequestController.scala)
+
+### Java version
+
+@[range-request](code/assets/controllers/JavaRangeRequestController.java)
+
+Both examples will delivery just part of the video file, according to the requested range.
diff --git a/manual/working/commonGuide/assets/AssetsSass.md b/manual/working/commonGuide/assets/AssetsSass.md
new file mode 100644
index 00000000..00f6cb1d
--- /dev/null
+++ b/manual/working/commonGuide/assets/AssetsSass.md
@@ -0,0 +1,95 @@
+
+# Using Sass
+
+[Sass](http://sass-lang.com/) is a dynamic stylesheet language. It allows considerable flexibility in the way you write CSS files including support for variables, mixins and more.
+
+Compilable assets in Play are typically defined in the `app/assets` directory. They are handled by the build process, and Sass sources are compiled into standard CSS files. The generated CSS files are distributed as standard resources into the same `public/` folder as the unmanaged assets, meaning that there is no difference in the way you use them once compiled.
+
+For example, Sass source file `app/assets/stylesheets/main.scss` will be available as standard CSS resource, at `public/stylesheets/main.css`.
+
+Sass sources are compiled automatically during an `assets` command, or when you refresh any page in your browser while you are running in development mode. Any compilation errors will be displayed in your browser:
+
+[[images/sassError.png]]
+
+## Working with partial Sass source files
+
+Any Sass file (`*.scss`/`*.sass`) will automatically be compiled. The Sass plugin will automatically determine which Sass syntax is being used (indented or not) based on the filename. A file who's name starts with an `_` will not be compiled separately. However, such files can be included in other Sass files by using the standard Sass import feature.
+
+## Layout
+
+Below an example layout for using Sass in your project is given:
+
+```
+app
+ └ assets
+ └ stylesheets
+ └ main.scss
+ └ utils
+ └ _reset.scss
+ └ _layout.scss
+```
+
+Given the following `main.scss` source:
+
+```scss
+@import "utils/reset";
+@import "utils/layout";
+
+h1 {
+ color: red;
+}
+```
+
+The Sass file outlined above, will be compiled into `public/stylesheets/main.css`. Hence, this file can be used in your template as any regular public asset:
+
+```html
+
+```
+
+## Mixing Sass and web-jars
+
+[WebJars](https://www.webjars.org) enable us to depend on client libraries without pulling all dependencies into our own code base manually.
+
+Compass is a library containing all sorts of reusable functions and mixins for Sass. Unfortunately, this library is targeted towards the Ruby implementation of Sass. There is a number of useful mixins that can be extracted from it. Fortunately, these mixins are wrapped in a web-jar.
+
+To include these compass mixins in your project is as easy as including the web-jar dependency in your library dependencies. For example, within a `build.sbt` file:
+
+```scala
+libraryDependencies += "org.webjars.bower" % "compass-mixins" % "0.12.7"
+```
+
+sbt-web will automatically extract WebJars into a `lib` directory relative to your asset's target directory. Therefore to use the Compass mixins you can import the mixins by:
+
+```scss
+@import "lib/compass-mixins/lib/compass";
+
+table.ellipsed-table {
+ tr td {
+ max-width: 100px;
+ @include ellipsis();
+ }
+}
+```
+
+The same idea can be used to include other Sass libraries, for instance the [official Sass port of bootstrap](https://github.com/twbs/bootstrap-sass). To include the WebJar use:
+
+```scala
+libraryDependencies += "org.webjars.bower" % "bootstrap-sass" % "3.3.6"
+```
+
+Then to use it in your project, you can use:
+
+```scss
+@import "lib/bootstrap-sass/assets/stylesheets/bootstrap";
+```
+
+## Enablement and Configuration
+
+Sass compilation is enabled by simply adding the sbt-sassify plugin to your plugins.sbt file when using the `PlayJava` or `PlayScala` plugins:
+
+```scala
+addSbtPlugin("org.irundaia.sbt" % "sbt-sassify" % "1.4.11")
+```
+
+The plugin's default configuration should normally be sufficient. However please refer to the [plugin's documentation](https://github.com/irundaia/sbt-sassify#options) for information on how it may be configured as well as its latest version.
+
diff --git a/manual/working/commonGuide/assets/RequireJS-support.md b/manual/working/commonGuide/assets/RequireJS-support.md
new file mode 100644
index 00000000..44f69f26
--- /dev/null
+++ b/manual/working/commonGuide/assets/RequireJS-support.md
@@ -0,0 +1,40 @@
+
+# RequireJS
+
+According to [RequireJS](https://requirejs.org/)' website
+
+> RequireJS is a JavaScript file and module loader. It is optimized for in-browser use, but it can be used in other JavaScript environments... Using a modular script loader like RequireJS will improve the speed and quality of your code.
+
+What this means in practice is that one can use [RequireJS](https://requirejs.org/) to modularize your JavaScript. RequireJS achieves this by implementing a semi-standard API called [Asynchronous Module Definition](http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition) (other similar ideas include [CommonJS](http://www.commonjs.org/) ). Using AMD makes it is possible to resolve and load javascript modules on the _client side_ while allowing server side _optimization_. For server side optimization module dependencies may be minified and combined using [UglifyJS 2](https://github.com/mishoo/UglifyJS2#uglifyjs-2).
+
+By convention RequireJS expects a main.js file to bootstrap its module loader.
+
+## Deployment
+
+The RequireJS optimizer shouldn't generally kick-in until it is time to perform a deployment i.e. by running the `start`, `stage` or `dist` tasks.
+
+If you're using WebJars with your build then the RequireJS optimizer plugin will also ensure that any JavaScript resources referenced from within a WebJar are automatically referenced from the [jsdelivr](https://www.jsdelivr.com) CDN. In addition if any `.min.js` file is found then that will be used in place of `.js`. An added bonus here is that there is no change required to your html!
+
+## Enablement and Configuration
+
+RequireJS optimization is enabled by simply adding the plugin to your plugins.sbt file when using the `PlayJava` or `PlayScala` plugins:
+
+```scala
+addSbtPlugin("com.typesafe.sbt" % "sbt-rjs" % "1.0.9")
+```
+
+To add the plugin to the asset pipeline you can declare it as follows (assuming just the one plugin for the pipeline - add others into the sequence such as digest and gzip as required):
+
+```scala
+pipelineStages := Seq(rjs)
+```
+
+A standard build profile for the RequireJS optimizer is provided and should suffice for most projects. However please refer to the [plugin's documentation](https://github.com/sbt/sbt-rjs#sbt-rjs) for information on how it may be configured.
+
+Note that RequireJS performs a lot of work and while it works when executed in-JVM under Trireme, you will be best to use Node.js as the js-engine from a performance perspective. For convenience you can set the `sbt.jse.engineType` property in `SBT_OPTS`. For example on Unix:
+
+```bash
+export SBT_OPTS="$SBT_OPTS -Dsbt.jse.engineType=Node"
+```
+
+Please refer to the [plugin's documentation](https://github.com/sbt/sbt-rjs#sbt-rjs) for information on how it may be configured.
diff --git a/manual/working/commonGuide/assets/code/CommonAssets.scala b/manual/working/commonGuide/assets/code/CommonAssets.scala
new file mode 100644
index 00000000..729e5001
--- /dev/null
+++ b/manual/working/commonGuide/assets/code/CommonAssets.scala
@@ -0,0 +1,8 @@
+/*
+ * Copyright (C) 2009-2019 Lightbend Inc. +> Play uses the `play.ws.ssl` prefix, so that, for instance the `ssl-config.loose.acceptAnyCertificate` becomes `play.ws.ssl.loose.acceptAnyCertificate` for your play `WSClient` configuration. + +## Further Reading + +JSSE is a complex product. For convenience, the JSSE materials are provided here: + +JDK 1.8: + +* [JSSE Reference Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/JSSERefGuide.html) +* [JSSE Crypto Spec](https://docs.oracle.com/javase/8/docs/technotes/guides/security/crypto/CryptoSpec.html#SSLTLS) +* [SunJSSE Providers](https://docs.oracle.com/javase/8/docs/technotes/guides/security/SunProviders.html#SunJSSEProvider) +* [PKI Programmer's Guide](https://docs.oracle.com/javase/8/docs/technotes/guides/security/certpath/CertPathProgGuide.html) +* [keytool](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html) diff --git a/manual/working/commonGuide/configuration/code/Configuration.scala b/manual/working/commonGuide/configuration/code/Configuration.scala new file mode 100644 index 00000000..86ce74a7 --- /dev/null +++ b/manual/working/commonGuide/configuration/code/Configuration.scala @@ -0,0 +1,15 @@ +/* + * Copyright (C) 2009-2019 Lightbend Inc.