{8.2.0-updated} OpenAPI Methodology

Unlike the other Juneau serializers and parsers that convert input and output directly to-and-from POJOs, the OpenAPI serializers and parsers use intermediate objects based on the type and format of the schema.

The following table shows the "natural" intermediate type of the object based on the type/format:

Type | Format | Intermediate Java Type
--- | --- | ---
string or empty | byte binary binary-spaced | byte[]
date date-time | {@link java.util.Calendar}
uon | No intermediate type. (serialized directly to/from POJO)
empty | {@link java.lang.String}
boolean | empty | {@link java.lang.Boolean}
integer | int32 | {@link java.lang.Integer}
int64 | {@link java.lang.Long}
number | float | {@link java.lang.Float}
double | {@link java.lang.Double}
array | empty | Arrays of intermediate types on this list.
uon | No intermediate type. (serialized directly to/from POJO)
object | empty | Map<String,Object>
uon | No intermediate type. (serialized directly to/from POJO)

The valid POJO types for serializing/parsing are based on the intermediate types above. As a general rule, any POJOs that are the intermediate type or transformable to or from the intermediate type are valid POJO types.

For example, the following POJO type can be transformed to and from a byte array.

// Sample POJO class convertable to and from a byte[]. public class MyPojo { // Constructor used by parser. public MyPojo(byte[] fromBytes) {...} // toX method used by serializer. public byte[] toBytes() {...} }

This example shows how that POJO can be converted to a BASE64-encoded string.

// Construct a POJO. MyPojo myPojo = ...; // Define a schema. HttpPartSchema schema = HttpPartSchema.tByte().build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer serializer = OpenApiSerializer.DEFAULT; String httpPart = serializer.serialize(schema, myPojo); // Convert BASE64-encoded string back into a POJO. HttpPartParser parser = OpenApiParser.DEFAULT; myPojo = parser.parse(schema, httpPart, MyPojo.class);

In addition to defining format, the schema also allows for validations of the serialized form.

// Construct a POJO. MyPojo myPojo = ...; // Define a schema. // Serialized string must be no smaller than 100 characters. HttpPartSchema schema = HttpPartSchema.tByte().minLength(100).build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer serializer = OpenApiSerializer.DEFAULT; String httpPart; try { httpPart = serializer.serialize(schema, myPojo); } catch (SchemaValidationException e) { // Oops, output too small. } // Convert BASE64-encoded string back into a POJO. HttpPartParser parser = OpenApiParser.DEFAULT; try { myPojo = parser.parse(schema, httpPart, MyPojo.class); } catch (SchemaValidationException e) { // Oops, input too small. }

It looks simple, but the implementation is highly sophisticated being able to serialize and parse and validate using complex schemas.

The next sections go more into depth on serializing and parsing various POJO types.