Skip to content

Commit 2e1f53c

Browse files
jknackjknack
committed
Add javadoc for new public methods
1 parent 95e79f9 commit 2e1f53c

8 files changed

Lines changed: 175 additions & 30 deletions

File tree

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

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -102,23 +102,51 @@ public Environment(@Nonnull ClassLoader classLoader, @Nonnull Config conf,
102102
return null;
103103
}
104104

105+
/**
106+
* List all the properties under the given key. Example:
107+
*
108+
* <pre>
109+
* user.name = "name"
110+
* user.password = "pass"
111+
* </pre>
112+
*
113+
* A call to <code>getProperties("user")</code> give you a map like:
114+
* <code>{user.name: name, user.password: pass}</code>
115+
*
116+
* @param key Key.
117+
* @return Properties under that key or empty map.
118+
*/
105119
public @Nonnull Map<String, String> getProperties(@Nonnull String key) {
106120
return getProperties(key, key);
107121
}
108122

109-
public @Nonnull Map<String, String> getProperties(@Nonnull String key, @Nonnull String prefix) {
123+
/**
124+
* List all the properties under the given key. Example:
125+
*
126+
* <pre>
127+
* user.name = "name"
128+
* user.password = "pass"
129+
* </pre>
130+
*
131+
* A call to <code>getProperties("user", "u")</code> give you a map like:
132+
* <code>{u.name: name, u.password: pass}</code>
133+
*
134+
* @param key Key.
135+
* @param prefix Prefix to use or <code>null</code> for none.
136+
* @return Properties under that key or empty map.
137+
*/
138+
public @Nonnull Map<String, String> getProperties(@Nonnull String key, @Nullable String prefix) {
110139
if (hasPath(conf, key)) {
111140
Map<String, String> settings = new HashMap<>();
141+
String p = prefix == null || prefix.length() == 0 ? "" : prefix + ".";
112142
conf.getConfig(key).entrySet().stream()
113143
.forEach(e -> {
114144
Object value = e.getValue().unwrapped();
115-
if (value != null) {
116-
if (value instanceof List) {
117-
value = ((List) value).stream().collect(Collectors.joining(", "));
118-
}
119-
String k = prefix + "." + e.getKey();
120-
settings.put(k, value.toString());
145+
if (value instanceof List) {
146+
value = ((List) value).stream().collect(Collectors.joining(", "));
121147
}
148+
String k = p + e.getKey();
149+
settings.put(k, value.toString());
122150
});
123151
return settings;
124152
}

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
import static io.jooby.MediaType.json;
1414

1515
/**
16-
* Catch and renderer application errors.
16+
* Catch and encode application errors.
1717
*
1818
* @author edgar
1919
* @since 2.0.0
@@ -97,6 +97,15 @@ public interface ErrorHandler {
9797
};
9898
}
9999

100+
/**
101+
* Build a line error message that describe the current web context and the status code.
102+
*
103+
* <pre>GET /path Status-Code Status-Reason</pre>
104+
*
105+
* @param ctx Web context.
106+
* @param statusCode Status code.
107+
* @return Single line message.
108+
*/
100109
static @Nonnull String errorMessage(@Nonnull Context ctx, @Nonnull StatusCode statusCode) {
101110
return new StringBuilder()
102111
.append(ctx.getMethod())

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -450,7 +450,7 @@ public Jooby errorCode(@Nonnull Class<? extends Throwable> type,
450450
return require(ServiceKey.key(type));
451451
}
452452

453-
public @Nonnull <T> T require(@Nonnull ServiceKey<T> key) {
453+
@Override public @Nonnull <T> T require(@Nonnull ServiceKey<T> key) {
454454
ServiceRegistry services = getServices();
455455
T service = services.getOrNull(key);
456456
if (service == null) {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ public interface Registry {
3939
/**
4040
* Provides an instance of the given type.
4141
*
42-
* @param type Object type.
42+
* @param key Object key.
4343
* @param <T> Object type.
4444
* @return Instance of this type.
4545
* @throws RegistryException If there was a runtime failure while providing an instance.

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

Lines changed: 34 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,34 @@
55
*/
66
package io.jooby;
77

8+
import javax.annotation.Nonnull;
9+
import javax.annotation.Nullable;
810
import java.util.HashMap;
911
import java.util.Map;
1012

11-
public class RequestScope {
13+
/**
14+
* Thread-Local request scope implementation useful for save/store request attribute and access
15+
* to them using a static way.
16+
*
17+
* This is part of public API but usage must be keep to minimum.
18+
*
19+
* @author edgar
20+
*/
21+
public final class RequestScope {
1222

1323
private static final ThreadLocal<Map<Object, Object>> CONTEXT_TL = new ThreadLocal<>();
1424

25+
private RequestScope() {
26+
}
27+
1528
/**
1629
* Check to see if there is already a value associated with the current
1730
* thread for the given key.
1831
*
1932
* @param key The key against which to check for a given value within the current thread.
2033
* @return True if there is currently a session bound.
2134
*/
22-
public static boolean hasBind(Object key) {
35+
public static boolean hasBind(@Nonnull Object key) {
2336
return get(key) != null;
2437
}
2538

@@ -28,21 +41,23 @@ public static boolean hasBind(Object key) {
2841
*
2942
* @param key The key to be bound.
3043
* @param value The value to be bound.
44+
* @param <T> Bind type.
3145
* @return Any previously bound session (should be null in most cases).
3246
*/
33-
public static <T> T bind(Object key, T value) {
34-
return (T) sessionMap(true).put(key, value);
47+
public static @Nullable <T> T bind(@Nonnull Object key, @Nonnull T value) {
48+
return (T) threadMap(true).put(key, value);
3549
}
3650

3751
/**
3852
* Unbinds the session (if one) current associated with the context for the
3953
* given session.
4054
*
4155
* @param key The factory for which to unbind the current session.
56+
* @param <T> Bind type.
4257
* @return The bound session if one, else null.
4358
*/
44-
public static <T> T unbind(Object key) {
45-
final Map<Object, Object> sessionMap = sessionMap();
59+
public static @Nullable <T> T unbind(@Nonnull Object key) {
60+
final Map<Object, Object> sessionMap = threadMap();
4661
T existing = null;
4762
if (sessionMap != null) {
4863
existing = (T) sessionMap.remove(key);
@@ -51,20 +66,27 @@ public static <T> T unbind(Object key) {
5166
return existing;
5267
}
5368

54-
public static <T> T get(Object key) {
55-
final Map<Object, Object> sessionMap = sessionMap();
69+
/**
70+
* Get a previously bind value for the given key or <code>null</code>.
71+
*
72+
* @param key Key.
73+
* @param <T> Object type.
74+
* @return Binded value or <code>null</code>.
75+
*/
76+
public static @Nullable <T> T get(@Nonnull Object key) {
77+
final Map<Object, Object> sessionMap = threadMap();
5678
if (sessionMap == null) {
5779
return null;
5880
} else {
5981
return (T) sessionMap.get(key);
6082
}
6183
}
6284

63-
private static Map<Object, Object> sessionMap() {
64-
return sessionMap(false);
85+
private static Map<Object, Object> threadMap() {
86+
return threadMap(false);
6587
}
6688

67-
private static Map<Object, Object> sessionMap(boolean createMap) {
89+
private static Map<Object, Object> threadMap(boolean createMap) {
6890
Map<Object, Object> sessionMap = CONTEXT_TL.get();
6991
if (sessionMap == null && createMap) {
7092
sessionMap = new HashMap<>();
@@ -74,7 +96,7 @@ private static Map<Object, Object> sessionMap(boolean createMap) {
7496
}
7597

7698
private static void doCleanup() {
77-
final Map<Object, Object> ctx = sessionMap(false);
99+
final Map<Object, Object> ctx = threadMap(false);
78100
if (ctx != null) {
79101
if (ctx.isEmpty()) {
80102
CONTEXT_TL.remove();

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

Lines changed: 46 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@ public interface Handler extends Serializable {
208208
public static final Handler METHOD_NOT_ALLOWED = ctx -> ctx
209209
.sendError(new StatusCodeException(StatusCode.METHOD_NOT_ALLOWED));
210210

211+
/** Handler for {@link StatusCode#NOT_ACCEPTABLE} responses. */
211212
public static final Route.Before ACCEPT = ctx -> {
212213
List<MediaType> produceTypes = ctx.getRoute().getProduces();
213214
MediaType contentType = ctx.accept(produceTypes);
@@ -217,6 +218,7 @@ public interface Handler extends Serializable {
217218
}
218219
};
219220

221+
/** Handler for {@link StatusCode#UNSUPPORTED_MEDIA_TYPE} responses. */
220222
public static final Route.Before SUPPORT_MEDIA_TYPE = ctx -> {
221223
MediaType contentType = ctx.getRequestType();
222224
if (contentType == null) {
@@ -305,7 +307,13 @@ public Route(@Nonnull String method, @Nonnull String pattern, @Nonnull Handler h
305307
return pathKeys;
306308
}
307309

308-
public Route setPathKeys(@Nonnull List<String> pathKeys) {
310+
/**
311+
* Set path keys.
312+
*
313+
* @param pathKeys Path keys or empty list.
314+
* @return This route.
315+
*/
316+
public @Nonnull Route setPathKeys(@Nonnull List<String> pathKeys) {
309317
this.pathKeys = pathKeys;
310318
return this;
311319
}
@@ -351,6 +359,12 @@ public Route setPathKeys(@Nonnull List<String> pathKeys) {
351359
return before;
352360
}
353361

362+
/**
363+
* Set before filter.
364+
*
365+
* @param before Before filter.
366+
* @return This route.
367+
*/
354368
public @Nonnull Route setBefore(@Nullable Before before) {
355369
this.before = before;
356370
return this;
@@ -365,6 +379,12 @@ public Route setPathKeys(@Nonnull List<String> pathKeys) {
365379
return after;
366380
}
367381

382+
/**
383+
* Set after filter.
384+
*
385+
* @param after After filter.
386+
* @return This route.
387+
*/
368388
public @Nonnull Route setAfter(@Nonnull After after) {
369389
this.after = after;
370390
return this;
@@ -379,6 +399,12 @@ public Route setPathKeys(@Nonnull List<String> pathKeys) {
379399
return decorator;
380400
}
381401

402+
/**
403+
* Set route decorator.
404+
*
405+
* @param decorator Decorator.
406+
* @return This route.
407+
*/
382408
public @Nonnull Route setDecorator(@Nullable Decorator decorator) {
383409
this.decorator = decorator;
384410
return this;
@@ -415,6 +441,12 @@ public Route setPathKeys(@Nonnull List<String> pathKeys) {
415441
return renderer;
416442
}
417443

444+
/**
445+
* Set renderer.
446+
*
447+
* @param renderer Renderer.
448+
* @return This route.
449+
*/
418450
public @Nonnull Route setRenderer(@Nonnull Renderer renderer) {
419451
this.renderer = renderer;
420452
return this;
@@ -526,12 +558,23 @@ public Route setPathKeys(@Nonnull List<String> pathKeys) {
526558
return parsers.getOrDefault(contentType.getValue(), Parser.UNSUPPORTED_MEDIA_TYPE);
527559
}
528560

561+
/**
562+
* Route message decoder.
563+
*
564+
* @return Message decoders.
565+
*/
529566
public @Nonnull Map<String, Parser> getParsers() {
530567
return parsers;
531568
}
532569

533-
public @Nonnull Route setParsers(@Nonnull Map<String, Parser> parsers) {
534-
this.parsers = parsers;
570+
/**
571+
* Set message decoders. Map key is a mime-type.
572+
*
573+
* @param decoders message decoder.
574+
* @return This route.
575+
*/
576+
public @Nonnull Route setParsers(@Nonnull Map<String, Parser> decoders) {
577+
this.parsers = decoders;
535578
return this;
536579
}
537580

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,11 @@ public interface ServiceRegistry extends Registry {
2626
*/
2727
@Nonnull Set<ServiceKey<?>> keySet();
2828

29+
/**
30+
* Registered service entries.
31+
*
32+
* @return Service entries.
33+
*/
2934
@Nonnull Set<Map.Entry<ServiceKey<?>, Provider<?>>> entrySet();
3035

3136
/**

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

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,47 @@
55
*/
66
package io.jooby;
77

8+
import javax.annotation.Nonnull;
9+
import javax.annotation.Nullable;
10+
11+
/**
12+
* Find, save and delete a session ID (cookie or header) into/from the web {@link Context}.
13+
*
14+
* @author edgar
15+
*/
816
public interface SessionId {
917

10-
String findSessionId(Context ctx);
18+
/**
19+
* Find session ID.
20+
*
21+
* @param ctx Web context.
22+
* @return Session ID or <code>null</code>.
23+
*/
24+
@Nullable String findSessionId(@Nonnull Context ctx);
1125

12-
void saveSessionId(Context ctx, String sessionId);
26+
/**
27+
* Save session ID in the web context.
28+
*
29+
* @param ctx Web context.
30+
* @param sessionId Session ID to save.
31+
*/
32+
void saveSessionId(@Nonnull Context ctx, @Nonnull String sessionId);
1333

14-
void deleteSessionId(Context ctx, String sessionId);
34+
/**
35+
* Delete session ID in the web context.
36+
*
37+
* @param ctx Web context.
38+
* @param sessionId Session ID to save.
39+
*/
40+
void deleteSessionId(@Nonnull Context ctx, @Nonnull String sessionId);
1541

16-
static SessionId cookie(Cookie cookie) {
42+
/**
43+
* Create a cookie-based Session ID.
44+
*
45+
* @param cookie Cookie template.
46+
* @return Session ID.
47+
*/
48+
static @Nonnull SessionId cookie(@Nonnull Cookie cookie) {
1749
String name = cookie.getName();
1850
return new SessionId() {
1951
@Override public String findSessionId(Context ctx) {
@@ -34,7 +66,13 @@ static SessionId cookie(Cookie cookie) {
3466
};
3567
}
3668

37-
static SessionId header(String name) {
69+
/**
70+
* Create a header-based Session ID.
71+
*
72+
* @param name Header name.
73+
* @return Session ID.
74+
*/
75+
static @Nonnull SessionId header(@Nonnull String name) {
3876
return new SessionId() {
3977
@Override public String findSessionId(Context ctx) {
4078
return ctx.headerMap().get(name);

0 commit comments

Comments
 (0)