raboof/pekko
1
0
Fork 0
Code Issues Pull requests Projects Releases 6 Packages Wiki Activity Actions 10

=doc complete alphabetical directive listing for scaladsl, improve scaladocs

Browse source
This commit is contained in:
Mathias 2015-06-18 16:03:18 +02:00
parent b4272b77c2
commit fc301396c6
17 changed files with 262 additions and 202 deletions
Download patch file Download diff file Expand all files Collapse all files

4
akka-http/src/main/scala/akka/http/scaladsl/server/directives/BasicDirectives.scala
View file

@ -115,12 +115,12 @@ trait BasicDirectives {
mapRequestContext(_ mapUnmatchedPath f)
/**
* Extracts the unmatched path from the RequestContext.
* Extracts the yet unmatched path from the RequestContext.
*/
def extractUnmatchedPath: Directive1[Uri.Path] = BasicDirectives._extractUnmatchedPath
/**
* Extracts the complete request.
* Extracts the current [[HttpRequest]] instance.
*/
def extractRequest: Directive1[HttpRequest] = BasicDirectives._extractRequest

6
akka-http/src/main/scala/akka/http/scaladsl/server/directives/CodingDirectives.scala
View file

@ -23,14 +23,14 @@ trait CodingDirectives {
/**
* Rejects the request with an UnacceptedResponseEncodingRejection
* if the given encoding is not accepted for the response.
* if the given response encoding is not accepted by the client.
*/
def responseEncodingAccepted(encoding: HttpEncoding): Directive0 =
extract(_.request.isEncodingAccepted(encoding))
.flatMap(if (_) pass else reject(UnacceptedResponseEncodingRejection(Set(encoding))))
/**
* Encodes the response with the encoding that is requested by the client with the `Accept-
* Encodes the response with the encoding that is requested by the client via the `Accept-
* Encoding` header. The response encoding is determined by the rules specified in
* http://tools.ietf.org/html/rfc7231#section-5.3.4.
*
@ -41,7 +41,7 @@ trait CodingDirectives {
encodeResponseWith(NoCoding, Gzip, Deflate)
/**
* Encodes the response with the encoding that is requested by the client with the `Accept-
* Encodes the response with the encoding that is requested by the client via the `Accept-
* Encoding` header. The response encoding is determined by the rules specified in
* http://tools.ietf.org/html/rfc7231#section-5.3.4.
*

12
akka-http/src/main/scala/akka/http/scaladsl/server/directives/CookieDirectives.scala
View file

@ -6,7 +6,7 @@ package akka.http.scaladsl.server
package directives
import akka.http.scaladsl.model._
import headers._
import akka.http.scaladsl.model.headers._
import akka.http.impl.util._
trait CookieDirectives {
@ -15,14 +15,14 @@ trait CookieDirectives {
import RouteDirectives._
/**
* Extracts an HttpCookie with the given name. If the cookie is not present the
* Extracts the [[HttpCookiePair]] with the given name. If the cookie is not present the
* request is rejected with a respective [[MissingCookieRejection]].
*/
def cookie(name: String): Directive1[HttpCookiePair] =
headerValue(findCookie(name)) | reject(MissingCookieRejection(name))
/**
* Extracts an HttpCookie with the given name.
* Extracts the [[HttpCookiePair]] with the given name as an ``Option[HttpCookiePair]``.
* If the cookie is not present a value of `None` is extracted.
*/
def optionalCookie(name: String): Directive1[Option[HttpCookiePair]] =
@ -34,13 +34,13 @@ trait CookieDirectives {
}
/**
* Adds a Set-Cookie header with the given cookies to all responses of its inner route.
* Adds a [[Set-Cookie]] response header with the given cookies.
*/
def setCookie(first: HttpCookie, more: HttpCookie*): Directive0 =
respondWithHeaders((first :: more.toList).map(`Set-Cookie`(_)))
/**
* Adds a Set-Cookie header expiring the given cookies to all responses of its inner route.
* Adds a [[Set-Cookie]] response header expiring the given cookies.
*/
def deleteCookie(first: HttpCookie, more: HttpCookie*): Directive0 =
respondWithHeaders((first :: more.toList).map { c ⇒
@ -48,7 +48,7 @@ trait CookieDirectives {
})
/**
* Adds a Set-Cookie header expiring the given cookie to all responses of its inner route.
* Adds a [[Set-Cookie]] response header expiring the cookie with the given properties.
*/
def deleteCookie(name: String, domain: String = "", path: String = ""): Directive0 =
deleteCookie(HttpCookie(name, "", domain = domain.toOption, path = path.toOption))

9
akka-http/src/main/scala/akka/http/scaladsl/server/directives/DebuggingDirectives.scala
View file

@ -12,12 +12,18 @@ import akka.http.scaladsl.model._
trait DebuggingDirectives {
import BasicDirectives._
/**
* Produces a log entry for every incoming request.
*/
def logRequest(magnet: LoggingMagnet[HttpRequest ⇒ Unit]): Directive0 =
extractRequestContext.flatMap { ctx ⇒
magnet.f(ctx.log)(ctx.request)
pass
}
/**
* Produces a log entry for every [[RouteResult]].
*/
def logResult(magnet: LoggingMagnet[RouteResult ⇒ Unit]): Directive0 =
extractRequestContext.flatMap { ctx ⇒
mapRouteResult { result ⇒
@ -26,6 +32,9 @@ trait DebuggingDirectives {
}
}
/**
* Produces a log entry for every incoming request and [[RouteResult]].
*/
def logRequestResult(magnet: LoggingMagnet[HttpRequest ⇒ RouteResult ⇒ Unit]): Directive0 =
extractRequestContext.flatMap { ctx ⇒
val logResult = magnet.f(ctx.log)(ctx.request)

23
akka-http/src/main/scala/akka/http/scaladsl/server/directives/FileAndResourceDirectives.scala
View file

@ -26,25 +26,22 @@ trait FileAndResourceDirectives {
import RangeDirectives._
/**
* Completes GET requests with the content of the given file. 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 file.
* If the file cannot be found or read the request is rejected.
*/
def getFromFile(fileName: String)(implicit resolver: ContentTypeResolver): Route =
getFromFile(new File(fileName))
/**
* Completes GET requests with the content of the given file. 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 file.
* If the file cannot be found or read the request is rejected.
*/
def getFromFile(file: File)(implicit resolver: ContentTypeResolver): Route =
getFromFile(file, resolver(file.getName))
/**
* Completes GET requests with the content of the given file. 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 file.
* If the file cannot be found or read the request is rejected.
*/
def getFromFile(file: File, contentType: ContentType): Route =
get {
@ -71,18 +68,14 @@ trait FileAndResourceDirectives {
} else pass)
/**
* Completes GET requests with the content of the given resource. The actual I/O operation is
* running detached in a `Future`, so it doesn't block the current thread (but potentially
* some other thread !).
* Completes GET requests with the content of the given class-path resource.
* If the resource cannot be found or read the Route rejects the request.
*/
def getFromResource(resourceName: String)(implicit resolver: ContentTypeResolver): Route =
getFromResource(resourceName, resolver(resourceName))
/**
* Completes GET requests with the content of the given resource. The actual I/O operation is
* running detached in a `Future`, so it doesn't block the current thread (but potentially
* some other thread !).
* Completes GET requests with the content of the given resource.
* If the resource is a directory or cannot be found or read the Route rejects the request.
*/
def getFromResource(resourceName: String, contentType: ContentType, classLoader: ClassLoader = defaultClassLoader): Route =

4
akka-http/src/main/scala/akka/http/scaladsl/server/directives/FormFieldDirectives.scala
View file

@ -16,14 +16,14 @@ trait FormFieldDirectives extends ToNameReceptacleEnhancements {
import FormFieldDirectives._
/**
* Extracts an HTTP form field from the request.
* Rejects the request if the defined form field matcher(s) don't match.
* Otherwise the form field value(s) are extracted and passed to the inner route.
*/
def formField(pdm: FieldMagnet): pdm.Out = pdm()
/**
* Extracts a number of HTTP form field from the request.
* Rejects the request if the defined form field matcher(s) don't match.
* Otherwise the form field value(s) are extracted and passed to the inner route.
*/
def formFields(pdm: FieldMagnet): pdm.Out = pdm()

6
akka-http/src/main/scala/akka/http/scaladsl/server/directives/FutureDirectives.scala
View file

@ -16,7 +16,7 @@ import akka.http.scaladsl.util.FastFuture._
trait FutureDirectives {
/**
* "Unwraps" a ``Future[T]`` and runs its inner route after future
* "Unwraps" a ``Future[T]`` and runs the inner route after future
* completion with the future's value as an extraction of type ``Try[T]``.
*/
def onComplete[T](future: ⇒ Future[T]): Directive1[Try[T]] =
@ -26,7 +26,7 @@ trait FutureDirectives {
}
/**
* "Unwraps" a ``Future[T]`` and runs its inner route after future
* "Unwraps" a ``Future[T]`` and runs the inner route after future
* completion with the future's value as an extraction of type ``T``.
* If the future fails its failure Throwable is bubbled up to the nearest
* ExceptionHandler.
@ -36,7 +36,7 @@ trait FutureDirectives {
def onSuccess(magnet: OnSuccessMagnet): Directive[magnet.Out] = magnet.directive
/**
* "Unwraps" a ``Future[T]`` and runs its inner route when the future has failed
* "Unwraps" a ``Future[T]`` and runs the inner route when the future has failed
* with the future's failure exception as an extraction of type ``Throwable``.
* If the future succeeds the request is completed using the values marshaller
* (This directive therefore requires a marshaller for the futures type to be

4
akka-http/src/main/scala/akka/http/scaladsl/server/directives/HeaderDirectives.scala
View file

@ -40,7 +40,7 @@ trait HeaderDirectives {
def headerValuePF[T](pf: PartialFunction[HttpHeader, T]): Directive1[T] = headerValue(pf.lift)
/**
* Extracts the value of the HTTP request header with the given name.
* Extracts the value of the first HTTP request header with the given name.
* If no header with a matching name is found the request is rejected with a [[spray.routing.MissingHeaderRejection]].
*/
def headerValueByName(headerName: Symbol): Directive1[String] = headerValueByName(headerName.toString)
@ -53,7 +53,7 @@ trait HeaderDirectives {
headerValue(optionalValue(headerName.toLowerCase)) | reject(MissingHeaderRejection(headerName))
/**
* Extracts the HTTP request header of the given type.
* Extracts the first HTTP request header of the given type.
* If no header with a matching type is found the request is rejected with a [[spray.routing.MissingHeaderRejection]].
*/
def headerValueByType[T <: HttpHeader](magnet: ClassMagnet[T]): Directive1[T] =

2
akka-http/src/main/scala/akka/http/scaladsl/server/directives/HostDirectives.scala
View file

@ -13,7 +13,7 @@ trait HostDirectives {
import RouteDirectives._
/**
* Extracts the hostname part of the Host header value in the request.
* Extracts the hostname part of the Host request header value.
*/
def extractHost: Directive1[String] = HostDirectives._extractHost

14
akka-http/src/main/scala/akka/http/scaladsl/server/directives/MethodDirectives.scala
View file

@ -15,37 +15,37 @@ trait MethodDirectives {
import MethodDirectives._
/**
* A route filter that rejects all non-DELETE requests.
* Rejects all non-DELETE requests.
*/
def delete: Directive0 = _delete
/**
* A route filter that rejects all non-GET requests.
* Rejects all non-GET requests.
*/
def get: Directive0 = _get
/**
* A route filter that rejects all non-HEAD requests.
* Rejects all non-HEAD requests.
*/
def head: Directive0 = _head
/**
* A route filter that rejects all non-OPTIONS requests.
* Rejects all non-OPTIONS requests.
*/
def options: Directive0 = _options
/**
* A route filter that rejects all non-PATCH requests.
* Rejects all non-PATCH requests.
*/
def patch: Directive0 = _patch
/**
* A route filter that rejects all non-POST requests.
* Rejects all non-POST requests.
*/
def post: Directive0 = _post
/**
* A route filter that rejects all non-PUT requests.
* Rejects all non-PUT requests.
*/
def put: Directive0 = _put

14
akka-http/src/main/scala/akka/http/scaladsl/server/directives/MiscDirectives.scala
View file

@ -12,33 +12,33 @@ trait MiscDirectives {
import RouteDirectives._
/**
* Returns a Directive which checks the given condition before passing on the [[spray.routing.RequestContext]] to
* its inner Route. If the condition fails the route is rejected with a [[spray.routing.ValidationRejection]].
* Checks the given condition before running its inner route.
* If the condition fails the route is rejected with a [[ValidationRejection]].
*/
def validate(check: ⇒ Boolean, errorMsg: String): Directive0 =
Directive { inner ⇒ if (check) inner() else reject(ValidationRejection(errorMsg)) }
/**
* Directive extracting the IP of the client from either the X-Forwarded-For, Remote-Address or X-Real-IP header
* Extracts the client's IP from either the X-Forwarded-For, Remote-Address or X-Real-IP header
* (in that order of priority).
*/
def extractClientIP: Directive1[RemoteAddress] = MiscDirectives._extractClientIP
/**
* Rejects the request if its entity is not empty.
* Rejects if the request entity is non-empty.
*/
def requestEntityEmpty: Directive0 = MiscDirectives._requestEntityEmpty
/**
* Rejects empty requests with a RequestEntityExpectedRejection.
* Rejects with a [[RequestEntityExpectedRejection]] if the request entity is empty.
* Non-empty requests are passed on unchanged to the inner route.
*/
def requestEntityPresent: Directive0 = MiscDirectives._requestEntityPresent
/**
* Converts responses with an empty entity into (empty) rejections.
* This way you can, for example, have the marshalling of a ''None'' option be treated as if the request could
* not be matched.
* This way you can, for example, have the marshalling of a ''None'' option
* be treated as if the request could not be matched.
*/
def rejectEmptyResponse: Directive0 = MiscDirectives._rejectEmptyResponse
}

10
akka-http/src/main/scala/akka/http/scaladsl/server/directives/ParameterDirectives.scala
View file

@ -15,29 +15,29 @@ trait ParameterDirectives extends ToNameReceptacleEnhancements {
import ParameterDirectives._
/**
* Extracts the requests query parameters as a Map[String, String].
* Extracts the request's query parameters as a ``Map[String, String]``.
*/
def parameterMap: Directive1[Map[String, String]] = _parameterMap
/**
* Extracts the requests query parameters as a Map[String, List[String]].
* Extracts the request's query parameters as a ``Map[String, List[String]]``.
*/
def parameterMultiMap: Directive1[Map[String, List[String]]] = _parameterMultiMap
/**
* Extracts the requests query parameters as a Seq[(String, String)].
* Extracts the request's query parameters as a ``Seq[(String, String)]``.
*/
def parameterSeq: Directive1[immutable.Seq[(String, String)]] = _parameterSeq
/**
* Extracts a query parameter value from the request.
* Rejects the request if the defined query parameter matcher(s) don't match.
* Otherwise the parameter value(s) are extracted and passed to the inner route.
*/
def parameter(pdm: ParamMagnet): pdm.Out = pdm()
/**
* Extracts a number of query parameter values from the request.
* Rejects the request if the defined query parameter matcher(s) don't match.
* Otherwise the parameter value(s) are extracted and passed to the inner route.
*/
def parameters(pdm: ParamMagnet): pdm.Out = pdm()

30
akka-http/src/main/scala/akka/http/scaladsl/server/directives/PathDirectives.scala
View file

@ -15,23 +15,22 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w
import PathMatcher._
/**
* Consumes a leading slash from the unmatched path of the [[akka.http.scaladsl.server.RequestContext]]
* before applying the given matcher. The matcher has to match the remaining path completely
* or leave only a single trailing slash.
* If matched the value extracted by the PathMatcher is extracted on the directive level.
* Applies the given [[PathMatcher]] to the remaining unmatched path after consuming a leading slash.
* The matcher has to match the remaining path completely.
* If matched the value extracted by the [[PathMatcher]] is extracted on the directive level.
*/
def path[L](pm: PathMatcher[L]): Directive[L] = pathPrefix(pm ~ PathEnd)
/**
* Consumes a leading slash from the unmatched path of the [[akka.http.scaladsl.server.RequestContext]]
* before applying the given matcher. The matcher has to match a prefix of the remaining path.
* Applies the given [[PathMatcher]] to a prefix of the remaining unmatched path after consuming a leading slash.
* The matcher has to match a prefix of the remaining path.
* If matched the value extracted by the PathMatcher is extracted on the directive level.
*/
def pathPrefix[L](pm: PathMatcher[L]): Directive[L] = rawPathPrefix(Slash ~ pm)
/**
* Applies the given matcher directly to the unmatched path of the [[akka.http.scaladsl.server.RequestContext]]
* (i.e. without implicitly consuming a leading slash).
* Applies the given matcher directly to a prefix of the unmatched path of the
* [[RequestContext]] (i.e. without implicitly consuming a leading slash).
* The matcher has to match a prefix of the remaining path.
* If matched the value extracted by the PathMatcher is extracted on the directive level.
*/
@ -44,13 +43,13 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w
}
/**
* Checks whether the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] has a prefix matched by the
* Checks whether the unmatchedPath of the [[RequestContext]] has a prefix matched by the
* given PathMatcher. In analogy to the `pathPrefix` directive a leading slash is implied.
*/
def pathPrefixTest[L](pm: PathMatcher[L]): Directive[L] = rawPathPrefixTest(Slash ~ pm)
/**
* Checks whether the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] has a prefix matched by the
* Checks whether the unmatchedPath of the [[RequestContext]] has a prefix matched by the
* given PathMatcher. However, as opposed to the `pathPrefix` directive the matched path is not
* actually "consumed".
*/
@ -63,10 +62,9 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w
}
/**
* Rejects the request if the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] does not have a suffix
* matched the given PathMatcher. If matched the value extracted by the PathMatcher is extracted
* and the matched parts of the path are consumed.
* Note that, for efficiency reasons, the given PathMatcher must match the desired suffix in reversed-segment
* Applies the given [[PathMatcher]] to a suffix of the remaining unmatchedPath of the [[RequestContext]].
* If matched the value extracted by the [[PathMatcher]] is extracted and the matched parts of the path are consumed.
* Note that, for efficiency reasons, the given [[PathMatcher]] must match the desired suffix in reversed-segment
* order, i.e. `pathSuffix("baz" / "bar")` would match `/foo/bar/baz`!
*/
def pathSuffix[L](pm: PathMatcher[L]): Directive[L] = {
@ -78,7 +76,7 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w
}
/**
* Checks whether the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] has a suffix matched by the
* Checks whether the unmatchedPath of the [[RequestContext]] has a suffix matched by the
* given PathMatcher. However, as opposed to the pathSuffix directive the matched path is not
* actually "consumed".
* Note that, for efficiency reasons, the given PathMatcher must match the desired suffix in reversed-segment
@ -93,7 +91,7 @@ trait PathDirectives extends PathMatchers with ImplicitPathMatcherConstruction w
}
/**
* Rejects the request if the unmatchedPath of the [[akka.http.scaladsl.server.RequestContext]] is non-empty,
* Rejects the request if the unmatchedPath of the [[RequestContext]] is non-empty,
* or said differently: only passes on the request to its inner route if the request path
* has been matched completely.
*/

2
akka-http/src/main/scala/akka/http/scaladsl/server/directives/RespondWithDirectives.scala
View file

@ -8,7 +8,7 @@ trait RespondWithDirectives {
import BasicDirectives._
/**
* Overrides the given response status on all HTTP responses of its inner Route.
* Overrides the response status code with the given one.
*/
def overrideStatusCode(responseStatus: StatusCode): Directive0 =
mapResponse(_.copy(status = responseStatus))

4
akka-http/src/main/scala/akka/http/scaladsl/server/directives/SecurityDirectives.scala
View file

@ -41,7 +41,7 @@ trait SecurityDirectives {
optionalHeaderValueByType[Authorization]().map(_.map(_.credentials))
/**
* A directive that wraps the inner route with Http Basic authentication support.
* Wraps the inner route with Http Basic authentication support using a given ``Authenticator[T]``.
* The given authenticator determines whether the credentials in the request are valid
* and, if so, which user object to supply to the inner route.
*/
@ -49,7 +49,7 @@ trait SecurityDirectives {
authenticateBasicAsync(realm, cred ⇒ FastFuture.successful(authenticator(cred)))
/**
* A directive that wraps the inner route with Http Basic authentication support.
* Wraps the inner route with Http Basic authentication support.
* The given authenticator determines whether the credentials in the request are valid
* and, if so, which user object to supply to the inner route.
*/

1
akka-http/src/main/scala/akka/http/scaladsl/server/directives/WebsocketDirectives.scala
View file

@ -9,7 +9,6 @@ import akka.http.scaladsl.model.ws.{ UpgradeToWebsocket, Message }
import akka.stream.scaladsl.Flow
trait WebsocketDirectives {
import BasicDirectives._
import RouteDirectives._
import HeaderDirectives._