Skip to content

Commit 490079c

Browse files
jknackjknack
committed
Update doc after renderer and parser
1 parent 08d60b0 commit 490079c

File tree

21 files changed

+303
-139
lines changed

21 files changed

+303
-139
lines changed

‎jooby-ftl/src/main/java/org/jooby/ftl/Ftl.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@
4747
import freemarker.template.TemplateException;
4848

4949
/**
50-
* Exposes a {@link Configuration} and a {@link BodyFormatter}.
50+
* Exposes a {@link Configuration} and a {@link Renderer}.
5151
*
5252
* <h1>usage</h1>
5353
* <p>

‎jooby-hbs/src/main/java/org/jooby/hbs/Hbs.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
import com.typesafe.config.ConfigValueFactory;
5757

5858
/**
59-
* Exposes a {@link Handlebars} and a {@link BodyFormatter}.
59+
* Exposes a {@link Handlebars} and a {@link Renderer}.
6060
*
6161
* <h1>usage</h1>
6262
* <p>

‎jooby-jackson/src/main/java/org/jooby/json/Jackson.java‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,7 @@
5454
* JSON support from the excellent <a href="https://github.com/FasterXML/jackson">Jackson</a>
5555
* library.
5656
*
57-
* This module provides a JSON {@link Parser} and {@link BodyFormatter}, but also an
57+
* This module provides a JSON {@link Parser} and {@link Renderer}, but also an
5858
* {@link ObjectMapper}.
5959
*
6060
* <h1>usage</h1>
@@ -144,8 +144,8 @@ public BodyHandler(final ObjectMapper mapper, final List<MediaType> types) {
144144

145145
@Override
146146
public Object parse(final TypeLiteral<?> type, final Parser.Context ctx) throws Exception {
147-
if (matcher.matches(ctx.type())) {
148-
JavaType javaType = mapper.constructType(type.getType());
147+
JavaType javaType = mapper.constructType(type.getType());
148+
if (matcher.matches(ctx.type()) && mapper.canDeserialize(javaType)) {
149149
return ctx.body(body -> mapper.readValue(body.bytes(), javaType));
150150
}
151151
return ctx.next();

‎jooby/src/main/java/org/jooby/Jooby.java‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -133,15 +133,15 @@
133133
/**
134134
* <h1>Getting Started:</h1>
135135
* <p>
136-
* A new application must extends Jooby, register one ore more {@link BodyFormatter} and some
136+
* A new application must extends Jooby, register one ore more {@link Renderer} and some
137137
* {@link Route routes}. It sounds like a lot of work to do, but it isn't.
138138
* </p>
139139
*
140140
* <pre>
141141
* public class MyApp extends Jooby {
142142
*
143143
* {
144-
* use(new Json()); // 1. JSON serializer.
144+
* renderer(new Json()); // 1. JSON serializer.
145145
*
146146
* // 2. Define a route
147147
* get("/", (req, rsp) {@literal ->} {
@@ -382,8 +382,8 @@
382382
public class Jooby {
383383

384384
/**
385-
* A module can publish or produces: {@link Route.Definition routes}, {@link BodyParser},
386-
* {@link BodyFormatter}, and any other application specific service or contract of your choice.
385+
* A module can publish or produces: {@link Route.Definition routes}, {@link Parser},
386+
* {@link Renderer}, and any other application specific service or contract of your choice.
387387
* <p>
388388
* It is similar to {@link com.google.inject.Module} except for the callback method receives a
389389
* {@link Env}, {@link Config} and {@link Binder}.
@@ -494,7 +494,7 @@ public Jooby() {
494494

495495
/**
496496
* Import ALL the direct routes from the given app. PLEASE NOTE: that ONLY routes are imported.
497-
* {@link Jooby.Module modules}, {@link BodyFormatter formatters}, etc... won't be import it.
497+
* {@link Jooby.Module modules}, {@link Renderer renderers}, etc... won't be import it.
498498
*
499499
* @param app Routes provider.
500500
* @return This jooby instance.
@@ -635,7 +635,7 @@ public Session.Definition session(final Session.Store store) {
635635
}
636636

637637
/**
638-
* Register a new param converter. See {@link ParamConverter} for more details.
638+
* Register a new param converter. See {@link Parser} for more details.
639639
*
640640
* @param parser A parser.
641641
* @return This jooby instance.
@@ -646,7 +646,7 @@ public Jooby parser(final Parser parser) {
646646
}
647647

648648
/**
649-
* Append a response renderer for write HTTP messages.
649+
* Append a response {@link Renderer} for write HTTP messages.
650650
*
651651
* @param renderer A renderer renderer.
652652
* @return This jooby instance.

‎jooby/src/main/java/org/jooby/Parser.java‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
/**
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
119
package org.jooby;
220

321
import java.io.IOException;
@@ -9,9 +27,12 @@
927
import com.google.inject.TypeLiteral;
1028

1129
/**
12-
* Convert a request param (path, query, form) or body to something else.
30+
* Parse a request param (path, query, form) or body to something else.
1331
*
14-
* <h1>Registering a parser</h1> There are two ways of registering a parser:
32+
* <h1>Registering a parser</h1>
33+
* <p>
34+
* There are two ways of registering a parser:
35+
* </p>
1536
*
1637
* <ol>
1738
* <li>Using the {@link Jooby#parser(Parser)} method</li>
@@ -55,7 +76,7 @@ public interface Parser {
5576
*
5677
* @author edgar
5778
*
58-
* @param <T>
79+
* @param <T> Type of data to parse.
5980
* @since 0.6.0
6081
*/
6182
interface Callback<T> {
@@ -72,7 +93,7 @@ interface Callback<T> {
7293
}
7394

7495
/**
75-
* Expose the HTTP body as a serie of bytes or text.
96+
* Expose the HTTP body as a series of bytes or text.
7697
*
7798
* @author edgar
7899
* @since 0.6.0

‎jooby/src/main/java/org/jooby/Renderer.java‎

Lines changed: 109 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
/**
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
119
package org.jooby;
220

321
import java.io.OutputStream;
@@ -7,6 +25,63 @@
725

826
import com.google.common.collect.ImmutableList;
927

28+
/**
29+
* Write a value into the HTTP response and apply a format, if need it.
30+
*
31+
* Renderers are executed in the order they were registered. The first renderer that write a
32+
* response wins!
33+
*
34+
* There are two ways of registering a rendering:
35+
*
36+
* <pre>
37+
* {
38+
* renderer((value, ctx) {@literal ->} {
39+
* ...
40+
* });
41+
* }
42+
* </pre>
43+
*
44+
* Or from inside a module:
45+
*
46+
* <pre>
47+
* {
48+
* use((env, conf, binder) {@literal ->} {
49+
* Multibinder.newSetBinder(binder, Renderer.class)
50+
* .addBinding()
51+
* .toInstance(renderer((value, ctx) {@literal ->} {
52+
* ...
53+
* }));
54+
* });
55+
* }
56+
* </pre>
57+
*
58+
* Inside a {@link Renderer} you can do whatever you want. For example you can check for a specific
59+
* type:
60+
*
61+
* <pre>
62+
* renderer((value, ctx) {@literal ->} {
63+
* if (value instanceof MyObject) {
64+
* ctx.text(value.toString());
65+
* }
66+
* });
67+
* </pre>
68+
*
69+
* For check for the <code>Accept</code> header:
70+
*
71+
* <pre>
72+
* renderer((value, ctx) {@literal ->} {
73+
* if (ctx.accepts("json")) {
74+
* ctx.text(toJson(value));
75+
* }
76+
* });
77+
* </pre>
78+
*
79+
* API is simply and powerful! It is so powerful that you can override any of the existing built-in
80+
* renderers, because application specific renderers has precedence over built-in renderers.
81+
*
82+
* @author edgar
83+
* @since 0.6.0
84+
*/
1085
public interface Renderer {
1186

1287
/**
@@ -47,18 +122,39 @@ interface Text {
47122
void write(java.io.Writer writer) throws Exception;
48123
}
49124

125+
/**
126+
* Contains a few utility methods for doing the actual rendering and writing.
127+
*
128+
* @author edgar
129+
* @since 0.6.0
130+
*/
50131
interface Context {
51132

133+
/**
134+
* @return Request attributes.
135+
*/
52136
Map<String, Object> locals();
53137

138+
/**
139+
* @param type The type to check for.
140+
* @return True if the given type matches the <code>Accept</code> header.
141+
*/
54142
default boolean accepts(final String type) {
55143
return accepts(MediaType.valueOf(type));
56144
}
57145

146+
/**
147+
* @param type The type to check for.
148+
* @return True if the given type matches the <code>Accept</code> header.
149+
*/
58150
default boolean accepts(final MediaType type) {
59151
return accepts(ImmutableList.of(type));
60152
}
61153

154+
/**
155+
* @param types Types to check for.
156+
* @return True if the given type matches the <code>Accept</code> header.
157+
*/
62158
boolean accepts(List<MediaType> types);
63159

64160
/**
@@ -71,14 +167,17 @@ default boolean accepts(final MediaType type) {
71167
Context type(MediaType type);
72168

73169
/**
74-
* Set the <code>Content-Length</code> header IF and ONLY IF, no <code>Content-Length</code>
75-
* was set yet.
170+
* Set the <code>Content-Length</code> header IF and ONLY IF, no <code>Content-Length</code> was
171+
* set yet.
76172
*
77173
* @param length A suggested length to use if one is missing.
78174
* @return This context.
79175
*/
80176
Context length(long length);
81177

178+
/**
179+
* @return Charset to use while writing text responses.
180+
*/
82181
Charset charset();
83182

84183
/**
@@ -100,5 +199,13 @@ default boolean accepts(final MediaType type) {
100199

101200
}
102201

202+
/**
203+
* Render the given value and write the response (if possible). If no response is written, the
204+
* next renderer in the chain will be invoked.
205+
*
206+
* @param object Object to render.
207+
* @param ctx Rendering context.
208+
* @throws Exception If rendering fails.
209+
*/
103210
void render(Object object, Context ctx) throws Exception;
104211
}

‎jooby/src/main/java/org/jooby/Response.java‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -462,8 +462,7 @@ default Response type(final String type) {
462462
}
463463

464464
/**
465-
* Responsible of writing the given body into the HTTP response. The {@link BodyFormatter} that
466-
* best matches the <code>Accept</code> header will be selected for writing the response.
465+
* Responsible of writing the given body into the HTTP response.
467466
*
468467
* @param result The HTTP body.
469468
* @throws Exception If the response write fails.
@@ -482,8 +481,7 @@ default void send(final Object result) throws Exception {
482481
}
483482

484483
/**
485-
* Responsible of writing the given body into the HTTP response. The {@link BodyFormatter} that
486-
* best matches the <code>Accept</code> header will be selected for writing the response.
484+
* Responsible of writing the given body into the HTTP response.
487485
*
488486
* @param result A HTTP response.
489487
* @throws Exception If the response write fails.

‎jooby/src/main/java/org/jooby/internal/BodyReferenceImpl.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
/**
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
119
package org.jooby.internal;
220

321
import java.io.File;

‎jooby/src/main/java/org/jooby/internal/BuiltinParser.java‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
import com.google.common.collect.ImmutableSortedSet;
4444
import com.google.inject.TypeLiteral;
4545

46+
@SuppressWarnings({"unchecked", "rawtypes" })
4647
public enum BuiltinParser implements Parser {
4748

4849
Basic {
@@ -130,7 +131,6 @@ private boolean matches(final TypeLiteral<?> toType) {
130131
&& toType.getType() instanceof ParameterizedType;
131132
}
132133

133-
@SuppressWarnings({"rawtypes", "unchecked" })
134134
@Override
135135
public Object parse(final TypeLiteral<?> type, final Parser.Context ctx) throws Exception {
136136
if (matches(type)) {
@@ -187,7 +187,6 @@ public Object parse(final TypeLiteral<?> type, final Parser.Context ctx)
187187
}
188188
},
189189

190-
@SuppressWarnings({"unchecked", "rawtypes" })
191190
Enum {
192191
@Override
193192
public Object parse(final TypeLiteral<?> type, final Parser.Context ctx)

‎jooby/src/main/java/org/jooby/internal/RenderContextImpl.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
/**
2+
* Licensed to the Apache Software Foundation (ASF) under one
3+
* or more contributor license agreements. See the NOTICE file
4+
* distributed with this work for additional information
5+
* regarding copyright ownership. The ASF licenses this file
6+
* to you under the Apache License, Version 2.0 (the
7+
* "License"); you may not use this file except in compliance
8+
* with the License. You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing,
13+
* software distributed under the License is distributed on an
14+
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15+
* KIND, either express or implied. See the License for the
16+
* specific language governing permissions and limitations
17+
* under the License.
18+
*/
119
package org.jooby.internal;
220

321
import java.io.OutputStream;

0 commit comments

Comments
 (0)