pekko/akka-docs/rst/java/http/routing-dsl/directives/path-directives/path.rst

.. _-path-java-:

path
====

Description
-----------
Matches the complete unmatched path of the ``RequestContext`` against the given ``PathMatcher``, potentially extracts
one or more values (depending on the type of the argument).

This directive filters incoming requests based on the part of their URI that hasn't been matched yet by other
potentially existing :ref:`-pathPrefix-java-` directives on higher levels of the routing structure.
Its one parameter is usually an expression evaluating to a ``PathMatcher`` instance (see also: :ref:`pathmatcher-dsl`).

As opposed to the :ref:`-rawPathPrefix-java-` or :ref:`-rawPathPrefixTest-java-` directives ``path`` automatically adds a leading
slash to its ``PathMatcher`` argument, you therefore don't have to start your matching expression with an explicit slash.

The ``path`` directive attempts to match the **complete** remaining path, not just a prefix. If you only want to match
a path prefix and then delegate further filtering to a lower level in your routing structure use the :ref:`-pathPrefix-java-`
directive instead. As a consequence it doesn't make sense to nest a ``path`` or :ref:`-pathPrefix-java-` directive
underneath another ``path`` directive, as there is no way that they will ever match (since the unmatched path underneath
a ``path`` directive will always be empty).

Depending on the type of its ``PathMatcher`` argument the ``path`` directive extracts zero or more values from the URI.
If the match fails the request is rejected with an :ref:`empty rejection set <empty rejections>`.

.. note:: The empty string (also called empty word or identity) is a **neutral element** of string concatenation operation,
 so it will match everything, but remember that ``path`` requires whole remaining path being matched, so (``/``) will succeed
 and (``/whatever``) will fail. The :ref:`-pathPrefix-java-` provides more liberal behaviour.


Example
-------
TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.
!htp #18919 #19519 New JavaDSL for Akka HTTP (#20518) * !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 2016-05-16 10:38:40 +02:00			`.. _-path-java-:`

			`path`
			`====`

			`Description`
			`-----------`
			Matches the complete unmatched path of the ``RequestContext`` against the given ``PathMatcher``, potentially extracts
			`one or more values (depending on the type of the argument).`

			`This directive filters incoming requests based on the part of their URI that hasn't been matched yet by other`
			potentially existing :ref:`-pathPrefix-java-` directives on higher levels of the routing structure.
			Its one parameter is usually an expression evaluating to a ``PathMatcher`` instance (see also: :ref:`pathmatcher-dsl`).

			As opposed to the :ref:`-rawPathPrefix-java-` or :ref:`-rawPathPrefixTest-java-` directives ``path`` automatically adds a leading
			slash to its ``PathMatcher`` argument, you therefore don't have to start your matching expression with an explicit slash.

			The ``path`` directive attempts to match the complete remaining path, not just a prefix. If you only want to match
			a path prefix and then delegate further filtering to a lower level in your routing structure use the :ref:`-pathPrefix-java-`
			directive instead. As a consequence it doesn't make sense to nest a ``path`` or :ref:`-pathPrefix-java-` directive
			underneath another ``path`` directive, as there is no way that they will ever match (since the unmatched path underneath
			a ``path`` directive will always be empty).

			Depending on the type of its ``PathMatcher`` argument the ``path`` directive extracts zero or more values from the URI.
			If the match fails the request is rejected with an :ref:`empty rejection set <empty rejections>`.

+doc #20521 Enrich docs and tests regarding empty strings used in matchers (#20719) 2016-06-08 15:20:21 +02:00			`.. note:: The empty string (also called empty word or identity) is a neutral element of string concatenation operation,`
			so it will match everything, but remember that ``path`` requires whole remaining path being matched, so (``/``) will succeed
			and (``/whatever``) will fail. The :ref:`-pathPrefix-java-` provides more liberal behaviour.

!htp #18919 #19519 New JavaDSL for Akka HTTP (#20518) * !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 2016-05-16 10:38:40 +02:00
			`Example`
			`-------`
			TODO: Example snippets for JavaDSL are subject to community contributions! Help us complete the docs, read more about it here: `write example snippets for Akka HTTP Java DSL #20466 <https://github.com/akka/akka/issues/20466>`_.