Release 6.1.0

Date: Feb 25, 2017

Juneau 6.1.0 is a major update.

In particular, this release cleans up the BeanContext API to match the PropertyStore/Context/ 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:

    • XmlFormat.ATTRS format can now be applied to bean classes to have all bean properties serialized as attributes instead of elements by default.
    • XmlFormat.ELEMENT format can now be applied to bean properties to override the XmlFormat.ATTRS setting above on specific bean properties.
    • New XmlFormat.ELEMENTS format can be applied to a bean property of type array/Collection to represent the child elements.
    • New XmlFormat.MIXED format can be applied to a bean property of type array/Collection to represent mixed content (text + child elements).
    • New XmlFormat.MIXED_PWS format. Identical to MIXED except preserves whitespace.
    • New XmlFormat.TEXT format can be applied to a bean property of a single object to represent a text node as a child.
    • New XmlFormat.TEXT_PWS format. Identical to TEXT except preserves whitespace.
    • New XmlFormat.XMLTEXT format that's identical to 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 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 XmlSerializer.DEFAULT serializer now has namespaces disabled, and 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 html documentation.

• New HTML5 DTO support: html5.

• BeanContext class split into separate BeanContext and 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 BeanContext.

• SerializerSession and ParserSession now extend directly from BeanSession.

• New settings in BeanContext:

  • BEAN_debug - Debug setting. Replaces individual debug properties in the serializer and parser contexts.
  • BEAN_locale - Specifies a default locale at the context level.
  • BEAN_timeZone - Specifies a default timezone at the context level.
  • 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:

    • Parser.parse(Object,Class) - Normal method.
    • 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 PojoSwap class. Now just two methods:

  • PojoSwap.swap(BeanSession,Object)
  • PojoSwap.unswap(BeanSession,Object,ClassMeta)

• General code improvements made to 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 BeanSession.getMediaType() method. Allows for swaps and serializer/parser behavior to be tailored to individual media types.

• Several new Calendar and Date swaps:

  • ToString, ToString - To Strings using the Date.toString() method.
  • ISO8601DT, ISO8601DT - To ISO8601 date-time strings.
  • ISO8601DTZ, ISO8601DTZ - Same as ISO8601DT, except always serializes in GMT.
  • ISO8601DTP, ISO8601DTP - Same as ISO8601DT except with millisecond precision.
  • ISO8601DTPZ, ISO8601DTPZ - Same as ISO8601DTZ except with millisecond precision.
  • RFC2822DT, RFC2822DT - To RFC2822 date-time strings.
  • RFC2822DTZ, RFC2822DTZ - Same as RFC2822DT, except always serializes in GMT.
  • RFC2822D, RFC2822D - To RFC2822 date strings.
  • DateTimeSimple, DateTimeSimple - To simple "yyyy/MM/dd HH:mm:ss" date-time strings.
  • DateSimple, DateSimple - To simple "yyyy/MM/dd" date strings.
  • TimeSimple, TimeSimple - To simple "HH:mm:ss" time strings.
  • DateFull, DateFull - To DateFormat.FULL date strings.
  • DateLong, DateLong - To DateFormat.LONG date strings.
  • DateMedium, DateMedium - To DateFormat.MEDIUM date strings.
  • DateShort, DateShort - To DateFormat.SHORT date strings.
  • TimeFull, TimeFull - To DateFormat.FULL time strings.
  • TimeLong, TimeLong - To DateFormat.LONG time strings.
  • TimeMedium, TimeMedium - To DateFormat.MEDIUM time strings.
  • TimeShort, TimeShort - To DateFormat.SHORT time strings.
  • DateTimeFull, DateTimeFull - To DateFormat.FULL date-time strings.
  • DateTimeLong, DateTimeLong - To DateFormat.LONG date-time strings.
  • DateTimeMedium, DateTimeMedium - To DateFormat.MEDIUM date-time strings.
  • DateTimeShort, DateTimeShort - To DateFormat.SHORT date-time strings.

• New method SerializerGroup.getSerializerMatch(String) that returns the matched serializer and media type.

• New method ParserGroup.getParserMatch(String) that returns the matched parser and media type.

• New method EncoderGroup.getEncoderMatch(String) that returns the matched encoder and encoding.

• General improvements to Bean Dictionary support.

  • New BeanDictionaryList class can be used for defining reusable sets of bean dictionaries consisting of classes annotated with @Bean(typeName).
  • New BeanDictionaryMap class can be used for defining reusable sets of bean dictionaries consisting of classes not annotated with @Bean(typeName).
  • New @Bean(beanDictionary) annotation.

• Removed restriction on getters and setters to be prefixed with "getX/setX/isX" if a @BeanProperty(name) annotation is used.

• Improvements to ATOM DTO:

  • New AtomBuilder class.
  • New setter method names for a better fluent design.
  • Updated atom documentation.

• New MapSwap and StringSwap classes.

• New WriterSerializer.println(Object) method. Useful for debugging purposes.

• New BeanContext.getClassMeta(Type,Type...) and 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 UonParser.DEFAULT and 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 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 @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

• RestRequest now passes locale and timezone to serializers/parsers/transforms.

• RestRequest.getTimeZone() method.

• Standardized the following methods in 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 NameValuePairs

• Fixed issue where whitespace was not added to UON/URL-Encoding output when &plainText=true specified.