6.2.0 (Apr 28, 2017)

Juneau 6.2.0 is a major update.

##### org.apache.juneau

- Revamped the serializer, parser classes to use builders for creation. Serializers and parsers are now unmodifiable objects once they are created. This is a breaking code change that will require adoption.

  /* Creating a new serializer or parser */ // Old way WriterSerializer s = new JsonSerializer().setUseWhitespace(true).pojoSwaps(BSwap. class).lock(); // New way WriterSerializer s = JsonSerializer. create().ws().pojoSwaps(BSwap. class).build(); /* Cloning an existing serializer or parser */ // Old way WriterSerializer s = SimpleJsonSerializer. DEFAULT .clone().setUseWhitespace(true).pojoSwaps(BSwap. class).lock(); // New way WriterSerializer s = SimpleJsonSerializer. DEFAULT .builder().ws().pojoSwaps(BSwap. class).build();

- Also introduced the following builder classes and related architecture changes to make the built objects unmodifiable:
  - {@link oaj.serializer.SerializerGroupBuilder}
  - {@link oaj.parser.ParserGroupBuilder}
  - {@link oaj.encoders.EncoderGroupBuilder}
- Revamped the config file API to use a build: `ConfigFileBuilder`.
- Removed the `Lockable` interface.
- New `addBeanTypeProperties` setting added to serializers to override the `SerializerContext.SERIALIZER_addBeanTypeProperties` setting for individual serializers in a serializer group:
  - `HtmlSerializerContext.HTML_addBeanTypeProperties`
  - `JsonSerializerContext.JSON_addBeanTypeProperties`
  - `MsgPackSerializerContext.MSGPACK_addBeanTypeProperties`
  - `UonSerializerContext.UON_addBeanTypeProperties`
  - `XmlSerializerContext.#XML_addBeanTypeProperties`
  - `RdfSerializerContext.RDF_addBeanTypeProperties`
- UON notation serializers and parsers moved into the new `org.apache.juneau.uon` package.
- New {@link oaj.xml.annotation.XmlFormat#VOID} format to identify HTML void elements.
- Tweaks to HTML5 support.
  - Fixed handling of empty non-void elements in HTML serializer.
  - Added `style()` override methods to all elements.
- Improvements to Swagger support.
  - New {@link oaj.dto.swagger.SwaggerBuilder} class.
  - Fluent-style setters added to the Swagger beans.
  - Added Swagger examples `here` and in the org.apache.juneau.dto.swagger javadocs.
- Improvements to {@link oaj.svl.VarResolver}.
  - New {@link oaj.svl.vars.IfVar $IF} variable for if-else block logic.
  - `$SWITCH` variable for switch block logic.
  - Whitespace wasn't being ignored in some cases.
- {@link oaj.html.HtmlParser} can now parse full body contents generated by {@link oaj.html.HtmlDocSerializer}.
- Parse-args supported added to {@link oaj.msgpack.MsgPackParser} to allow it to be used in remoteable proxies.
- Added some convenience classes for constructing collections using a fluent interface:
  - {@link oaj.utils.AList}
  - {@link oaj.utils.ASet}
  - {@link oaj.utils.AMap}
- New {@link oaj.annotation.Bean#typePropertyName @Bean(typePropertyName)} annotation allows you to specify the name of the "_type" property at the class level.
- New methods added to HTML5 container beans:
  - {@link oaj.dto.html5.HtmlElementContainer#getChild(int...)}
  - {@link oaj.dto.html5.HtmlElementMixed#getChild(int...)}
- New common serializer setting: `SerializerContext.SERIALIZER_abridged`.
- Support for defining interface proxies against 3rd-party REST interfaces.
  New package `org.apache.juneau.remoteable` for all remoteable proxy interface annotations.
  @Remoteable annotation has been moved to this package.
- Updated doc: `6 - Remoteable Services`
- New doc: `6.1 - Interface proxies against 3rd-party REST interfaces`
- New URL-encoding serializer setting: `UrlEncodingSerializerContext.URLENC_paramFormat`.
- New methods on {@link oaj.urlencoding.UrlEncodingSerializerBuilder}:
  - `UrlEncodingSerializerBuilder.paramFormat(String)`
  - `UrlEncodingSerializerBuilder.plainTextParams()`

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

- {@link oajr.annotation.RestResource @RestResource} annotation can now be applied to any class! You're no longer restricted to subclassing your resources from {@link oajr.RestServlet}.
  This is a major enhancement in the API. Anything you could do by subclassing from `RestServlet` should have an equivalent for non-`RestServlet` classes.
  The only restriction is that the top-level resource must subclass from `RestServlet`. Child resources do not.
  The majority of code has been split up into two separate classes:
  - `RestConfig` - A modifiable configuration of a resource. Subclasses from {@link javax.servlet.ServletConfig}.
  - {@link oajr.RestContext} - A read-only configuration that's the result of a snapshot of the config.
  The {@link oajr.RestServlet} class now has the following initialization method that allows you to override the config settings define via annotations:
  - `RestServlet.init(RestConfig)` - A modifiable configuration of a resource.
  Non-`RestServlet` classes must have one of the following to allow it to be instantiated:
  - A `public T(RestConfig)` constructor.
  - A `public T()` constructor.
  - The parent resource must have a customized {@link oajr.RestResourceResolver} for instantiating it.
  Non-`RestServlet` classes can optionally include the following init methods to gain access to the config and context:
  - `public init(RestConfig)`
  - `public init(RestContext)`
- New annotations added to {@link oajr.annotation.RestResource @RestResource} to allow non-`RestServlet` resources to do the same as subclassing directly from `RestServlet`:
  - {@link oajr.annotation.RestResource#resourceResolver() resourceResolver()} - Specify a {@link oajr.RestResourceResolver} class for resolving child resources.
  - {@link oajr.annotation.RestResource#callHandler() callHandler()} - Specify a {@link oajr.RestCallHandler} class for handling the lifecycle of a REST call.
  - {@link oajr.annotation.RestResource#infoProvider() infoProvider()} - Specify a {@link oajr.RestInfoProvider} class for customizing title/description/Swagger information on a REST resource.
  - {@link oajr.annotation.RestResource#logger() logger()} - Specify a {@link oajr.RestLogger} class for handling logging.
- New annotations added to {@link oajr.annotation.RestResource @RestResource} and {@link oajr.annotation.RestMethod @RestMethod} to simplify defining page title, text, and links on HTML views:
  - `@RestResource(pageTitle)`
  - `@RestMethod(pageTitle)`
  - `@RestResource(pageText)`
  - `@RestMethod(pageText)`
  - `@RestResource(pageLinks)`
  - `@RestMethod(pageLinks)`

  // Old method @RestResource( properties={ @Property(name=HTMLDOC_title, value="System properties resource"), @Property(name=HTMLDOC_description, value="REST interface for performing CRUD operations on system properties."), @Property(name=HTMLDOC_navlinks, value="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}") } ) // New method @RestResource( pageTitle="System properties resource", pageDescription="REST interface for performing CRUD operations on system properties.", pageLinks="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" )

  Typically you're going to simply want to use the `title` and `description` annotations which apply to both the page title/text and the swagger doc:

  @RestResource( title="System properties resource", description="REST interface for performing CRUD operations on system properties.", pageLinks="{up:'$R{requestParentURI}',options:'?method=OPTIONS'}" )

- `RestResource.stylesheet()` can now take in a comma-delimited list of stylesheet paths.
- `StreamResource` can now contain multiple sources from a variety of source types (e.g. `byte[]` arrays, `InputStreams`, `Files`, etc...) and is now immutable. It also includes a new `StreamResourceBuilder` class.
- Simplified remoteable proxies using the `@RestMethod(name="PROXY")` annotation on REST methods. Used to expose interface proxies without the need for `RemoteableServlet`.

  // Server side @RestMethod(name="PROXY", path="/myproxy/*") public IAddressBook getProxy() { return addressBook; } // Client side RestClient client = RestClient. create().rootUrl(samplesUrl).build(); IAddressBook ab = client.getRemoteableProxy(IAddressBook. class, "/addressBook/myproxy");

  See {@link oajr.annotation.RestMethod#name() @RestMethod(name)} for more information.
- {@link oajr.RestRequest#toString()} can be called at any time to view the headers and content of the request without affecting functionality. Very useful for debugging.
- {@link oajr.annotation.RestMethod#name() @RestMethod(name)} annotation is now optional. Defaults to "GET".

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

- Revamped the client API to use builders.
- New doc: 1.5 - Debugging
- The `RestClient` class `doX(Object url)` methods now handle HttpClient `URIBuilder` instances.
- New methods added/updated to {@link oajrc.RestClient}:
  - `RestClient.getRemoteableProxy(Class,Object)` - For interface proxies defined using `@RestMethod(name="PROXY")`.
  - `RestClient.getRemoteableProxy(Class,Object,Serializer,Parser)` - Same as above, but overrides the serializer and parser defined on the client.
  - {@link oajrc.RestClient#doPost(Object) doPost(Object)}
  - {@link oajrc.RestClient#doCall(HttpMethod,Object,Object) doCall(HttpMethod,Object,Object)} - Can now pass in instances of {@link oajrc.NameValuePairs} for easy form posts.
    This extends to all methods that take in the input.
- New methods on {@link oajrc.RestCall}:
  - {@link oajrc.RestCall#uri(Object) uri(Object)}
  - `query(String,Object,boolean,PartSerializer)`
  - {@link oajrc.RestCall#query(String,Object) query(String,Object)}
  - {@link oajrc.RestCall#queryIfNE(String,Object) queryIfNE(String,Object)}
  - {@link oajrc.RestCall#query(Map) query(Map)}
  - {@link oajrc.RestCall#queryIfNE(Map) queryIfNE(Map)}
  - {@link oajrc.RestCall#query(String) query(String)}
  - `formData(String,Object,boolean,PartSerializer)`
  - {@link oajrc.RestCall#formData(String,Object) formData(String,Object)}
  - {@link oajrc.RestCall#formDataIfNE(String,Object) formDataIfNE(String,Object)}
  - {@link oajrc.RestCall#formData(Map) formData(Map)}
  - {@link oajrc.RestCall#formDataIfNE(Map) formDataIfNE(Map)}
  - `header(String,Object,boolean,PartSerializer)`
  - {@link oajrc.RestCall#header(String,Object) header(String,Object)}
  - {@link oajrc.RestCall#headerIfNE(String,Object) headerIfNE(String,Object)}
  - {@link oajrc.RestCall#headers(Map) headers(Map)}
  - {@link oajrc.RestCall#headersIfNE(Map) headersIfNE(Map)}
  - {@link oajrc.RestCall#host(String) host(String)}
  - {@link oajrc.RestCall#port(int) port(int)}
  - {@link oajrc.RestCall#userInfo(String,String) userInfo(String,String)}
  - {@link oajrc.RestCall#userInfo(String) userInfo(String)}
  - {@link oajrc.RestCall#scheme(String) scheme(String)}
- New methods added to {@link oajrc.RestClientBuilder}:
  - {@link oajrc.RestClientBuilder#executorService(ExecutorService,boolean) executorService(ExecutorService,boolean)}
  - {@link oajrc.RestClientBuilder#paramFormat(String) paramFormat(ExecutorService,boolean)}
  - `RestClientBuilder.plainTextParams()`
  - {@link oajrc.RestClientBuilder#noTrace() noTrace()} - Adds a `No-Trace: true` header on all requests to prevent the servlet from logging errors.
    Useful for testing scenarios when you don't want the console to end up showing errors done on purpose.
  - {@link oajrc.RestClientBuilder#debug() debug()} now adds a `Debug: true` header on all requests.
- New methods added/updated to {@link oajrc.RestCall}:
  - {@link oajrc.RestCall#runFuture() runFuture()}
  - {@link oajrc.RestCall#getResponseFuture(Class) getResponseFuture(Class)}
  - {@link oajrc.RestCall#getResponseFuture(Type,Type...) getResponseFuture(Type,Type...)}
  - {@link oajrc.RestCall#getResponseAsStringFuture() getResponseAsStringFuture()}
  - {@link oajrc.RestCall#serializer(Serializer) serializer(Serializer)} - Override the serializer defined on the client for a single call.
  - {@link oajrc.RestCall#parser(Parser) parser(Parser)} - Override the parser defined on the client for a single call.
  - `input(Object)` - Now accepts instances of {@link oajrc.NameValuePairs}.
  - {@link oajrc.RestCall#getResponse(Class) getResponse(Class)} - Can now pass in any of the following:
    - {@link org.apache.http.HttpResponse} - Returns the raw `HttpResponse` returned by the inner `HttpClient`.
    - {@link java.io.Reader} - Returns access to the raw reader of the response.
    - {@link java.io.InputStream} - Returns access to the raw input stream of the response.
- New methods added to {@link oajrc.NameValuePairs}:
  - {@link oajrc.NameValuePairs#append(String,Object) append(String,Object)}
  - `append(String,Object,PartSerializer)`
- {@link oajrc.RetryOn} is now an abstract class with an additional method:
  - {@link oajrc.RetryOn#onResponse(HttpResponse) onResponse(HttpResponse)}

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

- "REST/port" configuration setting can now be a comma-limited list of port numbers to try.
  You can also specify one or more `0`s to try a random port.
- Methods added to {@link oaj.microservice.RestMicroservice} class:
  - {@link oaj.microservice.RestMicroservice#getPort()}
  - {@link oaj.microservice.RestMicroservice#getURI()}
  - Override methods added from {@link oaj.microservice.Microservice} class for easier method chaining.