Release 6.2.0

Date: 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:

  • SerializerGroup.Builder
  • ParserGroup.Builder
  • EncoderGroup.Builder

• Revamped the config file API to use a builder: 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 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 SwaggerBuilder class.
  • Fluent-style setters added to the Swagger beans.
  • Added Swagger examples here and in the swagger javadocs.

• Improvements to VarResolver.

  • New IfVar $IF variable for if-else block logic.
  • $SWITCH variable for switch block logic.
  • Whitespace wasn't being ignored in some cases.

• HtmlParser can now parse full body contents generated by HtmlDocSerializer.

• Parse-args supported added to MsgPackParser to allow it to be used in remoteable proxies.

• Added some convenience classes for constructing collections using a fluent interface:

  • AList
  • ASet
  • AMap

• New @Bean(typePropertyName) annotation allows you to specify the name of the "_type" property at the class level.

• New methods added to HTML5 container beans:

  • HtmlElementContainer.getChild(int...)
  • HtmlElementMixed.getChild(int...)

• New common serializer setting: SerializerContext.SERIALIZER_abridged.

• Support for defining interface proxies against 3rd-party REST interfaces. New package 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 UrlEncodingSerializer.Builder:

  • Builder.paramFormat(String)
  • Builder.plainTextParams()

org.apache.juneau.rest

• @RestResource annotation can now be applied to any class! You're no longer restricted to subclassing your resources from 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 javax.servlet.ServletConfig.
  • RestContext - A read-only configuration that's the result of a snapshot of the config.

  The 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 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 @RestResource to allow non-RestServlet resources to do the same as subclassing directly from RestServlet:

  • RestResource.resourceResolver() - Specify a RestResourceResolver class for resolving child resources.
  • RestResource.callHandler() - Specify a RestCallHandler class for handling the lifecycle of a REST call.
  • RestResource.infoProvider() - Specify a RestInfoProvider class for customizing title/description/Swagger information on a REST resource.
  • RestResource.logger() - Specify a RestLogger class for handling logging.

• New annotations added to @RestResource and @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 @RestMethod(name) for more information.

• RestRequest.toString() can be called at any time to view the headers and content of the request without affecting functionality. Very useful for debugging.

• @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 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.
  • RestClient.doPost(Object)
  • RestClient.doCall(HttpMethod,Object,Object) - Can now pass in instances of NameValuePairs for easy form posts. This extends to all methods that take in the input.

• New methods on RestCall:

  • RestCall.uri(Object)
  • query(String,Object,boolean,PartSerializer)
  • RestCall.query(String,Object)
  • RestCall.queryIfNE(String,Object)
  • RestCall.query(Map)
  • RestCall.queryIfNE(Map)
  • RestCall.query(String)
  • formData(String,Object,boolean,PartSerializer)
  • RestCall.formData(String,Object)
  • RestCall.formDataIfNE(String,Object)
  • RestCall.formData(Map)
  • RestCall.formDataIfNE(Map)
  • header(String,Object,boolean,PartSerializer)
  • RestCall.header(String,Object)
  • RestCall.headerIfNE(String,Object)
  • RestCall.headers(Map)
  • RestCall.headersIfNE(Map)
  • RestCall.host(String)
  • RestCall.port(int)
  • RestCall.userInfo(String,String)
  • RestCall.userInfo(String)
  • RestCall.scheme(String)

• New methods added to RestClient.Builder:

  • executorService(ExecutorService,boolean)
  • Builder.paramFormat(String)
  • Builder.plainTextParams()
  • 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.
  • debug() now adds a Debug: true header on all requests.

• New methods added/updated to RestCall:

  • RestCall.runFuture()

  • RestCall.getResponseFuture(Class)

  • RestCall.getResponseFuture(Type,Type...)

  • RestCall.getResponseAsStringFuture()

  • RestCall.serializer(Serializer) - Override the serializer defined on the client for a single call.

  • RestCall.parser(Parser) - Override the parser defined on the client for a single call.

  • input(Object) - Now accepts instances of NameValuePairs.

  • RestCall.getResponse(Class) - Can now pass in any of the following:

    • HttpResponse - Returns the raw HttpResponse returned by the inner HttpClient.
    • Reader - Returns access to the raw reader of the response.
    • InputStream - Returns access to the raw input stream of the response.

• New methods added to NameValuePairs:

  • NameValuePairs.append(String,Object)
  • append(String,Object,PartSerializer)

• RetryOn is now an abstract class with an additional method:

• RetryOn.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 0s to try a random port.

• Methods added to RestMicroservice class:

  • getPort()
  • getURI()
  • Override methods added from Microservice class for easier method chaining.