{title:'OpenAPI Parsers', updated: '8.2.0,9.0.0'}

The {@link oaj.oapi.OpenApiParser} class is used to convert HTTP parts back into POJOs.

The class hierarchy for the builder of this parser is:

Refer to the builder javadocs for configurable settings.

The following is the previous example of a schema that defines the format of a pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9"):

| import static org.apache.juneau.httppart.HttpPartSchema.*; | | HttpPartSchema schema = tArrayPipes( | tArrayCsv( | tInt64().min(0).max(100).minl(1).maxl(10) | ) | ).build();

The following code shows how the schema above can be used to parse our input into a POJO:

| // Our input being parsed. | String input = "1,2,3|4,5,6|7,8,9" | | // Convert string to a POJO. | try { | Long[][] pojo = OpenApi.to(schema, input, Long[][].class); | } catch (SchemaValidationException e) { | // Oops, one of the restrictions were not met. | }

As a general rule, any POJO convertible from the intermediate type for the type/format of the schema can be parsed using the OpenAPI parser. Here are the rules of POJO types allowed for various type/format combinations:

TypeFormatValid parameter types
string or empty byte
binary
binary-spaced
  • byte[] (default)
  • {@link java.io.InputStream} - Returns a {@link java.io.ByteArrayInputStream}.
  • {@link java.io.Reader} - Returns a {@link java.io.InputStreamReader} wrapped around a {@link java.io.ByteArrayInputStream}.
  • {@link java.lang.String} - Constructed using {@link java.lang.String#String(byte[])}.
  • {@link java.lang.Object} - Returns the default byte[].
  • Any POJO transformable from a byte[] (via constructors or static create methods).
date
date-time
  • {@link java.util.Calendar} (default)
  • {@link java.util.Date}
  • {@link java.util.GregorianCalendar}
  • {@link java.lang.String} - Converted using {@link java.util.Calendar#toString()}.
  • {@link java.lang.Object} - Returns the default {@link java.util.Calendar}.
  • Any POJO transformable from a {@link java.util.Calendar} (via constructors or static create methods).
uon
empty
  • {@link java.lang.String} (default)
  • {@link java.lang.Object} - Returns the default {@link java.lang.String}.
  • Any POJO transformable from a {@link java.lang.String} (via constructors, static create methods, or swaps).
boolean empty
  • {@link java.lang.Boolean} (default)
  • boolean
  • {@link java.lang.String}
  • {@link java.lang.Object} - Returns the default {@link java.lang.Boolean}.
  • Any POJO transformable from a {@link java.lang.Boolean} (via constructors, static create methods, or swaps).
integer int32
  • {@link java.lang.Integer} (default)
  • Any subclass of {@link java.lang.Number}
  • Any primitive number: (e.g int, float...)
  • {@link java.lang.String}
  • {@link java.lang.Object} - Returns the default {@link java.lang.Integer}.
  • Any POJO transformable from an {@link java.lang.Integer} (via constructors, static create methods, or swaps).
int64
  • {@link java.lang.Long} (default)
  • Any subclass of {@link java.lang.Number}
  • Any primitive number: (e.g int, float...)
  • {@link java.lang.String}
  • {@link java.lang.Object} - Returns the default {@link java.lang.Long}.
  • Any POJO transformable from an {@link java.lang.Long} (via constructors, static create methods, or swaps).
number float
  • {@link java.lang.Float} (default)
  • Any subclass of {@link java.lang.Number}
  • Any primitive number: (e.g int, float...)
  • {@link java.lang.String}
  • {@link java.lang.Object} - Returns the default {@link java.lang.Float}.
  • Any POJO transformable from an {@link java.lang.Float} (via constructors, static create methods, or swaps).
double
  • {@link java.lang.Double} (default)
  • Any subclass of {@link java.lang.Number}
  • Any primitive number: (e.g int, float...)
  • {@link java.lang.String}
  • {@link java.lang.Object} - Returns the default {@link java.lang.Double}.
  • Any POJO transformable from an {@link java.lang.Double} (via constructors, static create methods, or swaps).
array empty
  • Arrays or Collections of anything on this list.
  • Any POJO transformable from arrays of the default types (e.g. Integer[], Boolean[][], etc...).
uon
object empty
  • Map<String,Object> (default)
  • Beans with properties of anything on this list.
  • Maps with string keys.
uon

Additionally, any of the type above can also be wrapped as {@link java.util.Optional Optionals}.

For arrays, an example of "Any POJO transformable from arrays of the default types" is:

| // Sample POJO class convertable from a Long[][]. | public class MyPojo { | | // Constructor used by parser. | public MyPojo(Long[][] from2dLongs) {...} | }

In the example above, our POJO class can be constructed from our pipe-delimited list of comma-delimited numbers:

| // Our input being parsed. | String input = "1,2,3|4,5,6|7,8,9" | | // Convert string to a POJO. | try { | MyPojo pojo = OpenApi.to(schema, input, MyPojo.class); | } catch (SchemaValidationException e) { | // Oops, one of the restrictions were not met. | }

Just like serialization, the object type is not officially part of the OpenAPI standard but Juneau supports parsing HTTP parts in UON notation to Maps and beans.

The following shows an example of a bean with several properties of various types.

| public class MyBean { | public String f1; | public byte[] f2; | public byte[] f3; | public byte[] f4; | public Calendar f5; | public String f6; | public int f7; | public Long f8; | public float f9; | public Double f10; | public Boolean f11; | public Object fExtra; | }

We define the following schema again:

| import static org.apache.juneau.httppart.HttpPartSchema.*; | | HttpPartSchema schema = tObject() | .prop("f1", tString()) | .prop("f2", tByte()) | .prop("f3", tBinary()) | .prop("f4", tBinarySpaced()) | .prop("f5", tDateTime()) | .prop("f6", tUon()) | .prop("f7", tInteger()) | .prop("f8", tInt64()) | .prop("f9", tNumber()) | .prop("f10", tDouble()) | .prop("f11", tBoolean()) | .ap(tInteger()) | .build();

Then we parse our input into our POJO:

| String input = | "(f1=foo,f2=Zm9v,f3=666F6F,f4='66 6F 6F',f5=2012-12-21T12:34:56Z,f6=foo," | + "f7=1,f8=2,f9=1.0,f10=1.0,f11=true,fExtra=1)"; | | MyBean bean = OpenApi.to(schema, input, MyBean.class);

Note that serializing into generic Object properties would have produced similar results:

| public class MyBean { | public Object f1; | public Object f2; | public Object f3; | public Object f4; | public Object f5; | public Object f6; | public Object f7; | public Object f8; | public Object f9; | public Object f10; | public Object f11; | public Object fExtra; | }

We can also parse into Maps as well:

| String input = | "(f1=foo,f2=Zm9v,f3=666F6F,f4='66 6F 6F',f5=2012-12-21T12:34:56Z,f6=foo," | + "f7=1,f8=2,f9=1.0,f10=1.0,f11=true,fExtra=1)"; | | JsonMap map = OpenApi.to(schema, input, JsonMap.class);