Skip to content

Commit 70ad204

Browse files
jknackjknack
committed
more javadoc
1 parent 507ef8f commit 70ad204

File tree

20 files changed

+244
-46
lines changed

20 files changed

+244
-46
lines changed

‎TODO‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
* Review what to do with Result class
77
* Review unit test and document it
88
* Review integration test and document it.
9+
* Review content negation and render method and how to use it from MVC
910

1011
* doc
1112
* api doc

‎jooby/src/main/java/io/jooby/ContentNegotiation.java‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,9 @@
2222
import static io.jooby.MediaType.ALL;
2323
import static io.jooby.MediaType.MOST_SPECIFIC;
2424

25+
/**
26+
* Utility class for doing content negotiation.
27+
*/
2528
public class ContentNegotiation {
2629

2730
Map<MediaType, Throwing.Supplier<Object>> options = new LinkedHashMap<>();

‎jooby/src/main/java/io/jooby/ErrorHandler.java‎

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -26,29 +26,30 @@
2626
import static io.jooby.MediaType.html;
2727
import static io.jooby.MediaType.json;
2828

29+
/**
30+
* Catch and renderer application errors.
31+
*
32+
* @author edgar
33+
* @since 2.0.0
34+
*/
2935
public interface ErrorHandler {
3036

31-
static ErrorHandler log(Logger log, StatusCode... quiet) {
32-
Set<StatusCode> silent = new HashSet<>(Arrays.asList(quiet));
33-
return (ctx, cause, statusCode) -> {
34-
String msg = new StringBuilder()
35-
.append(ctx.getMethod())
36-
.append(" ")
37-
.append(ctx.pathString())
38-
.append(" ")
39-
.append(statusCode.value())
40-
.append(" ")
41-
.append(statusCode.reason())
42-
.toString();
43-
if (silent.contains(statusCode)) {
44-
log.debug(msg, cause);
45-
} else {
46-
log.error(msg, cause);
47-
}
48-
};
49-
}
50-
37+
/**
38+
* Default error handler with support for content-negotiation. It renders a html error page
39+
* or json.
40+
*/
5141
ErrorHandler DEFAULT = (ctx, cause, statusCode) -> {
42+
String msg = new StringBuilder()
43+
.append(ctx.getMethod())
44+
.append(" ")
45+
.append(ctx.pathString())
46+
.append(" ")
47+
.append(statusCode.value())
48+
.append(" ")
49+
.append(statusCode.reason())
50+
.toString();
51+
ctx.getRouter().getLog().error(msg.toLowerCase(), cause);
52+
5253
new ContentNegotiation()
5354
.accept(json, () -> {
5455
String message = Optional.ofNullable(cause.getMessage()).orElse(statusCode.reason());
@@ -98,6 +99,11 @@ static ErrorHandler log(Logger log, StatusCode... quiet) {
9899
@Nonnull void apply(@Nonnull Context ctx, @Nonnull Throwable cause,
99100
@Nonnull StatusCode statusCode);
100101

102+
/**
103+
* Chain this error handler with next and produces a new error handler.
104+
* @param next
105+
* @return
106+
*/
101107
@Nonnull default ErrorHandler then(@Nonnull ErrorHandler next) {
102108
return (ctx, cause, statusCode) -> {
103109
apply(ctx, cause, statusCode);

‎jooby/src/main/java/io/jooby/LogConfigurer.java‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,12 +25,41 @@
2525
import java.util.Map;
2626
import java.util.Optional;
2727

28-
import static java.util.Arrays.asList;
29-
28+
/**
29+
* Utility class that initializes logback or log4j2 logging implementation.
30+
*
31+
* Initializes the <code>logback.configurationFile</code> system property when a
32+
* <code>logback[.env].xml</code> file is found at <code>user.dir/conf</code> directory or
33+
* <code>user.dir</code>.
34+
*
35+
* Initializes the <code>log4j.configurationFile</code> system property when a
36+
* <code>log4j[.env].[ext]</code> file is found at <code>user.dir/conf</code> directory or
37+
* <code>user.dir</code>. Extension can be one of: <code>.xml</code>, <code>.properties</code>,
38+
* <code>.yaml</code> or <code>.json</code>.
39+
*
40+
* NOTE: This class must be call it before instantiating a logger instance. Otherwise, this setup
41+
* is completely ignored.
42+
*
43+
* @since 2.0.0
44+
* @author edgar
45+
*/
3046
public final class LogConfigurer {
3147
private LogConfigurer() {
3248
}
3349

50+
/**
51+
* Initializes the <code>logback.configurationFile</code> system property when a
52+
* <code>logback[.env].xml</code> file is found at <code>user.dir/conf</code> directory or
53+
* <code>user.dir</code>.
54+
*
55+
* Initializes the <code>log4j.configurationFile</code> system property when a
56+
* <code>log4j[.env].[ext]</code> file is found at <code>user.dir/conf</code> directory or
57+
* <code>user.dir</code>. Extension can be one of: <code>.xml</code>, <code>.properties</code>,
58+
* <code>.yaml</code> or <code>.json</code>.
59+
*
60+
* @param names Actives environment names. Useful for choosing an environment specific logging
61+
* configuration file.
62+
*/
3463
public static void configure(@Nonnull List<String> names) {
3564
String[] keys = {"logback.configurationFile", "log4j.configurationFile"};
3665
for (String key : keys) {

‎jooby/src/main/java/io/jooby/QueryString.java‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,26 @@
1515
*/
1616
package io.jooby;
1717

18+
import javax.annotation.Nonnull;
19+
20+
/**
21+
* Query string class for direct MVC parameter provisioning.
22+
*
23+
* @author edgar
24+
* @since 2.0.0
25+
*/
1826
public class QueryString extends Value.Hash {
27+
/** Empty query string. */
1928
public static final QueryString EMPTY = new QueryString("");
2029

2130
private final String queryString;
2231

23-
public QueryString(String queryString) {
32+
/**
33+
* Creates a query string object.
34+
*
35+
* @param queryString Raw string (no decoded it).
36+
*/
37+
public QueryString(@Nonnull String queryString) {
2438
this.queryString = queryString;
2539
}
2640

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

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,34 @@
1818
import javax.annotation.Nonnull;
1919
import java.nio.charset.StandardCharsets;
2020

21+
/**
22+
* Render a route output as byte array.
23+
*
24+
* @author edgar
25+
* @since 2.0.0
26+
*/
2127
public interface Renderer {
2228

29+
/** To string renderer. */
2330
Renderer TO_STRING = (ctx, value) -> value.toString().getBytes(StandardCharsets.UTF_8);
2431

25-
byte[] render(@Nonnull Context ctx, @Nonnull Object value) throws Exception;
32+
/**
33+
* Renderer a value into a byte array or <code>null</code> if given object isn't supported it.
34+
*
35+
* @param ctx Web context.
36+
* @param value Value to render.
37+
* @return Value as byte array or <code>null</code> if given object isn't supported it.
38+
* @throws Exception If something goes wrong.
39+
*/
40+
@Nonnull byte[] render(@Nonnull Context ctx, @Nonnull Object value) throws Exception;
2641

42+
/**
43+
* Execute this renderer only if the <code>Accept</code> header matches the content-type
44+
* parameter.
45+
*
46+
* @param contentType Mediatype to test.
47+
* @return A new renderer with accept header matching.
48+
*/
2749
@Nonnull default Renderer accept(@Nonnull MediaType contentType) {
2850
return (ctx, value) -> {
2951
if (ctx.accept(contentType)) {

‎jooby/src/main/java/io/jooby/ResourceKey.java‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,10 +37,20 @@ private ResourceKey(Class<T> type, String name) {
3737
this.hashCode = Objects.hash(type, name);
3838
}
3939

40+
/**
41+
* Resource type.
42+
*
43+
* @return Resource type.
44+
*/
4045
public @Nonnull Class<T> getType() {
4146
return type;
4247
}
4348

49+
/**
50+
* Resource name or <code>null</code>.
51+
*
52+
* @return Resource name or <code>null</code>.
53+
*/
4454
public @Nullable String getName() {
4555
return name;
4656
}
@@ -64,11 +74,26 @@ private ResourceKey(Class<T> type, String name) {
6474
return type.getName() + "(" + name + ")";
6575
}
6676

67-
public static <T> ResourceKey<T> key(Class<T> type) {
77+
/**
78+
* Creates a resource key.
79+
*
80+
* @param type Resource type.
81+
* @param <T> Type.
82+
* @return A new resource key.
83+
*/
84+
public static @Nonnull <T> ResourceKey<T> key(@Nonnull Class<T> type) {
6885
return new ResourceKey<>(type, null);
6986
}
7087

71-
public static <T> ResourceKey<T> key(Class<T> type, String name) {
88+
/**
89+
* Creates a named resource key.
90+
*
91+
* @param type Resource type.
92+
* @param name Resource name.
93+
* @param <T> Type.
94+
* @return A new resource key.
95+
*/
96+
public static @Nonnull <T> ResourceKey<T> key(@Nonnull Class<T> type, @Nonnull String name) {
7297
return new ResourceKey<>(type, name);
7398
}
7499
}

‎jooby/src/main/java/io/jooby/Sender.java‎

Lines changed: 80 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,24 +16,98 @@
1616
package io.jooby;
1717

1818
import javax.annotation.Nonnull;
19+
import javax.annotation.Nullable;
1920
import java.nio.charset.Charset;
2021
import java.nio.charset.StandardCharsets;
2122

23+
/**
24+
* Non-blocking sender. Reactive responses uses this class to send partial data in non-blocking
25+
* manner.
26+
*
27+
* RxJava example:
28+
*
29+
* <pre>{@code
30+
*
31+
* Sender sender = ctx.getSender();
32+
*
33+
* Flux.fromCallable(...)
34+
* .subscribe(new Subscriber () {
35+
*
36+
* onSubscribe(Subscription s) {
37+
* this.subscription = s;
38+
* this.subscription.request(1);
39+
* }
40+
*
41+
* onNext(Object next) {
42+
* sender.write(next, (ctx, cause) -> {
43+
* subscription.request(1);
44+
* });
45+
* }
46+
*
47+
* onError(Throwable error) {
48+
* subscription.cancel();
49+
* }
50+
*
51+
* onComplete() {
52+
* sender.close();
53+
* }
54+
* })
55+
*
56+
* }</pre>
57+
*
58+
* @since 2.0.0
59+
* @author edgar
60+
*/
2261
public interface Sender {
2362

63+
/**
64+
* Write callback.
65+
*/
2466
interface Callback {
25-
void onComplete(Context ctx, Throwable cause);
67+
/**
68+
* Callback after for <code>write</code> operation.
69+
*
70+
* @param ctx Web context.
71+
* @param cause Cause in case of error or <code>null</code> for success.
72+
*/
73+
void onComplete(@Nonnull Context ctx, @Nullable Throwable cause);
2674
}
2775

28-
default Sender sendString(@Nonnull String data, @Nonnull Callback callback) {
29-
return sendString(data, StandardCharsets.UTF_8, callback);
76+
/**
77+
* Write a string chunk. Chunk is flushed immediately.
78+
*
79+
* @param data String chunk.
80+
* @param callback Callback.
81+
* @return This sender.
82+
*/
83+
@Nonnull default Sender write(@Nonnull String data, @Nonnull Callback callback) {
84+
return write(data, StandardCharsets.UTF_8, callback);
3085
}
3186

32-
default Sender sendString(@Nonnull String data, Charset charset, @Nonnull Callback callback) {
33-
return sendBytes(data.getBytes(charset), callback);
87+
/**
88+
* Write a string chunk. Chunk is flushed immediately.
89+
*
90+
* @param data String chunk.
91+
* @param charset Charset.
92+
* @param callback Callback.
93+
* @return This sender.
94+
*/
95+
@Nonnull default Sender write(@Nonnull String data, @Nonnull Charset charset,
96+
@Nonnull Callback callback) {
97+
return write(data.getBytes(charset), callback);
3498
}
3599

36-
Sender sendBytes(@Nonnull byte[] data, @Nonnull Callback callback);
100+
/**
101+
* Write a bytes chunk. Chunk is flushed immediately.
102+
*
103+
* @param data Bytes chunk.
104+
* @param callback Callback.
105+
* @return This sender.
106+
*/
107+
@Nonnull Sender write(@Nonnull byte[] data, @Nonnull Callback callback);
37108

109+
/**
110+
* Close the sender.
111+
*/
38112
void close();
39113
}

‎jooby/src/main/java/io/jooby/annotations/FormParam.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,5 +39,11 @@
3939
@Retention(RetentionPolicy.RUNTIME)
4040
@Target(ElementType.PARAMETER)
4141
public @interface FormParam {
42+
43+
/**
44+
* Parameter name.
45+
*
46+
* @return Parameter name.
47+
*/
4248
String value() default "";
4349
}

‎jooby/src/main/java/io/jooby/annotations/HeaderParam.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,5 +36,11 @@
3636
@Retention(RetentionPolicy.RUNTIME)
3737
@Target(ElementType.PARAMETER)
3838
public @interface HeaderParam {
39+
40+
/**
41+
* Parameter name.
42+
*
43+
* @return Parameter name.
44+
*/
3945
String value() default "";
4046
}

0 commit comments

Comments
 (0)