V13.6 Java Content Server Administrator's Guide

Transcription

1 VirtualViewer V13.6 Java Content Server Administrator's Guide Note: An online version of this manual contains information on the latest updates to VirtualViewer. To find the most recent version of this manual, please visit the online version at or download the most recent version from our website at DOC

2 Copyright Information While Snowbound Software believes the information included in this publication is correct as of the publication date, information in this document is subject to change without notice. UNLESS EXPRESSLY SET FORTH IN A WRITTEN AGREEMENT SIGNED BY AN AUTHORIZED REPRESENTATIVE OF SNOWBOUND SOFTWARE CORPORATION MAKES NO WARRANTY OR REPRESENTATION OF ANY KIND WITH RESPECT TO THE INFORMATION CONTAINED HEREIN, INCLUDING WARRANTY OF MERCHANTABILITY AND FITNESS FOR A PURPOSE. Snowbound Software Corporation assumes no responsibility or obligation of any kind for any errors contained herein or in connection with the furnishing, performance, or use of this document. Software described in Snowbound documents (a) is the property of Snowbound Software Corporation or the third party, (b) is furnished only under license, and (c) may be copied or used only as expressly permitted under the terms of the license. All contents of this manual are copyrighted by Snowbound Software Corporation. The information contained herein is the exclusive property of Snowbound Software Corporation and shall not be copied, transferred, photocopied, translated on paper, film, electronic media, or computer-readable form, or otherwise reproduced in any way, without the express written permission of Snowbound Software Corporation. Microsoft, MS, MS-DOS, Windows, Windows NT, and SQL Server are either trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. Adobe, the Adobe logo, Acrobat, and the Acrobat logo are trademarks of Adobe Systems Incorporated. Sun, Sun Microsystems, the Sun Logo, and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. itext, the Initial Developers of the Original Code are Bruno Lowagie and Paolo Soares. Portions created by Bruno Lowagie are Copyright by Bruno Lowagie. Kakadu JPEG2000, is copyrighted by Dr. David Taubman, and is proprietary to NewSouth Innovations, Pty. Ltd, Australia. I-NET JWebEngine is proprietary to I-NET Software GmbH, and shall remain the sole and exclusive property of I- Net Software GmbH. United States Government Restricted Rights The Software is provided with RESTRICTED RIGHTS. Use, duplication or disclosure by the United States Government is subject to restrictions as set forth under subparagraph (c)(1)(ii) of The Rights in Technical Data and Computer Software clause of DFARS or subparagraphs (c)(i) and (2) of the Commercial Computer Software-Restricted Rights at 48 CFR as applicable. The Manufacturer is Snowbound Software Corporation, 309 Waverley Oaks Rd., Suite 401, Waltham, MA 02452, USA. All other trademarks and registered trademarks are the property of their respective holders. Manual Title: Snowbound Software VirtualViewer Java Content Server Administrator's Guide Part Number: DOC Revision: 03 VirtualViewer for Java Release Number: 13.6 VirtualViewer Release Number: 13.6 Printing Date: May 2014 Published by Snowbound Software Corporation. 309 Waverley Oaks Road, Suite 401 Waltham, MA USA phone: fax: by Snowbound Software Corporation. All rights reserved.

3 Table of Contents Chapter 1 - Quick Start Configuration for Evaluation 9 Quick Configuration for Evaluation 9 Step 1: Expand the web application 9 Step 2: Edit the web.xml (Server-Applet or Serlvet-AJAX Client only) 9 Step 3: Edit the applet.html 10 Chapter 2 - Configuring VirtualViewer Java for a Production Environment 11 Document Retrieval and Rendering Settings 11 Retrieval Servlet 11 Upload Servlet 11 Defining the Servlet Paths 12 Connecting to Your Document Store 12 Working with Error Logging 13 Servlet Logging 13 AFP Font Mapping 14 Enabling Redaction Support 14 Setting the DPI, Bit Depth, and Format Parameters 17 Adjusting Thumbnail Parameters 18 Setting the thumbbyteestimate Parameter 18 Setting the thumbnaildpi Parameter 18 Setting the Aspose Parameters 18 Setting the Aspose License Path Office Documents 19 Setting the Format Parameters to Display Color Output in Office iii

4 Documents Chapter 3 - Configuring to Maximize Your Performance or Quality 21 Reducing the Resolution - Setting the DPI 21 Adjusting Color vs. Black and White - Setting the Bit Depth 22 Setting the Format 23 Memory Recommendation 24 Determining Memory Requirements 24 Recommended Setting for the Parameters in the Web.xml File 25 Using the itext Library and Vector PDF Setting in the Web.xml File 26 Caching to Improve Performance 26 Do you need caching at all? 27 Sizing the Cache if You Need It 27 Defining the Number of Pages Cached in Memory 28 Cache Maintenance 28 Caching and Security 29 Chapter 4 - Connecting to Your Document Store 30 What is the Content Handler? 30 How the Content Handler Works 30 Defining a Custom Content Handler 31 Authentication 32 Document Caching 33 FlexSnapSIContentHandlerInterface 33 CacheValidator 33 CacheValidator Method Detail 34 iv

5 Event Notification and Handling 34 Extracting Parameters from ContentHandlerInput 39 Populating Parameters for ContentHandlerInput 40 Populating Parameters for ContentHandlerResult 40 Content Handler Methods 41 FlexSnapSIContentHandlerInterface Method Detail 43 FlexSnapSISaverInterface Method Detail 56 Using KEY_ANNOTATION_LAYERS 58 Chapter 5 - Working with Annotations 62 Annotation Security: Watermarks and Redactions 62 The Annotation Security Model 62 Permission levels 62 Level Definitions 63 Redaction Support 64 Working with XML Annotations 64 Saving Annotations to XML 64 Appendix A - Servlet Tags for web.xml 65 Required Servlet Parameters 65 Optional Servlet Parameters 66 Deprecated Servlet Parameters 71 Obsolete Servlet Parameters 71 Appendix B - Supported File Formats 73 Descriptions of Supported File Formats 73 File Type Constants Listed by File Type Number 84 v

6 Appendix C - AFP Font Mapping 86 AFP Font Mapping 86 Format of Font Mapping Data 86 Appendix D - Snowbound Error Codes 88 Detailed Status/Error Codes 88 General Error Define Values from Status Property 91 General Status/Error Codes 92 Appendix E - Troubleshooting 93 Submitting a Support Issue 93 Annotation Text Does Not Appear on Separate Lines 93 Unable to Enter More Text After Using the - Key in an Annotation 93 Getting an Evaluation Period Expired Error Message When Creating a War File 94 Fonts Do Not Display Correctly 94 Excel 2007 xlsx files return -7 Format_not_found error 95 Overlay Resources Not Pulled into APF or MODCA Document 95 Default Configuration Maximizes Performance 95 Configuring to Maximize Quality 96 Recommended JRE Memory Settings 96 Displaying a Document as Landscape 97 VirtualViewer Java Not Prompting for Save Changes 97 Saving Changes When Using Different Versions of Java Runtime 98 Getting a ClassNotFoundException Error 98 Resolving NoClassDefFound error due to AWT dependency 98 JDK 1.4 or greater 99 vi

7 List of Tables Table 3.1: DPI Parameter Value and Description 21 Table 3.2: Bit Depth Parameter Values and Description 22 Table 3.3: Format Parameter Values and Description 23 Table 3.4: Memory Requirements Based on Image Size 25 Table 3.5: Server and/or Client vectorpdf Parameter 26 Table 4.1: Method Summary 39 Table 4.2: Existing Keys from the Hash Table to Extra Parameter Data 39 Table 4.3: Property Descriptions 40 Table 4.4: FlexSnapSIContentHandlerInterface 41 Table 5.1: Permission Levels 62 Table 5.2: Level Definitions 63 Table A.1: ResponseServer 65 Table A.2: Required Servlet Parameters 65 Table A.3: RetrievalServlet Parameters 66 Table A.4: UploadServlet Parameters 70 Table A.5: ResponseServer Parameters. 71 Table A.6: ResponseServer Parameters. 71 Table B.1: File Format Key 73 Table B.2: Supported File Format Descriptions 73 Table B.3: File Type Constants listed by File Type Number 84 Table C.1: Description of a Sample Entry 87 Table D.1: Error Codes 88 vii

8 Table D.2: General Error Define Values Retrieved from Status Property 91 Table D.3: General Status/Error Codes 92 Table E.1: Memory Requirements Based on Image Size 97 viii

9 Chapter 1 - Quick Start Configuration for Evaluation Chapter 1 - Quick Start Configuration for Evaluation Quick Configuration for Evaluation Step 1: Expand the web application VirtualViewer Java can be run as a Servlet-Applet, a Servlet-AJAX Client or a standalone Applet-Only application. Therefore, there are three separate packages delivered as.zip files. The file name for the content server package is VirtualViewerJavaContentServer.zip. The file name for the HTML server is VirtualViewerHTML5.zip. The first step is to expand the applications that you need on the server you plan to use. The VirtualViewer Content Server Installation Guide will guide you through this process, including the prerequisites, and the necessary security changes, if any, on the client. Step 2: Edit the web.xml (Server-Applet or Serlvet-AJAX Client only) A sample web.xml file is supplied when the application is installed, and it is located in the WEB- INF directory. Warning: Please make a backup copy of the web.xml file before you edit it. If you want to change the location where you store your test images, right-click on the web.xml file to open it in a text editor such as Notepad. In the text of the web.xml file, change the value of the filepath parameter to the location of where you would like to store your images. For example, if you want to store your images in C:/images, change the value to C:/images/. By default, this value is set to./sample-documents, which is a sample document folder that goes along with the build package. If you want to store your images in the./sample- Documents directory, then this parameter does not need to be edited. The filepath parameter tells the default content handler where to look for image files that are requested. By default, it is set as: <param name="filepath" value="./sample-documents"/> You can set the value to the path where you will put your test images. For a Windows operating system, please see the following example: <param name="filepath" value="c:/imgs/"/> For a Linux or Mac operating system, please see the following example: 9

10 Chapter 1 - Quick Start Configuration for Evaluation <param name="filepath" value="/usr/share/imgs"/> If you wish to use your own content handler, then this parameter is not used. For more information, please see Connecting to Your Document Store. Step 3: Edit the applet.html The applet.html file is a sample.html file included when the Client application is installed. It is located in the web application root directory. The path depends on what version of Tomcat is installed and user preference. Right-click on the applet.html file and open it in a text editor such as Notepad to edit any of the parameters in the applet.html file. Below are examples of what the path looks like depending on your version of Tomcat and user preferences: C:\apache-tomcat \webapps\VirtualViewerJavaContentServer\ C:\Program Files\Apache Software Foundation\apache-tomcat \webapps\VirtualViewerJavaContentServer\ This file demonstrates how to run the Applet as a floating application and the Applet embedded in a web page. The servleturl parameter should be set to the proper server path where the server component was installed: <param name="servleturl" value=" /> To specify an image file to display when the application loads, use the startfile parameter and set the value of which is an image name (Servlet-Applet) or a full image path (Applet-Only) as shown in the following example: <param name="startfile" value="filename.ext" /> For example, if you want the file SnowLogo.JPG to display when the application loads, set the startfile parameter as shown below: <param name="startfile" value="snowlogo.jpg" /> Note: Step 3: Edit the applet.html does not apply to the VirtualViewer HTML5 product. Please see the next topic Chapter 2, Configuring VirtualViewer for a Production Environment. 10

11 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Chapter 2 - Configuring VirtualViewer Java for a Production Environment Document Retrieval and Rendering Settings The web.xml file is located in the WEB-INF directory and contains a number of tags that define both servlets and their behavior. There are two groups of tags. The first group is a pair of <servlet> tags, and the second group is a pair of <servlet-mapping> tags. To edit any of the tags, right click on the web.xml file to open it in a text editor such as Notepad. Retrieval Servlet The first <servlet> is the Response Server, which is responsible for handling when data needs to be sent to the applet. Various parameters within its tag define where to retrieve documents from, how it should render and deliver them to the applet, how to cache documents, logging, and more. Example 2.1: Retrieval Servlet <servlet> <servlet-name>retrievalservlet</servlet-name> <servlet-class> com.snowbound.snapserv.servlet.retrievalserver </servletclass> <init-param> <param-name>contenthandlerclass</param-name> <param-value>com.snowbound.snapserv.servlet.mycontenthandler </param-value> </init-param> <init-param> <param-name>loglevel</param-name> <param-value>finest</param-value> </init-param> </servlet> The valid values for the loglevel parameter are: Severe, Warning, Info, Config, Fine, Finer, Finest and All. The default value is Finest. Upload Servlet The second <servlet> is the Request Server. It is responsible for handling when data needs to be sent from the applet. Various parameters within its tag define settings for the serlvet when 11

12 Chapter 2 - Configuring VirtualViewer Java for a Production Environment saving documents and annotations. Example of Upload Servlet Example 2.2:Upload Servlet <servlet> <servlet-name>uploadservlet</servlet-name> <servlet- class>com.snowbound.snapserv.servlet.flexsnapsiuploadservlet</- servlet-class> <init-param> <param-name>saveannotationsasxml</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>tmpdir</param-name> <param-value>c:/tmp/</param-value> </init-param> </servlet> Defining the Servlet Paths Each servlet has its own <servlet-mapping> tag to define the path where it is found. Do not change these servlet-mapping definitions. Example 2.3: Servlet Paths <servlet-mapping> <servlet-name>retrievalservlet</servlet-name> <url-pattern>/responseserver</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>uploadservlet</servlet-name> <url-pattern>/requestserver</url-pattern> </servlet-mapping> Connecting to Your Document Store VirtualViewer Java includes a content handler that is a Java class that the serlvet will call on to perform various actions concerning the retrieval and storage of content. This allows you to connect with your document store. For more information on how to implement this, please see Connecting to Your Document Store. 12

13 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Working with Error Logging A public Java interface is included in the servlet which allows the customization of how logging is handled. Messages and trace logs will be written to a common log directory. Please see the following example: Example 2.4: Log Handling package com.snowbound.common.utils; public interface logwriter { public void init(); public void writelogmessage (int Level, String msg); public void writestacktrace (Throwable t); public void setlevel(int level); public void setlevel(string level); public int getlevel(); } Servlet Logging Within the web.xml file, there is a <servlet> parameter that allows the logwriter class to be set for the servlet. To edit any parameters in the web.xml file, right-click on the web.xml file to open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. Example 2.5: logwriter Parameter <init-param> <param-name>logwriter</param-name> <param-value>com.snowbound.common.utils.javalogwriter</paramvalue> </init-param> You can set the amount of information that is logged by setting the loglevel parameter in web.xml: Example 2.6: loglevel Parameter <init-param> <param-name>loglevel</param-name> 13

14 Chapter 2 - Configuring VirtualViewer Java for a Production Environment <param-value>finest</param-value> </init-param> The valid loglevel values are the following listed from least number of messages to most: Severe, Warning, Info, Config, Fine, Finer, Finest, All. The default value is Finest. AFP Font Mapping AFP files can use specific fonts to achieve a particular look. If you find that the fidelity of the output for your AFP documents is lacking, particularly in regards to text size and spacing or barcodes, then you can customize VirtualViewer Java to use particular fonts when processing your AFP files. VirtualViewer Java is easy to customize to improve the look of your AFP documents. Snowbound Software allows you to map the fonts in your AFP/MODCA document to fonts on your system using a mapping file named snbd_map.fnt. The snbd_map.fnt file is custom crafted to specify the fonts used in your AFP files and on your system. If you provide a representative sample AFP document to Snowbound Software by entering a support issue at we will provide you with a custom snbd_map.fnt file usually in a few business days that will improve the display and print quality of your AFP documents. For more information on how to implement AFP font mapping, please see AFP Font Mapping. Enabling Redaction Support If an annotation layer is indicated as having the Redaction permission, then the servlet will create the working image by applying the layer to the data (i.e. burn in the layer) before passing the working image to the applet so that it becomes part of the image and the data it redacts cannot be seen in any way. The original image is not altered. Turning on Redaction Support To turn on redaction support, set the following supportredactions parameter to true in the web.xml file. To edit any parameters in the web.xml file, right-click on the web.xml file to open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. The default value is false. Example 2.7: supportredactions Parameter <init-param> <param-name>supportredactions</param-name> <param-value>true</param-value> </init-param> 14

15 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Retrieving Annotation Layers When loading a document, annotation layers will need to be retrieved and have the correct permission level set. The process of loading an annotation layer is as follows: For each annotationkey returned by getannotationnames the following method will be called. public Hashtable getannotationproperties (clientinstanceid, documentkey, annotationkey) which returns a hashtable with the following expected key/value pairs for that annotation layer. Key/Value Pairs permissionlevel - String indicating the permission level. For more information, see (Table 5-1) Permission Levels. redactionflag - Boolean indicating whether Mark Layer As Redaction is selected in the applet The permissionlevel will determine how the layer is handled. If no value is set, an exception will occur. The redactionflag determines if the layer has Mark Layer As Redaction selected in the applet. If no value is set, an exception will occur. If the permissionlevel is set to PERM_REDACTION, the value of redactionflag is moot since the applet does not receive that layer as an annotation layer. If getannotationproperties returns null, an exception will occur. This prevents cases where a layer should have strict permissions but for some reason no permission level gets set. Saving Redaction Layers If a layer has Mark Layer As Redaction selected, when choosing Save Annotations the following will occur: The applet will pass both the permissionlevel and the redactionflag to the saveannotationcontent method in a Hashtable: public void saveannotationcontent(contenthandlerinput input) String clientinstanceid, String documentid, String annotationkey, byte[] data, Hashtable annproperties) Printing Layers When printing a document, the user may choose to print with or without annotations. Only documents visible in the Image Panel with layers having a Print permission level or higher will print. A layer which has been given a permissionlevel of PERM_REDACTION shall always 15

16 Chapter 2 - Configuring VirtualViewer Java for a Production Environment print as part of the image, (since it has been burned into the image), even if the user chose to print without annotations. Text Searching When searching a document with a redaction layer burned in, any term partially or fully beneath the redacted portions of the document should not be listed in the search results. Creating a Redaction A redaction layer is created just as any other annotation layer. Any objects on the layer will be burned in if upon retrieval the layer is given the Redaction permission. Indication of Redaction A user may use the menu command Mark Layer As Redaction to indicate that the layer is intended to be a redaction layer. Upon save, a flag will be passed indicating whether the layer was marked as redaction so that appropriate action may be taken to store the annotation file properly. 16

17 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Setting the DPI, Bit Depth, and Format Parameters One of the differences between raster and vector formats is that raster formats have specific dots per inch (DPI) and bit depths. Vector formats aren't inherently black and white or color, and while they typically have sizing in inches, there is nothing that says what DPI or bit depth to use when rendered as a raster image. When the content server pulls out a page from a vector format document, it must render that page to a certain DPI and bit depth, as well as save that image as some format to be passed to the client for display. The particular settings are determined on a per format basis by three servlet parameters. By adjusting the bit depth, DPI, and format parameters in various combinations, you can find the best settings for your environment, documents, and user load. Appendix A, Servlet Tags for web.xml has a full listing of all the format servlet parameters available. For more information on how to set the DPI, bit depth, and format parameters, please see Configuring to Maximize Your Performance or Quality. 17

18 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Adjusting Thumbnail Parameters You can adjust the thumbnail parameters described below in the web.xml file. To open the web.xml file, right-click on it and open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. Warning: Please make a backup copy of the web.xml file before you edit it. Setting the thumbbyteestimate Parameter The thumbbyteestimate parameter sets the initial byte size of the buffer used on the server to transport thumbnails. To adjust this parameter, please see the example below. The default value is Example 2.8: thumbbyteestimate Parameter <init-param> <param-name>thumbbyteestimate</param-name> <param-value>6000</param-value> </init-param> Setting the thumbnaildpi Parameter The thumbnaildpi parameter specifies the DPI to use when rendering thumbnails for vector formats such as PDF and MS Word.. To adjust this parameter, please see the example below. The default value is 60. Example 2.9: thumbbyteestimate Parameter <init-param> <param-name>thumbbyteestimate</param-name> <param-value>60</param-value> </init-param> Setting the Aspose Parameters If you have the option to view Office documents, you can set the available Aspose parameters described below in the web.xml file. To open the web.xml file, right-click on it and open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. 18

19 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Setting the Aspose License Path Office Documents If you have the option to view Office documents, set the officelicensepath parameter to call the Aspose license in the web.xml file. To open the web.xml file, right-click on it and open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. Warning: Please make a backup copy of the web.xml file before you edit it. Example 2.10: Setting the officelicensepath Parameters with an Absolute Path <init-param> <add key="officelicensepath" value="c:\\aspose\\aspose.words.lic, C:\\aspose\\Aspose.Cells.lic, C:\\aspose\\Aspose.Slides.lic"/> </init-param> Example 2.11: Setting the officelicensepath Parameters with a Relative Path <init-param> <add key="officelicensepath" value="/web- INF/Aspose.Words.lic, /WEB-INF/Aspose.Slides.lic"/> </init-param> Note: Aspose.Words.<jdk>.jar, Aspose.Cells.jar and dom4j jar all need to be on the CLASSPATH for Office documents to process without error. Please see Setting Up Office Support for VirtualViewer Java and VirtualViewer Java HTML5 for more information. Setting the Format Parameters to Display Color Output in Office Documents To display color output in Office documents, set the xlsxbitdepth and docxbitdepth parameters to 24 and the xlsxdpi and docxdpi parameters to 200 in the web.xml file. To open the web.xml file, right-click on it and open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. 19

20 Chapter 2 - Configuring VirtualViewer Java for a Production Environment Warning: Please make a backup copy of the web.xml file before you edit it. Example 2.12: Setting the Format Parameters to Display Color Output in Office Documents <init-param> <param-name>xlsxbitdepth</param-name> <param-value>24</param-value> </init-param> <init-param> <param-name>xlsxdpi</param-name> <param-value>200</param-value> </init-param> <init-param> <param-name>docxbitdepth</param-name> <param-value>24</param-value> </init-param> <param-name>docxdpi</param-name> <param-value>200</param-value> </init-param> <init-param> <param-name>xlsxdpi</param-name> <param-value>200</param-value> </init-param> <init-param> <param-name>docxbitdepth</param-name> <param-value>24</param-value> </init-param> <init-param> <param-name>docxdpi</param-name> <param-value>200</param-value> </init-param> Please see the next topic Chapter 3, Configuring to Maximize Your Performance or Quality. 20

21 Chapter 3 - Configuring to Maximize Your Performance or Quality Chapter 3 - Configuring to Maximize Your Performance or Quality One of the differences between raster and vector formats is that raster formats have specific dots per inch (DPI) and bit depths. Vector formats aren't inherently black and white or color, and while they typically have sizing in inches, there is nothing that says what DPI or bit depth to use when rendered as a raster image. When the content server pulls out a page from a vector format document, it must render that page to a certain DPI and bit depth, as well as save that image as some format to be passed to the client for display. The particular settings are determined on a per format basis by three servlet parameters: DPI, bit depth, and format. By adjusting the DPI, bit depth, and format parameters in various combinations, you can find the best settings for your environment, documents, and user load. Appendix A, Servlet Tags for web.xml has a full listing of all the format servlet parameters available. Reducing the Resolution - Setting the DPI To improve performance, you can lower the resolution of your image. For example if your image's resolution is 400 dots per inch (DPI), you can save it to 200 DPI. This will make the file size smaller and improve performance. Please note that there is always a trade off between performance and quality. To improve performance, the quality of the image may be less. This is true whenever working with any imaging software. You can also set the DPI parameters in the web.xml file to a lower resolution such as 200. The DPI parameters have a default setting of 200. The DPI parameters determine how many dots per inch should be used when converting a vector page. To edit the DPI parameters in the web.xml file, right-click on the web.xml file and open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. Please note that there is no way to set an external DPI for a TIFF file. TIFF files have an internal DPI setting and only contain raster data. Therefore, you cannot adjust the DPI of a TIFF file. Warning: Please make a backup copy of the web.xml file before you edit it. The available DPI parameters are shown in the table below: Table 3.1: DPI Parameter Value and Description 21

22 Chapter 3 - Configuring to Maximize Your Performance or Quality Parameter Name docxdpi iocadpi modcadpi pcldpi pdfdpi pptdpi worddpi xlsdpi Description The DPI to use for Word 2007 documents. The DPI to use when decompressing IOCA pages. The DPI to use when decompressing MO:DCA pages. The DPI to use when decompressing PCL pages. The DPI to use when decompressing PDF pages. The DPI to use when decompressing PPT pages. The DPI to use when decompressing Word pages. The DPI to use when decompressing XLS pages. Adjusting Color vs. Black and White - Setting the Bit Depth To improve the performance, you can set the bit depth parameters in the web.xml file to 1. The bit depth parameters determine what bit depth to use when converting the vector page. Valid settings for the bit depth parameters are 1 (for black and white, smaller) or 24 (for color, bigger). If any pages of the vector document might be in color, then the setting of 24 should be used, since there is no way to tell if a page might or might not contain color vector objects. This will make the file size smaller and improve performance. Please note that there is always a trade off between performance and quality. To improve performance, the quality of the image may be less. This is true whenever working with any imaging software. To edit any parameters in the web.xml file, right-click on the web.xml file to open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. The available bit depth parameters are shown in the table below: Table 3.2: Bit Depth Parameter Values and Description Parameter Name docxbitdepth iocabitdepth modcabitdepth pclbitdepth pdfbitdepth pptbitdepth Description The bit depth to use for Word 2007 documents. Valid values are 1 or 24. The bit depth to use when decompressing IOCA pages. Valid values are 1 or 24. The bit depth to use when decompressing MO:DCA pages. Valid values are 1 or 24. The bit depth to use when decompressing PCL pages. Valid values are 1 or 24. The bit depth to use when decompressing PDF pages. Valid values are 1 or 24. The bit depth to use when decompressing PPT pages. Valid values are 1 or

23 Chapter 3 - Configuring to Maximize Your Performance or Quality Parameter Name wordbitdepth xlsbitdepth Description The bit depth to use when decompressing Word pages. Valid values are 1 or 24. The bit depth to use when decompressing XLS pages. Valid values are 1 or 24. Setting the Format To improve performance, you can save your files as black and white or grayscale. For example, if you are converting a PDF document, you can try to save the document in the TIFF_G4_FAX file format. This will make the file size smaller and improve performance. Please note that there is always a trade off between performance and quality. To improve performance, the quality of the image may be less. This is true whenever working with any imaging software. The file format parameters determine which format the vector page will be rendered to for sending to the client. Valid values for this parameter are TIFF_G4_FAX (black and white, best for text documents, small size), JPEG (color, good for images, lesser quality for text, small size), TIFF_LZW (color or greyscale, good for documents with text and color elements), or PNG (color, better for text than JPEG, not as small). To edit the format parameters in the web.xml file, right-click on the web.xml file and open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. Warning: Please make a backup copy of the web.xml file before you edit it. The available format parameters are shown in the table below: Table 3.3: Format Parameter Values and Description Parameter Name docxformat iocaformat modcaformat pclformat pdfformat pptformat wordformat Description The format to convert Word 2007 documents to. Valid values should are TIFF_G4, JPEG, TIFF_LZW, PNG. The format to convert IOCA pages to. Valid values are TIFF_G4_FAX, JPEG, TIFF_LZW, PNG. The format to convert MO:DCA pages to. Valid values are TIFF_G4_FAX, JPEG, TIFF_LZW, PNG. The format to convert PCL pages to. Valid values are TIFF_G4_FAX, JPEG, TIFF_LZW, PNG. The format to convert PDF pages to. Valid values are TIFF_G4_FAX, JPEG, TIFF_LZW, PNG. The format to convert PPT pages to. Valid values are TIFF_G4_FAX, JPEG, TIFF_LZW, PNG The format to convert Word pages to. Valid values are 23

24 Chapter 3 - Configuring to Maximize Your Performance or Quality Parameter Name xlsformat Description TIFF_G4_FAX, JPEG, TIFF_LZW, PNG. The bit depth to use when decompressing XLS pages. Valid values are 1 or 24. The format to convert XLS pages to. Valid values are TIFF_G4_FAX, JPEG, TIFF_LZW, PNG. Memory Recommendation The amount of memory required to display a document may be significantly larger than the size of the document that is stored on disk. Just like a road map, the document is folded up and compressed when it is stored. In order to see the document, it must be unfolded (decompressed) and spread out so you can see the whole map. The map takes up much more room when open for viewing. The same is true of online documents. When a document is open, a black and white letter size page at 300 dpi takes roughly 1MB of memory to display and a color page takes 25MB. For maximum performance and to improve the speed of loading documents in VirtualViewer Java, we recommend generally 512 MB of memory for your application server but that also depends on the machine and network. If you experience memory related issues, we recommend that you steadily increase your maximum memory from 512 MB to at least two or three times that amount. If you still experience memory issues after increasing the maximum memory, please contact Snowbound Software Technical Support at Determining Memory Requirements The amount of memory required to view documents varies depending on the size of the documents you are processing and the number of documents you are processing at any one time. The amount of memory needed increases as: You go from black and white, to grayscale, to color documents (bits per pixel increases). You go from compressed to uncompressed document formats (lossy compression to raw image data). You go from low resolution to high resolution documents (dots per inch / quality increases). You go from small index card size images to large blueprint size images (number of pixels increases). Generally, higher quality documents require more memory to process. Snowbound Software does not have a one-size-fits-all recommendation for memory because our customers have such a variety of documents and different tolerances for the level of output quality. However, you can try doubling the memory available to see if that resolves the issue. Keep increasing 24

25 Chapter 3 - Configuring to Maximize Your Performance or Quality memory until you stop getting out of memory errors. If you hit a physical or financial limit on memory, then you can do the following: Decrease the number of documents you have open at any one time. Decrease the quality of the images requested by decreasing bits per pixel, the resolution, or the size. To calculate the amount of memory required for an image, you will need to know the size of the image in pixels and the number of bits per pixel in the image (black and white=1, grayscale=8, color=24). If you do not know the height or width in pixels, but you do know the size in inches and the dpi (dots per inch) of the image, then you can calculate the size in pixels as (width_in_ inches*dots_per_inch) = width_in_pixels. To calculate the amount of memory (in bytes), multiply the height, width and number of bits per pixel. Then, divide by 8 to convert from bits to bytes. See the following example: (height_in_pixels * width_in_pixels * bits_per_pixel)/ 8 = image_size_in_bytes Table 3.4: Memory Requirements Based on Image Size Image Size Required Memory 24-bit per pixel, 640 x 480 image 640 * 480 * (24 / 8) = bytes 1-bit per pixel, 8.5" x 11" image, at * 3300 * (1 / 8) = bytes dpi (2550 pixels by 3300 pixels) 24-bit per pixel, 8.5" x 11" image, at 300 dpi (2550 pixels by 3300 pixels) 2550 * 3300 * (24 / 8) = bytes (25 megabytes) Recommended Setting for the Parameters in the Web.xml File To improve performance and the speed of loading documents in VirtualViewer Java, try setting the values of the following parameters in the web.xml file as shown below. To edit any parameters in the web.xml file, right-click on the web.xml file to open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. Warning: Please make a backup copy of the web.xml file before you edit it. Example 3.1:Recommended Setting the Parameters in the Web.xml File <param-name>documentcachesize</param-name> <param-value> </param-value> <param-name>wordbitdepth</param-name> <param-value>1</param-value> <param-name>worddpi</param-name> 25

26 Chapter 3 - Configuring to Maximize Your Performance or Quality <param-value>100</param-value> <param-name>wordformat</param-name> <param-value>jpeg</param-value> <param-name>pdfbitdepth</param-name> <param-value>1</param-value> <param-name>pdfdpi</param-name> <param-value>100</param-value> <param-name>pdfformat</param-name> <param-value>jpeg</param-value> <param-name>xlsbitdepth</param-name> <param-value>1</param-value> <param-name>xlsdpi</param-name> <param-value>100</param-value> <param-name>xlsformat</param-name> <param-value>jpeg</param-value> Using the itext Library and Vector PDF Setting in the Web.xml File To improve performance and the speed of loading documents in VirtualViewer Java, try using the itext library for rendering PDFs on the client. For this to work properly, make sure that the itext.jar file is located in the library folder of the content server. Set the vectorpdf parameter in the web.xml file to true. By setting this to true, you can use the itext library for rendering PDFs on the client. This may speed up your server usage by minimizing the processing it has to do. To edit any parameters in the web.xml file, right-click on the web.xml file to open it in a text editor such as Notepad. The web.xml file is located in the WEB-INF directory. The table below shows the result for the settings for the server and/or client vectorpdf parameter: Table 3.5: Server and/or Client vectorpdf Parameter Server Client Result true true Client draws the PDF. true false Client renders the PDF. false either Server renders the PDF. Caching to Improve Performance The document cache keeps pages that VirtualViewer has displayed in server memory so that they do not have to be re-rendered the next time they are viewed. This enhances performance but consumes memory on the server. VirtualViewer lets you determine and configure this tradeoff between speed vs. memory consumption. 26

27 Chapter 3 - Configuring to Maximize Your Performance or Quality When caching is enabled, the VirtualViewer content server caches the entire document in memory. The HTML5 server caches the pages it receives from the content server. If the content server and HTML5 server are on the same machine (this is common), they will use the same cache. The caching configuration parameters mentioned below are in the RetrievalServlet portion of the content server s web.xml file. These are documented in Appendix A - Servlet Tags for web.xml. Do you need caching at all? If your users never view the same page twice, set the documentcachesize parameter to 0 to turn off document caching. Example 3.2: Turning Off Document Caching <init-param> <param-name>documentcachesize</param-name> <param-value>0</param-value> Sizing the Cache if You Need It If your users view the same pages frequently, calculate the number of these pages that should be cached away for faster viewing. This will be numberofpagestocache. Next determine how much memory will be used to cache each page, sizeofpageinbytes. To calculate the sizeofpageinbytes value you will need to know: Your page size in inches Are the pages black & white or color? Black & white uses 1-bit per pixel (bpp). Color uses 24-bpp. The desired resolution in dots per inch (DPI). 100 DPI is fine if the document will not be zoomed or printed. A higher DPI may be required if users are zooming in to look at details. The size can be calculated using the following formula: (height_in_pixels * width_in_pixels * bits_per_pixel) / (8 bits per byte) = image_size_in_bytes The value is in bytes and describes the uncompressed size of the page, so it may look rather large. For more information see Memory Recommendation. Here are some examples: 27

28 Chapter 3 - Configuring to Maximize Your Performance or Quality One black and white 8.5x11 inch page at 100 DPI = (8.5 inches* 300 dpi * 11 inches * 300 dpi) * (1 bit per pixel / 8 bits per byte) = bytes or 0.1MB per page for sizeofpageinbytes. One black and white 8.5x11 inch page at 300 DPI = (8.5 inches* 300 dpi * 11 inches * 300 dpi) * (1 bit per pixel / 8 bits per byte) = bytes or roughly 1 MB per page. One color 8.5x11 inch page at 300dpi is or roughly 25MB per page. Now, multiply numberofpagestocache x sizeofpageinbytes. Set the documentcachesize to the calculated cache size to turn on document caching. If this number is larger than the memory you have available on the system, you can adjust things like the document bit depth, resolution, or number of pages cached. For example a cache size of (1GB) will hold 40 full 24-bit color pages at 300 DPI or 1,000 black and white pages at 300 DPI or 9,187 black and white pages at 100 DPI Please see Adjusting Color vs. Black and White - Setting the Bit Depth and Reducing the Resolution - Setting the DPI for more information on how to adjust viewing bit depth and resolution. Defining the Number of Pages Cached in Memory You can improve performance on the server by allowing VirtualViewer Java to retain pages in the cache. The fewer requests VirtualViewer Java makes to the server the better performance you will see on that server. However, this may impact performance on the client JRE as VirtualViewer Java is now building memory. It is important to find a balance between the two by performance tuning the cache size during testing. The maxcachepages parameter will define the number of pages VirtualViewer Java will cache in memory so that it does not always request a page from the server that has already been viewed. The default value is 6. Example 3.3: Defining the Number of Pages Cached in Memory <init-param> <param-name>maxcachepages</param-name> <param-value>6</param-value> </init-param> Cache Maintenance If your users modify and save the documents being viewed, set the clearcacheonsave parameter to true (the default) so that older versions of the page are not displayed. 28

29 Chapter 3 - Configuring to Maximize Your Performance or Quality Example 3.4: Clearing Cache on Save <init-param> <param-name>clearcacheonsave</param-name> <param-value>true</param-value> </init-param> The cache is primarily maintained by your application server. The disk cache will be cleared of all temp files at VirtualViewer startup. If you start seeing Out of Memory (-1) errors, then you may need to resize your cache as described in the previous section. Caching and Security Snowbound Software has no mechanism to selectively remove cached content. However, a Cache Validation interface is provided so you can customize when cached content is permitted to be retrieved. You can implement the validatecache method to use your authentication system to validate that the current user is authorized to access the cached page content. See the CacheValidator section in Connecting to Your Document Store in Chapter 4 - Using Advanced Features. Please see the next topic Chapter 4, Connecting to Your Document Store. 29

30 Chapter 4 - Connecting to Your Document Store Chapter 4 - Connecting to Your Document Store The chapter contains the following topics: What is the Content Handler? FlexSnapSIContentHandlerInterface CacheValidator Extracting Parameters from ContentHandlerInput Populating Parameters for ContentHandlerInput Populating Parameters for ContentHandlerResult Content Handler Methods What is the Content Handler? The VirtualViewer Content Handler is a Java class that the serlvet will call on to perform various actions concerning the retrieval and storage of content. By default, the VirtualViewer servlet uses the FileContentHandler as its content handler to read and write to a file system. However, a different, custom class may be implemented in order to integrate VirtualViewer Java into a myriad of back-end systems. Warning: VirtualViewer Java includes a sample content handler that connects to the server's File System. This code sample is provided as a starting point to integrate VirtualViewer Java with your document storage. The content handler sample is not production quality. You should add error checking and permissions checking at the very least before releasing this into production. How the Content Handler Works Whenever the applet requests a document, the servlet will first check the cache to see if the document is present. If it is not, it then calls into the content handler for the document. The order of action is as follows: getdocumentcontent getannotationnames getannotationcontent (once for each layer name returned by getannotationnames) getbookmarkcontent 30

31 Chapter 4 - Connecting to Your Document Store Whenever the user chooses to save the document by choosing Save Document, the applet passes the appropriate data to the servlet, which calls the content handler method savedocumentcomponents. The saved file name will be the name of your document with the extension of the exported file type. For example, if you save the file image.jpg as a tiff file, the saved file is named image.tif. If you save annotations separately, the saved annotations file is named image.ann. Inside savedocumentcomponents, the following methods should be called separately when the appropriate data has changed: savedocumentcontent saveannotationcontent savebookmarkcontent Other methods within the content handler are called by various functions in the applet. Defining a Custom Content Handler The document Content Handler/Connector that VirtualViewer will use is set using the contenthandlerclass parameter in the application's web.xml file. Many customers create a custom content handler class that integrates with their document management and security systems. Please see the following example for specifying a custom content handler: Example 4.1: Setting Up the contenthandlerclass Parameter <init-param> <param-name>contenthandlerclass</param-name> <param-value>com.snowbound.flexsnap.custom.mycontenthandler </param-value> </init-param> <param-name>contenthandlerclass</param-name> <param-value>com.mycompany.viewer.documentconnector</param-value> VirtualViewer would then look for and invoke your custom content handler at./web-inf/classes/com/mycompany/viewer/documentconnector.class Snowbound provides two connectors with the VirtualViewer base product; the default File Connector and the URL Connector. Snowbound also provides full featured ICN, FileNet P8 and Documentum connectors as VirtualViewer options. To use the default File Connector specify: Example 4.2: Using the Default File Connector <param-name>contenthandlerclass</param-name> <param-value>com.snowbound.snapserv.servlet.filecontenthandler</paramvalue> <param name="filepath" value="c:/mydocuments"/> // folder on the server 31

32 Chapter 4 - Connecting to Your Document Store <param name='startfile' value='mylogo.gif'> // will display C:/MyDocuments/myLogo.gif in the client at start up To use the default URL Connector specify: Example 4.3: Using the Default URL Connector <param-name>contenthandlerclass</param-name> <param-value>com.snowbound.snapserv.servlet.fileandurlretriever</paramvalue> <param-name>baseurl</param-name> <param-value> <param name='startfile' value='mylogo.gif'> // will display in the client at start up The source code for the default file content handler is provided as a starting point for your own custom connector. The code is located in the VirtualViewer.war file under \Sample Code\Java Content Handler\SampleContentHandler.java. Authentication When customizing the VirtualViewer content handler to connect to your document storage, you may need to request or store authentication tokens as part of the process. You can store the tokens in the session object within the content handler. Use the HttpServletRequest session object in the content handler to achieve this. The user can get a handle to HttpServletRequest session object in the content handler by using this line of code: Example 4.4: Getting a Handle to HttpServletRequest Session Object in the Content Handler HttpServletRequest request = (HttpServletRequest) input.get (ContentHandlerInput.KEY_HTTP_SERVLET_REQUEST); The user can then get or set session attributes: Example 4.5:Getting or Setting Session Attributes request.getsession().getattribute(arg0); request.getsession().setattribute(arg0, arg1) 32