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 {@link oaj.annotation.BeanProperty#name() @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 `ConfigFile`:
  - `ConfigFile.put(String,String,String,boolean)`
  - `ConfigFile.put(String,String,Object,Serializer,boolean,boolean)`
  - `ConfigFile.getObject(String,Type,Type...)`
  - `ConfigFile.getObject(String,Parser,Type,Type...)`
  - `ConfigFile.getObject(String,Class)`
  - `ConfigFile.getObject(String,Parser,Class)`
  - `ConfigFile.getObject(String,String,Type,Type...)`
  - `ConfigFile.getObject(String,String,Parser,Type,Type...)`
  - `ConfigFile.getObject(String,String,Class)`
  - `ConfigFile.getObject(String,String,Parser,Class)`
  - `ConfigFile.getObjectWithDefault(String,Object,Type,Type...)`
  - `ConfigFile.getObjectWithDefault(String,Parser,Object,Type,Type...)`
  - `ConfigFile.getObjectWithDefault(String,Object,Class)`
  - `ConfigFile.getObjectWithDefault(String,Parser,Object,Class)`
- New ability to interact with config file sections with proxy interfaces with new method `ConfigFile.getSectionAsInterface(String,Class)`.
- {@link oaj.annotation.BeanProperty @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:
  - `Session.getProperty(String)`
  - `Session.getProperty(String,String)`
  - `Session.getProperty(Class,String)`
  - `Session.getProperty(Class,String,Object)`
- New `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:
  - `org.apache.juneau.rest.client.RestClientBuilder.partSerializer(Class)`
  - `org.apache.juneau.remoteable.Path.serializer`
  - `org.apache.juneau.remoteable.Query.serializer`
  - `org.apache.juneau.remoteable.QueryIfNE.serializer`
  - `org.apache.juneau.remoteable.FormData.serializer`
  - `org.apache.juneau.remoteable.FormDataIfNE.serializer`
  - `org.apache.juneau.remoteable.Header.serializer`
  - `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 {@link oaj.annotation.URI @URI}.
  - New classes:
    - {@link oaj.UriContext}
    - {@link oaj.UriRelativity}
    - {@link oaj.UriResolution}
    - {@link oaj.UriResolver}
  - New configuration properties:
  - `SerializerContext.SERIALIZER_uriContext`
  - `SerializerContext.SERIALIZER_uriRelativity`
  - `SerializerContext.SERIALIZER_uriResolution`
  - `SerializerContext.SERIALIZER_maxIndent`
- New annotation property: {@link oaj.annotation.BeanProperty#value() @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 `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.SerializerBuilder#listener(Class)}
  - {@link oajr.annotation.RestResource#serializerListener() @RestResource(serializerListener)}
  - `RestConfig.serializerListener(Class)`
  - {@link oaj.parser.ParserListener}
  - {@link oaj.parser.ParserBuilder#listener(Class)}
  - {@link oajr.annotation.RestResource#parserListener() @RestResource(parserListener)}
  - `RestConfig.parserListener(Class)`
  - `RestClientBuilder.listeners(Class,Class)`
  juneau-examples-core.import1.pngjuneau-examples-core.import1.png
- The {@link oaj.BeanContext#BEAN_debug} flag will now capture parser input and make it available through the `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:
    - `HtmlDocSerializerContext.HTMLDOC_title`
    - `HtmlDocSerializerContext.HTMLDOC_description`
    - `HtmlDocSerializerContext.HTMLDOC_branding`
    - `HtmlDocSerializerContext.HTMLDOC_header`
    - `HtmlDocSerializerContext.HTMLDOC_nav`
    - `HtmlDocSerializerContext.HTMLDOC_aside`
    - `HtmlDocSerializerContext.HTMLDOC_footer`
    - `HtmlDocSerializerContext.HTMLDOC_noResultsMessage`
    - `HtmlDocSerializerContext.HTMLDOC_cssUrl`
    - `HtmlDocSerializerContext.HTMLDOC_css`
    - `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}:
  - {@link oaj.BeanContext#BEAN_includeProperties BEAN_includeProperties}
  - {@link oaj.BeanContext#BEAN_excludeProperties BEAN_excludeProperties}
- New annotation property: {@link oaj.annotation.BeanProperty#format() @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:
  - {@link oajr.RestRequest#getBody()} - The request body.
  - {@link oajr.RestRequest#getHeaders()} - The request headers.
  - {@link oajr.RestRequest#getQuery()} - The request query parameters.
  - {@link oajr.RestRequest#getFormData()} - The request form data parameters.
  - {@link oajr.RestRequest#getPathMatch()} - The path variables and remainder.
  The following classes have been introduced:
  - {@link oajr.RequestBody}
  - {@link oajr.RequestHeaders}
  - {@link oajr.RequestQuery}
  - {@link oajr.RequestFormData}
  - {@link 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:
  - {@link oaj.http.Accept}
  - {@link oaj.http.AcceptCharset}
  - {@link oaj.http.AcceptEncoding}
  - {@link oaj.http.AcceptLanguage}
  - {@link oaj.http.Authorization}
  - {@link oaj.http.CacheControl}
  - {@link oaj.http.Connection}
  - {@link oaj.http.ContentLength}
  - {@link oaj.http.ContentType}
  - {@link oaj.http.Date}
  - {@link oaj.http.Expect}
  - {@link oaj.http.From}
  - {@link oaj.http.Host}
  - {@link oaj.http.IfMatch}
  - {@link oaj.http.IfModifiedSince}
  - {@link oaj.http.IfNoneMatch}
  - {@link oaj.http.IfRange}
  - {@link oaj.http.IfUnmodifiedSince}
  - {@link oaj.http.MaxForwards}
  - {@link oaj.http.Pragma}
  - {@link oaj.http.ProxyAuthorization}
  - {@link oaj.http.Range}
  - {@link oaj.http.Referer}
  - {@link oaj.http.TE}
  - {@link oaj.http.UserAgent}
  - {@link oaj.http.Upgrade}
  - {@link oaj.http.Via}
  - {@link oaj.http.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.
  - {@link oaj.utils.MessageBundle} - A resource bundle with additional features.
  - {@link java.util.Locale} - Client locale.
  - {@link oajr.RequestHeaders} - API for accessing request headers.
  - {@link oajr.RequestQuery} - API for accessing request query parameters.
  - {@link oajr.RequestFormData} - API for accessing request form data.
  - {@link oajr.RequestPath} - API for accessing path variables.
  - {@link 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.
  - {@link 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.
  - `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 {@link oajr.annotation.RestResource#paramResolvers() @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 {@link oajr.annotation.RestMethod @RestMethod}:
  - {@link oajr.annotation.RestMethod#defaultQuery() defaultQuery()}
  - {@link oajr.annotation.RestMethod#defaultFormData() defaultFormData()}
  - `bpIncludes()`
  - `bpExcludes()`
- Default values on header, query, and form-data annotations:
  - `@Header(def)` - Default header value.
  - `@Query(def)` - Default query parameter value.
  - `@FormData(def)` - Default form data parameter value.
- New attributes on {@link oajr.annotation.RestResource @RestResource}:
  - {@link oajr.annotation.RestResource#serializerListener() serializerListener()}
  - {@link oajr.annotation.RestResource#parserListener() parserListener()}
  - `widgets()`
  - {@link oajr.annotation.RestResource#swagger() swagger()}
  - {@link oajr.annotation.RestResource#htmldoc() htmldoc()}
- New attributes on {@link oajr.annotation.RestMethod @RestMethod}:
  - `widgets()`
  - {@link oajr.annotation.RestMethod#swagger() swagger()}
  - {@link oajr.annotation.RestMethod#htmldoc() htmldoc()}
- New string vars:
  - {@link oajr.vars.UrlVar} - Resolve "$U{...}" variables to URLs.
  - {@link oajr.vars.WidgetVar} - Resolve "$W{...}" variables to widget contents.
- New methods on `RestConfig`:
  - `setHtmlTitle(String)`
  - `setHtmlDescription(String)`
  - `setHtmlBranding(String)`
  - `setHtmlHeader(String)`
  - `setHtmlLinks(String)`
  - `setHtmlNav(String)`
  - `setHtmlAside(String)`
  - `setHtmlFooter(String)`
  - `setHtmlCss(String)`
  - `setHtmlCssUrl(String)`
  - `setHtmlNoWrap(boolean)`
  - `setHtmlNoResultsMessage(String)`
  - `setHtmlTemplate(Class)`
  - `setHtmlTemplate(HtmlDocTemplate)`
  - `addWidget(Class)`
- New methods on {@link oajr.RestResponse}:
  - `setHtmlTitle(Object)`
  - `setHtmlDescription(Object)`
  - `setHtmlBranding(Object)`
  - `setHtmlHeader(Object)`
  - `setHtmlLinks(Object)`
  - `setHtmlNav(Object)`
  - `setHtmlAside(Object)`
  - `setHtmlFooter(Object)`
  - `setHtmlCss(Object)`
  - `setHtmlCssUrl(Object)`
  - `setHtmlNoWrap(boolean)`
  - `setHtmlNoResultsMessage(Object)`
  - `setHtmlTemplate(Class)`
  - `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}
  - `PoweredByJuneauWidget`
  - `ContentTypeLinksColumnWidget`
  - `ContentTypeLinksRowWidget`
  - `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 `org.apache.juneau.remoteable.Path` annotation for specifying path variables on remoteable interfaces.
- New `@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.
  `org.apache.juneau.remoteable.FormData`,`org.apache.juneau.remoteable.FormDataIfNE`, `org.apache.juneau.remoteable.Query`,`org.apache.juneau.remoteable.QueryIfNE`, `org.apache.juneau.remoteable.Header`,`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.