diff --git a/akka-docs-dev/rst/images/akka-http-file-listing.png b/akka-docs-dev/rst/images/akka-http-file-listing.png new file mode 100644 index 0000000000..1616f85cf3 Binary files /dev/null and b/akka-docs-dev/rst/images/akka-http-file-listing.png differ diff --git a/akka-docs-dev/rst/java/code/docs/http/javadsl/server/PathDirectiveExampleTest.java b/akka-docs-dev/rst/java/code/docs/http/javadsl/server/PathDirectiveExampleTest.java index ff4224957f..313cdf63c0 100644 --- a/akka-docs-dev/rst/java/code/docs/http/javadsl/server/PathDirectiveExampleTest.java +++ b/akka-docs-dev/rst/java/code/docs/http/javadsl/server/PathDirectiveExampleTest.java @@ -5,7 +5,7 @@ package docs.http.javadsl.server; import akka.http.javadsl.model.StatusCodes; -import akka.http.javadsl.server.*; +import akka.http.javadsl.server.Handler1; import akka.http.javadsl.server.values.PathMatcher; import akka.http.javadsl.server.values.PathMatchers; import akka.http.javadsl.testkit.JUnitRouteTest; @@ -39,12 +39,7 @@ public class PathDirectiveExampleTest extends JUnitRouteTest { // matches "/admin/user/" Handler1 completeWithUserId = - new Handler1() { - @Override - public RouteResult apply(RequestContext ctx, Integer userId) { - return ctx.complete("Hello user " + userId); - } - }; + (ctx, userId) -> ctx.complete("Hello user " + userId); PathMatcher userId = PathMatchers.intValue(); pathPrefix("admin", "user").route( path(userId).route( diff --git a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala index a6d740aedf..39c51fa295 100644 --- a/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala +++ b/akka-docs-dev/rst/scala/code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala @@ -4,27 +4,14 @@ package docs.http.scaladsl.server.directives -import java.io.File - -import akka.event.Logging import akka.http.scaladsl.marshalling.ToEntityMarshaller -import akka.http.scaladsl.model._ -import akka.http.scaladsl.model.headers.RawHeader -import akka.http.scaladsl.server.RouteResult.Rejected -import akka.http.scaladsl.server._ +import akka.http.scaladsl.model.StatusCodes import akka.http.scaladsl.server.directives.DirectoryListing import akka.http.scaladsl.server.directives.FileAndResourceDirectives.DirectoryRenderer -import akka.stream.ActorMaterializer -import akka.stream.io.SynchronousFileSource -import akka.stream.scaladsl.{ Sink, Source } -import akka.util.ByteString import docs.http.scaladsl.server.RoutingSpec -import scala.concurrent.Future -import scala.util.control.NonFatal - class FileAndResourceDirectivesExamplesSpec extends RoutingSpec { - "0getFromFile" in compileOnlySpec { + "getFromFile-examples" in compileOnlySpec { import akka.http.scaladsl.server.directives._ import ContentTypeResolver.Default @@ -34,10 +21,10 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec { } Get("/logs/example") ~> route ~> check { - responseAs[String] shouldEqual "The length of the request URI is 25" + responseAs[String] shouldEqual "example file contents" } } - "0getFromResource" in compileOnlySpec { + "getFromResource-examples" in compileOnlySpec { import akka.http.scaladsl.server.directives._ import ContentTypeResolver.Default @@ -47,10 +34,10 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec { } Get("/logs/example") ~> route ~> check { - responseAs[String] shouldEqual "The length of the request URI is 25" + responseAs[String] shouldEqual "example file contents" } } - "0listDirectoryContents" in compileOnlySpec { + "listDirectoryContents-examples" in compileOnlySpec { val route = path("tmp") { listDirectoryContents("/tmp") @@ -63,7 +50,48 @@ class FileAndResourceDirectivesExamplesSpec extends RoutingSpec { } Get("/logs/example") ~> route ~> check { - responseAs[String] shouldEqual "The length of the request URI is 25" + responseAs[String] shouldEqual "example file contents" + } + } + "getFromBrowseableDirectory-examples" in compileOnlySpec { + val route = + path("tmp") { + getFromBrowseableDirectory("/tmp") + } + + Get("/tmp") ~> route ~> check { + status shouldEqual StatusCodes.OK + } + } + "getFromBrowseableDirectories-examples" in compileOnlySpec { + val route = + path("tmp") { + getFromBrowseableDirectories("/main", "/backups") + } + + + Get("/tmp") ~> route ~> check { + status shouldEqual StatusCodes.OK + } + } + "getFromDirectory-examples" in compileOnlySpec { + val route = + path("tmp") { + getFromDirectory("/tmp") + } + + Get("/tmp/example") ~> route ~> check { + responseAs[String] shouldEqual "example file contents" + } + } + "getFromResourceDirectory-examples" in compileOnlySpec { + val route = + path("examples") { + getFromResourceDirectory("/examples") + } + + Get("/examples/example-1") ~> route ~> check { + responseAs[String] shouldEqual "example file contents" } } diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst index 77766eefc1..bfa18445ed 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectories.rst @@ -3,8 +3,8 @@ getFromBrowseableDirectories ============================ -Serves the content of the given directories as a file system browser, i.e. files are sent and directories -served as browsable listings. +Serves the content of the given directories as a file system browser, +i.e. files are sent and directories served as *browsable* listings. Signature --------- @@ -15,9 +15,19 @@ Signature Description ----------- -The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories (like -``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``. Nesting this directive beneath -``get`` is not necessary as this directive will only respond to ``GET`` requests. +The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories +(like ``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``. -Use ``getFromBrowseableDirectory`` to serve only one directory. Use ``getFromDirectory`` if directory browsing isn't -required. +Nesting this directive beneath ``get`` is not necessary as this directive will only respond to ``GET`` requests. + +Use ``getFromBrowseableDirectory`` to serve only one directory. + +Use ``getFromDirectory`` if directory browsing isn't required. + +For more details refer to :ref:`-getFromBrowseableDirectory-`. + +Example +------- + +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: getFromBrowseableDirectories-examples diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst index 33b86daf7a..ef0ce61900 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromBrowseableDirectory.rst @@ -3,7 +3,8 @@ getFromBrowseableDirectory ========================== -The single-directory variant of :ref:`-getFromBrowseableDirectories-`. +Serves the content of the given directory as a file system browser, +i.e. files are sent and directories served as *browsable* listings. Signature --------- @@ -14,8 +15,40 @@ Signature Description ----------- +The ``getFromBrowseableDirectories`` is a combination of serving files from the specified directories (like +``getFromDirectory``) and listing a browseable directory with ``listDirectoryContents``. + +Nesting this directive beneath ``get`` is not necessary as this directive will only respond to ``GET`` requests. + +Use ``getFromBrowseableDirectory`` to serve only one directory. + +Use ``getFromDirectory`` if directory browsing isn't required. + +For more details refer to :ref:`-getFromBrowseableDirectory-`. + Example ------- -.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/BasicDirectivesExamplesSpec.scala - :snippet: 0extractSettings \ No newline at end of file +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: getFromBrowseableDirectory-examples + + +Default file listing page example +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Directives which list directories (e.g. ``getFromBrowsableDirectory``) use an implicit ``DirectoryRenderer`` +instance to perfm the actual rendering of the file listing. This rendered can be easily overriden by simply +providing one in-scope for the directives to use, so you can build your custom directory listings. + + +The default renderer is ``akka.http.scaladsl.server.directives.FileAndResourceDirectives.defaultDirectoryRenderer``, +and renders a listing which looks like this: + +.. figure:: ../../../../../images/akka-http-file-listing.png + :scale: 75% + :align: center + + Example page rendered by the ``defaultDirectoryRenderer``. + +It's possible to turn off rendering the footer stating which version of Akka HTTP is rendering this page by configuring +the ``akka.http.routing.render-vanity-footer`` configuration option to ``off``. \ No newline at end of file diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst index c9dd753035..ba1c9b6d46 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromDirectory.rst @@ -14,18 +14,27 @@ Signature Description ----------- -The ``unmatchedPath`` of the ``RequestContext`` is first transformed by the given ``pathRewriter`` function before being -appended to the given directory name to build the final file name. +Allows exposing a directory's files for GET requests for its contents. -The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread. If the file cannot -be read the route rejects the request. +The ``unmatchedPath`` (see :ref:`-extractUnmatchedPath-`) of the ``RequestContext`` is first transformed by +the given ``pathRewriter`` function, before being appended to the given directory name to build the final file name. -To serve a single file use ``getFromFile``. To serve browsable directory listings use ``getFromBrowseableDirectories``. -To serve files from a classpath directory use ``getFromResourceDirectory`` instead. +To serve a single file use :ref:`-getFromFile-`. +To serve browsable directory listings use :ref:`-getFromBrowseableDirectories-`. +To serve files from a classpath directory use :ref:`-getFromResourceDirectory-` instead. Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests. +.. note:: + The file's contents will be read using an Akka Streams :class:`SynchronousFileSource` which *automatically uses + a pre-configured dedicated blocking io dispatcher*, which separates the blocking file operations from the rest of the stream. + + Note also that thanks to using Akka Streams internally, the file will be served at the highest spead reachable by + the client, and not faster – i.e. the file will *not* end up being loaded in full into memory before writing it to + the client. + Example ------- -... \ No newline at end of file +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: getFromDirectory-examples \ No newline at end of file diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst index 9616eb00da..6b22a1d1ea 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromFile.rst @@ -14,15 +14,27 @@ Signature Description ----------- -The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread (but potentially -some other thread !). If the file cannot be found or read the request is rejected. +Allows exposing a file to be streamed to the client issuing the request. -To serve files from a directory use ``getFromDirectory``, instead. To serve a file from a classpath resource -use ``getFromResource`` instead. +The ``unmatchedPath`` (see :ref:`-extractUnmatchedPath-`) of the ``RequestContext`` is first transformed by +the given ``pathRewriter`` function, before being appended to the given directory name to build the final file name. + +To files from a given directory use :ref:`-getFromDirectory-`. +To serve browsable directory listings use :ref:`-getFromBrowseableDirectories-`. +To serve files from a classpath directory use :ref:`-getFromResourceDirectory-` instead. Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests. +.. note:: + The file's contents will be read using an Akka Streams :class:`SynchronousFileSource` which *automatically uses + a pre-configured dedicated blocking io dispatcher*, which separates the blocking file operations from the rest of the stream. + + Note also that thanks to using Akka Streams internally, the file will be served at the highest spead reachable by + the client, and not faster – i.e. the file will *not* end up being loaded in full into memory before writing it to + the client. + Example ------- -... \ No newline at end of file +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: getFromFile-examples diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst index 4c18e8bbe7..aa42760924 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResource.rst @@ -14,15 +14,15 @@ Signature Description ----------- -The actual I/O operation is running detached in a ``Future``, so it doesn't block the current thread (but potentially -some other thread !). If the file cannot be found or read the request is rejected. +Completes GET requests with the content of the given classpath resource. -To serve files from a classpath directory use ``getFromResourceDirectory`` instead. To serve files from a filesystem -directory use ``getFromDirectory``, instead. +For details refer to :ref:`getFromFile` which works the same way but obtaining the file from the filesystem +instead of the applications classpath. Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests. Example ------- -... \ No newline at end of file +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: getFromResource-examples \ No newline at end of file diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst index 4b699ca06d..9d798a51f2 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/getFromResourceDirectory.rst @@ -14,15 +14,15 @@ Signature Description ----------- -The actual I/O operation is running detached in a `Future`, so it doesn't block the current thread (but potentially -some other thread !). If the file cannot be found or read the request is rejected. +Completes GET requests with the content of the given classpath resource directory. -To serve a single resource use ``getFromResource``, instead. To server files from a filesystem directory use -``getFromDirectory`` instead. +For details refer to :ref:`getFromDirectory` which works the same way but obtaining the file from the filesystem +instead of the applications classpath. Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests. Example ------- -... \ No newline at end of file +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: getFromResourceDirectory-examples diff --git a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst index f4169c1a5d..d0c4e95807 100644 --- a/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst +++ b/akka-docs-dev/rst/scala/http/routing-dsl/directives/file-and-resource-directives/listDirectoryContents.rst @@ -15,15 +15,19 @@ Signature Description ----------- -The ``listDirectoryContents`` directive renders a response only for directories. To just serve files use -``getFromDirectory``. To serve files and provide a browseable directory listing use ``getFromBrowsableDirectories`` -instead. +The ``listDirectoryContents`` directive renders a response only for directories. -The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``. +To just serve files use :ref:`-getFromDirectory-`. + +To serve files and provide a browseable directory listing use :ref:`-getFromBrowsableDirectories-` instead. + +The rendering can be overridden by providing a custom ``Marshaller[DirectoryListing]``, you can read more about it in +:ref:`-getFromDirectory-` 's documentation. Note that it's not required to wrap this directive with ``get`` as this directive will only respond to ``GET`` requests. Example ------- -... \ No newline at end of file +.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/FileAndResourceDirectivesExamplesSpec.scala + :snippet: listDirectoryContents-examples