Why are routing directives not static methods (in Java)?

Akka Akka HTTP
1

The classes don’t appear to have any state. Using static imports would be more convenient. What about custom directives; do I have to create them all in a single class inheriting everything?

Mark

2

It has to do with how we actually defer all the Java routes to the Scala DSL route implementations behind the scenes in Akka HTTP.

If you are building custom routes and do not need to provide both Java and Scala APIs for them (or just would like to achieve that in some other way) there is no requirement at all to follow this design - static methods are a good option.

3

Seems this is a bug. Are you using the 2.12 build of the library? Which version of Akka?
Seems we missed to have tests that used the static methods style, however it absolutely is a good way and also intended to be working way of using the directives.

This should work, yet didn’t when I just tried on HEAD on 2.12 built Akka HTTP using Java 8:

  public Route example() {
    return AllDirectives.path("hello", () -> // should work, but did not on 10.1.1 + J8 + S2.12
        complete("ok")
    );
  }

I’ll open a bug ticket for it, thanks for reporting.
It relates to an issue that is a bit tricky to sometimes make sure the “static method forwarders” are properly generated in all cases, we will look into it.

For your own directives, yes, absolutely using static methods whenever possible is a very good idea.
Hope this helps and sorry that you bumped into this issue

4

Issue and PR opened, please track it for progress https://github.com/akka/akka-http/pull/1993

5

akka-http_2.12 version 10.1.1 which I think is still the latest version.

Without static methods I might end up with

class TeamOneDirectives extends AllDirectives {
}

class TeamTwoDirectives extends AllDirectives {
}

Now if I want to use both TeamOneDirectives and TeamTwoDirectives I have a problem unless I change one to extend the other. The Scala DSL on the other hand, uses traits and thus avoids the problem.

Mark

6

Thanks for confirming the versions, I confirm it is a bug; at least on 2.12; Yes, it is the latest version indeed.

Yes the classes problem is clear; which is why we intended and documented them to be possible to be used as static import, as mentioned – this is a bug so please track the linked ticket and PR for resolution soon. We will be all traveling home (various flights) in the next day so please allow for some time until we get to it, thanks!

7

Hi Mark,
we just noticed that it actually is all good. We missed one tiny naming detail and were in meetings all last week so under short-attention-span did not notice that mistake.

The static methods are actually available, and no static forwarders bug is present.
The difference is:

  • extends AllDirectives for extending
  • import static Directives.*; for importing them.

Mentioned in some example classes as well:
public class JavaTestServer extends AllDirectives { // or import static Directives.*;

I think we should make this clearer in documentation, so will change the ticket to be about that.
Hope this helps, and thanks for reporting the confusion!