The VirtualViewer HTML5 for Java client sends event notifications to VirtualViewer’s content handler on the server whenever the user does something that triggers an audited event. Event triggers include opening a document or going to another page in the document.

Event triggers include opening a document or going to another page in the document.

public ContentHandlerResult eventNotification (ContentHandlerInput input)
throws
VirtualViewerAPIException

Implement this content handler method to receive event notifications.

<param name="enableEventNotifications" value="true">

The following auditing events trigger event notification:

  • Page request
  • Save annotation
  • Save document
  • Print
  • Export
  • Document close

The sample file content handler logs these events to the web server’s log. For example, these events might appear in a TomCat web server log:

[exec] 04-30-2012 16:00:13 FileCoNtentHandler.eventNotification
[exec] 04-30-2012 16:00:13 Key: KEY_EVENT_PAGE_
REQUESTED_NUMBER, value: 0
[exec] 04-30-2012 16:00:13 Key: KEY_DOCUMENT_ID,
value: 6-Pages.tif
[exec] 04-30-2012 16:00:13 Key: cacheBuster, value:
0.7112829455936928
[exec] 04-30-2012 16:00:13 Key: KEY_EVENT, value:
VALUE_EVENT_PAGE_REQUESTED
[exec] 04-30-2012 16:00:13 FileCon-
tentHandler.eventNotification
[exec] 04-30-2012 16:00:13 Key: KEY_EVENT_PAGE_
REQUESTED_NUMBER, value: 0
[exec] 04-30-2012 16:00:13 Key: KEY_DOCUMENT_ID,
value: 6-Pages.tif
[exec] 04-30-2012 16:00:13 Key: cacheBuster, value:
0.1953655708607337
[exec] 04-30-2012 16:00:13 Key: KEY_EVENT, value: VALUE_EVENT_PAGE_REQUESTED

The server loglevel must be set to Info in order to see the event notifications. The logLevel must be set to Finest to see all the Key event details in the log file.

You can change the information being logged and the required loglevel by modifying the eventNotification method in the sample FileContentHandler.

The eventNotification method in the content handler can be customized to meet your needs. For example, you could add code to send a message to an audit logging system for certain events or change the log messages to match your company’s standard format.

PARAMETERS

The ContentHandlerInput hash table will contain a variety of elements depending on the type of event being logged. All values are strings:

Key Type Description
KEY_EVENT String One of the VALUE_EVENT_* values
VALUE_EVENT_PAGE_REQUESTED String The event being logged is a page request.
KEY_EVENT_PAGE_REQUESTED_NUMBER String The page number requested (zero-based)
KEY_DOCUMENT_DISPLAY_NAME String Getting document content as a byte array from a file and adding to ContentHandlerResult.KEY_DOCUMENT_CONTENT
VALUE_EVENT_SAVE_ANNOTATION String The event being logged is a save annotation request.
VALUE_EVENT_SAVE_ANNOTATION_LAYER_NAME_BASE String The base name of the keys containing the layer names. There will be one of these for each layer. For example: "KEY_EVENT_SAVE_ANNOTATION_LAYER_NAME_BASE0"
VALUE_EVENT_PRINT String The event being logged is a print request.
KEY_EVENT_PRINT_PAGE_NUMBERS String The page range being printed in the format ‘0-4’.
VALUE_EVENT_EXPORT String The event being logged is a document export request.
KEY_ANNOTATION_ID String The name of the annotation layer.

Key/Value pairs passed on page request

Key = ContentHandlerResult.KEY_EVENT
Value = ContentHandlerResult.VALUE_EVENT_PAGE_REQUESTED

Key = ContentHandlerResult.KEY_DOCUMENT_ID
Value = <documentId>

Key = ContentHandlerResult.KEY_CLIENT_INSTANCE_ID
Value = <clientInstanceId>

Key = ContentHandlerResult.KEY_EVENT_PAGE_REQUESTED
Value = <page number>

Key/Value pairs passed on annotation save

Key = ContentHandlerResult.KEY_EVENT
Value = ContentHandlerResult.VALUE_EVENT_SAVE_ANNOTATION

Key = ContentHandlerResult.KEY_DOCUMENT_ID
Value = <documentId>

Key = ContentHandlerResult.KEY_CLIENT_INSTANCE_ID
Value = <clientInstanceId>

Key/Value pairs passed on print

Key = ContentHandlerResult.KEY_EVENT
Value = ContentHandlerResult.VALUE_EVENT_PRINT

Key = ContentHandlerResult.KEY_DOCUMENT_ID
Value = <documentId>

Key = ContentHandlerResult.KEY_CLIENT_INSTANCE_ID
Value = <clientInstanceId>

Key = ContentHandlerResult.KEY_EVENT_PAGE_REQUESTED
Value = <page number>

Key/Value pairs passed on export

Key = ContentHandlerResult.KEY_EVENT
Value = ContentHandlerResult.VALUE_EVENT_EXPORT

Key = ContentHandlerResult.KEY_DOCUMENT_ID
Value = <documentId>

Key = ContentHandlerResult.KEY_CLIENT_INSTANCE_ID
Value = <clientInstanceId>

Key = ContentHandlerResult.KEY_EVENT_EXPORT_FORMAT_NAME
Value = <format>

Key/Value pairs passed on document close

Key = ContentHandlerResult.KEY_EVENT
Value = ContentHandlerResult.VALUE_EVENT_CLOSE_ DOCUMENT

Key = ContentHandlerResult.KEY_DOCUMENT_ID
Value = <documentId>

Key = ContentHandlerResult.KEY_CLIENT_INSTANCE_ID
Value = <clientInstanceId>

Key/Value pairs passed when retrieved from the internal cache

Key = ContentHandlerResult.KEY_EVENT
Value = ContentHandlerResult.VALUE_EVENT_DOCUMENT_RETRIEVED_FROM_CACHE

Key = ContentHandlerResult.KEY_DOCUMENT_ID<br />Value = <documentId>

Key = ContentHandlerResult.KEY_CLIENT_INSTANCE_ID
Value = <clientInstanceId>

Use the following sample eventNotification method in a custom content handler to make use of the new event for cache retrieval:

public ContentHandlerResult eventNotification
(ContentHandlerInput input)
throws
VirtualViewerAPIException
String eventType = (String) input.get("KEY_EVENT");
if (eventType.equals("VALUE_EVENT_DOCUMENT_RETRIEVED_FROM_CACHE")) {
String documentId = input.getDocumentId(); System.out.println("Document retrieved from cache: " + documentId); // do getDocumentContent related tasks here because getDocumentContent will not be called
}
return ContentHandlerResult.VOID;

RETURNS

A ContentHandlerResult object or null. The return value is currently ignored.

Event notification rotate page

Use the following example to capture the page rotation event as part of the Event Notification feature set.

var pageEvent = function() {
  if(vvConfig.enableEventNotification === false) {
  return;
}
var uri = new URI(vvConfig.servletPath);
uri.addQuery("action", "eventNotification"); uri.addQuery("KEY_EVENT", "VALUE_EVENT_PAGE_REQUESTED");
uri.addQuery("KEY_DOCUMENT_ID", virtualViewer.getDocumentId());
uri.addQuery("clientInstanceId", virtualViewer.getClientInstanceId());
uri.addQuery("KEY_EVENT_PAGE_REQUESTED_NUMBER", pageNumber);

Extracting Parameters from ContentHandlerInput

The interface for extracting result parameters from a ContentHandlerResult can be found in the Content Handler API documentation.