Skip to content

Commit 1c0e80b

Browse files
jknackjknack
committed
Documentation of MVC responses #1568 
1 parent 073b68b commit 1c0e80b

File tree

1 file changed

+127
-112
lines changed

1 file changed

+127
-112
lines changed

‎docs/asciidoc/mvc-api.adoc‎

Lines changed: 127 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,112 @@ To create a new MVC project open the `jooby` console and type:
6666
The <<getting-started, jooby console>> takes care of all configuration steps required by the
6767
annotation processing tool.
6868

69+
=== Registration
70+
71+
Mvc routes need to be registered (no classpath scanning). Registration is done from your application
72+
class:
73+
74+
.Simple MVC route registration
75+
[source, java, role = "primary"]
76+
----
77+
public class App extends Jooby {
78+
{
79+
mvc(new MyController());
80+
}
81+
82+
public static void main(String[] args) {
83+
runApp(args, App::new);
84+
}
85+
}
86+
----
87+
88+
.Kotlin
89+
[source, kotlin, role = "secondary"]
90+
----
91+
92+
import io.jooby.*
93+
94+
fun main(args: Array<String>) {
95+
runApp(args) {
96+
mvc(MyController())
97+
}
98+
}
99+
----
100+
101+
The javadoc:Jooby[mvc, java.lang.Object] install the mvc route. As showed in the example there is
102+
no dependency injection involved, you just instantiate a MVC route and register.
103+
104+
.Class MVC route registration
105+
[source, java, role = "primary"]
106+
----
107+
public class App extends Jooby {
108+
{
109+
mvc(MyController.class);
110+
}
111+
112+
public static void main(String[] args) {
113+
runApp(args, App::new);
114+
}
115+
}
116+
----
117+
118+
.Kotlin
119+
[source, kotlin, role = "secondary"]
120+
----
121+
122+
import io.jooby.*
123+
124+
fun main(args: Array<String>) {
125+
runApp(args) {
126+
mvc(MyController::class)
127+
}
128+
}
129+
----
130+
131+
The javadoc:Jooby[mvc, java.lang.Class] does the same job, but delegates route instantiation to a
132+
dependency injection framework of your choice.
133+
134+
NOTE: Jooby 1.x was built around Guice, this is not the case for 2.x. The entire project was built
135+
without dependency injection. This make DI optional and at same time give you freedom to choose the
136+
one you like most.
137+
138+
.Provider MVC route registration
139+
[source, java, role = "primary"]
140+
----
141+
142+
import javax.inject.Provider;
143+
144+
public class App extends Jooby {
145+
{
146+
Provider<MyController> provider = ...;
147+
148+
mvc(MyController.class, provider);
149+
}
150+
151+
public static void main(String[] args) {
152+
runApp(args, App::new);
153+
}
154+
}
155+
----
156+
157+
.Kotlin
158+
[source, kotlin, role = "secondary"]
159+
----
160+
import javax.inject.Provider
161+
import io.jooby.*
162+
163+
fun main(args: Array<String>) {
164+
runApp(args) {
165+
val provider = ...
166+
mvc(MyController::class, provider)
167+
}
168+
}
169+
----
170+
171+
The javadoc:Jooby[mvc, javax.inject.Provider] does the same job, might or might not delegate
172+
instantiation to a dependency injection framework but most important let you control lifecycle of
173+
MVC routes (Singleton vs Non-Singleton routes).
174+
69175
=== Parameters
70176

71177
HTTP parameter provision is available via `*Param` annotations.
@@ -450,111 +556,45 @@ class MyController {
450556

451557
<1> All context attributes must be set as arguments. They must be declared as `Map<String, Object>`
452558

453-
=== Registration
454-
455-
Mvc routes need to be registered (no classpath scanning). Registration is done from your application
456-
class:
457-
458-
.Simple MVC route registration
459-
[source, java, role = "primary"]
460-
----
461-
public class App extends Jooby {
462-
{
463-
mvc(new MyController());
464-
}
465-
466-
public static void main(String[] args) {
467-
runApp(args, App::new);
468-
}
469-
}
470-
----
471-
472-
.Kotlin
473-
[source, kotlin, role = "secondary"]
474-
----
475-
476-
import io.jooby.*
477-
478-
fun main(args: Array<String>) {
479-
runApp(args) {
480-
mvc(MyController())
481-
}
482-
}
483-
----
484-
485-
The javadoc:Jooby[mvc, java.lang.Object] install the mvc route. As showed in the example there is
486-
no dependency injection involved, you just instantiate a MVC route and register.
559+
=== Responses
487560

488-
.Class MVC route registration
489-
[source, java, role = "primary"]
490-
----
491-
public class App extends Jooby {
492-
{
493-
mvc(MyController.class);
494-
}
561+
==== Status Code
495562

496-
public static void main(String[] args) {
497-
runApp(args, App::new);
498-
}
499-
}
500-
----
563+
The default status code is `Success(200)`, except for `void` methods with the `@DELETE` annotation which is set to `No Content(204)`.
501564

502-
.Kotlin
503-
[source, kotlin, role = "secondary"]
504-
----
565+
There are two options if you need a different status code:
505566

506-
import io.jooby.*
567+
- Add a javadoc:Context[] parameter and set the javadoc:Context[setResponseCode, io.jooby.StatusCode]
568+
- Returns a javadoc:StatusCode[] instance
507569

508-
fun main(args: Array<String>) {
509-
runApp(args) {
510-
mvc(MyController::class)
511-
}
512-
}
513-
----
570+
==== NonBlocking
514571

515-
The javadoc:Jooby[mvc, java.lang.Class] does the same job, but delegates route instantiation to a
516-
dependency injection framework of your choice.
572+
Method returning a `CompletableFuture`, `Single`, `Maybe`, `Flowable`, `Mono` or `Flux` is
573+
considered a non-blocking route.
517574

518-
NOTE: Jooby 1.x was built around Guice, this is not the case for 2.x. The entire project was built
519-
without dependency injection. This make DI optional and at same time give you freedom to choose the
520-
one you like most.
575+
Kotlin suspend functions are supported too:
521576

522-
.Provider MVC route registration
523-
[source, java, role = "primary"]
577+
.Kotlin Coroutines
578+
[source, kotlin]
524579
----
525-
526-
import javax.inject.Provider;
527-
528-
public class App extends Jooby {
529-
{
530-
Provider<MyController> provider = ...;
531-
532-
mvc(MyController.class, provider);
533-
}
534-
535-
public static void main(String[] args) {
536-
runApp(args, App::new);
580+
class SuspendMvc {
581+
@GET
582+
@Path("/delay")
583+
suspend fun delayed(ctx: Context): String {
584+
delay(100)
585+
return ctx.getRequestPath()
537586
}
538587
}
539-
----
540-
541-
.Kotlin
542-
[source, kotlin, role = "secondary"]
543-
----
544-
import javax.inject.Provider
545-
import io.jooby.*
546588
547589
fun main(args: Array<String>) {
548590
runApp(args) {
549-
val provider = ...
550-
mvc(MyController::class, provider)
591+
use(SuspendMvc())
551592
}
552593
}
553594
----
554595

555-
The javadoc:Jooby[mvc, javax.inject.Provider] does the same job, might or might not delegate
556-
instantiation to a dependency injection framework but most important let you control lifecycle of
557-
MVC routes (Singleton vs Non-Singleton routes).
596+
A non-blocking route run on the event loop (by default) where *blocking is NOT allowed*. For more
597+
details please checkout the <<responses-nonblocking, non-blocking responses>> section.
558598

559599
=== Execution model
560600

@@ -725,31 +765,6 @@ Executor must be registered using via services or executor utility method:
725765

726766
The executor must be registered before the MVC route/controller.
727767

728-
=== Suspend functions
729-
730-
For Kotlin users MVC routes are allowed to use suspend functions
731-
732-
.Kotlin Coroutines
733-
[source, kotlin]
734-
----
735-
class SuspendMvc {
736-
@GET
737-
@Path("/delay")
738-
suspend fun delayed(ctx: Context): String {
739-
delay(100)
740-
return ctx.getRequestPath()
741-
}
742-
}
743-
744-
fun main(args: Array<String>) {
745-
runApp(args) {
746-
use(SuspendMvc())
747-
}
748-
}
749-
----
750-
751-
{love}
752-
753768
=== JAX-RS Annotations
754769

755770
Alternative you can use JAX-RS annotations to define MVC routes.

0 commit comments

Comments
 (0)