29029be31d
* !htt #18919 #19519 Align Java HTTP server DSL with Scala This commits replaces the Java HTTP server DSL with a Java-8 centric one which exposes all scala DSL concepts to be usable from Java, including custom directives, (un)marshallers, rejections, headers, and type safety for path and query parameters. * Add RequestContext and RouteResult to Java DSL fix websockets WIP bring java docs up to date. This applies some updates to the root-level documentation * [htp] Fix java documentation to correctly mention timeouts Timeouts are configured the same in Java and Scala. Hence, linking to the scala docs for timeouts from Java. * =htc fix optionalHeaderValueByType in Java * =htt #20200 fix java testkit always using NoLogging instead logger * +htt actually run new javadsl tests, allow overriding config * =htt improve javadsl test infra with more details when fails * =htt fix bug in wrong path matcher exposed * +htp add missing remaining path matcher * =htp Java DSL cookie tests fixed * =htt Java DSL ParameterDirectivesTest fixed Protect the tweets from scalariform Incorrect response expectations in cache condition directives spec fixed * =htt Path directives for Java DSL * +!htt PathMatchers rewritten, made uniform and tests passing * Bugfix in java reject and a little test-boyscouting * Revert "Incorrect response expectations in cache condition directives spec fixed" This reverts commit cd50e89d45db010309f8249b090ea654ebb11c7a. * +htc HttpAPIsTest is compile time only, not for running Also, moved from the client package since not strictly a client test. SecurityDirectives passing Two faulty tests and two actual bugs. Fix for cache condition spec not working * Not sending in Unit instad of the implicit magnet in the test * HeaderMagnet now works as expected * Java API added for - and + on DateTime PetStore example and test fixed * Annotations to make marshalling work without default constructor * Made model class immutable Incorrect tests fixed Some scaladoc boyscouting as bonus * =htt RequestValTest sprinkled out across multiple directive tests Client ip extraction test with incorrect header name fixed. * =htt Incorrect CodingDirectivesTest fixed. * =htt Bugfix for Java Unmarshaller.firstOf and fixes to JavaRouteTest * =htt MarshallerTest fixed * Missing seal signature added to JavaDSL * More consistent (with Scala) test kit setup for Java * missing Javadocs added * Thread.sleep in default exception handler removed * =htt copy directive docs, prepare for finishing it up * +htt SecurityDirectives.authorize variants and test coverage added * +htt Custom headers in Java DSL * =htt WIP on java docs * +htp add missing parameterOrDefault directive Fixed a lot of doc warnings * =htc intense progress on javadsl docs * =htc #20470 Link to issue about docs and fix compile error compile, migration guide don't mima check http-experimental * =htt Java DSL doc warnings fixed. Only `Could not lex literal_block` ones left now * =htc fix mima settings * =doc fix MethodDirectives doc test with custom method * =htc fix coding directives spec after bad merge * =htc fix concat being corresponding to route() in javadsl * =htt Disable consistency check for route/concat as it fails only on ci server * !htt Minor fixes to PathMatchers
107 lines
4.1 KiB
ReStructuredText
107 lines
4.1 KiB
ReStructuredText
.. _-parameters-scala-:
|
|
|
|
parameters
|
|
==========
|
|
|
|
Signature
|
|
---------
|
|
|
|
::
|
|
|
|
def parameters(param: <ParamDef[T]>): Directive1[T]
|
|
def parameters(params: <ParamDef[T_i]>*): Directive[T_0 :: ... T_i ... :: HNil]
|
|
def parameters(params: <ParamDef[T_0]> :: ... <ParamDef[T_i]> ... :: HNil): Directive[T_0 :: ... T_i ... :: HNil]
|
|
|
|
The signature shown is simplified and written in pseudo-syntax, the real signature uses magnets. [1]_ The type
|
|
``<ParamDef>`` doesn't really exist but consists of the syntactic variants as shown in the description and the examples.
|
|
|
|
.. [1] See `The Magnet Pattern`_ for an explanation of magnet-based overloading.
|
|
.. _`The Magnet Pattern`: http://spray.io/blog/2012-12-13-the-magnet-pattern/
|
|
|
|
Description
|
|
-----------
|
|
The parameters directive filters on the existence of several query parameters and extract their values.
|
|
|
|
Query parameters can be either extracted as a String or can be converted to another type. The parameter name
|
|
can be supplied either as a String or as a Symbol. Parameter extraction can be modified to mark a query parameter
|
|
as required, optional, or repeated, or to filter requests where a parameter has a certain value:
|
|
|
|
``"color"``
|
|
extract value of parameter "color" as ``String``
|
|
``"color".?``
|
|
extract optional value of parameter "color" as ``Option[String]``
|
|
``"color" ? "red"``
|
|
extract optional value of parameter "color" as ``String`` with default value ``"red"``
|
|
``"color" ! "blue"``
|
|
require value of parameter "color" to be ``"blue"`` and extract nothing
|
|
``"amount".as[Int]``
|
|
extract value of parameter "amount" as ``Int``, you need a matching ``Deserializer`` in scope for that to work
|
|
(see also :ref:`http-unmarshalling-scala`)
|
|
``"amount".as(deserializer)``
|
|
extract value of parameter "amount" with an explicit ``Deserializer``
|
|
``"distance".*``
|
|
extract multiple occurrences of parameter "distance" as ``Iterable[String]``
|
|
``"distance".as[Int].*``
|
|
extract multiple occurrences of parameter "distance" as ``Iterable[Int]``, you need a matching ``Deserializer`` in scope for that to work
|
|
(see also :ref:`http-unmarshalling-scala`)
|
|
``"distance".as(deserializer).*``
|
|
extract multiple occurrences of parameter "distance" with an explicit ``Deserializer``
|
|
|
|
You can use :ref:`Case Class Extraction` to group several extracted values together into a case-class
|
|
instance.
|
|
|
|
Requests missing a required parameter or parameter value will be rejected with an appropriate rejection.
|
|
|
|
There's also a singular version, :ref:`-parameter-`. Form fields can be handled in a similar way, see ``formFields``. If
|
|
you want unified handling for both query parameters and form fields, see ``anyParams``.
|
|
|
|
Examples
|
|
--------
|
|
|
|
Required parameter
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: required-1
|
|
|
|
Optional parameter
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: optional
|
|
|
|
Optional parameter with default value
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: optional-with-default
|
|
|
|
Parameter with required value
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: required-value
|
|
|
|
Deserialized parameter
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: mapped-value
|
|
|
|
Repeated parameter
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: repeated
|
|
|
|
CSV parameter
|
|
^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: csv
|
|
|
|
Repeated, deserialized parameter
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/ParameterDirectivesExamplesSpec.scala
|
|
:snippet: mapped-repeated
|