6.3.0 (Jun 30, 2017)

Juneau 6.3.0 is a major update with significant new functionality for defining proxy interfaces against arbitrary 3rd-party REST interfaces.

##### org.apache.juneau

- New package: {@link oaj.http}.
- Support for dynamic beans. See {@del @BeanProperty(name)}.
- New doc: 2.8 - Virtual Beans
- New doc: 2.13 - Comparison with Jackson
- All parsers now allow for numeric types with 'K'/'M'/'G' suffixes to represent kilobytes, megabytes, and gigabytes.

  // Example int i = JsonParser.DEFAULT.parse("123M"); // 123MB

- New/modified methods on {@del ConfigFile}:
  - {@del ConfigFile#put(String,String,String,boolean)}
  - {@del ConfigFile#put(String,String,Object,Serializer,boolean,boolean)}
  - {@del ConfigFile#getObject(String,Type,Type...)}
  - {@del ConfigFile#getObject(String,Parser,Type,Type...)}
  - {@del ConfigFile#getObject(String,Class)}
  - {@del ConfigFile#getObject(String,Parser,Class)}
  - {@del ConfigFile#getObject(String,String,Type,Type...)}
  - {@del ConfigFile#getObject(String,String,Parser,Type,Type...)}
  - {@del ConfigFile#getObject(String,String,Class)}
  - {@del ConfigFile#getObject(String,String,Parser,Class)}
  - {@del ConfigFile#getObjectWithDefault(String,Object,Type,Type...)}
  - {@del ConfigFile#getObjectWithDefault(String,Parser,Object,Type,Type...)}
  - {@del ConfigFile#getObjectWithDefault(String,Object,Class)}
  - {@del ConfigFile#getObjectWithDefault(String,Parser,Object,Class)}
- New ability to interact with config file sections with proxy interfaces with new method {@del ConfigFile#getSectionAsInterface(String,Class)}.
- {@del @BeanProperty} annotation can now be applied to getters and setters defined on interfaces.
- New methods on {@link oaj.serializer.SerializerSession} and {@link oaj.parser.ParserSession} for retrieving context and runtime-override properties:
  - {@del Session#getProperty(String)}
  - {@del Session#getProperty(String,String)}
  - {@del Session#getProperty(Class,String)}
  - {@del Session#getProperty(Class,String,Object)}
- New {@del org.apache.juneau.serializer.PartSerializer} interface particularly tailored to HTTP headers, query parameters, form-data parameters, and path variables.
  Allows easy user-defined serialization of these objects.
  The interface can be used in the following locations:
  - {@del org.apache.juneau.rest.client.RestClient.Builder#partSerializer(Class)}
  - {@del org.apache.juneau.remoteable.Path#serializer}
  - {@del org.apache.juneau.remoteable.Query#serializer}
  - {@del org.apache.juneau.remoteable.QueryIfNE#serializer}
  - {@del org.apache.juneau.remoteable.FormData#serializer}
  - {@del org.apache.juneau.remoteable.FormDataIfNE#serializer}
  - {@del org.apache.juneau.remoteable.Header#serializer}
  - {@del org.apache.juneau.remoteable.HeaderIfNE#serializer}
- Across-the-board improvements to the URI-resolution support (i.e. how URIs get serialized).
  - New support for resolving URIs with the following newly-recognized protocols:
    - "context:/..." - Relative to context-root of the application.
    - "servlet:/..." - Relative to the servlet URI.
    - "request:/..." - Relative to the request URI.
    For example, currently we define HTML page links using variables and servlet-relative URIs...

    pages="{up:'$R{requestParentURI}', options:'?method=OPTIONS', upload:'upload'}"

    With these new protocols, we can define them like so:

    links="{top:'context:/', up:'request:/..' ,options:'servlet:/?method=OPTIONS', upload:'servlet:/upload'}"

    The old method of using variables and servlet-relative URIs will still be supported, but using these new protocols should (hopefully) be easier to understand.
    These protocols work on all serialized URL and URI objects, as well as classes and properties annotated with {@del oaj.annotation.URI @URI}.
  - New classes:
    - {@link oaj.UriContext}
    - {@link oaj.UriRelativity}
    - {@link oaj.UriResolution}
    - {@link oaj.UriResolver}
  - New configuration properties:
  - {@del SerializerContext#SERIALIZER_uriContext}
  - {@del SerializerContext#SERIALIZER_uriRelativity}
  - {@del SerializerContext#SERIALIZER_uriResolution}
  - {@del SerializerContext#SERIALIZER_maxIndent}
- New annotation property: {@del @BeanProperty(value)}.
  The following two annotations are considered equivalent:

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

- Fixed a race condition in ClassMeta.
- URLENC_paramFormat has been moved to {@del UonSerializer#UON_paramFormat}, and the UON/URL-Encoding serializers will now always serialize all values as plain text.
  This means that arrays and maps are converted to simple comma-delimited lists.
- Listener APIs added to serializers and parsers:
  - {@link oaj.serializer.SerializerListener}
  - {@link oaj.serializer.Serializer.Builder#listener(Class)}
  - {@del @RestResource(serializerListener)}
  - {@del RestConfig#serializerListener(Class)}
  - {@link oaj.parser.ParserListener}
  - {@link oaj.parser.Parser.Builder#listener(Class)}
  - {@del @RestResource(parserListener)}
  - {@del RestConfig#parserListener(Class)}
  - {@del RestClient.Builder#listeners(Class,Class)}
  juneau-examples-core.import1.pngjuneau-examples-core.import1.png
- The {@del BEAN_debug} flag will now capture parser input and make it available through the {@del ParserSession#getInputAsString()} method so that it can be used in the listeners.
- Significant new functionality introduced to the HTML serializer.
  Lots of new options for customizing the HTML output.
  - New {@link oaj.html.annotation.Html#render() @Html(render)} annotation and {@link oaj.html.HtmlRender} class that allows you to customize the HTML output and CSS style on bean properties:
    Annotation can be applied to POJO classes and bean properties.
  - Several new properties for customizing parts of the HTML page:
    - {@del HtmlDocSerializerContext#HTMLDOC_title}
    - {@del HtmlDocSerializerContext#HTMLDOC_description}
    - {@del HtmlDocSerializerContext#HTMLDOC_branding}
    - {@del HtmlDocSerializerContext#HTMLDOC_header}
    - {@del HtmlDocSerializerContext#HTMLDOC_nav}
    - {@del HtmlDocSerializerContext#HTMLDOC_aside}
    - {@del HtmlDocSerializerContext#HTMLDOC_footer}
    - {@del HtmlDocSerializerContext#HTMLDOC_noResultsMessage}
    - {@del HtmlDocSerializerContext#HTMLDOC_cssUrl}
    - {@del HtmlDocSerializerContext#HTMLDOC_css}
    - {@del HtmlDocSerializerContext#HTMLDOC_template}
  - New interface {@link oaj.html.HtmlDocTemplate} that allows full control over rendering of HTML produced by {@link oaj.html.HtmlDocSerializer}.
- {@link oaj.annotation.NameProperty @NameProperty} and {@link oaj.annotation.ParentProperty @ParentProperty} can now be applied to fields.
- New properties on {@link oaj.BeanContext}:
  - {@del BEAN_includeProperties}
  - {@del BEAN_excludeProperties}
- New annotation property: {@del @BeanProperty(format)}.

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

- MAJOR enhancements made to the REST API.
- The {@link oajr.RestRequest} class functionality has been broken up into the following functional pieces to reduce its complexity:
  - {@del oajr.RestRequest#getBody()} - The request body.
  - {@link oajr.RestRequest#getHeaders()} - The request headers.
  - {@del RestRequest#getQuery()} - The request query parameters.
  - {@del RestRequest#getFormData()} - The request form data parameters.
  - {@del RestRequest#getPathMatch()} - The path variables and remainder.
  The following classes have been introduced:
  - {@del oajr.RequestBody}
  - {@del oajr.RequestHeaders}
  - {@del oajr.RequestQuery}
  - {@del oajr.RequestFormData}
  - {@del oajr.RequestPath}
- The un-annotated parameter types that can be passed in through REST Java methods has been significantly expanded.
  For reference, the previous supported types were:
  - {@link oajr.RestRequest} - The request object.
  - {@link javax.servlet.http.HttpServletRequest} - The superclass of RestRequest.
  - {@link oajr.RestResponse} - The response object.
  - {@link javax.servlet.http.HttpServletResponse} - The superclass of RestResponse.
  The new supported types are:
  - {@del Accept}
  - {@del AcceptCharset}
  - {@del AcceptEncoding}
  - {@del AcceptLanguage}
  - {@del Authorization}
  - {@del CacheControl}
  - {@del Connection}
  - {@del ContentLength}
  - {@del ContentType}
  - {@del Date}
  - {@del Expect}
  - {@del From}
  - {@del Host}
  - {@del IfMatch}
  - {@del IfModifiedSince}
  - {@del IfNoneMatch}
  - {@del IfRange}
  - {@del IfUnmodifiedSince}
  - {@del MaxForwards}
  - {@del Pragma}
  - {@del ProxyAuthorization}
  - {@del Range}
  - {@del Referer}
  - {@del TE}
  - {@del UserAgent}
  - {@del Upgrade}
  - {@del Via}
  - {@del Warning}
  - {@link java.util.TimeZone}
  - {@link java.io.InputStream}
  - {@link javax.servlet.ServletInputStream}
  - {@link java.io.Reader}
  - {@link java.io.OutputStream}
  - {@link javax.servlet.ServletOutputStream}
  - {@link java.io.Writer}
  - {@link java.util.ResourceBundle} - Client-localized resource bundle.
  - {@del oaj.utils.MessageBundle} - A resource bundle with additional features.
  - {@link java.util.Locale} - Client locale.
  - {@del oajr.RequestHeaders} - API for accessing request headers.
  - {@del oajr.RequestQuery} - API for accessing request query parameters.
  - {@del oajr.RequestFormData} - API for accessing request form data.
  - {@del oajr.RequestPath} - API for accessing path variables.
  - {@del oajr.RequestBody} - API for accessing request body.
  - {@link oaj.http.HttpMethod} - The method name matched (when using @RestMethod(name="*"))
  - {@link java.util.logging.Logger} - The logger to use for logging.
  - {@del oaj.internal.JuneauLogger} - Logger with additional features.
  - {@link oajr.RestContext} - The resource read-only context.
  - {@link oaj.parser.Parser} - The parser matching the request content type.
  - {@link oaj.dto.swagger.Swagger} - The auto-generated Swagger doc.
  - {@del ConfigFile} - The external config file for the resource.
  So, for example...

  /** Old way */ @RestMethod(name="*", path="/example1/{a1}/{a2}/{a3}/*") public String example1( @Method String method, @Path("a1") String a1, @Path("a2") int a2, @Path("a3") UUID a3, @Query("p1") int p1, @Query("p2") String p2, @Query("p3") UUID p3, @Header("Accept-Language") String lang, @Header("Accept") String accept ) /** New way */ @RestMethod(name="*", path="/example2/{a1}/{a2}/{a3}/*") public String example2( HttpMethod httpMethod, RequestPathParams pathParams, RequestQuery query, AcceptLanguage acceptLanguage, Accept accept )

- A new annotation {@del @RestResource(paramResolvers)}} that allows you to define your own custom Java method parameter resolvers.
- Fixed bug where Writer returned by {@link oajr.RestResponse#getWriter()} was not being flushed automatically at the end of the HTTP call.
- New annotations added to {@del oajr.annotation.RestMethod @RestMethod}:
  - {@del oajr.annotation.RestMethod#defaultQuery() defaultQuery()}
  - {@del oajr.annotation.RestMethod#defaultFormData() defaultFormData()}
  - {@del bpIncludes()}
  - {@del bpExcludes()}
- Default values on header, query, and form-data annotations:
  - {@del @Header(def)} - Default header value.
  - {@del @Query(def)} - Default query parameter value.
  - {@del @FormData(def)} - Default form data parameter value.
- New attributes on {@del @RestResource}:
  - {@del serializerListener()}
  - {@del parserListener()}
  - {@del widgets()}
  - {@del swagger()}
  - {@del htmldoc()}
- New attributes on {@del oajr.annotation.RestMethod @RestMethod}:
  - {@del widgets()}
  - {@del oajr.annotation.RestMethod#swagger() swagger()}
  - {@del oajr.annotation.RestMethod#htmldoc() htmldoc()}
- New string vars:
  - {@link oajr.vars.UrlVar} - Resolve "$U{...}" variables to URLs.
  - {@del oajr.vars.WidgetVar} - Resolve "$W{...}" variables to widget contents.
- New methods on {@del RestConfig}:
  - {@del setHtmlTitle(String)}
  - {@del setHtmlDescription(String)}
  - {@del setHtmlBranding(String)}
  - {@del setHtmlHeader(String)}
  - {@del setHtmlLinks(String)}
  - {@del setHtmlNav(String)}
  - {@del setHtmlAside(String)}
  - {@del setHtmlFooter(String)}
  - {@del setHtmlCss(String)}
  - {@del setHtmlCssUrl(String)}
  - {@del setHtmlNoWrap(boolean)}
  - {@del setHtmlNoResultsMessage(String)}
  - {@del setHtmlTemplate(Class)}
  - {@del setHtmlTemplate(HtmlDocTemplate)}
  - {@del addWidget(Class)}
- New methods on {@link oajr.RestResponse}:
  - {@del setHtmlTitle(Object)}
  - {@del setHtmlDescription(Object)}
  - {@del setHtmlBranding(Object)}
  - {@del setHtmlHeader(Object)}
  - {@del setHtmlLinks(Object)}
  - {@del setHtmlNav(Object)}
  - {@del setHtmlAside(Object)}
  - {@del setHtmlFooter(Object)}
  - {@del setHtmlCss(Object)}
  - {@del setHtmlCssUrl(Object)}
  - {@del setHtmlNoWrap(boolean)}
  - {@del setHtmlNoResultsMessage(Object)}
  - {@del setHtmlTemplate(Class)}
  - {@del setHtmlTemplate(HtmlDocTemplate)}
- &plainText=true parameter now works on byte-based serializers by converting the output to hex.
- New classes for widget support:
  - {@link oajr.widget.Widget}
  - {@del PoweredByJuneauWidget}
  - {@del ContentTypeLinksColumnWidget}
  - {@del ContentTypeLinksRowWidget}
  - {@del QueryWidget}
- devops.css cleaned up.
- Removed a bunch of URL-related methods from {@link oajr.RestRequest}. These all have equivalents in {@link oajr.RestRequest#getUriContext()}.
- New annotation attributes:
  - {@link oaj.http.annotation.Query#name() @Query(name)}
  - {@link oaj.http.annotation.FormData#name() @FormData(name)}
  - {@link oaj.http.annotation.Header#name() @Header(name)}
  - {@link oaj.http.annotation.Path#name() @Path(name)}
  - {@link oaj.http.annotation.HasQuery#name() @HasQuery(name)}
  - {@link oaj.http.annotation.HasFormData#name() @HasFormData(name)}

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

- New {@del org.apache.juneau.remoteable.Path} annotation for specifying path variables on remoteable interfaces.
- New {@del @RequestBean} annotation for specifying beans with remoteable annotations defined on properties.
- The following annotations (and related methods on RestCall) can now take NameValuePairs and beans as input when using "*" as the name.
  {@del org.apache.juneau.remoteable.FormData},{@del org.apache.juneau.remoteable.FormDataIfNE}, {@del org.apache.juneau.remoteable.Query},{@del org.apache.juneau.remoteable.QueryIfNE}, {@del org.apache.juneau.remoteable.Header},{@del org.apache.juneau.remoteable.HeaderIfNE}

##### org.apache.juneau.microservice

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

- Many code enhancements make to examples to reflect new functionality.
- All pages now render aside comments to help explain what feature they're trying to explain using the new features that allow you to customize various elements of the page.