6.1.0 (Feb 25, 2017)

Juneau 6.1.0 is a major update.

In particular, this release cleans up the {@link oaj.BeanContext} API to match the {@link oaj.PropertyStore}/{@link oaj.Context}/{@link oaj.Session} paradigm previously used in the serializer and parser APIs. It also makes several improvements to the HTML and XML serialization support and introduces HTML5 DTO beans.

##### org.apache.juneau

- Improvements to XML serialization support.
  - New supported XML formats:
    - {@link oaj.xml.annotation.XmlFormat#ATTRS} format can now be applied to bean classes to have all bean properties serialized as attributes instead of elements by default.
    - {@link oaj.xml.annotation.XmlFormat#ELEMENT} format can now be applied to bean properties to override the {@link oaj.xml.annotation.XmlFormat#ATTRS} setting above on specific bean properties.
    - New {@link oaj.xml.annotation.XmlFormat#ELEMENTS} format can be applied to a bean property of type array/Collection to represent the child elements.
    - New {@link oaj.xml.annotation.XmlFormat#MIXED} format can be applied to a bean property of type array/Collection to represent mixed content (text + child elements).
    - New {@link oaj.xml.annotation.XmlFormat#MIXED_PWS} format. Identical to MIXED except preserves whitespace.
    - New {@link oaj.xml.annotation.XmlFormat#TEXT} format can be applied to a bean property of a single object to represent a text node as a child.
    - New {@link oaj.xml.annotation.XmlFormat#TEXT_PWS} format. Identical to TEXT except preserves whitespace.
    - New {@link oaj.xml.annotation.XmlFormat#XMLTEXT} format that's identical to {@link oaj.xml.annotation.XmlFormat#TEXT} except XML content is not escaped and serialized directly as the child content. The parser will reconvert this to the original XML text during parsing.
  - New support methodology and other improvements to org.apache.juneau.xml documentation.
  - Eliminated unnecessary <string> elements.
  - Eliminated XmlContentHandler class.
  - Parser efficiency improvements through reuse of string builders.
  - Reworked and simplified the default XML serializers. The {@link oaj.xml.XmlSerializer#DEFAULT} serializer now has namespaces disabled, and {@link oaj.xml.XmlSerializer#DEFAULT_NS} has namespaces enabled. The 'XML-JSON' serializers have been eliminated.
  - Eliminated the addJsonTypeAttrs and addJsonStringTypeAttrs settings.
  - Namespace support is now disabled by default.
- Significant modifications and improvements to HTML serialization support.
  - Parser converted from XMLEventReader-based to XMLStreamReader.
  - Eliminated many unnecessary type tags and <string> elements and improved the readable layout. The new format is much leaner.
  - New exhaustive support methodology section added to org.apache.juneau.html documentation.
- New HTML5 DTO support: org.apache.juneau.dto.html5.
- {@link oaj.BeanContext} class split into separate {@link oaj.BeanContext} and {@link oaj.BeanSession} classes.
  - Session object meant to be single-use that can be discarded after use and contains session-level object cache and overridable Locale and TimeZone.
- SerializerContext and ParserContext now extend directly from {@link oaj.BeanContext}.
- {@link oaj.serializer.SerializerSession} and {@link oaj.parser.ParserSession} now extend directly from {@link oaj.BeanSession}.
- New settings in {@link oaj.BeanContext}:
  - {@link oaj.BeanContext#BEAN_debug} - Debug setting. Replaces individual debug properties in the serializer and parser contexts.
  - {@link oaj.BeanContext#BEAN_locale} - Specifies a default locale at the context level.
  - {@link oaj.BeanContext#BEAN_timeZone} - Specifies a default timezone at the context level.
  - {@link oaj.BeanContext#BEAN_mediaType} - Specifies a default media type at the context level.
- Improvements to Parser class:
  - Simplified the parse methods (e.g. parseMap(), parseCollection()) by replacing them with two simple methods:
    - {@link oaj.parser.Parser#parse(Object,Class)} - Normal method.
    - {@link oaj.parser.Parser#parse(Object,Type,Type...)} - Method for parsing into parameterized maps and collections.
    Using these methods, you can construct arbitrarily complex objects consisting of maps and collections. You could do this before, but it required constructing a ClassMeta object.
    For example:

    // Old way: ClassMeta<?> cm = parser.getMapClassMeta( HashMap.class, String.class, parser.getCollectionClassMeta( LinkedList.class, MyBean.class ) ); Map<String,List<MyBean>> map = (Map<String,List<MyBean>>)parser.parse(input, cm); // New way: Map<String,List<MyBean>> map = parser.parse(input, HashMap.class, String.class, LinkedList.class, MyBean.class);

  - Arbitrarily-complex parameterized maps and collections can now be parsed without the need for creating intermediate ClassMeta objects.
  - No need for casting anymore if you were using the old parseMap() and parseCollection() methods!
  - Changes allow me to eliminate BeanContext.normalizeClassMeta() method.
  - Convenience methods added for setting parser properties:

    // Old way: new JsonParser().setProperty(PARSER_strict, true).setProperty(BEAN_locale, mylocale); // New way: new JsonParser().setStrict(true).setLocale(mylocale);

- Improvements to Serializer class:
  - Convenience methods added for setting serializer properties:

    // Old way: new JsonSerializer().setProperty(JSON_simpleMode, true).setProperty(SERIALIZER_quoteChar, '"'); // New way: new JsonSerializer().setSimpleMode(true).setQuoteChar('"');

- Simplified {@link oaj.transform.PojoSwap} class. Now just two methods:
  - {@link oaj.transform.PojoSwap#swap(BeanSession,Object)}
  - {@link oaj.transform.PojoSwap#unswap(BeanSession,Object,ClassMeta)}
- General code improvements made to {@link oaj.ClassMeta} class.
  - All fields are now final which should improve overall performance.
  - Replaced support for toObjectMap() and fromObjectMap()/T(ObjectMap) methods with generalized swap(BeanSession)/unswap(BeanSession,X)/T(BeanSession,X) methods.
    See new section Swap methods for information.
- Session-level media type now available through {@link oaj.BeanSession#getMediaType()} method. Allows for swaps and serializer/parser behavior to be tailored to individual media types.
- Several new {@link java.util.Calendar} and {@link java.util.Date} swaps:
  - {@link oaj.transforms.CalendarSwap.ToString},{@link oaj.transforms.DateSwap.ToString} - To {@link java.lang.String Strings} using the {@code Date.toString()} method.
  - {@link oaj.transforms.CalendarSwap.ISO8601DT},{@link oaj.transforms.DateSwap.ISO8601DT} - To ISO8601 date-time strings.
  - {@link oaj.transforms.CalendarSwap.ISO8601DTZ},{@link oaj.transforms.DateSwap.ISO8601DTZ} - Same as ISO8601DT, except always serializes in GMT.
  - {@link oaj.transforms.CalendarSwap.ISO8601DTP},{@link oaj.transforms.DateSwap.ISO8601DTP} - Same as ISO8601DT except with millisecond precision.
  - {@link oaj.transforms.CalendarSwap.ISO8601DTPZ},{@link oaj.transforms.DateSwap.ISO8601DTPZ} - Same as ISO8601DTZ except with millisecond precision.
  - {@link oaj.transforms.CalendarSwap.RFC2822DT},{@link oaj.transforms.DateSwap.RFC2822DT} - To RFC2822 date-time strings.
  - {@link oaj.transforms.CalendarSwap.RFC2822DTZ},{@link oaj.transforms.DateSwap.RFC2822DTZ} - Same as RFC2822DT, except always serializes in GMT.
  - {@link oaj.transforms.CalendarSwap.RFC2822D},{@link oaj.transforms.DateSwap.RFC2822D} - To RFC2822 date strings.
  - {@link oaj.transforms.CalendarSwap.DateTimeSimple},{@link oaj.transforms.DateSwap.DateTimeSimple} - To simple "yyyy/MM/dd HH:mm:ss" date-time strings.
  - {@link oaj.transforms.CalendarSwap.DateSimple},{@link oaj.transforms.DateSwap.DateSimple} - To simple "yyyy/MM/dd" date strings.
  - {@link oaj.transforms.CalendarSwap.TimeSimple},{@link oaj.transforms.DateSwap.TimeSimple} - To simple "HH:mm:ss" time strings.
  - {@link oaj.transforms.CalendarSwap.DateFull},{@link oaj.transforms.DateSwap.DateFull} - To {@link java.text.DateFormat#FULL} date strings.
  - {@link oaj.transforms.CalendarSwap.DateLong},{@link oaj.transforms.DateSwap.DateLong} - To {@link java.text.DateFormat#LONG} date strings.
  - {@link oaj.transforms.CalendarSwap.DateMedium},{@link oaj.transforms.DateSwap.DateMedium} - To {@link java.text.DateFormat#MEDIUM} date strings.
  - {@link oaj.transforms.CalendarSwap.DateShort},{@link oaj.transforms.DateSwap.DateShort} - To {@link java.text.DateFormat#SHORT} date strings.
  - {@link oaj.transforms.CalendarSwap.TimeFull},{@link oaj.transforms.DateSwap.TimeFull} - To {@link java.text.DateFormat#FULL} time strings.
  - {@link oaj.transforms.CalendarSwap.TimeLong},{@link oaj.transforms.DateSwap.TimeLong} - To {@link java.text.DateFormat#LONG} time strings.
  - {@link oaj.transforms.CalendarSwap.TimeMedium},{@link oaj.transforms.DateSwap.TimeMedium} - To {@link java.text.DateFormat#MEDIUM} time strings.
  - {@link oaj.transforms.CalendarSwap.TimeShort},{@link oaj.transforms.DateSwap.TimeShort} - To {@link java.text.DateFormat#SHORT} time strings.
  - {@link oaj.transforms.CalendarSwap.DateTimeFull},{@link oaj.transforms.DateSwap.DateTimeFull} - To {@link java.text.DateFormat#FULL} date-time strings.
  - {@link oaj.transforms.CalendarSwap.DateTimeLong},{@link oaj.transforms.DateSwap.DateTimeLong} - To {@link java.text.DateFormat#LONG} date-time strings.
  - {@link oaj.transforms.CalendarSwap.DateTimeMedium},{@link oaj.transforms.DateSwap.DateTimeMedium} - To {@link java.text.DateFormat#MEDIUM} date-time strings.
  - {@link oaj.transforms.CalendarSwap.DateTimeShort},{@link oaj.transforms.DateSwap.DateTimeShort} - To {@link java.text.DateFormat#SHORT} date-time strings.
- New method {@link oaj.serializer.SerializerGroup#getSerializerMatch(String)} that returns the matched serializer and media type.
- New method {@link oaj.parser.ParserGroup#getParserMatch(String)} that returns the matched parser and media type.
- New method {@link oaj.encoders.EncoderGroup#getEncoderMatch(String)} that returns the matched encoder and encoding.
- General improvements to Bean Dictionary support.
  - New {@link oaj.BeanDictionaryList} class can be used for defining reusable sets of bean dictionaries consisting of classes annotated with {@link oaj.annotation.Bean#typeName() @Bean(typeName)}.
  - New {@link oaj.BeanDictionaryMap} class can be used for defining reusable sets of bean dictionaries consisting of classes not annotated with {@link oaj.annotation.Bean#typeName() @Bean(typeName)}.
  - New {@link oaj.annotation.Bean#beanDictionary() @Bean(beanDictionary)} annotation.
- Removed restriction on getters and setters to be prefixed with "getX/setX/isX" if a {@link oaj.annotation.BeanProperty#name() @BeanProperty(name)} annotation is used.
- Improvements to ATOM DTO:
  - New {@link oaj.dto.atom.AtomBuilder} class.
  - New setter method names for a better fluent design.
  - Updated org.apache.juneau.dto.atom documentation.
- New {@link oaj.transform.MapSwap} and {@link oaj.transform.StringSwap} classes.
- New {@link oaj.serializer.WriterSerializer#println(Object)} method. Useful for debugging purposes.
- New {@link oaj.BeanContext#getClassMeta(Type,Type...)} and {@link oaj.BeanSession#getClassMeta(Type,Type...)} methods for retrieving Map and Collection class metas. Replaces the various getMapClassMeta()/getCollectionClassMeta() methods.
- New section added to this document: Juneau Data Transfer Objects (org.apache.juneau.dto)
- Modified the UON specification to work with mixed content.
  - The new specification is considerably cleaner and eliminates the need for separate normal/simple modes.
    It also allows for arbitrary whitespace to be added to the output without any confusion.
  - Eliminated the UonParser.DEFAULT_WS_AWARE and UrlEncodingParser.DEFAULT_WS_AWARE parsers.
    The normal {@link oaj.uon.UonParser#DEFAULT} and {@link oaj.urlencoding.UrlEncodingParser#DEFAULT} parsers will now handle whitespace.
  - Eliminated the UonParserContext.UON_whitespaceAware configuration setting.
  - Eliminated the UonSerializer.DEFAULT_SIMPLE, UonSerializer.DEFAULT_SIMPLE_ENCODING and UrlEncodingSerializer.DEFAULT_SIMPLE serializers since there is no separate simple mode anymore.
  - Eliminated the UonParserContext.UON_simpleMode configuration setting.
- Added new OutputStreamSerializer.serializeToHex(Object) method.
  Useful mostly for testing purposes.
  Equivalently, the {@link oaj.parser.InputStreamParser#parse(Object,Class)} method can now read the output from this method.
- Eliminated the @Bean(subTypeProperty) and @Bean(subTypes) annotations and replaced them with the ability to define subtypes using the existing {@link oaj.annotation.Bean#beanDictionary() @Bean(beanDictionary)} annotation on parent classes and interfaces.
  This has the added benefit of simplifying the overall code.
- The SerializerContext.SERIALIZER_addBeanTypeProperties setting is now enabled by default.
- Combined the SERIALIZER_addIndentation/JSON_addWhitespace/UON_addWhitespace properties into a single SerializerContext.SERIALIZER_useWhitespace setting.

##### org.apache.juneau.rest

- {@link oajr.RestRequest} now passes locale and timezone to serializers/parsers/transforms.
- RestRequest.getTimeZone() method.
- Standardized the following methods in {@link oajr.RestRequest} to remove dependency on ClassMeta objects and eliminate the need for casts:
  - RestRequest.getHeader(String,Class)
  - RestRequest.getHeader(String,Object,Class)
  - RestRequest.getHeader(String,Type,Type...)
  - RestRequest.getQueryParameter(String,Class)
  - RestRequest.getQueryParameter(String,Object,Class)
  - RestRequest.getQueryParameter(String,Type,Type...)
  - RestRequest.getQueryParameter(String,Object,Type,Type...)
  - RestRequest.getQueryParameters(String,Class)
  - RestRequest.getQueryParameters(String,Type,Type...)
  - RestRequest.getFormDataParameter(String,Class)
  - RestRequest.getFormDataParameter(String,Object,Class)
  - RestRequest.getFormDataParameters(String,Class)
  - RestRequest.getFormDataParameter(String,Type,Type...)
  - RestRequest.getFormDataParameters(String,Type,Type...)
  - RestRequest.getPathParameter(String,Class)
  - RestRequest.getPathParameter(String,Type,Type...)
  - RestRequest.getBody(Class)
  - RestRequest.getBody(Type,Type...)
- New methods on {@link oajrc.NameValuePairs}
- Fixed issue where whitespace was not added to UON/URL-Encoding output when &plainText=true specified.