org.jooby

Interface Parser

public interface Parser

Parse a request param (path, query, form) or body to something else.

Registering a parser

There are two ways of registering a parser:

1. Using the Jooby.parser(Parser) method
2. From a Guice module:

      Multibinder<Parser> pcb = Multibinder
           .newSetBinder(binder, Parser.class);
        pcb.addBinding().to(MyParser.class);
    

Parsers are executed in the order they were registered. The first converter that resolved the type: wins!.

Built-in parsers

These are the built-in parsers:

1. Primitives and String: convert to int, double, char, string, etc...
2. Enums (case-sensitive)
3. Date: It parses a date using the application.dateFormat property.
4. LocalDate: It parses a date using the application.dateFormat property.
5. Locale
6. Classes with a static method: valueOf
7. Classes with a static method: fromName
8. Classes with a static method: fromString
9. Classes with a public constructor with one String argument
10. It is an Optional<T>, List<T>, Set<T> or SortedSet<T> where T satisfies one of previous rules

Since:

0.6.0

Author:

edgar

See Also:

Jooby.parser(Parser)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Parser.BodyReference Expose the HTTP body as a series of bytes or text.
static interface	Parser.Builder A parser can be executed against a simply HTTP param, a set of HTTP params, an file Upload or HTTP Parser.BodyReference.
static interface	Parser.Callback<T> A parser callback.
static interface	Parser.Context Allows you to access to parsing strategies, content type view Parser.Context.type() and invoke next parser in the chain via Parser.Context.next() methods.
static interface	Parser.ParamReference<T> Expose HTTP params from path, query, form url encoded or multipart request as a raw string.

Field Summary

Fields

Modifier and Type	Field and Description
static Function<String,String>	NOT_EMPTY Utility function to handle empty values as NoSuchElementException.

Method Summary

Modifier and Type	Method and Description
static Parser	bean(boolean lenient) Overwrite the default bean parser with empty/null supports.
Object	parse(com.google.inject.TypeLiteral<?> type, Parser.Context ctx) Parse one or more values to the required type.

Field Detail

NOT_EMPTY

static final Function<String,String> NOT_EMPTY

Utility function to handle empty values as NoSuchElementException.

Method Detail

parse

Object parse(com.google.inject.TypeLiteral<?> type,
             Parser.Context ctx)
      throws Throwable

Parse one or more values to the required type. If the parser doesn't support the required type a call to Parser.Context.next(TypeLiteral, Object) must be done.

Example:

  Parser converter = (type, ctx)  -> {
    if (type.getRawType() == MyType.class) {
      // convert to MyType
      return ctx.param(values  -> 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)  -> {
    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();
  }
 

Parameters:

type - Requested type.

ctx - Execution context.

Returns:

A parsed value.

Throws:

Throwable - If conversion fails.

bean

static Parser bean(boolean lenient)

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 Optional otherwise parsing fails with a 404/500 status code. For example:

 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.

Parameters:

lenient - Enabled null/empty supports while parsing HTTP params as Java Beans.

Returns:

A new bean parser.