Then the sole method defines a resource endpoint thanks to its @GET annotation (similar annotations are available for other HTTP verbs). The parameter "/message" tells that this endpoint is mounted on /message relative to RESTX base path (/api in this case, this is defined in the web.xml).
The parameter String who defines a query parameter (a parameter that will be provided after the ? in the URL).
The content of the method is called when a matching request is received, and constructs a Message object and returns it, using joda time to get current date / time.
`Message` is not part of RESTX API, it could be any class that Jackson is able to map to JSON. See below to have details on that class in this example.
You can set a breakpoint in this method and run your app in debug to see when this is called. You can also use the open call hierarchy action of your IDE to see the caller of the method. Here is the generated code:
As you can see the code generated by annotation processing is readable, with comments on the type of parameters. The reader/writer registries are used to determine which reader should be used to process request body into an object and writer is used to convert returned Object into a stream in the response body.
Writing routes manually is also possible, though most of the time using annotation processing is fine, it's good to know that you can always fall back to a more low level code. All you need to do for that is declare a component implementing the RestxRoute interface.
The Message class is part of the application domain (it’s also called an entity):
This is a plain Java bean: the toString method is not mandatory, and using fluent setter (which returns this) is not mandatory either.
Binding to JSON is done using the jackson library, check their docs to see how to configure JSON mapping.
You can also use Bean Validation (JSR 303) / Hibernate Validator annotations to add validation to your beans when they are used as body parameters.
What is called a spec in RESTX is a yaml file describing a resource behaviour, or a set of behaviours chained in a scenario.
In the generated app, you can check the should_say_hello.spec.yaml file in src/test/resources/specs/hello:
The notation follows BDD terminology givenwhenthen (wts stands for When ThenS).
In the given section the state of the system before the HTTP requests is described. In this case we only specify the time in ISO format.
Then a list of whenthen pairs follows, the when specify HTTP request, the then HTTP response.
This spec is used for 2 things:
example in the API docs
Because RESTX app follows REST principles, the server has no conversation state. Therefore any HTTP request can be tested in isolation.
The principle of scenario is there mainly to avoid repeating the `given` part too frequently, or also to be able to verify that the system state change after an HTTP request, for example issue a `GET` after a `PUT` to verify that the new resource representation has been stored.
To actually be able to run this spec as a test, it is necessary to write a JUnit test to run it:
As you can see this code is very basic thanks to provided runner and @FindSpecsIn annotation. The comments also show how to use a JUnit rule to do pretty much the same thing but more programmatically.
In either cases the test will start a server on a free port, and verify the spec (i.e. issue HTTP requests and verify the results) against it.
In the AppModule, you will be able to define lots of Application scoped objects, such as :
- An admin password, which will be used to authenticate on the ` RESTX Administration Console
- An application name, which will be used in different ways, particularly by suffixing RESTX Cookies names`
This file is the standard JavaEE web descriptor. It’s used to configure the RESTX servlet:
This file is not needed if you use SimpleFramework integration rather than JavaEE web container.
RESTX module descriptor
RESTX uses its own module descriptor format, which is build tool agnostic. The file is called md.restx.json:
This file is used at build time only, its the source used by RESTX to:
generate Maven POM or Ivy files
download dependencies (with restx deps install or for restx app run)