diff --git a/akka-docs-dev/rst/java/http/index.rst b/akka-docs-dev/rst/java/http/index.rst index a3547ea710..d2094d0701 100644 --- a/akka-docs-dev/rst/java/http/index.rst +++ b/akka-docs-dev/rst/java/http/index.rst @@ -3,13 +3,39 @@ Akka HTTP ========= +The Akka HTTP modules implement a full server- and client-side HTTP stack on top of *akka-actor* and *akka-stream*. It's +not a web-framework but rather a more general toolkit for providing and consuming HTTP-based services. While interaction +with a browser is of course also in scope it is not the primary focus of Akka HTTP. + +Akka HTTP follows a rather open design and many times offers several different API levels for "doing the same thing". +You get to pick the API level of abstraction that is most suitable for your application. +This means that, if you have trouble achieving something using a high-level API, there's a good chance that you can get +it done with a low-level API, which offers more flexibility but might require you to write more application code. + +Akka HTTP is structured into several modules: + +akka-http-core + A complete, mostly low-level, server- and client-side implementation of HTTP (incl. WebSockets). + Includes a model of all things HTTP. + +akka-http + Higher-level functionality, like (un)marshalling, (de)compression as well as a powerful DSL + for defining HTTP-based APIs on the server-side + +akka-http-testkit + A test harness and set of utilities for verifying server-side service implementations + +akka-http-jackson + Predefined glue-code for (de)serializing custom types from/to JSON with jackson_ + .. toctree:: :maxdepth: 2 - introduction configuration http-model server-side/low-level-server-side-api server-side/websocket-support routing-dsl/index - client-side/index \ No newline at end of file + client-side/index + +.. _jackson: https://github.com/FasterXML/jackson \ No newline at end of file diff --git a/akka-docs-dev/rst/java/http/introduction.rst b/akka-docs-dev/rst/java/http/introduction.rst deleted file mode 100644 index d7080f2a1c..0000000000 --- a/akka-docs-dev/rst/java/http/introduction.rst +++ /dev/null @@ -1,28 +0,0 @@ -Introduction -============ - -The Akka HTTP modules implement a full server- and client-side HTTP stack on top of *akka-actor* and *akka-stream*. It's -not a web-framework but rather a more general toolkit for providing and consuming HTTP-based services. While interaction -with a browser is of course also in scope it is not the primary focus of Akka HTTP. - -Akka HTTP follows a rather open design and many times offers several different API levels for "doing the same thing". -You get to pick the API level of abstraction that is most suitable for your application. -This means that, if you have trouble achieving something using a high-level API, there's a good chance that you can get -it done with a low-level API, which offers more flexibility but might require you to write more application code. - -Akka HTTP is structured into several modules: - -akka-http-core - A complete, mostly low-level, server- and client-side implementation of HTTP (incl. WebSockets) - -akka-http - Higher-level functionality, like (un)marshalling, (de)compression as well as a powerful DSL - for defining HTTP-based APIs on the server-side - -akka-http-testkit - A test harness and set of utilities for verifying server-side service implementations - -akka-http-jackson - Predefined glue-code for (de)serializing custom types from/to JSON with jackson_ - -.. _jackson: https://github.com/FasterXML/jackson diff --git a/akka-docs-dev/rst/java/http/routing-dsl/directives/index.rst b/akka-docs-dev/rst/java/http/routing-dsl/directives/index.rst index c72ee6c145..fdba78b675 100644 --- a/akka-docs-dev/rst/java/http/routing-dsl/directives/index.rst +++ b/akka-docs-dev/rst/java/http/routing-dsl/directives/index.rst @@ -3,4 +3,57 @@ Directives ========== -TODO \ No newline at end of file +A directive is a wrapper for a route or a list of alternative routes that adds one or more of the following +functionality to its nested route(s): + + * it filters the request and lets only matching requests pass (e.g. the `get` directive lets only GET-requests pass) + * it modifies the request or the ``RequestContext`` (e.g. the `path` directives filters on the unmatched path and then + passes an updated ``RequestContext`` unmatched path) + * it modifies the response coming out of the nested route + +akka-http provides a set of predefined directives for various tasks. You can access them by either extending from +``akka.http.javadsl.server.AllDirectives`` or by importing them statically with +``import static akka.http.javadsl.server.Directives.*;``. + +These classes of directives are currently defined: + +BasicDirectives + Contains methods to create routes that complete with a static values or allow specifying :ref:`handlers-java` to + process a request. + +CacheConditionDirectives + Contains a single directive ``conditional`` that wraps its inner route with support for Conditional Requests as defined + by http://tools.ietf.org/html/draft-ietf-httpbis-p4-conditional-26. + +CodingDirectives + Contains directives to decode compressed requests and encode responses. + +CookieDirectives + Contains a single directive ``setCookie`` to aid adding a cookie to a response. + +ExecutionDirectives + Contains directives to deal with exceptions that occurred during routing. + +FileAndResourceDirectives + Contains directives to serve resources from files on the file system or from the classpath. + +HostDirectives + Contains directives to filter on the ``Host`` header of the incoming request. + +MethodDirectives + Contains directives to filter on the HTTP method of the incoming request. + +MiscDirectives + Contains directives that validate a request by user-defined logic. + +PathDirectives + Contains directives to match and filter on the URI path of the incoming request. + +RangeDirectives + Contains a single directive ``withRangeSupport`` that adds support for retrieving partial responses. + +SchemeDirectives + Contains a single directive ``scheme`` to filter requests based on the URI scheme (http vs. https). + +WebsocketDirectives + Contains directives to support answering Websocket requests. \ No newline at end of file diff --git a/akka-docs-dev/rst/java/http/routing-dsl/handlers.rst b/akka-docs-dev/rst/java/http/routing-dsl/handlers.rst index 57b0710f3d..205199db52 100644 --- a/akka-docs-dev/rst/java/http/routing-dsl/handlers.rst +++ b/akka-docs-dev/rst/java/http/routing-dsl/handlers.rst @@ -59,7 +59,7 @@ route structure, this time representing segments from the URI path. Handlers in Java 8 ------------------ -In Java 8 handlers can be provided as function literals. The example from before then looks like this: +In Java 8 handlers can be provided as function literals. The previous example can then be written like this: .. includecode:: /../../akka-http-tests-java8/src/test/java/docs/http/javadsl/server/HandlerExampleSpec.java :include: handler2-example-full diff --git a/akka-docs-dev/rst/java/http/routing-dsl/index.rst b/akka-docs-dev/rst/java/http/routing-dsl/index.rst index 2ec80185ba..bcddb020ed 100644 --- a/akka-docs-dev/rst/java/http/routing-dsl/index.rst +++ b/akka-docs-dev/rst/java/http/routing-dsl/index.rst @@ -3,7 +3,7 @@ High-level Server-Side API ========================== -... +To use the high-level API you need to add a dependency to the ``akka-http-experimental`` module. .. toctree:: :maxdepth: 1 diff --git a/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst b/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst index 678db867e3..e808599e77 100644 --- a/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst +++ b/akka-docs-dev/rst/java/http/routing-dsl/request-vals/index.rst @@ -27,11 +27,19 @@ service. These request values are defined: - * in ``RequestVals``: request values for basic data like URI components, request method, peer address, or the entity data - * in ``Cookies``: request values representing cookies - * in ``FormFields``: request values to access form fields unmarshalled to various primitive Java types - * in ``Headers``:: request values to access request headers or header values - * ``HttpBasicAuthenticator``: an abstract class to implement to create a request value representing a HTTP basic authenticated principal - * in ``Parameters``: request values to access URI paramaters unmarshalled to various primitive Java types - * in ``PathMatchers``: request values to match and access URI path segments - * ``CustomRequestVal``: an abstract class to implement arbitrary custom request values +RequestVals + Contains request values for basic data like URI components, request method, peer address, or the entity data. +Cookies + Contains request values representing cookies. +FormFields + Contains request values to access form fields unmarshalled to various primitive Java types. +Headers + Contains request values to access request headers or header values. +HttpBasicAuthenticator + An abstract class to implement to create a request value representing a HTTP basic authenticated principal. +Parameters + Contains request values to access URI paramaters unmarshalled to various primitive Java types. +PathMatchers + Contains request values to match and access URI path segments. +CustomRequestVal + An abstract class to implement arbitrary custom request values. diff --git a/akka-http/src/main/scala/akka/http/javadsl/server/directives/BasicDirectives.scala b/akka-http/src/main/scala/akka/http/javadsl/server/directives/BasicDirectives.scala index d8589b2dc0..419f976107 100644 --- a/akka-http/src/main/scala/akka/http/javadsl/server/directives/BasicDirectives.scala +++ b/akka-http/src/main/scala/akka/http/javadsl/server/directives/BasicDirectives.scala @@ -7,7 +7,7 @@ package akka.http.javadsl.server.directives import scala.annotation.varargs import java.lang.reflect.{ ParameterizedType, Method } -import akka.http.javadsl.model.{ ContentType, StatusCode, HttpResponse } +import akka.http.javadsl.model.{ Uri, ContentType, StatusCode, HttpResponse } import akka.http.javadsl.server._ import akka.http.impl.server.RouteStructure._ import akka.http.impl.server._ @@ -16,7 +16,7 @@ import scala.concurrent.Future abstract class BasicDirectives { /** - * Tries the given routes in sequence until the first one matches. + * Tries the given route alternatives in sequence until the first one matches. */ @varargs def route(innerRoute: Route, moreInnerRoutes: Route*): Route = @@ -63,6 +63,13 @@ abstract class BasicDirectives { def handle(ctx: RequestContext): RouteResult = ctx.completeAs(marshaller, value) } + /** + * Completes the request with redirection response of the given type to the given URI. + * + * The ``redirectionType`` must be a StatusCode for which ``isRedirection`` returns true. + */ + def redirect(uri: Uri, redirectionType: StatusCode): Route = Redirect(uri, redirectionType) + /** * A route that extracts a value and completes the request with it. */ diff --git a/akka-http/src/main/scala/akka/http/javadsl/server/directives/RouteDirectives.scala b/akka-http/src/main/scala/akka/http/javadsl/server/directives/RouteDirectives.scala deleted file mode 100644 index 4e005935c9..0000000000 --- a/akka-http/src/main/scala/akka/http/javadsl/server/directives/RouteDirectives.scala +++ /dev/null @@ -1,18 +0,0 @@ -/* - * Copyright (C) 2009-2015 Typesafe Inc. - */ - -package akka.http.javadsl.server -package directives - -import akka.http.impl.server.RouteStructure.Redirect -import akka.http.javadsl.model.{ StatusCode, Uri } - -abstract class RouteDirectives extends RangeDirectives { - /** - * Completes the request with redirection response of the given type to the given URI. - * - * The ``redirectionType`` must be a StatusCode for which ``isRedirection`` returns true. - */ - def redirect(uri: Uri, redirectionType: StatusCode): Route = Redirect(uri, redirectionType) -} diff --git a/akka-http/src/main/scala/akka/http/javadsl/server/directives/SchemeDirectives.scala b/akka-http/src/main/scala/akka/http/javadsl/server/directives/SchemeDirectives.scala index 36fbca898e..7678ae04f3 100644 --- a/akka-http/src/main/scala/akka/http/javadsl/server/directives/SchemeDirectives.scala +++ b/akka-http/src/main/scala/akka/http/javadsl/server/directives/SchemeDirectives.scala @@ -9,7 +9,7 @@ import akka.http.javadsl.server.Route import scala.annotation.varargs -abstract class SchemeDirectives extends RouteDirectives { +abstract class SchemeDirectives extends RangeDirectives { /** * Rejects all requests whose Uri scheme does not match the given one. */