Blog

In 7.2.0, I'm adding support for POJO REST requests that don't include Accept and Media-Type headers.

Previously, if your requests did not contain Accept or Content-Type headers, you had to use Readers and Writers to work with the HTTP request and response bodies.  Otherwise you would get Not Acceptable (406) and Unsupported Media Type (415) response codes.  

This behavior is now being relaxed.  If your request does not contain media-type headers, then you can still used POJOs for requests and responses.

For example, this is a snippet from the Javadoc on the Body annotation describing the types of objects you can use in REST Java methods to represent the body of the request:

JUnit Test Results

FYI....JUnit testcase results have been added to the Jenkins builds...

I'm adding the following classes to the juneau-rest-server module to allow you to unit test your REST resources without the need of running them in a servlet container:

Here's an example of it in use...

Instead of routing requests through a servlet container, it simply creates the RestContext object for the resource and calls the RestContext.getCallHandler().service(request, response); method with mocked-up ServletRequest and ServletResponse objects.

Here's what it looks like in expanded form:

In theory, everything should work identically to how it would behave in a servlet container, only faster and more efficient.

The MockRest object can also be used with the RestClient class to perform serverless client-side testing against REST resource classes:

This last feature is useful if you want to perform serverless unit testing of REST proxy interfaces.

 

 

Configurable look-and-feel

This change is being introduced in 7.1.1 to resolve the following feature request:

https://issues.apache.org/jira/projects/JUNEAU/issues/JUNEAU-82

 

The change introduces an external folder in the JVM working directory containing images and stylesheets used by the microservice:

The REST configuration section can be used to tailor the header and footer on the pages:

The BasicRestConfig interface (which defines the default settings for BasicRestServlet) is now defined as:

Note that the theme files are externally accessible and can be modified to produce any look-and-feel you desire.

The microservice still works without the files directory.  An embedded devops.css is included in the jar as a default spreadsheet.

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:

 

Quick update on the Swagger UI enhancements.

The design allows you to pull in Swagger from any of the following sources (or any combination):

  • Localized Swagger JSON files on the classpath.
  • Swagger defined on class-level and method-level annotations.
  • Swagger fragments defined in resource bundles.
  • Auto-detection if not found above (paths, methods, schemas, etc...).

The general idea is you can let Juneau auto-generate the Swagger documentation, or provide your own Swagger JSON, or do a combination of auto and manual.

 

Here's the Petstore app OPTIONS page based on the Swagger.io Petstore example...

 

Operations are expandable and gives you information about the schema.  

In this case, the schema information was auto-detected and generated using the JsonSchemaSerializer. 

 

Examples for all the supported types are provided via a select when an @Example-annotated method exists on the POJO class (or otherwise defined in the Swagger JSON).

 

For example, RDF....

 

 

 

Swagger UI enhancements

A quick update on the work I've been doing around Swagger enhancements.  There's still much work to do, but I wanted to provide a sneak-peek.

As previously requested, it would be nice to have more user-friendly OPTIONS pages based on Swagger UI. 

Here's an example of what it looks like so far...

It's implemented as a per-media-type PojoSwap<Swagger,Div> that replaces a Swagger object with HTML5 beans when rendered as HTML.

 

The examples can be embedded in the Swagger JSON or annotations. They can also come from the beans themselves via a new @Example annotation that can be applied to static methods on a bean:

public class Pet {

	@Example
	public static Pet example() {
		// return an example of this object.
	}
}

These examples beans are then serialized to all the supported languages and inserted into the generated Swagger.

 

Here's what it looks like in the light and dark themes...

 

 

There are also general improvements coming to the Swagger API itself such as better support for definitions and references, and other fixes for pain-points I'm discovering along the way.

 

Documentation Updates

I think I'm finally finished cleaning up the documentation.  I've been working at it since December and it's been quite time consuming, but I'm pretty happy with the results:

http://juneau.apache.org/index.html#documentation.html

There's a LOT of documentation to go through, but anyone willing to get into the depths of Juneau and do some proofreading?  You might even find some interesting features you never knew existed. (smile)

Configuration API changes

We've made some significant changes to the Configuration API in 7.1.0.

Feature include:

  • Support for pluggable storage.
  • File-system watcher integration support.
  • New builder-based design.

The documentation has been rewritten for the juneau-config module and can be found here:

http://juneau.apache.org/site/apidocs/overview-summary.html#juneau-config

Homepage header image vote

Anyone have any preferences on changing the page header on our web page?

All but the first one are pulled from pexels.com.

1.

2.

3.

4.

5.

6.

7.

8.

9.

10

 

One last one that I kind of like....

 

FYI....the topics in the Javadoc overview document are now collapsable with zoom-in/out hover pointers:

(Technically they were always collapsable, but it wasn't obvious that you could do so without the mouse pointer)

Javadoc Link Tester

FYI....I just added a utility for finding broken links in the generated Javadocs.  I found hundreds of them.

It's just a simple class called JavadocLinkTester.  Just run it without args after running mvn javadoc:aggregate and it will find any broken links..

 

I recommend using it if you make any extensive updates to the Javadocs.

I looked for existing tools online but came up empty.  I also tried using the W3C link checker utility, but it was REALLY slow since it actually crawled all the links.

It would be nice to include this as part of the Maven build but I'm not familiar with creating Maven components.  

Source can be found here:

https://github.com/apache/juneau/blob/master/juneau-core/juneau-core-test/src/test/java/org/apache/juneau/utils/JavadocLinkTester.java

Support for POJO builders.

The Juneau parsers now support parsing into beans created through builders:

A typical code pattern is shown below:

This feature will be added in 7.1.0.

Full details can be found here:

http://juneau.apache.org/site/apidocs/overview-summary.html#juneau-marshall.PojoBuilders

 

 

Swagger DTO updates

I just delivered some significant updates to the Swagger DTO API.  These will be delivered as a part of 7.1.0.

 

New generalized getter and setter methods allow you to now set arbitrary fields:

The get/set methods can be used on existing properties as well.

The helper setter methods can now take in JSON as well as beans:

 

Other changes:

  • The toString() method serializes directly to JSON.
  • All the Javadocs have been cleaned up.
  • Added 250+ JUnit testcases to cover the Swagger DTO.

It may not be well known that we maintain extensive package-level Javadocs in our code.  Whereas the overview document is meant to provide a general overview of the features in Juneau, the package-level docs are intended to provide in-depth information.

To help make these docs more visible, I've added "Additional Information" sections to the overview document that mirror the TOCs of the package-level docs.

Here's an example:

Caveat - Some of these package-level docs need some cleanup.  Also, some of the detailed information currently in the overview document can probably be moved into the package-level docs now that the subtopics are more visible.

 

I've made some improvements to the APIs involved with serializing and parsing HTTP parts (e.g. headers, form data, query parameters, path variables).  This was based on pain-points experienced by the Apache Streams team using the client and proxy APIs.  My hope is that this simplifies their code.

I've added a new package in the juneau-marshall project:

I removed the part handling code in the UON and URL-encoding marshallers and put them in these classes.  

The SimpleUonPartSerializer implementation treats everything as plain-text except for beans and maps (which continue to be serialized as UON objects).  This is now the DEFAULT part marshaller in both the client and server APIs.  So if you were creating your own part serializers (or using StringReaders) to get around how strings were being serialized by UrlEncodingSerializer, this change lets you get rid of them.

This change sacrifices "purity" for "practicality".  It should make adoption considerably easier.

Note that this replaces the existing PartSerializer/PartParser/PartType classes, so there will be code adoption.  But it should be straightforward.

Refer to the 7.0.2 release notes for more information:
http://juneau.apache.org/site/apidocs/overview-summary.html#7.0.2