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}
  - {@del ExternalDocs}
  - {@del Items}
  - {@link oaj.http.annotation.License}
  - {@del Schema}
  - {@del SubItems}
  - {@del oaj.http.annotation.Tag}
  Additionally, the @Remoteable annotation has been split into the following two annotations:
  - {@del oaj.remote.RemoteInterface} - Used for remote proxy interfaces served up through {@del RemoteInterfaceServlet} or REST "PROXY" methods.
    Defaults to "POST" with method signatures as paths.
  - {@del 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:
  - {@del 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 {@del @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:
  - {@del oaj.serializer.OutputStreamSerializer#OSSERIALIZER_binaryFormat}
  - {@del oaj.parser.InputStreamParser#ISPARSER_binaryFormat}
- Added support for auto-detection of fluent-style setters:
  - {@del oaj.BeanContext#BEAN_fluentSetters}
  - {@del oaj.annotation.Bean#fluentSetters()}
- The SERIALIZER_abridged setting has been replaced with {@del oaj.serializer.Serializer#SERIALIZER_addRootType SERIALIZER_addRootType}
- The SERIALIZER_addBeanTypeProperties setting has been replaced with {@del 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 {@del oaj.parser.Parser#PARSER_debugOutputLines} for controlling how many input lines are added to the exception message above.
- New property {@del oaj.BeanContext#BEAN_useEnumNames} for controlling whether enums are serialized using their name or the toString() method.
- New property {@del 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 {@del @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 {@del oaj.annotation.BeanProperty#name()}
- New formats for the {@link oaj.html.annotation.Html#format() @Html(format)} annotation:
  - {@del oaj.html.annotation.HtmlFormat#HTML_CDC} - Format collections as comma-delimited lists.
  - {@del 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 {@del oaj.ObjectMap ObjectMaps} and {@del oaj.ObjectList ObjectLists}.
  - {@del oaj.ObjectMap}
    - {@del oaj.ObjectMap#isUnmodifiable() isUnmodifable()}
    - {@del oaj.ObjectMap#unmodifiable() unmodifiable()}
    - {@del oaj.ObjectMap#modifiable() modifiable()}
  - {@del oaj.ObjectList}
    - {@del oaj.ObjectList#isUnmodifiable() isUnmodifable()}
    - {@del oaj.ObjectList#unmodifiable() unmodifiable()}
    - {@del 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}
      - {@del oaj.marshall.Jso}
      - {@link oaj.marshall.MsgPack}
- New/updated documentation:
  - 2.15.3 - Simplified JSON

##### juneau-dto

- Fixed bug where Swagger {@del 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 {@del RestSwagger Swagger UI}.
- Simplified {@del @RestResource(swagger)} and {@del 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 {@del RemoteInterfaceServlet}.
- {@del 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:
  - {@del oajr.helper}
    - {@del oajr.helper.BeanDescription}
    - {@del oajr.helper.ChildResourceDescriptions}
    - {@del ReaderResource}
    - {@del ReaderResourceBuilder}
    - {@del oajr.helper.SeeOtherRoot}
    - {@del oajr.helper.ResourceDescription}
    - {@del StreamResource}
    - {@del StreamResourceBuilder}
- Predefined HTTP responses.
  - {@del oajr.response}
    - {@del oajr.response.Accepted}
    - {@del oajr.response.AlreadyReported}
    - {@del oajr.response.Continue}
    - {@del oajr.response.Created}
    - {@del oajr.response.EarlyHints}
    - {@del oajr.response.Found}
    - {@del oajr.response.IMUsed}
    - {@del oajr.response.MovedPermanently}
    - {@del oajr.response.MultipleChoices}
    - {@del oajr.response.MultiStatus}
    - {@del oajr.response.NoContent}
    - {@del oajr.response.NonAuthoritiveInformation}
    - {@del oajr.response.NotModified}
    - {@del oajr.response.Ok}
    - {@del oajr.response.PartialContent}
    - {@del oajr.response.PermanentRedirect}
    - {@del oajr.response.Processing}
    - {@del oajr.response.ResetContent}
    - {@del oajr.response.SeeOther}
    - {@del oajr.response.SwitchingProtocols}
    - {@del oajr.response.TemporaryRedirect}
    - {@del oajr.response.UseProxy}
- Predefined HTTP error throwables.
  When added to REST Java methods, reflected in generated Swagger documentation.
  - {@del oajr.exception}
    - {@del oajr.exception.BadRequest}
    - {@del oajr.exception.Conflict}
    - {@del oajr.exception.ExpectationFailed}
    - {@del oajr.exception.FailedDependency}
    - {@del oajr.exception.Forbidden}
    - {@del oajr.exception.Gone}
    - {@del oajr.exception.HttpVersionNotSupported}
    - {@del oajr.exception.InsufficientStorage}
    - {@del oajr.exception.InternalServerError}
    - {@del oajr.exception.LengthRequired}
    - {@del oajr.exception.Locked}
    - {@del oajr.exception.LoopDetected}
    - {@del oajr.exception.MethodNotAllowed}
    - {@del oajr.exception.MisdirectedRequest}
    - {@del oajr.exception.NetworkAuthenticationRequired}
    - {@del oajr.exception.NotAcceptable}
    - {@del oajr.exception.NotExtended}
    - {@del oajr.exception.NotFound}
    - {@del oajr.exception.NotImplemented}
    - {@del oajr.exception.PayloadTooLarge}
    - {@del oajr.exception.PreconditionFailed}
    - {@del oajr.exception.PreconditionRequired}
    - {@del oajr.exception.RangeNotSatisfiable}
    - {@del oajr.exception.RequestHeaderFieldsTooLarge}
    - {@del oajr.exception.ServiceUnavailable}
    - {@del oajr.exception.TooManyRequests}
    - {@del oajr.exception.Unauthorized}
    - {@del oajr.exception.UnavailableForLegalReasons}
    - {@del oajr.exception.UnprocessableEntity}
    - {@del oajr.exception.UnsupportedMediaType}
    - {@del oajr.exception.UpgradeRequired}
    - {@del oajr.exception.UriTooLong}
    - {@del oajr.exception.VariantAlsoNegotiates}
- The {@del oajr.annotation.HtmlDoc#nav() @HtmlDoc(nav)} and {@del 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 {@del 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:
  - {@del MockRest}
- @RestMethod(inherit) annotation has been removed and replaced with the following classes:
  - {@del oajr.Inherit}
  - {@del oajr.None}
  These can be used in the following locations:
  - {@del RestResource#serializers()}
  - {@del RestResource#parsers()}
  - {@del RestResource#beanFilters()}
  - {@del RestResource#pojoSwaps()}
  - {@del oajr.annotation.RestMethod#serializers()}
  - {@del oajr.annotation.RestMethod#parsers()}
  - {@del RestMethod#beanFilters()}
  - {@del 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 {@del 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}
    - {@del getBeforeShowScript(RestRequest)}
    - {@del getAfterShowScript(RestRequest)}
- New methods added to {@link oajr.widget.Widget} to allow retrieving classpath resources with embedded SVL variables:
  - {@link oajr.widget.Widget}
    - {@del loadHtmlWithVars(RestRequest,String)}
    - {@del loadScriptWithVars(RestRequest,String)}
    - {@del loadStyleWithVars(RestRequest,String)}
- New/updated documentation:
  juneau-rest-server.UnitTesting
- The behavior of the default values for {@del oajr.annotation.RestMethod#name()} and {@del oajr.annotation.RestMethod#path()} have changed.
  If not specified, the values are inferred from the Java method name.
  See Also: {@del RestMethod}
- RedirectToServletRoot class has been renamed to {@del oajr.helper.SeeOtherRoot}.
- New REST context settings:
  - {@link oajr.RestContext}
    - {@del oajr.RestContext#REST_uriAuthority REST_uriAuthority}
    - {@del oajr.RestContext#REST_uriContext REST_uriContext}
    - {@del oajr.RestContext#REST_uriRelativity REST_uriRelativity}
    - {@del oajr.RestContext#REST_uriResolution REST_uriResolution}
- New convenience annotations for specifying default Accept and Content-Type headers:
  - {@del RestResource}
    - {@del defaultAccept}
    - {@del defaultContentType}
  - {@del oajr.annotation.RestMethod}
    - {@del oajr.annotation.RestMethod#defaultAccept defaultAccept}
    - {@del 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.RestClient.Builder}
    - {@del oajrc.RestClient.Builder#sslProtocols(String...) sslProtocols(String...)}
    - {@del oajrc.RestClient.Builder#cipherSuites(String...) cipherSuites(String...)}
    - {@del oajrc.RestClient.Builder#hostnameVerifier(HostnameVerifier) hostnameVerifier(HostnameVerifier)}
    - {@del oajrc.RestClient.Builder#keyManagers(KeyManager...) keyManagers(KeyManager...)}
    - {@del oajrc.RestClient.Builder#trustManagers(TrustManager...)}
    - {@del oajrc.RestClient.Builder#secureRandom(SecureRandom)}
    - {@del oajrc.RestClient.Builder#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.RestClient.Builder}
    - {@link oajrc.RestClient.Builder#json() json()}
    - {@link oajrc.RestClient.Builder#xml() xml()}
    - {@link oajrc.RestClient.Builder#html() html()}
    - {@link oajrc.RestClient.Builder#uon() uon()}
    - {@link oajrc.RestClient.Builder#urlEnc() urlEnc()}
    - {@link oajrc.RestClient.Builder#msgPack() msgPack()}
    - {@link oajrc.RestClient.Builder#plainText() plainText()}
- New method added for allowing serverless client testing against REST interfaces.
  - {@link oajrc.RestClient.Builder}
    - {@del mockHttpConnection(MockHttpConnection)}
- Removed the deprecated RestCall.execute() method.
  Use {@del oajrc.RestCall#run()}.
- RestCall.input(Object) method renamed to {@del oajrc.RestCall#body(Object)} to match OpenAPI terminology.
- Made constructors on RestClient and RestClient.Builder 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}
    - {@del RestClient#getRemoteInterface(Class)}
    - {@del RestClient#getRemoteInterface(Class,Object)}
    - {@del RestClient#getRemoteInterface(Class,Object,Serializer,Parser)}
    - {@del oajrc.RestClient#getRemoteResource(Class)}
    - {@del oajrc.RestClient#getRemoteResource(Class,Object)}
    - {@del 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.