All serializers and parsers extend from the {@link org.apache.juneau.BeanContext} class.
Therefore, the following properties are common to all serializers and parsers:

• {@link org.apache.juneau.BeanContext}
  • {@link org.apache.juneau.BeanContext#BEAN_beanClassVisibility BEAN_beanClassVisibility}
  • {@link org.apache.juneau.BeanContext#BEAN_beanConstructorVisibility BEAN_beanConstructorVisibility}
  • {@link org.apache.juneau.BeanContext#BEAN_beanDictionary BEAN_beanDictionary}
  • {@link org.apache.juneau.BeanContext#BEAN_beanFieldVisibility BEAN_beanFieldVisibility}
  • {@link org.apache.juneau.BeanContext#BEAN_beanFilters BEAN_beanFilters}
  • {@link org.apache.juneau.BeanContext#BEAN_beanMapPutReturnsOldValue BEAN_beanMapPutReturnsOldValue}
  • {@link org.apache.juneau.BeanContext#BEAN_beanMethodVisibility BEAN_beanMethodVisibility}
  • {@link org.apache.juneau.BeanContext#BEAN_beansRequireDefaultConstructor BEAN_beansRequireDefaultConstructor}
  • {@link org.apache.juneau.BeanContext#BEAN_beansRequireSerializable BEAN_beansRequireSerializable}
  • {@link org.apache.juneau.BeanContext#BEAN_beansRequireSettersForGetters BEAN_beansRequireSettersForGetters}
  • {@link org.apache.juneau.BeanContext#BEAN_beansRequireSomeProperties BEAN_beansRequireSomeProperties}
  • {@link org.apache.juneau.BeanContext#BEAN_beanTypePropertyName BEAN_beanTypePropertyName}
  • {@link org.apache.juneau.BeanContext#BEAN_debug BEAN_debug}
  • {@link org.apache.juneau.BeanContext#BEAN_examples BEAN_examples}
  • {@link org.apache.juneau.BeanContext#BEAN_excludeProperties BEAN_excludeProperties}
  • {@link org.apache.juneau.BeanContext#BEAN_fluentSetters BEAN_fluentSetters}
  • {@link org.apache.juneau.BeanContext#BEAN_ignoreInvocationExceptionsOnGetters BEAN_ignoreInvocationExceptionsOnGetters}
  • {@link org.apache.juneau.BeanContext#BEAN_ignoreInvocationExceptionsOnSetters BEAN_ignoreInvocationExceptionsOnSetters}
  • {@link org.apache.juneau.BeanContext#BEAN_ignorePropertiesWithoutSetters BEAN_ignorePropertiesWithoutSetters}
  • {@link org.apache.juneau.BeanContext#BEAN_ignoreUnknownBeanProperties BEAN_ignoreUnknownBeanProperties}
  • {@link org.apache.juneau.BeanContext#BEAN_ignoreUnknownNullBeanProperties BEAN_ignoreUnknownNullBeanProperties}
  • {@link org.apache.juneau.BeanContext#BEAN_implClasses BEAN_implClasses}
  • {@link org.apache.juneau.BeanContext#BEAN_includeProperties BEAN_includeProperties}
  • {@link org.apache.juneau.BeanContext#BEAN_locale BEAN_locale}
  • {@link org.apache.juneau.BeanContext#BEAN_mediaType BEAN_mediaType}
  • {@link org.apache.juneau.BeanContext#BEAN_notBeanClasses BEAN_notBeanClasses}
  • {@link org.apache.juneau.BeanContext#BEAN_notBeanPackages BEAN_notBeanPackages}
  • {@link org.apache.juneau.BeanContext#BEAN_pojoSwaps BEAN_pojoSwaps}
  • {@link org.apache.juneau.BeanContext#BEAN_propertyNamer BEAN_propertyNamer}
  • {@link org.apache.juneau.BeanContext#BEAN_sortProperties BEAN_sortProperties}
  • {@link org.apache.juneau.BeanContext#BEAN_timeZone BEAN_timeZone}
  • {@link org.apache.juneau.BeanContext#BEAN_useEnumNames BEAN_useEnumNames}
  • {@link org.apache.juneau.BeanContext#BEAN_useInterfaceProxies BEAN_useInterfaceProxies}
  • {@link org.apache.juneau.BeanContext#BEAN_useJavaBeanIntrospector BEAN_useJavaBeanIntrospector}

In addition to the common properties above, the following properties are common to all serializers:

• {@link org.apache.juneau.BeanTraverseContext}
  • {@link org.apache.juneau.BeanTraverseContext#BEANTRAVERSE_detectRecursions BEANTRAVERSE_detectRecursions}
  • {@link org.apache.juneau.BeanTraverseContext#BEANTRAVERSE_ignoreRecursions BEANTRAVERSE_ignoreRecursions}
  • {@link org.apache.juneau.BeanTraverseContext#BEANTRAVERSE_initialDepth BEANTRAVERSE_initialDepth}
  • {@link org.apache.juneau.BeanTraverseContext#BEANTRAVERSE_maxDepth BEANTRAVERSE_maxDepth}
  • {@link org.apache.juneau.serializer.Serializer}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_addBeanTypes SERIALIZER_addBeanTypes}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_addRootType SERIALIZER_addRootType}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_listener SERIALIZER_listener}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_sortCollections SERIALIZER_sortCollections}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_sortMaps SERIALIZER_sortMaps}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_trimEmptyCollections SERIALIZER_trimEmptyCollections}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_trimEmptyMaps SERIALIZER_trimEmptyMaps}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_trimNullProperties SERIALIZER_trimNullProperties}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_trimStrings SERIALIZER_trimStrings}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriContext SERIALIZER_uriContext}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriRelativity SERIALIZER_uriRelativity}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_uriResolution SERIALIZER_uriResolution}
    • {@link org.apache.juneau.serializer.Serializer#SERIALIZER_useWhitespace SERIALIZER_useWhitespace}
    • {@link org.apache.juneau.serializer.WriterSerializer}
      • {@link org.apache.juneau.serializer.WriterSerializer#WSERIALIZER_maxIndent WSERIALIZER_maxIndent}
      • {@link org.apache.juneau.serializer.WriterSerializer#WSERIALIZER_quoteChar WSERIALIZER_quoteChar}
    • {@link org.apache.juneau.serializer.OutputStreamSerializer}
      • {@link org.apache.juneau.serializer.OutputStreamSerializer#OSSERIALIZER_binaryFormat OSSERIALIZER_binaryFormat}

In addition to the common properties above, the following properties are common to all parsers:

• {@link org.apache.juneau.parser.Parser}
  • {@link org.apache.juneau.parser.Parser#PARSER_autoCloseStreams PARSER_autoCloseStreams}
  • {@link org.apache.juneau.parser.Parser#PARSER_debugOutputLines PARSER_debugOutputLines}
  • {@link org.apache.juneau.parser.Parser#PARSER_listener PARSER_listener}
  • {@link org.apache.juneau.parser.Parser#PARSER_strict PARSER_strict}
  • {@link org.apache.juneau.parser.Parser#PARSER_trimStrings PARSER_trimStrings}
  • {@link org.apache.juneau.parser.Parser#PARSER_unbuffered PARSER_unbuffered}
  • {@link org.apache.juneau.parser.ReaderParser}
    • {@link org.apache.juneau.parser.ReaderParser#RPARSER_fileCharset RPARSER_fileCharset}
    • {@link org.apache.juneau.parser.ReaderParser#RPARSER_inputStreamCharset RPARSER_inputStreamCharset}
  • {@link org.apache.juneau.parser.InputStreamParser}
    • {@link org.apache.juneau.parser.InputStreamParser#ISPARSER_binaryFormat ISPARSER_binaryFormat}

{@link org.apache.juneau.transform.PojoSwap PojoSwaps} are a critical component of Juneau. They allow the serializers and parsers to handle Java objects that wouldn't normally be serializable.

Swaps are, simply put, 'object swappers' that swap in serializable objects for non-serializable ones during serialization, and vis-versa during parsing.

Some examples of non-serializable POJOs are File, Reader, Iterable, etc... These are classes that aren't beans and cannot be represented as simple maps, collections, or primitives.

In the following example, we introduce a PojoSwap that will swap in ISO8601 strings for Date objects:

// Sample swap for converting Dates to ISO8601 strings. public class MyDateSwap extends PojoSwap<Date,String> { // ISO8601 formatter. private DateFormat format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ"); // Converts a Date object to an ISO8601 string. @Override /* PojoSwap */ public String swap(BeanSession session, Date o) { return format.format(o); } // Converts an ISO8601 string to a Date object. @Override /* PojoSwap */ public Date unswap(BeanSession session, String o, ClassMeta hint) throws Exception { return format.parse(o); } }

The swap can then be associated with serializers and parsers like so:

// Sample bean with a Date field. public class MyBean { public Date date = new Date(112, 2, 3, 4, 5, 6); } // Create a new JSON serializer, associate our date swap with it, and serialize a sample bean. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(MyDateSwap.class).build(); String json = s.serialize(new MyBean()); // == "{date:'2012-03-03T04:05:06-0500'}" // Create a JSON parser, associate our date swap with it, and reconstruct our bean (including the date). ReaderParser p = JsonParser.create().pojoSwaps(MyDateSwap.class).build(); MyBean bean = p.parse(json, MyBean.class); int day = bean.date.getDay(); // == 3

The {@link org.apache.juneau.BeanMap#get(Object)} and {@link org.apache.juneau.BeanMap#put(String,Object)} methods will automatically convert to swapped values as the following example shows:

// Create a new bean context and add our swap. BeanContext bc = BeanContext.create().pojoSwaps(MyDateSwap.class).build(); // Create a new bean. MyBean myBean = new MyBean(); // Wrap it in a bean map. BeanMap<Bean> beanMap = bc.forBean(myBean); // Use the get() method to get the date field as an ISO8601 string. String date = (String)beanMap.get("date"); // == "2012-03-03T04:05:06-0500" // Use the put() method to set the date field to an ISO8601 string. beanMap.put("date", "2013-01-01T12:30:00-0500"); // Set it to a new value. // Verify that the date changed on the original bean. int year = myBean.date.getYear(); // == 113

Another example of a PojoSwap is one that converts byte[] arrays to BASE64-encoded strings:

public class ByteArrayBase64Swap extends StringSwap<byte[]> { @Override /* StringSwap */ public String swap(byte[] b) throws Exception { ByteArrayOutputStream baos = new ByteArrayOutputStream(); OutputStream b64os = MimeUtility.encode(baos, "base64"); b64os.write(b); b64os.close(); return new String(baos.toByteArray()); } @Override /* StringSwap */ public byte[] unswap(String s, ClassMeta<?> hint) throws Exception { byte[] b = s.getBytes(); ByteArrayInputStream bais = new ByteArrayInputStream(b); InputStream b64is = MimeUtility.decode(bais, "base64"); byte[] tmp = new byte[b.length]; int n = b64is.read(tmp); byte[] res = new byte[n]; System.arraycopy(tmp, 0, res, 0, n); return res; } }

The following example shows the BASE64 swap in use:

// Create a JSON serializer and register the BASE64 encoding swap with it. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(ByteArrayBase64Swap.class).build(); ReaderParser p = JsonParser.create().pojoSwaps(ByteArrayBase64Swap.class).build(); byte[] bytes = {1,2,3}; String json = s.serialize(bytes); // Produces "'AQID'" bytes = p.parse(json, byte[].class); // Reproduces {1,2,3} byte[][] bytes2d = {{1,2,3},{4,5,6},null}; json = s.serialize(bytes2d); // Produces "['AQID','BAUG',null]" bytes2d = p.parse(json, byte[][].class); // Reproduces {{1,2,3},{4,5,6},null}

Several PojoSwaps are already provided for common Java objects:

• org.apache.juneau.transforms
  • {@link org.apache.juneau.transforms.ByteArrayBase64Swap}
  • {@link org.apache.juneau.transforms.CalendarSwap}
  • {@link org.apache.juneau.transforms.DateSwap}
  • {@link org.apache.juneau.transforms.EnumerationSwap}
  • {@link org.apache.juneau.transforms.IteratorSwap}
  • {@link org.apache.juneau.transforms.ReaderSwap}
  • {@link org.apache.juneau.transforms.XMLGregorianCalendarSwap}

In particular, the {@link org.apache.juneau.transforms.CalendarSwap} and {@link org.apache.juneau.transforms.DateSwap} transforms provide a large number of customized swaps to ISO, RFC, or localized strings.

Swaps have access to the session locale and timezone through the {@link org.apache.juneau.BeanSession#getLocale()} and {@link org.apache.juneau.BeanSession#getTimeZone()} methods.
This allows you to specify localized swap values when needed.

If using the REST server API, the locale and timezone are set based on the Accept-Language and Time-Zone headers on the request.

• The 'swapped' class type must be a serializable type.
  See the definition for Category 4 objects in {@doc PojoCategories}.

Swaps can also be defined per-media-type.

The {@link org.apache.juneau.transform.PojoSwap#forMediaTypes()} method can be overridden to provide a set of media types that the swap is invoked on.
It's also possible to define multiple swaps against the same POJO as long as they're differentiated by media type.
When multiple swaps are defined, the best-match media type is used.

In the following example, we define 3 swaps against the same POJO. One for JSON, one for XML, and one for all other types.

public class PojoSwapTest { public static class MyPojo {} public static class MyJsonSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public MediaType[] forMediaTypes() { return MediaType.forStrings("*/json"); } @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) throws Exception { return "It's JSON!"; } } public static class MyXmlSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public MediaType[] forMediaTypes() { return MediaType.forStrings("*/xml"); } @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) throws Exception { return "It's XML!"; } } public static class MyOtherSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public MediaType[] forMediaTypes() { return MediaType.forStrings("*/*"); } @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) throws Exception { return "It's something else!"; } } @Test public void doTest() throws Exception { SerializerGroup g = SerializerGroup.create() .append(JsonSerializer.class, XmlSerializer.class, HtmlSerializer.class) .sq() .pojoSwaps(MyJsonSwap.class, MyXmlSwap.class, MyOtherSwap.class) .build(); MyPojo myPojo = new MyPojo(); String json = g.getWriterSerializer("text/json").serialize(myPojo); assertEquals("'It\\'s JSON!'", json); String xml = g.getWriterSerializer("text/xml").serialize(myPojo); assertEquals("<string>It's XML!</string>", xml); String html = g.getWriterSerializer("text/html").serialize(myPojo); assertEquals("<string>It's something else!</string>", html); } }

When multiple swaps match the same media type, a best-match algorithm is applied to find the correct swap to use.

In later sections we describe how annotations can be used to shorten this syntax:

@Swaps({MyJsonSwap.class,MyXmlSwap.class,MyOtherSwap.class}) public static class MyPojo {} @Swap(mediaTypes="*/json") public static class MyJsonSwap extends PojoSwap<MyPojo,String> {...} @Swap(mediaTypes="*/xml") public static class MyXmlSwap extends PojoSwap<MyPojo,String> {...} @Swap(mediaTypes="*/*") public static class MyOtherSwap extends PojoSwap<MyPojo,String> {...}

In the previous sections, we defined two-way swaps, meaning swaps where the original objects could be reconstructing during parsing.
However, there are certain kinds of POJOs that we may want to support for serializing, but that are not possible to reconstruct during parsing.
For these, we can use one-way object swaps.

A one-way POJO swap is simply an object transform that only implements the {@code swap()} method.
The {@code unswap()} method is simply left unimplemented.

An example of a one-way swaps would be one that allows {@code Iterators} to be serialized as JSON arrays.
It can make sense to be able to render {@code Iterators} as arrays, but in general it's not possible to reconstruct an {@code Iterator} during parsing.

public class IteratorSwap extends PojoSwap<Iterator,List> { @Override /* PojoSwap */ public List swap(Iterator o) { List l = new LinkedList(); while (o.hasNext()) l.add(o.next()); return l; } }

Here is an example of our one-way swap being used.
Note that trying to parse the original object will cause a {@link org.apache.juneau.parser.ParseException} to be thrown.

// Create a JSON serializer that can serialize Iterators. WriterSerializer s = JsonSerializer.create().simple().pojoSwaps(IteratorSwap.class).build(); // Construct an iterator we want to serialize. Iterator i = new ObjectList(1,2,3).iterator(); // Serialize our Iterator String json = s.serialize(i); // Produces "[1,2,3]" // Try to parse it. ReaderParser p = JsonParser.create().pojoSwaps(IteratorSwap.class).build(); i = p.parse(s, Iterator.class); // Throws ParseException!!!

{@link org.apache.juneau.annotation.Swap @Swap} can be used to associate a swap class using an annotation.
This is often cleaner than using the builder pojoSwaps() method since you can keep your swap class near your POJO class.

@Swap(MyPojoSwap.class) public class MyPojo { ... } // Sample swap for converting MyPojo classes to a simple string. public class MyPojoSwap extends PojoSwap<MyPojo,String> { @Override /* PojoSwap */ public String swap(BeanSession session, MyPojo o) { return o.toSomeSerializableForm(); } }

Multiple swaps can be associated with a POJO by using the {@link org.apache.juneau.annotation.Swaps @Swaps} annotation:

@Swaps( { @Swap(MyJsonSwap.class), @Swap(MyXmlSwap.class), @Swap(MyOtherSwap.class) } ) public class MyPojo {}

Readers get serialized directly to the output of a serializer. Therefore it's possible to implement a swap that provides fully-customized output.

public class MyJsonSwap extends PojoSwap<MyPojo,Reader> { public MediaType[] forMediaTypes() { return MediaType.forStrings("*/json"); } public Reader swap(BeanSession session, MyPojo o) throws Exception { return new StringReader("{message:'Custom JSON!'}"); } }

The @Swap annotation can also be used on getters and setters as well to apply a swap to individual property values:

public class MyBean { private MyPojo myPojo; // Swap applied to bean property. @BeanProperty(swap=MyPojoSwap.class) public MyPojo getMyPojo() { return myPojo; } }

When applied to bean properties, the swap annotation need only be applied to either the getter, setter, or field.

The swap annotation can also be applied to the private field of a bean property, like so:

public class MyBean { @BeanProperty(swap=MyPojoSwap.class) private MyPojo myPojo; public MyPojo getMyPojo() { return myPojo; } public MyBean setMyPojo(MyPojo myPojo) { this.myPojo = myPojo; return this; } }

The {@link org.apache.juneau.annotation.Swap#template() @Swap(template)} annotation allows you to associate arbitrary contextual strings with swaps.
The primary purpose is for providing template names, such as for Apache FreeMarker, therefore the name 'template'.
However, the usage of the string is open-ended.

For example, you could pair a template string like so:

@Swap(impl=FreeMarkerSwap.class, template="MyPojo.div.ftl") public class MyPojo {}

The implementation of the FreeMarker swap would look something like this:

// Our templated swap class. public class FreeMarkerSwap extends PojoSwap<Object,Reader> { public MediaType[] forMediaTypes() { // Make sure this only applies to the HTML serializer. return MediaType.forStrings("*/html"); } public Reader swap(BeanSession session, Object o, String template) throws Exception { // Call some method that uses FreeMarker to convert 'o' to raw HTML using // the 'MyPojo.div.ftl' template. return getFreeMarkerReader(template, o); } }

Various methods can be defined on a class directly to affect how it gets serialized.
This can often be simpler than using PojoSwaps.

Objects serialized as Strings can be parsed back into their original objects by implementing one of the following methods on the class:

• public static T fromString(String) method.
  Any of the following method names also work:
  • valueOf(String)
  • parse(String)
  • parseString(String)
  • forName(String)
  • forString(String)
• public T(String) constructor.

Note that these methods cover conversion from several built-in Java types, meaning the parsers can automatically construct these objects from strings:

• fromString(String) - {@link java.util.UUID}
• valueOf(String) - {@link java.lang.Boolean}, {@link java.lang.Byte}, {@link java.lang.Double}, {@link java.lang.Float}, {@link java.lang.Integer}, {@link java.lang.Long}, {@link java.lang.Short}, {@link java.sql.Date}, {@link java.sql.Time}, {@link java.sql.Timestamp}
• parse(String) - {@link java.text.DateFormat}, {@link java.text.MessageFormat}, {@link java.text.NumberFormat}, {@link java.util.Date}, {@link java.util.logging.Level}
• parseString(String) - {@link javax.xml.bind.DatatypeConverter}
• forName(String) - {@link java.lang.Class}

If you want to force a bean-like class to be serialized as a string, you can use the {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} annotation on the class to force it to be serialized to a string using the toString() method.

Serializing to other intermediate objects can be accomplished by defining a swap method directly on the class:

• public X swap(BeanSession) method, where X is any serializable object.

The BeanSession parameter allows you access to various information about the current serialization session.
For example, you could provide customized results based on the media type being produced ({@link org.apache.juneau.BeanSession#getMediaType()}).

The following example shows how an HTML5 form template object can be created that gets serialized as a populated HTML5 {@link org.apache.juneau.dto.html5.Form} bean.

import static org.apache.juneau.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. */ public class FormTemplate { private String action; private int value1; private boolean value2; // Some constructor that initializes our fields. public FormTemplate(String action, int value1, boolean value2) { this.action = action; this.value1 = value1; this.value2 = value2; } // Special swap method that converts this template to a serializable bean public Form swap(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

Swapped objects can be converted back into their original form by the parsers by specifying one of the following methods:

• public static T unswap(BeanSession, X) method where X is the swap class type.
• public T(X) constructor where X is the swap class type.

The following shows how our form template class can be modified to allow the parsers to reconstruct our original object:

import static org.apache.juneau.dto.html5.HtmlBuilder.*; /** * A simple HTML form template whose serialized form is an HTML5 Form object. * This time with parsing support. */ @Bean(beanDictionary=HtmlBeanDictionary.class) public class FormTemplate { private String action; private int value1; private boolean value2; // Our 'unswap' constructor public FormTemplate(Form f) { this.action = f.getAttr("action"); this.value1 = f.getChild(Input.class, 0) .getAttr(int.class, "value"); this.value2 = f.getChild(Input.class, 1) .getAttr(boolean.class, "value"); } public FormTemplate(String action, int value1, boolean value2) { this.action = action; this.value1 = value1; this.value2 = value2; } public Form swap(BeanSession session) { return form(action, input("text").name("v1").value(value1), input("text").name("v2").value(value2) ); } }

Surrogate classes are very similar in concept to PojoSwaps except they're simpler to define.

For example, let's say we want to be able to serialize the following class, but it's not serializable for some reason (for example, there are no properties exposed):

// Not serializable because it's not a bean because it has no public properties. public class MyNonSerializableClass { protected String foo; }

This could be solved with the following PojoSwap.

// A serializable bean with 1 property. public class MySerializableSurrogate { public String foo; } // A PojoSwap that swaps out our non-serializable object with our serializable object. public class MySwap extends PojoSwap<MyNonSerializableClass,MySerializableSurrogate> { @Override /* PojoSwap */ public MySerializableSurrogate swap(MyNonSerializableClass o) { // Create some serializable class and manually copy the data into it. MySerializableSurrogate s = new MySerializableSurrogate(); s.foo = o.foo; return s; } }

However, the same can be accomplished by using a surrogate class that simply contains a constructor with the non-serializable class as an argument:

public class MySerializableSurrogate { public String foo; // Constructor takes in our non-serializable object! public MySerializableSurrogate(MyNonSerializableClass c) { this.foo = c.foo; } }

The surrogate class is registered in the same way as a PojoSwap:

// Create a JSON serializer that can serialize Iterators. WriterSerializer s = JsonSerializer.create().pojoSwaps(MySerializableSurrogate.class).build();

When the serializer encounters the non-serializable class, it will serialize an instance of the surrogate instead.

See Also:

• {@link org.apache.juneau.transform.Surrogate}

The {@link org.apache.juneau.annotation.Bean @Bean} annotation is used to tailor how beans are interpreted by the framework.

Bean property inclusion and ordering on a bean class can be done using the {@link org.apache.juneau.annotation.Bean#properties() @Bean(properties)} annotation.

// Address class with only street/city/state properties (in that order). // All other properties are ignored. @Bean(properties="street,city,state") public class Address { ... }

Bean properties can be excluded using the {@link org.apache.juneau.annotation.Bean#excludeProperties() @Bean(excludeProperties)} annotation.

// Address class with only street/city/state properties (in that order). // All other properties are ignored. @Bean(excludeProperties="city,state"}) public class Address { ... }

Bean properties can be sorted alphabetically using {@link org.apache.juneau.annotation.Bean#sort() @Bean(sort)}

// Address class with only street/city/state properties (in that order). // All other properties are ignored. @Bean(sort=true) public class MyBean { ... }

The {@link org.apache.juneau.annotation.Bean#propertyNamer() @Bean(propertyNamer)} annotation is used to provide customized naming of properties.

Property namers are used to transform bean property names from standard form to some other form.
For example, the {@link org.apache.juneau.PropertyNamerDLC} will convert property names to dashed-lowercase, and these will be used as attribute names in JSON and element names in XML.

// Define a class with dashed-lowercase property names. @Bean(propertyNamer=PropertyNamerDashedLC.class) public class MyBean { ... }

The {@link org.apache.juneau.annotation.Bean#interfaceClass @Bean(interfaceClass)} annotation is used to limit properties on beans to specific interface classes.
When specified, only the list of properties defined on the interface class will be used during serialization.
Additional properties on subclasses will be ignored.

// Parent class @Bean(interfaceClass=A.class) public abstract class A { public String f0 = "f0"; } // Child class public class A1 extends A { public String f1 = "f1"; } JsonSerializer s = SimpleJsonSerializer.DEFAULT; A1 a1 = new A1(); String r = s.serialize(a1); assertEquals("{f0:'f0'}", r); // Note f1 is not serialized.

Note that this annotation can be used on the parent class so that it filters to all child classes.
Or can be set individually on the child classes.

The {@link org.apache.juneau.annotation.Bean#stopClass @Bean(stopClass)} annotation is another way to limit which properties are serialized (except from the opposite direction).
It's identical in purpose to the stop class specified by {@link java.beans.Introspector#getBeanInfo(Class, Class)}.
Any properties in the stop class or in its base classes will be ignored during analysis.

For example, in the following class hierarchy, instances of C3 will include property p3, but not p1 or p2.

public class C1 { public int getP1(); } public class C2 extends C1 { public int getP2(); } @Bean(stopClass=C2.class) public class C3 extends C2 { public int getP3(); }

The {@link org.apache.juneau.annotation.Bean#propertyFilter() @Bean(propertyFilter)} annotation and {@link org.apache.juneau.transform.PropertyFilter} class can be used to perform interception and inline handling of bean getter and setter calls.

// Register filter on bean class. @Bean(propertyFilter=AddressPropertyFilter.class) public class Address { public String getTaxInfo() {...} public void setTaxInfo(String s) {...} } // Property filter that strips out sensitive information in our bean. public class AddressPropertyFilter extends PropertyFilter { @Override /* PropertyFilter */ public Object readProperty(Object bean, String name, Object value) { if ("taxInfo".equals(name)) return "redacted"; return value; } @Override /* PropertyFilter */ public Object writeProperty(Object bean, String name, Object value) { AddressBook a = (Address)bean; if ("taxInfo".equals(name) && "redacted".equals(value)) return TaxInfoUtils.lookUpByName(a.getStreet(), a.getCity(), a.getState()); return value; } }

The {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotation is used to tailor how individual bean properties are interpreted by the framework.

The {@link org.apache.juneau.annotation.BeanProperty#name() @BeanProperty(name)} annotation is used to override the name of the bean property.

public class MyBean { @BeanProperty(name="Bar") public String getFoo() {...} }

If the {@link org.apache.juneau.BeanContext#BEAN_beanFieldVisibility} setting on the bean context excludes this field (e.g. the visibility is set to the default of PUBLIC, but the field is PROTECTED), this annotation can be used to force the field to be identified as a property.

public class MyBean { @BeanProperty protected String getFoo() {...} }

The bean property named "*" is the designated "dynamic property" which allows for "extra" bean properties not otherwise defined.
This is similar in concept to the Jackson @JsonGetterAll and @JsonSetterAll annotations, but generalized for all supported marshall languages.
The primary purpose is for backwards compatibility in parsing newer streams with addition information into older beans.

The following shows various ways of using dynamic bean properties.

// Option #1 - A simple public Map field. // The field name can be anything. public class BeanWithDynaField { @BeanProperty(name="*") public Map<String,Object> extraStuff = new LinkedHashMap<String,Object>(); } // Option #2 - Getters and setters. // Method names can be anything. // Getter must return a Map with String keys. // Setter must take in two arguments, a String and Object. public class BeanWithDynaMethods { @BeanProperty(name="*") public Map<String,Object> getMyExtraStuff() { ... } @BeanProperty(name="*") public void setAnExtraField(String name, Object value) { ... } } // Option #3 - Getter only. // Properties will be added through the getter. public class BeanWithDynaGetterOnly { @BeanProperty(name="*") public Map<String,Object> getMyExtraStuff() { ... } }

Similar rules apply for value types and swaps.
The property values optionally can be any serializable type or use swaps.

// A serializable type other than Object. public class BeanWithDynaFieldWithListValues { @BeanProperty(name="*") public Map<String,List<String>> getMyExtraStuff() { ... } } // A swapped value. public class BeanWithDynaFieldWithSwappedValues { @BeanProperty(name="*", swap=CalendarSwap.ISO8601DTZ.class) public Map<String,Calendar> getMyExtraStuff() { ... } }

• Note that if you're not interested in these additional properties, you can also use the {@link org.apache.juneau.BeanContext#BEAN_ignoreUnknownBeanProperties} setting to ignore values that don't fit into existing properties.

The {@link org.apache.juneau.annotation.BeanProperty#value() @BeanProperty(value)} annotation is a synonym for {@link org.apache.juneau.annotation.BeanProperty#name() @BeanProperty(name)}.
Use it in cases where you're only specifying a name so that you can shorten your annotation.

The following annotations are equivalent:

@BeanProperty(name="foo") @BeanProperty("foo")

The {@link org.apache.juneau.annotation.BeanProperty#type() @BeanProperty(type)} annotation is used to identify a specialized class type for a generalized property.
Normally the type is inferred through reflection of the field type or getter return type.
However, you'll want to specify this value if you're parsing beans where the bean property class is an interface or abstract class to identify the bean type to instantiate.
Otherwise, you may cause an {@link java.lang.InstantiationException} when trying to set these fields.

This property must denote a concrete class with a no-arg constructor.

public class MyBean { // Identify concrete type as a HashMap. @BeanProperty(type=HashMap.class) public Map p1; }

The {@link org.apache.juneau.annotation.BeanProperty#params() @BeanProperty(params)} annotation is for bean properties of type map or collection.
It's used to identify the class types of the contents of the bean property object when the general parameter types are interfaces or abstract classes.

public class MyBean { // This is a HashMap<String,Integer>. @BeanProperty(type=HashMap.class, params={String.class,Integer.class}) public Map p1; }

The {@link org.apache.juneau.annotation.BeanProperty#properties() @BeanProperty(properties)} annotation is used to limit which child properties are rendered by the serializers.
It can be used on any of the following bean property types:

• Beans - Only render the specified properties of the bean.
• Maps - Only render the specified entries in the map.
• Bean/Map arrays - Same, but applied to each element in the array.
• Bean/Map collections - Same, but applied to each element in the collection.

public class MyClass { // Only render 'f1' when serializing this bean property. @BeanProperty(properties={"f1"}) public MyChildClass x1 = new MyChildClass(); } public class MyChildClass { public int f1 = 1; public int f2 = 2; } // Renders "{x1:{f1:1}}" String json = JsonSerializer.DEFAULT.serialize(new MyClass());

The {@link org.apache.juneau.annotation.BeanProperty#format() @BeanProperty(format)} annotation specifies a String format for converting a bean property value to a formatted string.

// Serialize a float as a string with 2 decimal places. @BeanProperty(format="$%.2f") public float price;

The {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} annotation is used to map constructor arguments to property names on bean with read-only properties.
Since method parameter names are lost during compilation, this annotation essentially redefines them so that they are available at runtime.

The definition of a read-only bean is a bean with properties with only getters, like shown below:

// Our read-only bean. public class Person { private final String name; private final int age; @BeanConstructor(properties="name,age"}) public Person(String name, int age) { this.name = name; this.age = age; } // Read only properties. // Getters, but no setters. public String getName() { return name; } public int getAge() { return age; } }

// Parsing into a read-only bean. String json = "{name:'John Smith',age:45}"; Person p = JsonParser.DEFAULT.parse(json); String name = p.getName(); // "John Smith" int age = p.getAge(); // 45

Beans can also be defined with a combination of read-only and read-write properties.

The {@link org.apache.juneau.annotation.BeanIgnore @BeanIgnore} annotation is used to ignore classes, fields, and methods from being interpreted as beans or bean components.

When applied to classes, objects will be converted to strings even though they look like beans.

// Not really a bean! Use toString() instead! @BeanIgnore public class MyBean {...}

When applied to fields and getters/setters, they will be ignored as bean properties.

public class MyBean { // Not a bean property! @BeanIgnore public String foo; // Not a bean property! @BeanIgnore public String getBar() {...} }

The {@link org.apache.juneau.annotation.NameProperty @NameProperty} annotation is used to identify a setter as a method for setting the name of a POJO as it's known by its parent object.

A commonly-used case is when you're parsing a JSON map containing beans where one of the bean properties is the key used in the map.

// JSON { id1: {name: 'John Smith', sex: 'M'}, id2: {name: 'Jane Doe', sex: 'F'} }

public class Person { @NameProperty public String id; // Value gets assigned from object key public String name; public char sex; }

The {@link org.apache.juneau.annotation.ParentProperty @ParentProperty} annotation is used to identify a setter as a method for adding a parent reference to a child object.

A commonly-used case is when you're parsing beans and a child bean has a reference to a parent bean.

public class AddressBook { public List<Person> people; } public class Person { @ParentProperty public AddressBook addressBook; // A reference to the containing address book. public String name; public char sex; }

Parsers will automatically set this field for you in the child beans.

Juneau parsers can use builders to instantiate POJOs.
This is useful in cases where you want to create beans with read-only properties.
Note that while it's possible to do this using the {@link org.apache.juneau.annotation.BeanConstructor @BeanConstructor} annotation, using builders can often be cleaner.

A typical builder usage is shown below:

MyBean b = MyBean.create().foo("foo").bar(123).build();

The code for such a builder is shown below:

public class MyBean { // Read-only properties. public final String foo; public final int bar; // Private constructor. private MyBean(MyBeanBuilder b) { this.foo = b.foo; this.bar = b.bar; } // Static method that creates a builder. public static MyBeanBuilder create() { return new MyBeanBuilder(); } // Builder class. public static class MyBeanBuilder { private String foo; private int bar; // Method that creates the bean. public MyBean build() { return new MyBean(this); } // Bean property setters. @BeanProperty public MyBeanBuilder foo(String foo) { this.foo = foo; return this; } @BeanProperty public MyBeanBuilder bar(int bar) { this.bar = bar; return this; } } }

The POJO class can be any type including beans.
Builders MUST be beans with one or more writable properties.
The bean properties themselves do not need to be readable (i.e. getters are optional).

Builders require two parts:

1. A way to detect and instantiate a builder using reflection.
2. A way to instantiate a POJO from a builder.

The first can be accomplished through any of the following:

• A static create() method on the POJO class that returns a builder instance.

  public static MyBuilder create() {...}

• A public constructor on the POJO class that takes in a single parameter that implements the {@link org.apache.juneau.transform.Builder} interface.
  The builder class must have a public no-arg constructor.

  public MyPojo(MyBuilder b) {...}

• A {@link org.apache.juneau.annotation.Builder @Builder} annotation on the POJO class.
  The builder class must have a public no-arg constructor.

  @Builder(MyBuilder.class) public class MyPojo {...}

The second can be accomplished through any of the following:

• The existence of a build() method on the builder class.

  public MyPojo build() {...}

• The existence of a public constructor on the POJO class that takes in the builder instance.

  public MyPojo(MyBuilder b) {...}

See Also:

• {@link org.apache.juneau.annotation.Builder}
• {@link org.apache.juneau.transform.Builder}

The {@link org.apache.juneau.transform.BeanFilter} class is the programmatic equivalent to the {@link org.apache.juneau.annotation.Bean @Bean} annotation.

In practice, it's usually simpler to use the {@link org.apache.juneau.annotation.Bean @Bean} and {@link org.apache.juneau.annotation.BeanProperty @BeanProperty} annotations on your bean classes.
However, bean filters make it possible to accomplish the same when you can't add annotations to existing code.

Bean filters are defined through {@link org.apache.juneau.transform.BeanFilterBuilder BeanFilterBuilders}.

In the previous examples, we defined this bean annotation:

@Bean(properties="street,city,state") public class Address { ... }

The programmatic equivalent would be:

public class AddressFilter extends BeanFilterBuilder<Address> { // Must provide a no-arg constructor! public AddressFilter() { includeProperties("street,city,state"); // The properties we want exposed. } }

Bean filters are added to serializers and parsers using the following:

• {@link org.apache.juneau.BeanContext#BEAN_beanFilters}
• {@link org.apache.juneau.BeanContextBuilder#beanFilters(Object...)}

For example:

// Create a new JSON serializer and associate a bean filter with it. WriterSerializer s = JsonSerializer .create() .beanFilters(AddressFilter.class) .build();

Note that if you use the annotation, you do NOT need to set anything on the serializers/parsers.
The annotations will be detected and bean filters will automatically be created for them.

The {@link org.apache.juneau.BeanContextBuilder#beanFilters(Object...)} method also allows you to pass in interfaces.
Any class that's not a subclass of {@link org.apache.juneau.transform.BeanFilterBuilder} get interpreted as bean interface classes.
These cause bean implementations of those interfaces to only expose the properties defined on the interface.

// An interface with the 3 properties we want serialized. public interface AddressInterface { public String getStreet(); public String getCity(); public String getState(); } // Our bean implementation. public class Address implements AddressInterface { public String getStreet() {...}; public String getCity() {...}; public String getState() {...}; public String getCountry() {...}; } // Create a new JSON serializer that only exposes street,city,state on Address bean. // The 'country' field will be ignored. WriterSerializer s = JsonSerializer .create() .beanFilters(AddressInterface.class) .build();

Occasionally, you may want to limit bean properties to only those defined on a parent class or interface.
This is accomplished through interface filters.

Interface filters are defined through the following:

• {@link org.apache.juneau.BeanContext#BEAN_beanFilters}
• {@link org.apache.juneau.annotation.Bean#interfaceClass() @Bean(interfaceClass)}
• {@link org.apache.juneau.transform.BeanFilterBuilder#interfaceClass(Class)}

For example, let's define the following interface and implementation:

// Interface public class MyInterface { public String getFoo(); } // Implementation public class MyInterfaceImpl implements MyInterface { public String getFoo() {...} public String getBar() {...} }

Suppose we only want to render the properties defined on our interface, not the implementation.
To do so, we can define the following bean filter:

// Define transform that limits properties to only those defined on MyClass public class MyInterfaceFilter extends BeanFilter<MyInterface> { public MyInterfaceFilter() { interfaceClass(MyInterface.class); } }

When serialized, the serialized bean will only include properties defined on the interface.

WriterSerializer s = JsonSerializer .create() .simple() .beanFilters(MyInterfaceFilter.class) .build(); MyInterface o = new MyInterfaceImpl(); // Prints "{foo:'foo'}" // bar is ignored because it's not on the interface String json = s.serialize(o);

The {@link org.apache.juneau.BeanContextBuilder#beanFilters(Object...)} method will automatically interpret any non-BeanFilter classes passed in as meaning interface classes.
So in the previous example, the BeanFilter class could have been avoided altogether by just passing in MyInterface.class to the serializer, like so:

WriterSerializer s = JsonSerializer .create() .beanFilters(MyInterface.class) Shortcut! .build();

The annotation equivalent is {@link org.apache.juneau.annotation.Bean#interfaceClass() Bean#interfaceClass()}.

@Bean(interfaceClass=MyInterface.class) public class MyInterfaceImpl implements MyInterface { public String getFoo() {...} public String getBar() {...} }

The annotation can be used in a couple of ways.

Using the annotation on an interface will be inherited by all children.

@Bean(interfaceClass=MyInterface.class) public class MyInterface { public String getFoo(); }

The annotation can be used on parent classes as well.
Child beans will only serialize properties defined on the parent class.

@Bean(interfaceClass=MyAbstractClass.class) public abstract class MyAbstractClass { public String getFoo() {...}; }

Whereas interface filters limit properties defined on child classes, stop filters do the opposite and limit properties defined on parent classes.

Stop classes are defined through the following:

• {@link org.apache.juneau.annotation.Bean#stopClass() @Bean(stopClass)}
• {@link org.apache.juneau.transform.BeanFilterBuilder#stopClass(Class)}

Stop classes are identical in purpose to the stop class specified by {@link java.beans.Introspector#getBeanInfo(Class, Class)}.
Any properties in the stop class or in its base classes will be ignored during serialization.

For example, in the following class hierarchy, instances of C3 will include property p3, but not p1 or p2.

public class C1 { public int getP1(); } public class C2 extends C1 { public int getP2(); } @Bean(stopClass=C2.class) public class C3 extends C2 { public int getP3(); } // Serializes property 'p3', but NOT 'p1' or 'p2'. String json = JsonSerializer.DEFAULT.serialize(new C3());

Juneau serializers treat instances of Readers and InputStreams special by simply serializing their contents directly to the output stream or writer.
This allows you to embed fully customized serializer output.

public class MyBean { // A bean property that produces raw JSON. public Reader f1 = new StringReader("{'foo':'bar'}"); } // Produces "{f1:{'foo':'bar'}}" String json = SimpleJsonSerializer.DEFAULT .toString(new MyBean());

Note that if you're serializing Readers and InputStreams, it's up to you to make sure you're producing valid output (in this case JSON).

A more typical scenario where this is useful is by using swaps to convert POJOs to Readers whose contents are determined via the {@link org.apache.juneau.BeanSession#getMediaType()} method.
In the following example, we're customizing the JSON output for a particular bean type, but leaving all other renditions as-is:

@Swap(MyBeanSwapSometimes.class) public class MyBean {...} // A swap that produces specialized output for JSON, but default serialization for // all other media types. public class MyBeanSwapSometimes extends PojoSwap<MyBean,Object> { public Object swap(BeanSession session, MyPojo o) throws Exception { MediaType mt = session.getMediaType(); if (mt.hasSubType("json")) return new StringReader("{myPojo:'foobar'}"); // Custom JSON output return o; // Otherwise serialize it as a normal bean } }

• Due to the nature of the RDF serializers, Readers and InputStreams are serialized as literals, not as RDF text. This is due to the fact that the RDF serializers use a DOM for serialization, so we don't have access to the underlying stream.

In addition to the bean type name support described above, simplified support is provided for bean subtypes.

Bean subtypes are similar in concept to bean type names, except for the following differences:

• You specify the list of possible subclasses through an annotation on a parent bean class.
• You do not need to register the subtype classes on the bean dictionary of the parser.

In the following example, the abstract class has two subclasses:

// Abstract superclass @Bean( beanDictionary={A1.class, A2.class} ) public abstract class A { public String f0 = "f0"; } // Subclass 1 @Bean(typeName="A1") public class A1 extends A { public String f1; } // Subclass 2 @Bean(typeName="A2") public class A2 extends A { public String f2; }

When serialized, the subtype is serialized as a virtual "_type" property:

JsonSerializer s = SimpleJsonSerializer.DEFAULT; A1 a1 = new A1(); a1.f1 = "f1"; String r = s.serialize(a1); assertEquals("{_type:'A1',f1:'f1',f0:'f0'}", r);

The following shows what happens when parsing back into the original object.

JsonParser p = JsonParser.DEFAULT; A a = p.parse(r, A.class); assertTrue(a instanceof A1);

The JSON data type produced depends on the Java object type being serialized.

• Primitives and primitive objects are converted to JSON primitives.
• Beans and Maps are converted to JSON objects.
• Collections and arrays are converted to JSON arrays.
• Anything else is converted to JSON strings.

Data type conversions:

In addition, swaps can be used to convert non-serializable POJOs into serializable forms, such as converting Calendar object to ISO8601 strings, or byte[] arrays to Base-64 encoded strings.

The {@link org.apache.juneau.json.JsonSerializer} class is used to serialize POJOs into JSON.

The JSON serializer provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonSerializer Common Serializer Properties}
• {@link org.apache.juneau.json.JsonSerializer}
  • {@link org.apache.juneau.json.JsonSerializer#JSON_addBeanTypes JSON_addBeanTypes}
  • {@link org.apache.juneau.json.JsonSerializer#JSON_escapeSolidus JSON_escapeSolidus}
  • {@link org.apache.juneau.json.JsonSerializer#JSON_simpleMode JSON_simpleMode}

The following pre-configured serializers are provided for convenience:

• {@link org.apache.juneau.json.JsonSerializer}
  • {@link org.apache.juneau.json.JsonSerializer#DEFAULT DEFAULT}
  • {@link org.apache.juneau.json.JsonSerializer#DEFAULT_READABLE DEFAULT_READABLE}
• {@link org.apache.juneau.json.SimpleJsonSerializer}
  • {@link org.apache.juneau.json.SimpleJsonSerializer#DEFAULT DEFAULT}
  • {@link org.apache.juneau.json.SimpleJsonSerializer#DEFAULT_READABLE DEFAULT_READABLE}

The {@link org.apache.juneau.json.SimpleJsonSerializer} class can be used to serialized POJOs into Simplified JSON notation.

Simplified JSON is identical to JSON except for the following:

• JSON attributes are only quoted when necessary.
• Uses single-quotes for quoting.

Examples:

// Some free-form JSON. ObjectMap m = new ObjectMap() .append("foo", "x1") .append("_bar", "x2") .append(" baz ", "x3") .append("123", "x4") .append("return", "x5"); .append("", "x6");

// Serialized to standard JSON { "foo": "x1", "_bar": "x2", " baz ": "x3", "123": "x4", "return": "x5", "": "x6" }

// Serialized to simplified JSON { foo: 'x1', _bar: 'x2', ' baz ': 'x3', // Quoted due to embedded spaces. '123': 'x4', // Quoted to prevent confusion with number. 'return': 'x5', // Quoted because it's a keyword. '': 'x6' // Quoted because it's an empty string. }

The advantage to simplified JSON is you can represent it in a Java String in minimal form with minimal escaping.
This is particularly useful in cases such as unit testing where you can easily validate POJOs by simplifying them to Simplified JSON and do a simple string comparison.

WriterSerializer ws = SimpleJsonSerializer.DEFAULT; assertEquals("{foo:'bar',baz:123}", ws.toString(myPojo));

See Also:

• {@link org.apache.juneau.json.JsonSerializer#JSON_simpleMode}

The {@link org.apache.juneau.json.JsonParser} class is used to parse JSON into POJOs.

The JSON parser provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonParser Common Parser Properties}
• {@link org.apache.juneau.json.JsonParser}
  • {@link org.apache.juneau.json.JsonParser#JSON_validateEnd JSON_validateEnd}

The following pre-configured parsers are provided for convenience:

• {@link org.apache.juneau.json.JsonParser}
  • {@link org.apache.juneau.json.JsonParser#DEFAULT DEFAULT}
  • {@link org.apache.juneau.json.JsonParser#DEFAULT_STRICT DEFAULT_STRICT}

The JSON parser supports ALL valid JSON, including:

• Javascript comments.
• Single or double quoted values.
• Quoted (strict) or unquoted (non-strict) attributes.
• JSON fragments (such as string, numeric, or boolean primitive values).
• Concatenated strings.

The {@link org.apache.juneau.json.annotation.Json @Json} annotation is used to override the behavior of {@link org.apache.juneau.json.JsonSerializer} on individual bean classes or properties.

The annotation can be applied to beans as well as other objects serialized to other types (e.g. strings).

• {@link org.apache.juneau.json.annotation.Json}
  • {@link org.apache.juneau.json.annotation.Json#wrapperAttr() wrapperAttr}

The {@link org.apache.juneau.json.annotation.Json#wrapperAttr() @Json(wrapperAttr)} annotation can be used to wrap beans inside a JSON object with a specified attribute name.

Example:

@Json(wrapperAttr="personBean") public class Person { public String name = "John Smith"; }

The following shows the JSON representation with and without the annotation present:

Juneau provides the {@link org.apache.juneau.json.JsonSchemaSerializer} class for generating JSON-Schema documents that describe the output generated by the {@link org.apache.juneau.json.JsonSerializer} class.
This class shares the same properties as JsonSerializer.
For convenience the {@link org.apache.juneau.json.JsonSerializer#getSchemaSerializer()} method has been added for creating instances of schema serializers from the regular serializer instance.

Sample Beans

public class Person { // Bean properties public String name; public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

The code for creating our POJO model and generating JSON-Schema is shown below:

// Get the one of the default schema serializers. JsonSchemaSerializer s = JsonSchemaSerializer.DEFAULT_SIMPLE_READABLE; // Get the JSON Schema for the POJO. String jsonSchema = s.serialize(new Person()); // This also works. jsonSchema = s.serialize(Person.class);

JSON Schema

{ type: 'object', description: 'org.apache.juneau.sample.Person', properties: { name: { type: 'string', description: 'java.lang.String' }, birthDate: { type: 'string', description: 'java.util.Calendar' }, addresses: { type: 'array', description: 'java.util.LinkedList<org.apache.juneau.sample.Address>', items: { type: 'object', description: 'org.apache.juneau.sample.Address', properties: { street: { type: 'string', description: 'java.lang.String' }, city: { type: 'string', description: 'java.lang.String' }, state: { type: 'string', description: 'java.lang.String' }, zip: { type: 'number', description: 'int' }, isCurrent: { type: 'boolean', description: 'boolean' } } } } } }

The following examples show how different data types are represented in XML. They mirror how the data structures are represented in JSON.

Simple types

The representation of loose (not a direct bean property value) simple types are shown below:

Maps

Loose maps and beans use the element <object> for encapsulation.

_type attributes are added to bean properties or map entries if the type cannot be inferred through reflection (e.g. an Object or superclass/interface value type).

Arrays

Loose collections and arrays use the element <array> for encapsulation.

Beans

Beans with Map properties

The {@link org.apache.juneau.xml.XmlSerializer} class is used to serialize POJOs into XML.

The {@link org.apache.juneau.xml.XmlDocSerializer} class is the same, but serializes a <?xml?> header at the top of the file.

The XML serializers provide the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonSerializer Common Serializer Properties}
• {@link org.apache.juneau.xml.XmlSerializer}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_addBeanTypes XML_addBeanTypes}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_addNamespaceUrisToRoot XML_addNamespaceUrisToRoot}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_autoDetectNamespaces XML_autoDetectNamespaces}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_defaultNamespace XML_defaultNamespace}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_enableNamespaces XML_enableNamespaces}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_namespaces XML_namespaces}
  • {@link org.apache.juneau.xml.XmlSerializer#XML_xsNamespace XML_xsNamespace}

The following pre-configured serializers are provided for convenience:

• {@link org.apache.juneau.xml.XmlSerializer}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT DEFAULT}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_JUNEAU_NAMESPACE DEFAULT_JUNEAU_NAMESPACE}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_NS DEFAULT_NS}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_NS_SQ DEFAULT_NS_SQ}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_NS_SQ_READABLE DEFAULT_NS_SQ_READABLE}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_SQ DEFAULT_SQ}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_SQ_READABLE DEFAULT_SQ_READABLE}
  • {@link org.apache.juneau.xml.XmlSerializer#DEFAULT_XS_NAMESPACE DEFAULT_XS_NAMESPACE}

The {@link org.apache.juneau.xml.XmlParser} class is used to parse XML into POJOs.

The XML parser provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonParser Common Parser Properties}
• {@link org.apache.juneau.xml.XmlParser}
  • {@link org.apache.juneau.xml.XmlParser#XML_eventAllocator XML_eventAllocator}
  • {@link org.apache.juneau.xml.XmlParser#XML_preserveRootElement XML_preserveRootElement}
  • {@link org.apache.juneau.xml.XmlParser#XML_reporter XML_reporter}
  • {@link org.apache.juneau.xml.XmlParser#XML_resolver XML_resolver}
  • {@link org.apache.juneau.xml.XmlParser#XML_validating XML_validating}

The following pre-configured parsers are provided for convenience:

• {@link org.apache.juneau.xml.XmlParser}
  • {@link org.apache.juneau.xml.XmlParser#DEFAULT DEFAULT}

The {@link org.apache.juneau.annotation.Bean#typeName() @Bean(typeName)} annotation can be used to override the Juneau default name on bean elements. Types names serve two distinct purposes:

1. To override the element name.
2. To serve as a class identifier so that the bean class can be inferred during parsing if it cannot automatically be inferred through reflection.

Example

On bean properties, a _type attribute will be added if a type name is present and the bean class cannot be inferred through reflection.

In the following example, a type attribute is used on property 'b' but not property 'a' since 'b' is of type Object and therefore the bean class cannot be inferred.

Example

• string, number, boolean, object, array, and null are reserved keywords that cannot be used as type names.

Beans with type names are often used in conjunction with the {@link org.apache.juneau.annotation.Bean#beanDictionary() @Bean(beanDictionary)} and {@link org.apache.juneau.annotation.BeanProperty#beanDictionary() @BeanProperty(beanDictionary)} annotations so that the beans can be resolved at parse time.
These annotations are not necessary during serialization, but are needed during parsing in order to resolve the bean types.

The following examples show how type names are used under various circumstances.

Pay special attention to when _type attributes are and are not used.

Examples

Bean type names are also used for resolution when abstract fields are used.
The following examples show how they are used in a variety of circumstances.

On a side note, characters that cannot be represented in XML 1.0 are encoded using a simple encoding.
Note in the examples below, some characters such as '\n', '\t', and '\r' can be represented as XML entities when used in text but not in element names. Other characters such as '\b' and '\f' cannot be encoded in XML 1.0 at all without inventing our own notation.
Whitespace characters in element names are encoded as well as whitespace end characters in text.

While it's true that these characters CAN be represented in XML 1.1, it's impossible to parse XML 1.1 text in Java without the XML containing an XML declaration.
Unfortunately, this, and the uselessness of the {@link javax.xml.stream.XMLInputFactory#IS_REPLACING_ENTITY_REFERENCES} setting in Java forced us to make some hard design decisions that may not be the most elegant.

The {@link org.apache.juneau.xml.annotation.Xml#childName() @Xml(childName)} annotation can be used to specify the name of XML child elements for bean properties of type collection or array.

Example

The {@link org.apache.juneau.xml.annotation.Xml#format() @Xml(format)} annotation can be used to tweak the XML format of a POJO.
The value is set to an enum value of type {@link org.apache.juneau.xml.annotation.XmlFormat}.
This annotation can be applied to both classes and bean properties.

The {@link org.apache.juneau.xml.annotation.XmlFormat#ATTR} format can be applied to bean properties to serialize them as XML attributes instead of elements.
Note that this only supports properties of simple types (e.g. strings, numbers, booleans).

Example

The {@link org.apache.juneau.xml.annotation.XmlFormat#ATTRS} format can be applied to bean classes to force all bean properties to be serialized as XML attributes instead of child elements.

Example

The {@link org.apache.juneau.xml.annotation.XmlFormat#ELEMENT} format can be applied to bean properties to override the {@link org.apache.juneau.xml.annotation.XmlFormat#ATTRS} format applied on the bean class.

Example

The {@link org.apache.juneau.xml.annotation.XmlFormat#ATTRS} format can be applied to a single bean property of type Map<String,Object> to denote arbitrary XML attribute values on the element.
These can be mixed with other {@link org.apache.juneau.xml.annotation.XmlFormat#ATTR} annotated properties, but there must not be an overlap in bean property names and map keys.

Example

The {@link org.apache.juneau.xml.annotation.XmlFormat#COLLAPSED} format can be applied to bean properties of type array/Collection.
This causes the child objects to be serialized directly inside the bean element.
This format must be used in conjunction with {@link org.apache.juneau.xml.annotation.Xml#childName() @Xml(childName)} to differentiate which collection the values came from if you plan on parsing the output back into beans.
Note that child names must not conflict with other property names.

The {@link org.apache.juneau.xml.annotation.XmlFormat#ELEMENTS} format can be applied to a single bean property of either a simple type or array/Collection.
It allows free-form child elements to be formed.
All other properties on the bean MUST be serialized as attributes.

The {@link org.apache.juneau.xml.annotation.XmlFormat#MIXED} format is similar to {@link org.apache.juneau.xml.annotation.XmlFormat#ELEMENTS} except elements names on primitive types (string/number/boolean/null) are stripped from the output.
This format particularly useful when combined with bean dictionaries to produce mixed content.
The bean dictionary isn't used during serialization, but it is needed during parsing to resolve bean types.

The {@link org.apache.juneau.xml.annotation.XmlFormat#MIXED_PWS} format identical to {@link org.apache.juneau.xml.annotation.XmlFormat#MIXED} except whitespace characters are preserved in the output.

Whitespace (tabs and newlines) are not added to MIXED child nodes in readable-output mode.
This helps ensures strings in the serialized output can be losslessly parsed back into their original forms when they contain whitespace characters.
If the {@link javax.xml.stream.XMLInputFactory#IS_REPLACING_ENTITY_REFERENCES} setting was not useless in Java, we could support lossless readable XML for MIXED content.
But as of Java 8, it still does not work.

XML suffers from other deficiencies as well that affect MIXED content.
For example, <X></X> and <X/> are equivalent in XML and indistinguishable by the Java XML parsers.
This makes it impossible to differentiate between an empty element and an element containing an empty string.
This causes empty strings to get lost in translation.
To alleviate this, we use the constructs "_xE000_" to represent an empty string, and "_x0020_" to represent leading and trailing spaces.

The examples below show how whitespace is handled under various circumstances:

It should be noted that when using MIXED, you are not guaranteed to parse back the exact same content since side-by-side strings in the content will end up concatenated when parsed.

The {@link org.apache.juneau.xml.annotation.XmlFormat#TEXT} format is similar to {@link org.apache.juneau.xml.annotation.XmlFormat#MIXED} except it's meant for solitary objects that get serialized as simple child text nodes.
Any object that can be serialize to a String can be used.
The {@link org.apache.juneau.xml.annotation.XmlFormat#TEXT_PWS} is the same except whitespace is preserved in the output.

The {@link org.apache.juneau.xml.annotation.XmlFormat#XMLTEXT} format is similar to {@link org.apache.juneau.xml.annotation.XmlFormat#TEXT} except it's meant for strings containing XML that should be serialized as-is to the document.
Any object that can be serialize to a String can be used.
During parsing, the element content gets parsed with the rest of the document and then re-serialized to XML before being set as the property value. This process may not be perfect (e.g. double quotes may be replaced by single quotes, etc...).

Let's go back to the example of our original Person bean class, but add some namespace annotations:

Sample Beans

@Xml(prefix="per") @Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Xml(prefix="addr") @Bean(typeName="address") public class Address { // Bean properties @Xml(prefix="mail") public String street, city; @Xml(prefix="mail") public StateEnum state; @Xml(prefix="mail") public int zip; public boolean isCurrent; // Getters/setters omitted }

The namespace URLs can either be defined as part of the {@link org.apache.juneau.xml.annotation.Xml @Xml} annotation, or can be defined at the package level with the {@link org.apache.juneau.xml.annotation.XmlSchema @XmlSchema} annotation.
Below shows it defined at the package level:

package-info.java

@XmlSchema( prefix="ab", // Default namespace xmlNs={ @XmlNs(prefix="ab", namespaceURI="http://www.apache.org/addressBook/"), @XmlNs(prefix="per", namespaceURI="http://www.apache.org/person/"), @XmlNs(prefix="addr", namespaceURI="http://www.apache.org/address/"), @XmlNs(prefix="mail", namespaceURI="http://www.apache.org/mail/") } ) package org.apache.juneau.examples.addressbook;

Sample Code

Person p = new Person() .name("John Smith") .birthDate("1946-08-12T00:00:00Z") .addresses( new Address() .street("100 Main Street") .city("Anywhereville") .state(NY) .zip(12345) .isCurrent(true); ); // Create a new serializer with readable output, this time with namespaces enabled. // Note that this is identical to XmlSerializer.DEFAULT_NS_SQ_READABLE. XmlSerializer s = XmlSerializer.create().ns().ws().sq().build(); String xml = s.serialize(p);

Now when we run this code, we'll see namespaces added to our output:

<per:person> <per:name>John Smith</per:name> <per:birthDate>1946-08-12T04:00:00Z</per:birthDate> <per:addresses> <addr:address> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </addr:address> </per:addresses> </per:person>

Enabling the {@link org.apache.juneau.xml.XmlSerializer#XML_addNamespaceUrisToRoot} setting results in the namespace URLs being added to the root node:

<per:person xmlns='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/' > <per:name>John Smith</per:name> <per:birthDate>1946-08-12T04:00:00Z</per:birthDate> <per:addresses> <addr:address> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </addr:address> </per:addresses> </per:person>

We can simplify the output by setting the default namespace on the serializer so that all the elements do not need to be prefixed:

// Create a new serializer with readable output, this time with namespaces enabled. XmlSerializer s = XmlSerializer.create().ws().sq().ns() .defaultNamespaceUri("http://www.apache.org/person/") .build();

This produces the following equivalent where the elements don't need prefixes since they're already in the default document namespace:

<person xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/' > <name>John Smith</name> <birthDate>1946-08-12T04:00:00Z</birthDate> <addresses> <addr:address> <mail:street>100 Main Street</mail:street> <mail:city>Anywhereville</mail:city> <mail:state>NY</mail:state> <mail:zip>12345</mail:zip> <addr:isCurrent>true</addr:isCurrent> </addr:address> </addresses> </person>

One important property on the XML serializer class is {@link org.apache.juneau.xml.XmlSerializer#XML_autoDetectNamespaces XML_autoDetectNamespaces}.
This property tells the serializer to make a first-pass over the data structure to look for namespaces defined on classes and bean properties.
In high-performance environments, you may want to consider disabling auto-detection and providing your own explicit list of namespaces to the serializer to avoid this scanning step.

The following code will produce the same output as before, but will perform slightly better since it avoids this pre-scan step.

// Create a new serializer with readable output, this time with namespaces enabled. XmlSerializer s = XmlSerializer.create() .ws() .sq() .autoDetectNamespaces(false) .namespaces("{per:'http://www.apache.org/person/'}") .build();

Juneau provides the {@link org.apache.juneau.xmlschema.XmlSchemaSerializer} class for generating XML-Schema documents that describe the output generated by the {@link org.apache.juneau.xml.XmlSerializer} class.
This class shares the same properties as XmlSerializer.
Since the XML output differs based on settings on the XML serializer class, the XML-Schema serializer class must have the same property values as the XML serializer class it's describes.
To help facilitate creating an XML Schema serializer with the same properties as the corresponding XML serializer, the {@link org.apache.juneau.xml.XmlSerializer#getSchemaSerializer()} method has been added.

XML-Schema requires a separate file for each namespace.
Unfortunately, does not mesh well with the Juneau serializer architecture which serializes to single writers.
To get around this limitation, the schema serializer will produce a single output, but with multiple schema documents separated by the null character ('\u0000') to make it simple to split apart.

Lets start with an example where everything is in the same namespace.
We'll use the classes from before, but remove the references to namespaces.
Since we have not defined a default namespace, everything is defined under the default Juneau namespace.

Sample Beans

@Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Bean(typeName="address") public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

The code for creating our POJO model and generating XML Schema is shown below:

// Create a new serializer with readable output. XmlSerializer s = XmlSerializer.create() .ws() .ns() .sq() .addNamespaceUrisToRoot(true) .build(); // Create the equivalent schema serializer. XmlSchemaSerializer ss = s.getSchemaSerializer(); // Get the XML Schema corresponding to the XML generated above. String xmlSchema = ss.serialize(new Person());

XML-Schema results

<schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/2013/Juneau' elementFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau'> <element name='person' _type='juneau:org.apache.juneau.examples.addressbook.Person'/> <complexType name='org.apache.juneau.examples.addressbook.Person'> <sequence> <element name='name' _type='string' minOccurs='0'/> <element name='birthDate' _type='juneau:java.util.Calendar' minOccurs='0'/> <element name='addresses' _type='juneau:java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_' minOccurs='0'/> </sequence> </complexType> <complexType name='java.util.Calendar'> <sequence> <any processContents='skip' maxOccurs='unbounded' minOccurs='0'/> </sequence> </complexType> <complexType name='java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_'> <sequence> <choice minOccurs='0' maxOccurs='unbounded'> <element name='address' _type='juneau:org.apache.juneau.examples.addressbook.Address'/> <element name='null' _type='string'/> </choice> </sequence> </complexType> <complexType name='org.apache.juneau.examples.addressbook.Address'> <sequence> <element name='street' _type='string' minOccurs='0'/> <element name='city' _type='string' minOccurs='0'/> <element name='state' _type='string' minOccurs='0'/> <element name='zip' _type='integer' minOccurs='0'/> <element name='isCurrent' _type='boolean' minOccurs='0'/> </sequence> </complexType> </schema>

Now if we add in some namespaces, we'll see how multiple namespaces are handled.

Sample Beans with multiple namespaces

@Xml(prefix="per") @Bean(typeName="person") public class Person { // Bean properties public String name; @Swap(CalendarSwap.ISO8601DTZ.class) public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } @Xml(prefix="addr") @Bean(typeName="address") public class Address { // Bean properties @Xml(prefix="mail") public String street, city; @Xml(prefix="mail") public StateEnum state; @Xml(prefix="mail") public int zip; public boolean isCurrent; // Getters/setters omitted }

The schema consists of 4 documents separated by a '\u0000' character.

XML-Schema results

<schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/2013/Juneau' elementFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/person/' schemaLocation='per.xsd'/> <import namespace='http://www.apache.org/address/' schemaLocation='addr.xsd'/> <import namespace='http://www.apache.org/mail/' schemaLocation='mail.xsd'/> <complexType name='int'> <simpleContent> <extension base='integer'/> </simpleContent> </complexType> <complexType name='java.lang.String'> <simpleContent> <extension base='string'/> </simpleContent> </complexType> <complexType name='java.net.URI'> <simpleContent> <extension base='string'/> </simpleContent> </complexType> <complexType name='java.util.Calendar'> <sequence> <any processContents='skip' maxOccurs='unbounded' minOccurs='0'/> </sequence> </complexType> <complexType name='java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_'> <sequence> <choice minOccurs='0' maxOccurs='unbounded'> <element name='address' _type='addr:org.apache.juneau.examples.addressbook.Address'/> <element name='null' _type='string'/> </choice> </sequence> </complexType> <complexType name='boolean'> <simpleContent> <extension base='boolean'/> </simpleContent> </complexType> </schema> [\u0000] <schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/person/' elementFormDefault='qualified' attributeFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/2013/Juneau' schemaLocation='juneau.xsd'/> <import namespace='http://www.apache.org/address/' schemaLocation='addr.xsd'/> <import namespace='http://www.apache.org/mail/' schemaLocation='mail.xsd'/> <element name='person' _type='per:org.apache.juneau.examples.addressbook.Person'/> <complexType name='org.apache.juneau.examples.addressbook.Person'> <sequence> <any minOccurs='0' maxOccurs='unbounded'/> </sequence> <attribute name='uri' _type='string'/> </complexType> <element name='name' _type='juneau:java.lang.String'/> <element name='birthDate' _type='juneau:java.util.Calendar'/> <element name='addresses' _type='juneau:java.util.LinkedList_x003C_org.apache.juneau.examples.addressbook.Address_x003E_'/> </schema> [\u0000] <schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/address/' elementFormDefault='qualified' attributeFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/2013/Juneau' schemaLocation='juneau.xsd'/> <import namespace='http://www.apache.org/person/' schemaLocation='per.xsd'/> <import namespace='http://www.apache.org/mail/' schemaLocation='mail.xsd'/> <complexType name='org.apache.juneau.examples.addressbook.Address'> <sequence> <any minOccurs='0' maxOccurs='unbounded'/> </sequence> </complexType> <element name='isCurrent' _type='juneau:boolean'/> </schema> [\u0000] <schema xmlns='http://www.w3.org/2001/XMLSchema' targetNamespace='http://www.apache.org/mail/' elementFormDefault='qualified' attributeFormDefault='qualified' xmlns:juneau='http://www.apache.org/2013/Juneau' xmlns:per='http://www.apache.org/person/' xmlns:addr='http://www.apache.org/address/' xmlns:mail='http://www.apache.org/mail/'> <import namespace='http://www.apache.org/2013/Juneau' schemaLocation='juneau.xsd'/> <import namespace='http://www.apache.org/person/' schemaLocation='per.xsd'/> <import namespace='http://www.apache.org/address/' schemaLocation='addr.xsd'/> <element name='street' _type='juneau:java.lang.String'/> <element name='city' _type='juneau:java.lang.String'/> <element name='state' _type='juneau:java.lang.String'/> <element name='zip' _type='juneau:int'/> </schema>

For convenience, the {@link org.apache.juneau.xmlschema.XmlSchemaSerializer #getValidator(SerializerSession,Object)} method is provided to create a {@link javax.xml.validation.Validator} using the input from the serialize method.

The following examples show how different data types are represented in HTML. They mirror how the data structures are represented in JSON.

Simple types

The representation for simple types mirror those produced by the XML serializer. Tags are added to help differentiate data types when they cannot be inferred through reflection. These tags are ignored by browsers and treated as plain text.

Maps

Maps and beans are represented as tables.

The _type attribute is added to differentiate between objects (maps/beans) and arrays (arrays/collections).

Arrays

Collections and arrays are represented as ordered lists.

Collections

Beans

Beans with Map properties

The {@link org.apache.juneau.html.HtmlSerializer} class is used to serialize POJOs into HTML.

The {@link org.apache.juneau.html.HtmlDocSerializer} class is the same, but wraps the serialized POJO inside a document template consisting of header, nav, aside, and footer sections.

The HTML serializers provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonSerializer Common Serializer Properties}
• {@link org.apache.juneau.html.HtmlSerializer}
  • {@link org.apache.juneau.html.HtmlSerializer#HTML_addBeanTypes HTML_addBeanTypes}
  • {@link org.apache.juneau.html.HtmlSerializer#HTML_addKeyValueTableHeaders HTML_addKeyValueTableHeaders}
  • {@link org.apache.juneau.html.HtmlSerializer#HTML_detectLabelParameters HTML_detectLabelParameters}
  • {@link org.apache.juneau.html.HtmlSerializer#HTML_detectLinksInStrings HTML_detectLinksInStrings}
  • {@link org.apache.juneau.html.HtmlSerializer#HTML_labelParameter HTML_labelParameter}
  • {@link org.apache.juneau.html.HtmlSerializer#HTML_uriAnchorText HTML_uriAnchorText}
• {@link org.apache.juneau.html.HtmlDocSerializer}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_aside HTMLDOC_aside}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_footer HTMLDOC_footer}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_head HTMLDOC_head}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_header HTMLDOC_header}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_nav HTMLDOC_nav}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_navlinks HTMLDOC_navlinks}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_noResultsMessage HTMLDOC_noResultsMessage}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_nowrap HTMLDOC_nowrap}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_script HTMLDOC_script}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_style HTMLDOC_style}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_stylesheet HTMLDOC_stylesheet}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_template HTMLDOC_template}

The following pre-configured serializers are provided for convenience:

• {@link org.apache.juneau.html.HtmlSerializer}
  • {@link org.apache.juneau.html.HtmlSerializer#DEFAULT }
  • {@link org.apache.juneau.html.HtmlSerializer#DEFAULT_SQ }
  • {@link org.apache.juneau.html.HtmlSerializer#DEFAULT_SQ_READABLE }
• {@link org.apache.juneau.html.HtmlDocSerializer}
  • {@link org.apache.juneau.html.HtmlDocSerializer#DEFAULT }

The {@link org.apache.juneau.html.HtmlParser} class is used to parse HTML into POJOs.
They can also parse the contents produced by {@link org.apache.juneau.html.HtmlDocSerializer}.

The HTML parser provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonParser Common Parser}

The following pre-configured parsers are provided for convenience:

• {@link org.apache.juneau.html.HtmlParser}
  • {@link org.apache.juneau.html.HtmlParser#DEFAULT DEFAULT}

The {@link org.apache.juneau.html.annotation.Html @Html} annotation can be used to customize how POJOs are serialized to HTML on a per-class/field/method basis.

• {@link org.apache.juneau.html.annotation.Html}
  • {@link org.apache.juneau.html.annotation.Html#anchorText() anchorText}
  • {@link org.apache.juneau.html.annotation.Html#format() format}
  • {@link org.apache.juneau.html.annotation.Html#link() link}
  • {@link org.apache.juneau.html.annotation.Html#noTableHeaders() noTableHeaders}
  • {@link org.apache.juneau.html.annotation.Html#noTables() noTables}
  • {@link org.apache.juneau.html.annotation.Html#render() render}

The {@link org.apache.juneau.html.annotation.Html#link @Html(link)} annotation adds a hyperlink to a bean property when rendered as HTML.

Example:

public class FileSpace { // Add a hyperlink to this bean property. @Html(link="servlet:/drive/{drive}") public String getDrive() {...} }

The {@link org.apache.juneau.html.annotation.Html#anchorText @Html(anchorText)} annotation is used to specify the anchor text of a hyperlink.

Example:

// Produces <a href='...'>CLICK ME!</a> when serialized to HTML. public class FileSpace { // Add a hyperlink to this bean property. @Html(link="servlet:/drive/{drive}", anchorText="CLICK ME!") public String getDrive() {...} }

The {@link org.apache.juneau.html.annotation.Html#format @Html(format)} annotation is used to specify what format to use for HTML elements.
For example, the HTML beans defined in the {@link org.apache.juneau.dto.html5} package use format=XML so that the beans get serialized as standard XML:

Example:

// Parent class of all HTML DTO beans. @Html(format=XML) public abstract class HtmlElement {...}

The {@link org.apache.juneau.html.annotation.Html#noTableHeaders @Html(noTableHeaders)} annotation is used to prevent beans from being serialized with table headers.

The {@link org.apache.juneau.html.annotation.Html#noTables @Html(noTables)} annotation is used to force beans to be serialized as trees instead of tables

The {@link org.apache.juneau.html.annotation.Html#render @Html(render)} annotation allows for custom rendering of bean property values when serialized as HTML. Using this class, you can alter the CSS style and HTML content of the bean property.

The following example shows two render classes that customize the appearance of the pctFull and status columns in the code below:

import static org.apache.juneau.dto.html5.HtmlBuilder.*; // Our bean class public class FileSpace { private final String drive; private final long total, available; public FileSpace(String drive, long total, long available) { this.drive = drive; this.total = total; this.available = available; } @Html(link="drive/{drive}") public String getDrive() { return drive; } public long getTotal() { return total; } public long getAvailable() { return available; } @Html(render=FileSpacePctRender.class) public float getPctFull() { return ((100 * available) / total); } @Html(render=FileSpaceStatusRender.class) public FileSpaceStatus getStatus() { float pf = getPctFull(); if (pf < 80) return FileSpaceStatus.OK; if (pf < 90) return FileSpaceStatus.WARNING; return FileSpaceStatus.SEVERE; } }

// Possible values for the getStatus() method public enum FileSpaceStatus { OK, WARNING, SEVERE; }

// Custom render for getPctFull() method public class FileSpacePctRender extends HtmlRender<Float> { @Override public String getStyle(SerializerSession session, Float value) { if (value < 80) return "background-color:lightgreen;text-align:center"; if (value < 90) return "background-color:yellow;text-align:center"; return "background-color:red;text-align:center;border:;animation:color_change 0.5s infinite alternate"; } @Override public Object getContent(SerializerSession session, Float value) { if (value >= 90) return div( String.format("%.0f%%", value), style("@keyframes color_change { from { background-color: red; } to { background-color: yellow; }") ); return String.format("%.0f%%", value); } }

// Custom render for getStatus() method public class FileSpaceStatusRender extends HtmlRender<FileSpaceStatus> { @Override public String getStyle(SerializerSession session, FileSpaceStatus value) { return "text-align:center"; } @Override public Object getContent(SerializerSession session, FileSpaceStatus value) { switch (value) { case OK: return img().src(URI.create("servlet:/htdocs/ok.png")); case WARNING: return img().src(URI.create("servlet:/htdocs/warning.png")); default: return img().src(URI.create("servlet:/htdocs/severe.png")); } } }

{@link org.apache.juneau.html.HtmlDocSerializer} is an extension of {@link org.apache.juneau.html.HtmlSerializer} that wraps serialized POJOs in a complete HTML document.

• {@link org.apache.juneau.html.HtmlDocSerializer}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_aside HTMLDOC_aside}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_footer HTMLDOC_footer}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_head HTMLDOC_head}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_header HTMLDOC_header}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_nav HTMLDOC_nav}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_navlinks HTMLDOC_navlinks}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_noResultsMessage HTMLDOC_noResultsMessage}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_nowrap HTMLDOC_nowrap}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_script HTMLDOC_script}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_style HTMLDOC_style}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_stylesheet HTMLDOC_stylesheet}
  • {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_template HTMLDOC_template}

This class is used extensively in the creation of POJO-based user interfaces in the REST API.

Example:

/** * Sample REST resource that prints out a simple "Hello world!" message. */ @RestResource( path="/helloWorld", htmldoc=@HtmlDoc( navlinks={ "up: request:/..", "options: servlet:/?method=OPTIONS" }, aside={ "<div style='max-width:400px' class='text'>", " <p>This page shows a resource that simply response with a 'Hello world!' message</p>", " <p>The POJO serialized is a simple String.</p>", "</div>" } ) ) public class HelloWorldResource extends BasicRestServlet {...}

The {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_template HTMLDOC_template} setting defines a template for the HTML page being generated. The default template is described next.

The {@link org.apache.juneau.html.BasicHtmlDocTemplate} class defines a default template for HTML documents created by {@link org.apache.juneau.html.HtmlDocSerializer}.

The HTML document created by this template consists of the following structure:

<html> <head> <style type='text/css'> CSS styles and links to stylesheets </style> </head> <body> <header> Page header </header> <nav> Navigation links </nav> <aside> Side-bar text </aside> <article> Contents of serialized object </article> <footer> Footer message </footer> </body> </html>

Custom page templates can be created by implementing the {@link org.apache.juneau.html.HtmlDocTemplate} interface and associating it with your {@link org.apache.juneau.html.HtmlDocSerializer} using the {@link org.apache.juneau.html.HtmlDocSerializer#HTMLDOC_template HTMLDOC_template} setting.

• {@link org.apache.juneau.html.HtmlDocTemplate}
  • {@link org.apache.juneau.html.HtmlDocTemplate#writeTo(HtmlDocSerializerSession,HtmlWriter,Object) writeTo(HtmlDocSerializerSession,HtmlWriter,Object)}

The interface implementation is open-ended allowing you to define the contents of the page any way you wish.

The {@link org.apache.juneau.html.HtmlSchemaSerializer} class is the HTML-equivalent to the {@link org.apache.juneau.json.JsonSchemaSerializer} class. It's used to generate HTML versions of JSON-Schema documents that describe the output generated by the {@link org.apache.juneau.json.JsonSerializer} class.

Sample Beans

public class Person { // Bean properties public String name; public Calendar birthDate; public List<Address> addresses; // Getters/setters omitted } public class Address { // Bean properties public String street, city; public StateEnum state; public int zip; public boolean isCurrent; // Getters/setters omitted }

The code for creating our POJO model and generating HTML-Schema is shown below:

// Get the one of the default schema serializers. HtmlSchemaSerializer s = HtmlSchemaSerializer.DEFAULT_SIMPLE_READABLE; // Get the HTML Schema for the POJO. String htmlSchema = s.serialize(new Person()); // This also works. htmlSchema = s.serialize(Person.class);

The result is the HTML table shown below:

General methodology:

Refer to the UON specification for a complete set of syntax rules.

The {@link org.apache.juneau.uon.UonSerializer} class is used to serialize POJOs into UON.

The UON serializers provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonSerializer Common Serializer Properties}
• {@link org.apache.juneau.uon.UonSerializer}
  • {@link org.apache.juneau.uon.UonSerializer#UON_addBeanTypes UON_addBeanTypes}
  • {@link org.apache.juneau.uon.UonSerializer#UON_encoding UON_encoding}
  • {@link org.apache.juneau.uon.UonSerializer#UON_paramFormat UON_paramFormat}

The following pre-configured serializers are provided for convenience:

• {@link org.apache.juneau.uon.UonSerializer}
  • {@link org.apache.juneau.uon.UonSerializer#DEFAULT DEFAULT}
  • {@link org.apache.juneau.uon.UonSerializer#DEFAULT_ENCODING DEFAULT_ENCODING}
  • {@link org.apache.juneau.uon.UonSerializer#DEFAULT_READABLE DEFAULT_READABLE}

The {@link org.apache.juneau.uon.UonParser} class is used to parse UON into POJOs.

The UON parser provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonParser Common Parser Properties}
• {@link org.apache.juneau.uon.UonParser}
  • {@link org.apache.juneau.uon.UonParser#UON_decoding UON_decoding}
  • {@link org.apache.juneau.uon.UonParser#UON_validateEnd UON_validateEnd}

The following pre-configured parsers are provided for convenience:

• {@link org.apache.juneau.uon.UonParser}
  • {@link org.apache.juneau.uon.UonParser#DEFAULT DEFAULT}
  • {@link org.apache.juneau.uon.UonParser#DEFAULT_DECODING DEFAULT_DECODING}

General methodology:

Refer to the UON specification for a complete set of syntax rules.

The {@link org.apache.juneau.urlencoding.UrlEncodingSerializer} class is used to serialize POJOs into URL-Encoding.

The URL-Encoding serializers provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonSerializer Common Serializer Properties}
• {@link org.apache.juneau.urlencoding.UrlEncodingSerializer}
  • {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#URLENC_expandedParams URLENC_expandedParams}

The following pre-configured serializers are provided for convenience:

• {@link org.apache.juneau.urlencoding.UrlEncodingSerializer}
  • {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#DEFAULT DEFAULT}
  • {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#DEFAULT_EXPANDED DEFAULT_EXPANDED}
  • {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#DEFAULT_PLAINTEXT DEFAULT_PLAINTEXT}
  • {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#DEFAULT_READABLE DEFAULT_READABLE}

The {@link org.apache.juneau.urlencoding.UrlEncodingParser} class is used to parse URL-Encoding into POJOs.

The URL-Encoding parser provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonParser Common Parser Properties}
• {@link org.apache.juneau.urlencoding.UrlEncodingParser}
  • {@link org.apache.juneau.urlencoding.UrlEncodingParser#URLENC_expandedParams URLENC_expandedParams}

The following pre-configured parsers are provided for convenience:

• {@link org.apache.juneau.urlencoding.UrlEncodingParser}
  • {@link org.apache.juneau.urlencoding.UrlEncodingParser#DEFAULT DEFAULT}

The {@link org.apache.juneau.urlencoding.annotation.UrlEncoding @UrlEncoding} annotation is used to override the behavior of {@link org.apache.juneau.urlencoding.UrlEncodingSerializer} on individual bean classes or properties.

• {@link org.apache.juneau.urlencoding.annotation.UrlEncoding}
  • {@link org.apache.juneau.urlencoding.annotation.UrlEncoding#expandedParams() expandedParams}

The {@link org.apache.juneau.urlencoding.annotation.UrlEncoding#expandedParams() expandedParams} setting is used to force bean properties of type array or Collection to be expanded into multiple key/value pairings.
It's identical in behavior to using the {@link org.apache.juneau.urlencoding.UrlEncodingSerializer#URLENC_expandedParams} and {@link org.apache.juneau.urlencoding.UrlEncodingParser#URLENC_expandedParams} properties, but applies to only individual bean properties.

The {@link org.apache.juneau.msgpack.MsgPackSerializer} class is used to serialize POJOs into MessagePack.

The MessagePack serializer provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonSerializer Common Serializer Properties}
• {@link org.apache.juneau.msgpack.MsgPackSerializer}
  • {@link org.apache.juneau.msgpack.MsgPackSerializer#MSGPACK_addBeanTypes MSGPACK_addBeanTypes}

The following pre-configured serializers are provided for convenience:

• {@link org.apache.juneau.msgpack.MsgPackSerializer}
  • {@link org.apache.juneau.msgpack.MsgPackSerializer#DEFAULT DEFAULT}

The {@link org.apache.juneau.msgpack.MsgPackParser} class is used to parse MessagePack into POJOs.

The MessagePack parser provides the following settings:

• {@doc juneau-marshall.ConfigurableProperties.Common Common Properties}
• {@doc juneau-marshall.ConfigurableProperties.CommonParser Common Parser Properties}

The following pre-configured parsers are provided for convenience:

• {@link org.apache.juneau.msgpack.MsgPackParser}
  • {@link org.apache.juneau.msgpack.MsgPackParser#DEFAULT DEFAULT}

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:

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.create().type("string").format("byte").build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart = s.serialize(schema, myPojo); // Convert BASE64-encoded string back into a POJO. HttpPartParser p = OpenApiParser.DEFAULT; myPojo = p.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.create().type("string").format("byte").minLength(100).build(); // Convert POJO to BASE64-encoded string. HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart; try { httpPart = s.serialize(schema, myPojo); } catch (SchemaValidationException e) { // Oops, output too small. } // Convert BASE64-encoded string back into a POJO. HttpPartParser p = OpenApiParser.DEFAULT; try { myPojo = p.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.

The {@link org.apache.juneau.oapi.OpenApiSerializer} class is used to convert POJOs to HTTP parts.

Later we'll describe how to use HTTP-Part annotations to define OpenAPI schemas for serialization and parsing of HTTP parts.
The following example is a preview showing an HTTP body defined as pipe-delimited list of comma-delimited numbers (e.g. "1,2,3|4,5,6|7,8,9"):

@RestMethod(method="POST", path="/2dLongArray") public void post2dLongArray( @Body( schema=@Schema( items=@Items( collectionFormat="pipes", items=@SubItems( collectionFormat="csv", type="integer", format="int64", minimum="0", maximum="100" minLength=1, maxLength=10 ) ) minLength=1, maxLength=10 ) ) Long[][] body ) {...}

Under-the-covers, this gets converted to the following schema object:

import static org.apache.juneau.httppart.HttpPartSchema.*; HttpPartSchema schema = create() .items( create() .collectionFormat("pipes") .items( create() .collectionFormat("csv") .type("integer") .format("int64") .minimum("0") .maximum("100") .minLength(1) .maxLength=(10) ) ) .build();

The following code shows how the schema above can be used to create our pipe+csv list of numbers:

// Our POJO being serialized. Long[][] input = .... // The serializer to use. HttpPartSerializer s = OpenApiSerializer.DEFAULT; // Convert POJO to a string. try { String httpPart = s.serialize(schema, input); } catch (SchemaValidationException e) { // Oops, one of the restrictions were not met. }

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

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

// Sample POJO class convertable to a Long[][]. public class MyPojo { // toX method used by serializer. public Long[][] to2dLongs() {...} }

In the example above, our POJO class can be used to create our pipe-delimited list of comma-delimited numbers:

// Our POJO being serialized. MyPojo input = .... // The serializer to use. HttpPartSerializer s = OpenApiSerializer.DEFAULT; // Convert POJO to a string. try { String httpPart = s.serialize(schema, input); } catch (SchemaValidationException e) { // Oops, one of the restrictions were not met. }

The object type is not officially part of the OpenAPI standard. However, Juneau supports serializing Maps and beans to HTTP parts using UON notation.

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

public class MyBean { private static byte[] FOOB = "foo".getBytes(); public String f1 = "foo"; public byte[] f2 = FOOB; public byte[] f3 = FOOB; public byte[] f4 = FOOB; public Calendar f5 = parseIsoCalendar("2012-12-21T12:34:56Z"); public String f6 = "foo"; public int f7 = 1; public Long f8 = 2l; public float f9 = 1.0; public Double f10 = 1.0; public Boolean f11 = true; public Object fExtra = "1"; }

We define the following schema:

import static org.apache.juneau.httppart.HttpPartSchema.*; HttpPartSchema ps = schema("object") .property("f1", schema("string")) .property("f2", schema("string", "byte")) .property("f3", schema("string", "binary")) .property("f4", schema("string", "binary-spaced")) .property("f5", schema("string", "date-time")) .property("f6", schema("string", "uon")) .property("f7", schema("integer")) .property("f8", schema("integer", "int64")) .property("f9", schema("number")) .property("f10", schema("number", "double")) .property("f11", schema("boolean")) .additionalProperties(schema("integer")) .build();

Then we serialize our bean:

HttpPartSerializer s = OpenApiSerializer.DEFAULT; String httpPart = s.serialize(schema, new MyBean());

The results of this serialization is shown below:

( 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 )

The following is an example of a bean with various array property types:

public class MyBean { private static byte[] FOOB = "foo".getBytes(); public String[] f1 = new String[]{"a,b",null}, public byte[][] f2 = new byte[][]{FOOB,null}, public byte[][] f3 = new byte[][]{FOOB,null}, public byte[][] f4 = new byte[][]{FOOB,null}, public Calendar[] f5 = new Calendar[]{parseIsoCalendar("2012-12-21T12:34:56Z"),null}, public String[] f6 = new String[]{"a","b",null}, public int[] f7 = new int[]{1,2,null}, public Integer[] f8 = new Integer[]{3,4,null}, public float[] f9 = new float[]{1f,2f,null}, public Float[] f10 = new Float[]{3f,4f,null}, public Boolean[] f11 = new Boolean[]{true,false,null}, public Object[] fExtra = new Object[]{1,"2",null}; }