How do I host the HTML5 Document Viewer Demo Application on a Windows or Linux Machine using Java?

Introduction:
The LEADTOOLS DocumentViewer consists of web services and clients that work together to provide a seamless experience for document viewing, annotating, editing, and conversion, among other features. The Java version of the LEADTOOLS Documents Service is a port of the original LEADTOOLS ASP.NET Web Api Documents Service. For readability and ease of development for all, these services keep code organization the same as much as possible. Both services are configured to run with the LEADTOOLS Document Viewer client applications, and can share cache locations if the serialization format for the LEADTOOLS FileCache is JSON.

In addition, the Java version of the DocumentViewer can be used on both Linux and Windows machines, while the .NET version of the DocumentViewer is only available through a Windows machine using Microsoft Visual Studio.

This document will run through the configuration of both client on a Linux machine and service on a Linux or Windows machine using Eclipse IDE and the Apache Tomcat server.

Please Note the specific case where your development configuration includes:

• A Linux OS running within virtual machine software (such as VirtualBox) with a bridged network to allow local network access
  
• The LEADTOOLS Java Documents Service running on localhost on that virtual machine
  
• The LEADTOOLS DocumentViewer client running locally on the host Windows machine or another Windows machine
  

With this setup, recent versions of Microsoft Edge and Windows proxy settings will not allow the client to reach the service. Accessing the Linux machine service outside of localhost, running the service on a Windows machine, or using any other supported browser will provide the expected results.

Client:
The web clients for the DocumentViewer rely on HTML5 and JavaScript, which are platform-independent. The .NET version of the DocumentViewer organizes each client as a TypeScript-only project and an HTML/CSS/JavaScript web project, with the former used to compile JavaScript files for the latter. These projects are shipped pre-built; because of this separated and pre-built configuration, a user may opt out of the use of TypeScript from the very start.

The Java version of the DocumentViewer client does not contain the TypeScript project and removes all Visual Studio references, leaving only the final HTML/CSS/JavaScript project as a directory. This directory can be immediately hosted using any Windows or Linux hosting service that serves static files, but the client will not function correctly until the service is correctly configured.

Setup in Linux using Apache

1. Install the Apache HTTP Server.
   
   
2. Create a directory for the DocumentViewer client.
   
   
3. Copy the contents of “/home/leadtools/LEADTOOLS19/Examples/JS/Documents/DocumentViewer/Clients/Apps/App1/site” to the newly-created directory.
   
   
4. Update the “serviceHost” key in the /var/www/html/lt-docviewer/serviceConfig.json file with the ip:port of the DocumentViewer Service.
   
5. Setup permissions.
   
   
6. Browse to “localhost/lt-docviewer/” in your browser.
   

Service
The Java Documents Service requires configuration of the machine for Java and Eclipse. The steps below will cover the configuration and setup of the project in Eclipse for either a Windows or Linux machine, making distinctions between the platforms where necessary. Once the project is set up in Eclipse and running, the user can refer to the root index.html and /Resources/development.html for more information on development, client connections, and deployment. Major topics from /Resources/development.html are available at the end of this document.

Any code instructions below are written for Windows by default unless otherwise specified.

Installations

Prerequisite: Platform Types
At the time of this writing, only certain configurations of the platforms types between the OS, JDK, and Eclipse work correctly:

• 32-bit OS | 32-bit JDK | 32-bit Eclipse (32-bit only)
  
• 64-bit OS | 32-bit JDK | 32-bit Eclipse
  
• 64-bit OS | 64-bit JDK | 64-bit Eclipse (64-bit only)
  

Decide prior to installing the JDK and Eclipse below which type you will need for your Operating System.

Java
The Java Development Kit can be installed from Oracle. Please note that the Java Development Kit (JDK) is needed, not simply the JRE. Either Java 7 (Version 1.7) or Java 8 (Version 1.8) is acceptable.

1. Download the JDK version you wish to use.
   
2. Extract/move/copy the downloaded JDK to a permanent location on the machine.
   
   *If using Tomcat: Set this permanent location (the directory above bin) to the %JAVA_HOME% (in Linux: $JAVA_HOME) environment variable.
   
   
3. Add this location (the directory above bin) to the %PATH% variable. This step is sometimes handled by the installation tool, but not always.
   
   *Or if using Tomcat: Add the %JAVA_HOME% environment variable to the %PATH% instead.
   
   

You can verify this process was successful by typing java -version in a command line tool.

Eclipse
Eclipse IDE has many different flavors to match the different types of development offered with Java. To run Dynamic Web Applications, “Eclipse IDE for Java EE Developers” is needed. Download the correct version matching your OS. At the time of this writing, the version is Eclipse Mars (4.5).

Ensure that Eclipse and its support files are moved to a permanent location on the machine.

Installing Eclipse Additional Web Tools
You must verify that Eclipse has the proper settings before it can run a web project.

1. After opening Eclipse, select Help > Install New Software...
   
2. Click the Add... button to add a new download site, and add the following information:
   
   a. Name: "The Eclipse Web Tools Platform (WTP) software repository"
   
   
   b. Location: http://download.eclipse....webtools/repository/mars (may be different if your version is not Eclipse Mars)
   
   
3. Ensure these items are checked:
   
   a. Eclipse Java EE Developer Tools
   
   
   b. Eclipse Java Web Developer Tools
   
   
   c. Eclipse Web Developer Tools
   
   
   d. JST Server Adapters
   
   
   e. JST Server Adapters Extensions
   
   
4. Complete the installation process for these updates, and restart Eclipse if prompted.
   

Maven
Maven is a Dependency Management system used by the Java Documents Service. It must be downloaded to take care of 3rd party libraries used by the service.

1. Download the latest version of Maven.
   
2. Unpack the download in a permanent location on the machine.
   
3. Add the bin folder of this permanent location to your %PATH% environment variable.
   

You can verify this process was successful by typing mvn --version (in Linux: mvn -version) in a command line tool.

Tomcat
If not using Tomcat, please disregard this section.
The version of Tomcat matches the version of JDK. If you installed Java 8 (Version 1.8) you will need Tomcat 8, for example.

1. Download the correct version of Apache Tomcat that matches your OS. While many Linux users prefer to use the “apt-get” command to install software like Tomcat, this may install the necessary files in atypical locations. It is best to download from the Apache Tomcat website.
   
2. Move the download folder to a permanent location on the machine.
   
3. Set this permanent location (the directory above bin) to the %CATALINA_HOME% environment variable.
   

You can verify this process was successful using the below steps:

1. Type “%CATALINA_HOME%”\bin\startup.bat (in Linux: $CATALINA_HOME\bin\startup.sh) in a command line tool to start the server.
   
2. Type “%CATALINA_HOME%”\bin\shutdown to stop the server.
   

Project Setup
Now that all the necessary applications are installed, the project can be added to Eclipse. Import the project with File > Import > Existing Projects Into Workspace, and choose not to copy into the workspace.
At this point, the project may give some initial errors. This is normal, and more setup must be done.

Adding and configuring the Tomcat Server in Eclipse
If not using Tomcat, please disregard this section.
While developing, Tomcat must be added to Eclipse. For deployment, the project can be exported as a WAR file and moved to a different location for a full Tomcat server.
Use the below steps to set up the server in Eclipse:

1. Open the dialog at Window > Preferences > Server > Runtime Environments.
   
2. Click the Add... button and select your server from the list.
   
3. On the following screen, ensure the installation directory points to your server installation from before. In some cases, Eclipse may recognize the %CATALINA_HOME% path and have it already entered.
   
4. Choose your downloaded JDK from the JRE selection box. If it is not visible, add your JDK using the Installed JREs... dialog and then select it.
   

Use the below steps to add the server view and connect it to the project:

1. Add the Server view to Eclipse if is not added, either from Window > Show View > Server or Window > Show View > Other....
   
2. Click the link in this view or right-click and select New > Server to create a new server.
   
3. Select the same server from the list, and set the server name.
   
4. Select the server runtime environment you just created.
   
5. On the following screen, add your project from the “Available” to “Configured” view.
   

Now the server has been added for our project, but it may not be configured to your full specifications. By double-clicking the newly created server entry, the name and ports can be configured further.

Additional Server Configuration
Please follow this step regardless of server configuration and regardless of whether using Eclipse or a full server on the machine.

Finally, the LEADTOOLS Documents Service uses a caching system for quick access to documents that have already been loaded. In the event the client performs a document conversion, a URL is created pointing to the converted document’s location in the cache. For this reason, the server must be configured to statically serve the cache directory.

The cache directory, by default, is the cache directory under the root of the project. This can be changed in the src/main/resources/config.properties file (discussed more below). This value in the configuration may be either an absolute path on the server or a relative one from the lt.Application.BaseDirectory. Whatever the final directory is, it must be added to the server’s configuration file so that it is visible to the client. In Linux, the directory must also exist before the server is started.

For Tomcat, this means changing bottom of the server.xml file (available under the “Servers” folder in the Project Explorer) to the following:

This feature should be available in all servers. After changing this file, be sure to right-click the server in the Server view and run the Clean... command.

Configuring the Project for the Server
One of our final steps is to now set properties on the project to match the server.

1. Add the server libraries to the project.
   
   a. Right-click the project in Project Explorer and select Properties > Java Build Path > Libraries.
   
   
   b. Remove and edit any entries for the JRE System Library until only the proper JDK is present (or add it through Add Library... > JRE System Library if none exist). This is the one installed from above that should match the server’s JDK.
   
   
   c. Remove and edit any entries for the server runtime until only the proper server runtime is present (or add it through Add Library... > Server Runtime if none exist). This is the one created above.
   
   
   d. Under the Order and Export tab, check the box for the server runtime so that it is exported.
   
   
2. Change the context root.
   
   a. Right-click the project in Project Explorer and select Properties > Web Project Settings.
   
   
   b. Change the context root to the desired path. The default should be “/”, meaning the project will run at the root of the server.
   
   
3. Change the targeted runtime.
   
   a. Right-click the project in Project Explorer and select Properties > Target Runtimes.
   
   
   b. Make sure your server runtime is selected.
   
   

Verifying LEADTOOLS Jar paths and linked files
If errors are still visible, check that the references for the LEADTOOLS jars are correct. They may be incorrect based on your project location. If you need to modify these entries or add others, make sure all these steps are followed:

1. The library was added under Properties > Java Build Path > Libraries.
   
2. The library is selected to be exported under Properties > Java Build Path > Order and Export.
   
3. The library is set to be deployed under Properties > Deployment Assembly.
   

Running the Java Documents Service
At this point, all errors should be resolved and the project should be ready to run. The final step is to input our specific settings for the demo into the src/main/resources/config.properties file. Most of the values in this configuration file can be left blank, but

• lt.Application.BaseDirectory must be set to the path for the project
  
• lt.Application.DllDirectory must be set to the LEADTOOLS installation bin folder
  

Finally, to run the service, hit either the “Debug” or “Run” button in the Server view with your server selected. When you see the “Server startup in ____ ms” message, the service is ready for connections. Navigate to the port set by your server runtime to see the command page for the service, including a link to the /Resources/development.html for more information on development, client connections, and deployment. Important sections from that development page are available below.

When making changes to the Java Documents Service in Eclipse, the server may attempt to restart itself after detecting changes. LEADTOOLS always recommends stopping and restarting the server, since this may cause unexpected issues with our libraries.

Considerations for Deployment
Below are the sections of /Resources/development.html that have not been covered above already, for an additional area of reference.

Servers and Deployment
This service was primarily built with and tested for Apache Tomcat 8 running through Eclipse. The service also has been verified to run on Eclipse Jetty 9 and WildFly (Formerly JBOSS) 10 in Eclipse with a minimum Java version of 1.7. If you experience issues with other servers, it is recommended to try first to get a working implementation of the service with Tomcat due to its wide popularity and availability for support.

This service was also tested when deployed to a full application server (Tomcat 8). While Maven is used in the project for dependency management, the use of LEADTOOLS jars and linked files (for use with the .NET implementation) has proven to make efforts to deploy via Maven very complicated. The best way to deploy remains to export a WAR file from Eclipse, where the build path entries are correctly configured.

Document Conversion and Server Settings
The ASP.NET version of the Documents Service allows for default static serving of directories without any additional configuration of IIS. With this Java service, however, configuration of the server is necessary for Document Conversion. Documents Service Document Conversion uses the LEADTOOLS FileCache to store the input and output for the DocumentConverterDemo JAR, which handles the actual conversion process. The service must be provided the path to the jar in the config.properties file. The service executes the JAR using Java ProcessBuilder.

The DocumentConverterDemo JAR must be exported as a Runnable JAR. This allows it to be called by the service without needing additional information about the context. This option is available from Eclipse in the export dialog.

When the conversion completes successfully, the converted document is made available on the server for download at a URL. This is where the static serving comes in, and where the developer must ensure they have the proper settings on their server's server.xml or equivalent configuration file (discussed above). The values supplied here must match the config.properties entries for the LEADTOOLS FileCache Directory and Virtual Directory. If using Eclipse to run the server, be sure to clean the server afterward so the changes are reflected.

Linked Files
Some files in this project are linked from other folders in \Examples\JS\Documents. These files are linked so that they receive changes to the source file. While in .NET, these linked files need to be copied manually or through an event, a build from Eclipse will automatically copy the linked files to the desired location.

Service Exceptions
Exception handling is important in this Jersey service, and is based off the implementation from ASP.NET Web Api. The classes within com.leadtools.documents_service.tools.exceptions contribute to detailed exception-reporting back to the client. A request / response debugger like Telerik's Fiddler may be helpful in understanding the ServiceError object returned from the service when an error occurs.

In com.leadtools.documents_service.controllers, each action may have a ServiceErrorAnnotation that determines the generic exception message returned. Additional controller methods should take advantage of this annotation. Exceptions are returned as a serialized ServiceError object (which in turn comes from the ServiceException object) for ease in parsing the exception in the client LEADTOOLS Document Library.

JSON Serialization
Although Jersey's MOXy is the recommended and default framework for JSON binding in Jersey applications from version 2.0 and on, the more popular Jackson JSON Library is used in this Documents Service for its ease of configuration. Internal LEADTOOLS jars have JAXB annotation support, GSON annotation support, and Jackson annotation support.

Google's GSON is used for internal serialization, whereas Jackson is used for request/response serialization. MOXy can be made to work as the request/ response serialization provider if the developer adds support for the serialization of non-numeric values (e.g., NaN) to match what Jackson does automatically. The Jackson serialization can be configured with the provided com.leadtools.documents_service.startup.JacksonMapper class.

CORS
CORS is enabled via the CorsFilter class in CorsFilter.java. The class is marked with the @Provider and @PreMatching annotations to designate that it is used as a filter before the URL is matched to a path and method. Changing the values in this method (programmatically or manually) will allow fine-grained control over CORS. By default, all origins are allowed via allowedOrigins.add("*");

Attached is a downloadable PDF document containing this information as well.

Edited by moderator Monday, February 3, 2020 8:28:28 AM(UTC)  | Reason: Not specified