7.2.0 (Sept 25, 2018)

7.2.0 is a major release that introduces several significant new features:

- OpenAPI part serializing and parsing with full support for OpenAPI validation of input and output in the REST servlet and client APIs.
- Swagger UI.
- New HTTP-Part annotations that are applicable to both the servlet and client APIs.
- Serverless servlet and client unit testing.
- Simplified UI customization.
- Marshalls that combines serializers and parsers into a single API.

##### juneau-marshall

- The REST client @Remoteable annotations and REST server @RemoteMethod annotations which used to be in separate packages in the client and server projects have been combined into a single set of annotations in the {@link oaj.http.annotation} package.
  This fixes a long-standing problem where it was easy to mix up using client-side annotations in server-side code, and vis-versa.
  Additionally, much work has been done on these annotations to add support for Swagger-style validations and documentation.
  - {@link oaj.http.annotation.Body}
  - {@link oaj.http.annotation.FormData}
  - {@link oaj.http.annotation.Header}
  - {@link oaj.http.annotation.Path}
  - {@link oaj.http.annotation.Query}
  - {@link oaj.http.annotation.HasFormData}
  - {@link oaj.http.annotation.HasQuery}
  - {@link oaj.http.annotation.Request}
  These are used with new Swagger schema/documentation annotations to produce schema-based serialization/parsing/validation and auto-generated Swagger documentation:
  - {@link oaj.http.annotation.Contact}
  - `ExternalDocs`
  - `Items`
  - {@link oaj.http.annotation.License}
  - `Schema`
  - `SubItems`
  - {@link oaj.http.annotation.Tag}
  Additionally, the @Remoteable annotation has been split into the following two annotations:
  - {@link oaj.remote.RemoteInterface} - Used for remote proxy interfaces served up through `RemoteInterfaceServlet` or REST "PROXY" methods.
    Defaults to "POST" with method signatures as paths.
  - {@link oajrc.remote.RemoteResource} - Used for 3rd-party REST interfaces.
    Defaults to "GET" with standardized naming conventions for paths.
- Support for multi-valued parameters as maps or beans on server-side annotations (it was previously supported on client-side): `@Query("*")`, `@FormData("*")`, `@Header("*")`, `@Path("*")`
- Support for server-side use of @Request annotation on @RestMethod annotations and new {@link oajr.RestRequest#getRequest(RequestBeanMeta)} method.
- Fixed bug where `@Bean(typeName)` was not being detected on non-bean POJO classes.
- Fixed bug where HTML-Schema was not being rendered correctly.
- Support for POJO examples:
  - {@link oaj.BeanContext#BEAN_examples}
  - {@link oaj.annotation.Example}
- Fixed bug where parsers could report the wrong line number when an error occurred.
- A runtime exception is now thrown if you define a `@BeanProperty(name)` but forget to add it to your `@Bean(properties)` annotation.
- `@Html(asXml)` and `@Html(asPlainText)` replaced with {@link oaj.html.annotation.Html#format() @Html(format)}.
- HTML serializer will now serializers beans and maps as HTML even when those objects are embedded within an object with `@Html(format=XML)`.
  The previous behavior was to serialize it as XML.
- New settings for binary-based serializers and parsers:
  - {@link oaj.serializer.OutputStreamSerializer#OSSERIALIZER_binaryFormat}
  - {@link oaj.parser.InputStreamParser#ISPARSER_binaryFormat}
- Added support for auto-detection of fluent-style setters:
  - {@link oaj.BeanContext#BEAN_fluentSetters}
  - {@link oaj.annotation.Bean#fluentSetters()}
- The SERIALIZER_abridged setting has been replaced with {@link oaj.serializer.Serializer#SERIALIZER_addRootType SERIALIZER_addRootType}
- The SERIALIZER_addBeanTypeProperties setting has been replaced with {@link oaj.serializer.Serializer#SERIALIZER_addBeanTypes SERIALIZER_addBeanTypes} and is disabled by default.
- Parse exception messages are now clearer and include code snippets of where a parse exception occurred:

  org.apache.juneau.parser.ParseException: Expected '[' at beginning of JSON array. At line 80, column 20. While parsing into: currentClass: List<String> currentProperty: required: java.util.List, field=[null], getter=[public java.util.List org.apache.juneau.dto.swagger.SchemaInfo.getRequired()], setter=[public org.apache.juneau.dto.swagger.SchemaInfo org.apache.juneau.dto.swagger.SchemaInfo.setRequired(java.util.Collection)] ---start-- 0075: "name": "body", 0076: "description": "Pet object that needs to be added to the store", 0077: "required": true, 0078: "schema": { 0079: "required": true, 0080: } 0081: } 0082: ], 0083: "responses": { 0084: "405": { 0085: "description": "Invalid input" ---end---

- New property {@link oaj.parser.Parser#PARSER_debugOutputLines} for controlling how many input lines are added to the exception message above.
- New property {@link oaj.BeanContext#BEAN_useEnumNames} for controlling whether enums are serialized using their name or the `toString()` method.
- New property {@link oaj.BeanContext#BEAN_examples} for defining examples of POJOs.
- New {@link oaj.annotation.Example @Example} annotation for defining examples of POJOs.
  Used heavily in JSON-Schema support.
- If a bean has both a `getX()` and `isX()` method, the `getX()` method takes precedence.
  The previous behavior was arbitrary.
- Significant improvements to JSON-Schema serialization support.
  - New `@JsonSchema` annotation.
- Fixed `NullPointerException` when serializing beans with a dyna-property (i.e. `@Bean("*")`) which returns a null value.
- New option for dyna-property (i.e. `@Bean("*")`) using a method that returns a collection of extra keys.
  See new options #4 on {@link oaj.annotation.BeanProperty#name()}
- New formats for the {@link oaj.html.annotation.Html#format() @Html(format)} annotation:
  - {@link oaj.html.annotation.HtmlFormat#HTML_CDC} - Format collections as comma-delimited lists.
  - {@link oaj.html.annotation.HtmlFormat#HTML_SDC} - Format collections as space-delimited lists.
- Serializers now allow for q-values on the media types they handle.
  For example, the accept media type on `JsonSerializer.Simple` is "application/json+simple,application/json;q=0.9".
  This means the serializer CAN handle requests for "application/json" if no other serializers provide a better match.
- New methods for creating unmodifiable {@link oaj.ObjectMap ObjectMaps} and {@link oaj.ObjectList ObjectLists}.
  - {@link oaj.ObjectMap}
    - {@link oaj.ObjectMap#isUnmodifiable() isUnmodifable()}
    - {@link oaj.ObjectMap#unmodifiable() unmodifiable()}
    - {@link oaj.ObjectMap#modifiable() modifiable()}
  - {@link oaj.ObjectList}
    - {@link oaj.ObjectList#isUnmodifiable() isUnmodifable()}
    - {@link oaj.ObjectList#unmodifiable() unmodifiable()}
    - {@link oaj.ObjectList#modifiable() modifiable()}
- The `JsonSerializer.Simple` class has been moved into the top-level {@link oaj.json.SimpleJsonSerializer} class.
- RDF serializer subclasses have been moved into top-level classes:
  - `RdfSerializer.Xml` -> {@link oaj.jena.RdfXmlSerializer}
  - `RdfSerializer.XmlAbbrev` -> {@link oaj.jena.RdfXmlAbbrevSerializer}
  - `RdfSerializer.N3` -> {@link oaj.jena.N3Serializer}
  - `RdfSerializer.NTriple` -> {@link oaj.jena.NTripleSerializer}
  - `RdfSerializer.Turtle` -> {@link oaj.jena.TurtleSerializer}
  - `RdfParser.Xml` -> {@link oaj.jena.RdfXmlParser}
  - `RdfParser.N3` -> {@link oaj.jena.N3Parser}
  - `RdfParser.NTriple` -> {@link oaj.jena.NTripleParser}
  - `RdfParser.Turtle` -> {@link oaj.jena.TurtleParser}
- New API for pairing serializers and parsers for simplified syntax:

  ##### Examples:

  // Using instance. Json json = new Json(); MyPojo myPojo = json.read(string, MyPojo.class); String string = json.write(myPojo);

  // Using DEFAULT instance. MyPojo myPojo = Json.DEFAULT.read(string, MyPojo.class); String string = Json.DEFAULT.write(myPojo);

  - {@link oaj.marshall.Marshall}
    - {@link oaj.marshall.CharMarshall}
      - {@link oaj.marshall.Html}
      - {@link oaj.marshall.Json}
      - {@link oaj.marshall.PlainText}
      - {@link oaj.marshall.SimpleJson}
      - {@link oaj.marshall.Uon}
      - {@link oaj.marshall.UrlEncoding}
      - {@link oaj.marshall.Xml}
      - {@link oaj.marshall.N3}
      - {@link oaj.marshall.NTriple}
      - {@link oaj.marshall.RdfXml}
      - {@link oaj.marshall.RdfXmlAbbrev}
      - {@link oaj.marshall.Turtle}
    - {@link oaj.marshall.StreamMarshall}
      - {@link oaj.marshall.Jso}
      - {@link oaj.marshall.MsgPack}
- New/updated documentation:
  - 2.15.3 - Simplified JSON

##### juneau-dto

- Fixed bug where Swagger {@link oaj.dto.swagger.SchemaInfo#required(Object...)} was defined as a boolean instead of a list of strings.
- Boolean attributes are now handled correctly for HTML5.
  For example, calling `new Select().disabled(true)` will produce `<select disabled='disabled'>`

##### juneau-rest-server

- Auto-generated {@doc juneau-rest-server.Swagger Swagger UI}.
- Simplified {@link oajr.annotation.RestResource#swagger() @RestResource(swagger)} and {@link oajr.annotation.RestMethod#swagger() @RestMethod(swagger)} annotations.
- Fixed bug in `UriResolver` when request path info had special characters.
- Fixed bug where incorrect media type was being set on responses (e.g. `text/html+schema` instead of `text/html` for schema documents).
- The `RemoteableServlet` class has been moved and renamed to `RemoteInterfaceServlet`.
- `RemoteInterfaceServlet` now provides a form page for invoking remote interface methods in a browser.
- Newlines were being stripped from `@HtmlDoc(script)` when serialized which could cause script lines to become commented out.
- New {@link oaj.http.annotation.Response @Response} annotation that can be applied to throwables thrown from REST methods and POJOs returned by REST methods to specify non-200 status return codes and descriptions in Swagger documentation.
- Swagger fields added to the following annotations:
  - {@link oaj.http.annotation.Body}
  - {@link oaj.http.annotation.FormData}
  - {@link oaj.http.annotation.Header}
  - {@link oaj.http.annotation.Path}
  - {@link oaj.http.annotation.Query}
- The @PathRemainder annotation has been removed entirely.
  Use `@Path("/*")` to access the path remainder which includes all the new OpenAPI parsing support.
- "Helper" classes (i.e. reusable beans that can be returned by REST methods) have been moved to the following package with some new additions:
  - {@link oajr.helper}
    - {@link oajr.helper.BeanDescription}
    - {@link oajr.helper.ChildResourceDescriptions}
    - `ReaderResource`
    - `ReaderResourceBuilder`
    - {@link oajr.helper.SeeOtherRoot}
    - {@link oajr.helper.ResourceDescription}
    - `StreamResource`
    - `StreamResourceBuilder`
- Predefined HTTP responses.
  - {@link oajr.response}
    - {@link oajr.response.Accepted}
    - {@link oajr.response.AlreadyReported}
    - {@link oajr.response.Continue}
    - {@link oajr.response.Created}
    - {@link oajr.response.EarlyHints}
    - {@link oajr.response.Found}
    - {@link oajr.response.IMUsed}
    - {@link oajr.response.MovedPermanently}
    - {@link oajr.response.MultipleChoices}
    - {@link oajr.response.MultiStatus}
    - {@link oajr.response.NoContent}
    - {@link oajr.response.NonAuthoritiveInformation}
    - {@link oajr.response.NotModified}
    - {@link oajr.response.Ok}
    - {@link oajr.response.PartialContent}
    - {@link oajr.response.PermanentRedirect}
    - {@link oajr.response.Processing}
    - {@link oajr.response.ResetContent}
    - {@link oajr.response.SeeOther}
    - {@link oajr.response.SwitchingProtocols}
    - {@link oajr.response.TemporaryRedirect}
    - {@link oajr.response.UseProxy}
- Predefined HTTP error throwables.
  When added to REST Java methods, reflected in generated Swagger documentation.
  - {@link oajr.exception}
    - {@link oajr.exception.BadRequest}
    - {@link oajr.exception.Conflict}
    - {@link oajr.exception.ExpectationFailed}
    - {@link oajr.exception.FailedDependency}
    - {@link oajr.exception.Forbidden}
    - {@link oajr.exception.Gone}
    - {@link oajr.exception.HttpVersionNotSupported}
    - {@link oajr.exception.InsufficientStorage}
    - {@link oajr.exception.InternalServerError}
    - {@link oajr.exception.LengthRequired}
    - {@link oajr.exception.Locked}
    - {@link oajr.exception.LoopDetected}
    - {@link oajr.exception.MethodNotAllowed}
    - {@link oajr.exception.MisdirectedRequest}
    - {@link oajr.exception.NetworkAuthenticationRequired}
    - {@link oajr.exception.NotAcceptable}
    - {@link oajr.exception.NotExtended}
    - {@link oajr.exception.NotFound}
    - {@link oajr.exception.NotImplemented}
    - {@link oajr.exception.PayloadTooLarge}
    - {@link oajr.exception.PreconditionFailed}
    - {@link oajr.exception.PreconditionRequired}
    - {@link oajr.exception.RangeNotSatisfiable}
    - {@link oajr.exception.RequestHeaderFieldsTooLarge}
    - {@link oajr.exception.ServiceUnavailable}
    - {@link oajr.exception.TooManyRequests}
    - {@link oajr.exception.Unauthorized}
    - {@link oajr.exception.UnavailableForLegalReasons}
    - {@link oajr.exception.UnprocessableEntity}
    - {@link oajr.exception.UnsupportedMediaType}
    - {@link oajr.exception.UpgradeRequired}
    - {@link oajr.exception.UriTooLong}
    - {@link oajr.exception.VariantAlsoNegotiates}
- The {@link oajr.annotation.HtmlDoc#nav() @HtmlDoc(nav)} and {@link oajr.annotation.HtmlDoc#navlinks() @HtmlDoc(navlinks)} can now both be used on the same annotation.
  The contents of `nav()` are free-form HTML that gets rendered immediately after the navigation links.
- The following new parameter types can be used on REST methods:
  - {@link oaj.parser.ReaderParser} - The reader parser matching the request content type.
  - {@link oaj.parser.InputStreamParser} - The input stream parser matching the request content type.
- The `$F` variable can now be used as a initialization time variable.
  For example, the `AtomFeedResource` example pulls a bean example from a file on the classpath:

  @RestResource( path="/atom", title="Sample ATOM feed resource", properties={ @Property(name=BEAN_examples, value="{'org.apache.juneau.dto.atom.Feed': $F{AtomFeedResource_example.json}}") }, ... )

  It should be noted that you cannot use the `$F` variable to retrieve localized versions of files (since you're not within the scope of a client request.
- The `RestResource.nowrap()` annotation has been changed to a string with a default value of "true".
  Having it as a string allows us to differentiate between a set and unset value so that it can be overridden in subclasses.
- The {@link oaj.http.annotation.Path#name()} annotation parameter is now required.
- New class for mock unit testing of REST resources:
  - {@link oajr.mock.MockRest}
- `@RestMethod(inherit)` annotation has been removed and replaced with the following classes:
  - {@link oajr.Inherit}
  - {@link oajr.None}
  These can be used in the following locations:
  - {@link oajr.annotation.RestResource#serializers()}
  - {@link oajr.annotation.RestResource#parsers()}
  - {@link oajr.annotation.RestResource#beanFilters()}
  - {@link oajr.annotation.RestResource#pojoSwaps()}
  - {@link oajr.annotation.RestMethod#serializers()}
  - {@link oajr.annotation.RestMethod#parsers()}
  - {@link oajr.annotation.RestMethod#beanFilters()}
  - {@link oajr.annotation.RestMethod#pojoSwaps()}
  One advantage is that you now have control over the precedence of serializers and parsers by where you insert the `Inherit` class.
- `RequestPathMatch` class has been renamed to {@link oajr.RequestPath}.
- {@link oaj.http.annotation.Request @Request} objects can now be used as parameters in @RestMethod methods.
  Includes new methods on {@link oajr.RestRequest}:
  - {@link oajr.RestRequest#getRequest(Class) getRequest(Class)}
  - {@link oajr.RestRequest#getRequest(RequestBeanMeta) getRequest(RequestBeanMeta)}
- New methods added to {@link oajr.widget.MenuItemWidget} to allow population of menu item content using Javascript and Ajax calls:
  - {@link oajr.widget.MenuItemWidget}
    - {@link oajr.widget.MenuItemWidget#getBeforeShowScript(RestRequest) getBeforeShowScript(RestRequest)}
    - {@link oajr.widget.MenuItemWidget#getAfterShowScript(RestRequest) getAfterShowScript(RestRequest)}
- New methods added to {@link oajr.widget.Widget} to allow retrieving classpath resources with embedded SVL variables:
  - {@link oajr.widget.Widget}
    - {@link oajr.widget.Widget#loadHtmlWithVars(RestRequest,String) loadHtmlWithVars(RestRequest,String)}
    - {@link oajr.widget.Widget#loadScriptWithVars(RestRequest,String) loadScriptWithVars(RestRequest,String)}
    - {@link oajr.widget.Widget#loadStyleWithVars(RestRequest,String) loadStyleWithVars(RestRequest,String)}
- New/updated documentation:
  {@doc juneau-rest-server.UnitTesting}
- The behavior of the default values for {@link oajr.annotation.RestMethod#name()} and {@link oajr.annotation.RestMethod#path()} have changed.
  If not specified, the values are inferred from the Java method name.
  See Also: {@doc juneau-rest-server.RestMethod}
- `RedirectToServletRoot` class has been renamed to {@link oajr.helper.SeeOtherRoot}.
- New REST context settings:
  - {@link oajr.RestContext}
    - {@link oajr.RestContext#REST_uriAuthority REST_uriAuthority}
    - {@link oajr.RestContext#REST_uriContext REST_uriContext}
    - {@link oajr.RestContext#REST_uriRelativity REST_uriRelativity}
    - {@link oajr.RestContext#REST_uriResolution REST_uriResolution}
- New convenience annotations for specifying default `Accept` and `Content-Type` headers:
  - {@link oajr.annotation.RestResource}
    - {@link oajr.annotation.RestResource#defaultAccept defaultAccept}
    - {@link oajr.annotation.RestResource#defaultContentType defaultContentType}
  - {@link oajr.annotation.RestMethod}
    - {@link oajr.annotation.RestMethod#defaultAccept defaultAccept}
    - {@link oajr.annotation.RestMethod#defaultContentType defaultContentType}

##### juneau-rest-client

- Remote Resource interfaces support OpenAPI annotations.
- Made improvements to the builder API for defining SSL support.
  New methods added:
  - {@link oajrc.RestClientBuilder}
    - {@link oajrc.RestClientBuilder#sslProtocols(String...) sslProtocols(String...)}
    - {@link oajrc.RestClientBuilder#cipherSuites(String...) cipherSuites(String...)}
    - {@link oajrc.RestClientBuilder#hostnameVerifier(HostnameVerifier) hostnameVerifier(HostnameVerifier)}
    - {@link oajrc.RestClientBuilder#keyManagers(KeyManager...) keyManagers(KeyManager...)}
    - {@link oajrc.RestClientBuilder#trustManagers(TrustManager...)}
    - {@link oajrc.RestClientBuilder#secureRandom(SecureRandom)}
    - {@link oajrc.RestClientBuilder#httpClientConnectionManager(HttpClientConnectionManager)}
- Clients no longer have JSON defined as the default serializer and parser.
  Instead, the clients can now be used with no serializer/parser if you're working with InputStreams/Readers or POJOs that can be converted to Strings and converted from Strings/InputStreams/Readers.
- Methods added to client builder to make it easy to define the transport language:
  - {@link oajrc.RestClientBuilder}
    - {@link oajrc.RestClientBuilder#json() json()}
    - {@link oajrc.RestClientBuilder#xml() xml()}
    - {@link oajrc.RestClientBuilder#html() html()}
    - {@link oajrc.RestClientBuilder#uon() uon()}
    - {@link oajrc.RestClientBuilder#urlEnc() urlEnc()}
    - {@link oajrc.RestClientBuilder#msgpack() msgpack()}
    - {@link oajrc.RestClientBuilder#plainText() plainText()}
- New method added for allowing serverless client testing against REST interfaces.
  - {@link oajrc.RestClientBuilder}
    - {@link oajrc.RestClientBuilder#mockHttpConnection(MockHttpConnection) mockHttpConnection(MockHttpConnection)}
- Removed the deprecated `RestCall.execute()` method.
  Use {@link oajrc.RestCall#run()}.
- `RestCall.input(Object)` method renamed to {@link oajrc.RestCall#body(Object)} to match OpenAPI terminology.
- Made constructors on `RestClient` and `RestClientBuilder` protected so that they can be subclassed.
- The `RestClient.getRemoteableProxy()` methods have been split into separate methods for Remote Interfaces and Remote Resources:
  - {@link oajrc.RestClient}
    - `RestClient.getRemoteInterface(Class)`
    - `RestClient.getRemoteInterface(Class,Object)`
    - `RestClient.getRemoteInterface(Class,Object,Serializer,Parser)`
    - {@link oajrc.RestClient#getRemoteResource(Class)}
    - {@link oajrc.RestClient#getRemoteResource(Class,Object)}
    - {@link oajrc.RestClient#getRemoteResource(Class,Object,Serializer,Parser)}

##### juneau-rest-microservice

- The look-and-feel of an application is now controlled through the external configuration file and access to CSS stylesheets in the working directory in a new folder called `files`:
  The default configuration is this:

  #======================================================================================================================= # REST settings #======================================================================================================================= [REST] staticFiles = htdocs:files/htdocs # Stylesheet to use for HTML views. theme = servlet:/htdocs/themes/devops.css headerIcon = servlet:/htdocs/images/juneau.png headerLink = http://juneau.apache.org footerIcon = servlet:/htdocs/images/asf.png footerLink = http://www.apache.org icon = $C{REST/headerIcon} header = <a href='$U{$C{REST/headerLink}}'><img src='$U{$C{REST/headerIcon}}' style='position:absolute;top:5;right:5;background-color:transparent;height:30px'/></a> footer = <a href='$U{$C{REST/footerLink}}'><img style='float:right;padding-right:20px;height:32px' src='$U{$C{REST/footerIcon}}'>

  Note that static files can now be served up from the `files` directory in the working directory, and you have access to modify the CSS theme files.
  The `SwaggerUI.css` file controls the look-and-feel of the Swagger UI, so you can make modification there as well.
  The `BasicRestConfig` interface (which defines the default settings for the `BasicRestServlet` class) now looks like this...

  @RestResource( ... htmldoc=@HtmlDoc( header={ "<h1>$R{resourceTitle}</h1>", "<h2>$R{methodSummary,resourceDescription}</h2>", "$C{REST/header}" }, navlinks={ "up: request:/.." }, stylesheet="$C{REST/theme,servlet:/htdocs/themes/devops.css}", head={ "<link rel='icon' href='$U{$C{REST/icon}}'/>" }, footer="$C{REST/footer}" ), // These are static files that are served up by the servlet under the specified sub-paths. // For example, "/servletPath/htdocs/javadoc.css" resolves to the file "[servlet-package]/htdocs/javadoc.css" staticFiles={"$C{REST/staticFiles}"} ) public interface BasicRestConfig {}

  The `PoweredByApache` widget which used to serve as a page footer has been eliminated.
  If you're testing out changes in the theme stylesheets, you may want to set the following system property that prevents caching of those files so that you don't need to restart the microservice each time a change is made:

  #======================================================================================================================= # System properties #======================================================================================================================= [SystemProperties] # Disable classpath resource caching. # Useful if you're attached using a debugger and you're modifying classpath resources while running. RestContext.useClasspathResourceCaching.b = false

- Upgraded to Jetty 9.4.12.