* There are two ways of registering a parser: *
* *
* Multibinder<Parser> pcb = Multibinder
.newSetBinder(binder, Parser.class);
pcb.addBinding().to(MyParser.class);
*
* * These are the built-in parsers: *
*application.dateFormat
* property.application.dateFormat
* property.valueOffromNamefromStringString argument
* {
* parser((type, ctx) {@literal ->} {
* if (type.getRawType() == int.class) {
* return ctx
* .param(values {@literal ->} Integer.parseInt(values.get(0))
* .body(body {@literal ->} Integer.parseInt(body.text()));
* }
* return ctx.next();
* });
*
* get("/", req {@literal ->} {
* // use the param strategy
* return req.param("p").intValue();
* });
*
* post("/", req {@literal ->} {
* // use the body strategy
* return req.body().intValue();
* });
* }
*
*
* @author edgar
* @since 0.6.0
*/
interface Builder {
/**
* Add a HTTP body callback. The Callback will be executed when current context is bound to the
* HTTP body via {@link Request#body()}.
*
* If current {@link Context} isn't a HTTP body a call to {@link Context#next()} is made.
*
* @param callback A body parser callback.
* @return This builder.
*/
Builder body(Callbacktext/plain.
*
* @return Current type.
*/
MediaType type();
/**
* Invoke next parser in the chain.
*
* @return A parsed value.
* @throws Exception An err with a 400 status.
*/
Object next() throws Throwable;
/**
* Invoke next parser in the chain and switch/change the target type we are looking for. Useful
* for generic containers classes, like collections or optional values.
*
* @param type A new type to use.
* @return A parsed value.
* @throws Exception An err with a 400 status.
*/
Object next(TypeLiteral type) throws Throwable;
/**
* Invoke next parser in the chain and switch/change the target type we are looking for but also
* the current value. Useful for generic containers classes, like collections or optional
* values.
*
* @param type A new type to use.
* @param data Data to be parsed.
* @return A parsed value.
* @throws Exception An err with a 400 status.
*/
Object next(TypeLiteral type, Object data) throws Throwable;
}
/** Utility function to handle empty values as {@link NoSuchElementException}. */
static Function* Parse one or more values to the required type. If the parser doesn't support the required type * a call to {@link Context#next(TypeLiteral, Object)} must be done. *
* * Example: * *
* Parser converter = (type, ctx) {@literal ->} {
* if (type.getRawType() == MyType.class) {
* // convert to MyType
* return ctx.param(values {@literal ->} new MyType(values.get(0)));
* }
* // no luck! move next
* return ctx.next();
* }
*
*
* It's also possible to create generic/parameterized types too:
*
*
* public class MyContainerType<T> {}
*
* ParamConverter converter = (type, ctx) {@literal ->} {
* if (type.getRawType() == MyContainerType.class) {
* // Creates a new type from current generic type
* TypeLiterale<?> paramType = TypeLiteral
* .get(((ParameterizedType) toType.getType()).getActualTypeArguments()[0]);
*
* // Ask param converter to resolve the new/next type.
* Object result = ctx.next(paramType);
* return new MyType(result);
* }
* // no luck! move next
* return ctx.next();
* }
*
*
* @param type Requested type.
* @param ctx Execution context.
* @return A parsed value.
* @throws Throwable If conversion fails.
*/
Object parse(TypeLiteral type, Context ctx) throws Throwable;
/**
* Overwrite the default bean parser with empty/null supports. The default bean
* parser doesn't allow null, so if a parameter is optional you must declare it as
* {@link Optional} otherwise parsing fails with a 404/500 status code.
*
* For example:
* {@code
*
* public class Book {
*
* public String title;
*
* public Date releaseDate;
*
* public String toString() {
* return title + ":" + releaseDate;
* }
* }
*
* {
* parser(Parser.bean(true));
*
* post("/", req -> {
* return req.params(Book.class).toString();
* });
* }
* }
*
*
* With /?title=Title&releaseDate= prints Title:null.
*
* Now, same call with lenient=false results in Bad Request: 400
* because releaseDate if required and isn't present in the HTTP request.
*
* This feature is useful while submitting forms. *
* * @param lenient Enabled null/empty supports while parsing HTTP params as Java Beans. * @return A new bean parser. */ static Parser bean(final boolean lenient) { return new BeanParser(lenient); } }