Blog: Tech Talk

agsdix-fas fa-home

Blog: Home

agsdix-fas fa-pen-fancy

Blog: CEO's Corner

agsdix-fas fa-code

Blog: Tech Talk

Blog: Product Releases

agsdix-fas fa-chalkboard-teacher

Blog: Viewing

Blog: Conversion

arrow left circle icon Blog: Tech Talk

Introducing A New RESTful Content Handler for VirtualViewer® HTML5

by | Sep 28, 2020

The latest release for VirtualViewer® HTML5 introduces a new RESTful content handler that provides a more flexible development and deployment process for customers. Snowbound’s Senior Software Engineer Leah Foster explains…

What is the RESTful content handler?

VirtualViewer is designed to retrieve data from an organization’s content management system and provide that data to the client document viewer. 

The content handler is the link between VirtualViewer and the content management system that actually stores documents. Whenever a user clicks a link to open a document in VirtualViewer or loads up a document in a new tab, VirtualViewer calls a content handler function requesting that document data.

It’s up to the content handler, and the custom code inside it, to load data from the CMS and hand it to VirtualViewer. While the example content handler simply reads files from the server’s file system, production content handlers are usually more complex. It might handle its own database connection or reach out further to a remote content server or database.

Currently, the content handler is custom Java code built into a jar file, which is then added to the VirtualViewer build. Configuration lets VirtualViewer hook into content handler code and call its Java functions.

The RESTful content handler is a Snowbound-provided jar that is already in the VirtualViewer build. It sends HTTP requests to a configured URI in order to request data, store data, and send notifications. Instead of writing Java code to fit the VirtualViewer interface, the custom-written content handler may now be a completely separate server application that receives these web requests. 

REST is a code architecture design style for APIs that communicate over a network. Using the RESTful content handler means that the API design is intended to be simple, navigable, and resource-focused. On a practical level, it means that VirtualViewer changes how it treats the content handler API—from direct Java communication to HTTP requests and responses.

Configuring the RESTful content handler means that custom code no longer must be a Java class that passes data to VirtualViewer. The custom code can be completely independent and pass data to VirtualViewer over a network instead.

Why to use it?

The content handler serves as an isolation layer between a CMS and VirtualViewer so the CMS and VirtualViewer can both be flexibly deployed and configured independent of each other. 

Currently, content handler code is tied very closely to VirtualViewer. Despite providing the isolation layer, the content handler cannot be isolated from VirtualViewer. The content handler has to be written in Java, it has to be deployed with the VirtualViewer build, and it generally uses VirtualViewer dependencies. 

Loosening those ties with VirtualViewer allows for a real expansion of flexibility in deployment

First, it allows for near complete isolation of the VirtualViewer server application. If there’s no additional code to add to a VirtualViewer deployment then VirtualViewer could be deployed easily on Docker, or in another managed services context.

Even deploying VirtualViewer directly on internally-managed platforms becomes easier with a more isolated setup. Moving to a system where custom code is no longer added to the VirtualViewer build removes a substantial step from deployment. 

The road between downloading a new build and production becomes shorter and easier.

The development process eases as well. Java is a widely used language, but VirtualViewer would no longer require a Java developer to get it running—the code can match existing systems and existing development capabilities. 

The link between VirtualViewer and the content management system could be written in any language: a .NET setup could communicate easily with VirtualViewer Java, for example.

How it works

Enabling the RESTful content handler is a matter of configuration in web.xml:

  • Set VirtualViewer to use the correct Java class
  • Provide an API key that VirtualViewer will send with every request
  • And provide a URL that points to the content handler

With this setup, VirtualViewer now emits HTTP requests instead of Java function calls for data storage and retrieval. This configuration changes how VirtualViewer uses custom content handler code.

Now, the content handler code may be written in any framework or programming language. It must listen for HTTP requests at a few URIs that VirtualViewer will call out to and return data in the specified format.

Calling this configuration RESTful implies a few things, right off the bat. REST is a programming design philosophy for APIs that communicate over HTTP. While the content handler setup may not be strictly RESTful, it means that VirtualViewer is making some assumptions. 

First, VirtualViewer assumes that the content handler is stateless, so it sends an API key with every request and does not count on an existing session on the content handler.

Second, VirtualViewer treats the entire API—the custom content handler—as a collection of resources. Each HTTP request it sends will ask to get, create, or update a resource.

A document is a resource: VirtualViewer might ask to get an image by sending an HTTP request to the URI “https://contenthandler-server-uri.com/documents/mydocumentid.

An annotation layer is a resource: VirtualViewer might save a new annotation layer by sending a request to the URI “https://contenthandler-server-uri.com/documents/mydocumentid/annotations” with the new annotation data in the body.

After ensuring the content handler server is listening on the specified API routes, the implementation can be completed according to the needs of the content management system.

We want your feedback

This RESTful Content Handler is an alpha version that Snowbound will continue to work on and improve. If you are a customer who has test driven the handler, we would appreciate your feedback via this short survey.

Leah Foster is Snowbound’s Senior Software Engineer.

Action Items: