Web page updates

A few web page updates....

I've simplified the ABOUT page and moved the rest of it into a separate COMPONENTS page with subpages....

I also added a Table of Contents section to the DOCUMENTATION page since it seemed kinda empty...

 

That is all...

 

In an attempt to help determine the cause of the intermittent REST call failures in the juneau-microservice-test project, I've made some debugging enhancements to the microservice.

The test project will now generate 4 log files...

 

The jetty-thread-dump.log file is generated by Jetty on the event of a failed request and shows a snapshot of the current state of the threads in Jetty.  The retry handler in TestMicroservice is shown below and will stop the tests as soon as the first error occurs...

 

The jetty-requests.log is generated by adding this to the jetty.xml file...

This just shows if Jetty actually got the request from the last call.

 

Note that the jetty.xml file now supports embedded Juneau variables (e.g. $C{Logging/logDir}).

I also created a separate Jetty section in the config file...

Note that we now support dynamically specifying the port again through the use of the $S{availablePort} variable.

 

The test.0.log file now contains the entire debug logging generated by Jetty (yea...it's big...7.8MB).  I had to create a new org.apache.juneau.microservice.JettyLogger class to serve as a simple bridge between Jetty logging and java-util-logging, but it now allows all the logging to be directed to a single log file.  The configuration for doing this is shown below:

If an error is occurring somewhere in Jetty, it should show up here.

 

The third-party-proxy-resource.txt file contains log entries from RestHooks added to the ThirdPartyProxyResource class (which seems to be a common place for failure).  This makes sure that the failure isn't occurring within our logic.  If we see START/PRE/POST/END messages for our calls, then we know we're not causing a problem.

 

If you do encounter testcase failure due to HTTP request errors, I recommend using WireShark listening on port 10001:

This should help show whether the requests appear to be failing on the server or client side...

 

 

 

FYI...

I've made some significant modifications to the Javadoc overview document so that it mirrors the new Maven artifacts...

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

The Introduction has been rewritten:

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

I've also added a new section describing how to use Juneau REST with Spring:

http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-rest-server.Injection

The ObjectMap section contains new information:

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

There's a new section on using HTTP/2 features, but it's just a placeholder for now:

http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-rest-server.HTTP2

The packaging has been updated for the template and examples projects so that they're contained within self-encapsulated zip files that can be easily imported into a stand-alone Eclipse workspace.  The docs have been updated to reflect these changes:

http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-microservice-template

http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-examples-core

http://juneau.incubator.apache.org/site/apidocs/overview-summary.html#juneau-examples-rest

 

I've created an updated "about" page on the website.  It's currently not linked, but can be viewed via this URL...

http://juneau.incubator.apache.org/index2.html

I've tried to break up the information based on the Maven artifacts.  

Let me know your thoughts....

 

Project structure changes

FYI.....I plan on reworking the Juneau projects to use nested feature group projects.  The groups will be as follows...

  • juneau-core - Core projects.
  • juneau-rest - REST and Microservice projects.
  • juneau-examples - Example projects.
  • juneau-releng - Release engineering projects.

The layout will be as follows....

Note:  The juneau-rest-test project prereqs the juneau-microservice project which is why the REST and microservice projects are in the same group. 

Let me know if anyone has any concerns with this change.

 

The Juneau serializers will now serialize the contents of Readers and InputStreams directly to the output stream.  They used to just call call the toString() method on these objects (which wasn't particularly useful).

When used in conjunction with swaps, you can now provide low-level serialization of POJOs for any of the non-RDF languages:


* This doesn't work for RDF because we don't have access to the underlying stream.  Instead, we use an intermediate Jena model.  In this case, the contents of the Reader/InputStream are converted to a literal.

 

This is a stepping stone to supporting FreeMarker template support for POJOs.  Instead of a solution for just HTML, I'm interested in finding a generalized template solution for any language that builds upon the existing Swap API.  

The general idea is that we can define template strings against POJOs using an annotation such as the following:

Or they can be defined on @RestResource and @RestMethod annotations...

Engines would be tied to media types.  So for example, the FreeMarkerTemplateEngine would be mapped to the "text/html" media type and thus only be invoked by HtmlSerializer.  The engine would swap out POJOs with either Readers or HTML5 beans.  

 

 

 

New @RestHook annotation.

I've added a new annotation that resolves the feature request shown below.

  1. JUNEAU-64 Support advanced annotated variables on methods implementing onPreCall and onPostCall

It also adds the capability for performing child resource initialization before parent resource initialization.

 

The change replaces the various servlet and REST call lifecycle methods with a single unifying method annotation:
http://juneau.incubator.apache.org/site/apidocs/org/apache/juneau/rest/annotation/RestHook.html

 

One of the nice features is that you can add as many of these annotated methods as you like to your class.  For example, instead of a single init(RestConfig) method, just add your own init methods and never have to worry about calling super.init(RestConfig).                

In order to get this to work, I did have to make the RestServlet.init(ServletConfig) final so that it can no longer be extended.  The normal HttpServlet.init() method can still be overridden, however it's probably best-practice to just use @RestHook(INIT).

 

I debated whether to keep these, but decided to remove them from the RestServlet class to keep things simple:

Some updates have been made around the use of Jetty in the microservice API:

  1. The version of Jetty has been upgraded to v9.4.6.v20170531

  2. The microservice now ships with a default jetty.xml file that can be used to configure Jetty.  Settings related to authentication and SSL have been removed from the cfg file.  You can still define resource mappings and used ports in the cfg file, but the default behavior is to specify these in the jetty.xml file.  

  3. The introduction of the new Jetty version required me to bump up the javax.servlet version from 3.0.1 to 3.1.0 and add some minor code changes.  This is going to require at least a minor version bump.

 

Some improvements I've just added surrounding the menu-item widgets:

  • Widget classes can now be defined as inner-classes of resources.
  • New Tooltip template class has been added that allows you to programmatically specify a tooltip.  It can be mixed with arbitrary HTML5 beans.

I've added a new menu-item example to the Pet Store resource complete with tooltips:

 

The menu item is defined as an inner class on the PetStoreResource class and gets added via a new addPet() method...

 

The Tooltip class is a simple POJO with a swap method that wraps the contents in a Div tag....

This is a notification of changes being made internally in the serializers and parsers.  Existing APIs and behavior are unchanged.

The major change is that SerializerSession and ParserSession objects are now reusable as long as they're reused within the same thread.  They used to be throw-away objects that would only exist for the duration of a single serialization/parse.

// Old way (still works)
JsonSerializer.DEFAULT.serialize(writer1, pojo1);
JsonSerializer.DEFAULT.serialize(writer2, pojo2);

// New way now possible
SerializerSession session = JsonSerializer.DEFAULT.createSession();
try {
  session.serialize(writer1, pojo1);
  session.serialize(writer2, pojo2);
} finally {
session.close();
}  
 

The original driver behind this change was so that the existing HtmlSerializerSession can be used in the MenuItemWidget (and other widgets) to serialize POJOs to match the formatting rules on the rest of the page. 

Internally, the actual serialization and parsing code has been moved from the Serializer/Parser subclasses into the Session classes.  This had the nice side effect of allowing me to eliminate many of the getter methods on the session objects and replace them with references to private final fields which cleaned up the code quite a bit.  There might be some slight performance improvements, but the GIT compiler was probably already inlining much of this code.

Session objects are rather cheap to create, but they do still involve setting 20+ private final fields.  So I can envision the sessions being reused when ultra-efficiency is needed.  But again the usecase would be limited since they're not designed to be thread safe.

 

Objective: 

Bind a specific POJO to a freemarker template and render the object as an html element.

Steps:

First, your project should include freemarker:

Next, you need a proper pojo containing multiple fields. Here's the pojo I'm trying to customize: 

Adr.java

 

Next, create a freemarker template to translate an instance of this bean type into a specific HTML element.

Here's an example that renders the address class as a DIV, using a conditional on the addr2 field, and combining city state and zip into a single row.

MemberAddressRender.div.html

 

Next, you need to create an HtmlRender class for this type of bean.  For example:

MemberAddressRender.java

 

Finally, you need to bind the custom Render class onto the class(es) which have the class you are customizing as a child.

MemberHtml.java

In case you are interested, here's the auto-generated Member class whose presentation is being customized.

Member.java

 

Great.  Now any resource which returns a MemberHtml or a List<MemberHtml> to the Juneau HTML Serializer will see the freemarker template applied to any Adr instances within the appropriate cell.

BEFORE:

AFTER:

Test blog post #2

The @RestMethod.bpIncludes()/bpExcludes() annotations have been replaced simplified syntax.

Instead of LAX JSON, it's now an array of simple key/value pairs and the names have been shortened:

// Old:
@RestMethod(
   bpExcludes="{Bean1: 'foo,bar', '*': 'baz,qux'}"
)
// New:
@RestMethod(
   bpx={"Bean1: foo,bar", "*: baz,qux"}
)

See:
http://juneau.incubator.apache.org/site/apidocs/org/apache/juneau/rest/annotation/RestMethod.html#bpi--
http://juneau.incubator.apache.org/site/apidocs/org/apache/juneau/rest/annotation/RestMethod.html#bpx--

I've simplified the way the headers are defined on the HTML pages.

I've eliminated the @HtmlDoc.title()/description()/branding() annotations (and related methods and properties).  Instead, you just use the @HtmlDoc.header() with variables to define the header.

The default header value is defined in RestServletDefault as shown:

You can easily override this value to specify any value you wish.  This makes the header much more flexible and easier-to-understand.

The $R variable was changed to a DefaultingVar so that you can chain possible values to find a first-match (as shown above).

I've also added a new $F variable for pulling in values directly from localized files if you don't want to embed a bunch of HTML inside your annotations:

It's similar to widgets except it resolves to just arbitrary text (and doesn't support javascript and css like widgets do).
It's also similar to Class.getResourceAsStream(), but searches up the servlet class hierarchy for the file.  It can even pull the file from the JVM working directory as last resort.  
It also supports localized names based on the request Accept-Language.  So in the example above, if the request language is Japanese, we'll also search for DockerRegistryResourceAside_ja_JP.html and DockerRegistryResourceAside_ja.html.

Like widgets, it also strips comments from HTML files so you can add Apache license headers to your files.

Javadoc is here:  http://juneau.incubator.apache.org/site/apidocs/org/apache/juneau/rest/vars/FileVar.html

Just like widgets, the $F variable file contents can contain other variables.  (Heck...it can even contain other $F variables if you want to do fancy recursive nesting of files)

The full list of variables has been update here and linked to from various locations where they can be used:
http://juneau.incubator.apache.org/site/apidocs/org/apache/juneau/rest/RestContext.html#getVarResolver--

 

I've added an "INHERIT" literal string that can be used in the @HtmlDoc annotation to inherit and extend values from the servlet class.

Where this is useful is when you want to define a a set of links on a class, but want to add an additional link on a particular method.  Previously this meant you had to duplicate all the links on the method annotation such as shown below from the PetStore example:

Links defined on class:

Links overridden on method to add a single QUERY menu item:

With the "INHERIT" literal, you can include the parent links and augment them with more links like so:

The parent links are included in the position specified in the array, so you can include links before or after the list parent links, or you can optionally use square brackets to specify an index position if you want to insert your link in the middle of the parent links.  

The "INHERIT" literal can be used in any of the following @HtmlDoc values:  header, script, style, links, aside, footer.

When used on the @HtmlDoc in the @RestResource annotation, it inherits the value from the parent class.