public interface VirtualViewerContentHandlerInterface
Modifier and Type | Field and Description |
---|---|
static Integer |
PERM_CREATE
Deprecated.
|
static Integer |
PERM_DELETE
Deprecated.
|
static Integer |
PERM_EDIT
Deprecated.
|
static Integer |
PERM_HIDDEN
Deprecated.
|
static Integer |
PERM_PRINT
Deprecated.
|
static Integer |
PERM_PRINT_WATERMARK
Deprecated.
|
static Integer |
PERM_REDACTION
Deprecated.
|
static Integer |
PERM_VIEW
Deprecated.
|
static Integer |
PERM_VIEW_WATERMARK
Deprecated.
|
Modifier and Type | Method and Description |
---|---|
ContentHandlerResult |
getDocumentContent(ContentHandlerInput input)
Returns the content for the specified document key.
|
void |
init(javax.servlet.ServletConfig config)
Used to set up each content handler instance before any methods are called.
|
ContentHandlerResult |
saveDocumentComponents(ContentHandlerInput input)
This method is used to save or update an existing document and sub-components of the document, such as annotations,
bookmarks, document notes and watermarks.
|
ContentHandlerResult |
saveDocumentComponentsAs(ContentHandlerInput input)
This method is used to save a copy of a document under a new key, along with sub-components of the document, such
as annotations, bookmarks, document notes and watermarks.
|
ContentHandlerResult |
saveDocumentContent(ContentHandlerInput input)
This method is used to update document data only.
|
@Deprecated static final Integer PERM_HIDDEN
@Deprecated static final Integer PERM_REDACTION
@Deprecated static final Integer PERM_PRINT_WATERMARK
@Deprecated static final Integer PERM_VIEW_WATERMARK
@Deprecated static final Integer PERM_VIEW
@Deprecated static final Integer PERM_PRINT
@Deprecated static final Integer PERM_CREATE
@Deprecated static final Integer PERM_EDIT
@Deprecated static final Integer PERM_DELETE
void init(javax.servlet.ServletConfig config) throws VirtualViewerAPIException
config
- The ServletConfig object for the VirtualViewer server. Can be used to retrieve web.xml parameters.VirtualViewerAPIException
- if content handler throws exceptionContentHandlerResult getDocumentContent(ContentHandlerInput input) throws VirtualViewerAPIException
Returns the content for the specified document key. The content is usually returned as a byte array, but it can also be a stream or a File object; it can also be a list of byte arrays, streams, or File objects to represent a document made of multiple parts. (VirtualViewer refers to these parts as "content elements").
VirtualViewer is entirely agnostic about the source of document content. It can come from the local file system, a remote system, a database or any other source as long as your content handler can provide data to VirtualViewer in any of its supported forms.
Another note is that the content handler does not need to be consistent between documents. Any individual document should be returned in the same form each request, but different documents do not need to use the same form. The same content handler can return one document as a byte array, a second as a stream, a third as several components and yet another in sparse form.
This is the most common use case - a single file represents a single document. This file can be returned as a byte array, input stream or File object - although the first two forms are recommended.
// This example retrieves the document content from a specific directory in the local filesystem.
public ContentHandlerResult getDocumentContent(ContentHandlerInput input)
throws VirtualViewerAPIException
{
String clientInstanceId = input.getClientInstanceId();
String documentKey = input.getDocumentId();
String fullFilePath = gFilePath + URLDecoder.decode(documentKey);
File file = new File(fullFilePath);
byte[] fileBytes = com.snowbound.common.utils.ClientServerIO.getFileBytes(file);
ContentHandlerResult result = new ContentHandlerResult();
result.put(ContentHandlerResult.KEY_DOCUMENT_CONTENT, fileBytes);
return result;
}
Using compound documents, you can make a single VirtualViewer document composed of multiple files of different formats. For example, if you provide a PDF and an image file in that order, VirtualViewer will treat it as one document with the image file as the last page.
Document modifications, such as rotating or inserting/deleting pages, cannot be done to a compound document without converting it to a single-file document (either a PDF or a TIF, depending on if the first content element was a text or image file).
To return a compound document, return several content elements in the KEY_DOCUMENT_CONTENT_ELEMENTS parameter. These can be either a byte array, input stream or File and the items in the list do not have to all match. If only one content element is returned it will functionally be the same as a single-content element document described above.
// This example retrieves document content from the local file system and adds the same cover page to every
// requested document by returning them as a compound document.
public ContentHandlerResult getDocumentContent(ContentHandlerInput input)
throws VirtualViewerAPIException
{
String clientInstanceId = input.getClientInstanceId();
String documentKey = input.getDocumentId();
List<Object> contentElements = new List<Object>();
//Adding the cover page first will make it the first page(s) of the document
InputStream coverPage = getCoverPageStream();
contentElements.put(coverPage);
//Add the file content from the local system next
String fullFilePath = gFilePath + URLDecoder.decode(documentKey);
File file = new File(fullFilePath);
byte[] fileBytes = com.snowbound.common.utils.ClientServerIO.getFileBytes(file);
contentElements.put(fileBytes);
ContentHandlerResult result = new ContentHandlerResult();
result.put(ContentHandlerResult.KEY_DOCUMENT_CONTENT_ELEMENTS, contentElements);
return result;
}
Sparse documents are a special case of compound document. In this case, every content element represents a single page, and each page/content element can be requested and returned in separate chunks as needed. The ideal use case for sparse documents is when a) the document is already split up into single-page files and b) retrieving each page is relatively time-expensive, making retrieving the whole document prohibitive. An example use case could be if a physical document was scanned and converted to a series of large image files, one for each page, and those files were stored on a remote server with a poor connection. Retrieving all of those image files at once may be prohibitive; the document could be represented in sparse form to avoid that cost.
To implement sparse documents you will need to read the KEY_SPARSE_PAGE_INDEX value from input and return at least that page. The index is zero-based. Several additional pages around that page can also be returned - VirtualViewer will cache each page as it retrieves it, so returning additional pages will help limit future requests from VirtualViewer. VirtualViewer suggests an amount of pages to return with KEY_SPARSE_PAGE_COUNT but the suggestion is not required.
Note: if KEY_SPARSE_PAGE_INDEX's value is null then all sparse page elements must be returned. This is for operations that require the entire document, such as emailing or printing. All page elements should be returned in the same way as a partial sparse document: using KEY_DOCUMENT_SPARSE_ELEMENTS.
When returning a sparse document, four values should be returned: the list of sparse content elements, the zero-based page index the returned pages start at, the number of pages being returned, and the total number of pages in the document.
Note: sparse document content elements do not support the File object. Each content element should be a byte array or input stream.
// This example assumes the existence of a function that returns a single page of the document. To fit the best
// use case of sparse documents, this function should be relatively expensive, so calling it for each page of
// the document is not ideal.
public ContentHandlerResult getDocumentContent(ContentHandlerInput input)
throws VirtualViewerAPIException
{
String clientInstanceId = input.getClientInstanceId();
String documentKey = input.getDocumentId();
Integer requestedPageIndex = input.get(ContentHandlerInput.KEY_SPARSE_PAGE_INDEX);
List<byte[]> sparseElements = new List<byte[]>();
int documentPageCount = getDocumentPageCount(documentKey);
int startPageIndex = 0;
int returnPageCount = documentPageCount;
//If KEY_SPARSE_PAGE_INDEX is null, all pages should be returned. If it is set then we will return the requested
//page and the two next pages.
if(requestedPageIndex != null) {
startPageIndex = requestedPageIndex;
returnPageCount = 3;
//Make sure not to request more pages than the document has
if(startPageIndex + returnPageCount > documentPageCount) {
returnPageCount = documentPageCount - startPageIndex;
}
}
for(int index = startPageIndex; index < startPageIndex + returnPageCount; index++) {
byte[] documentPage = getSingleDocumentPage(documentKey, index);
sparseElements.put(documentPage);
}
ContentHandlerResult result = new ContentHandlerResult();
result.put(ContentHandlerResult.KEY_DOCUMENT_SPARSE_ELEMENTs, sparseElements);
result.put(ContentHandlerResult.KEY_DOCUMENT_SPARSE_PAGE_INDEX, startPageIndex);
result.put(ContentHandlerResult.KEY_DOCUMENT_SPARSE_RETURN_PAGE_COUNT, returnPageCount);
// For this example we are assuming each document is exactly 10 pages long.
// In actual code the real length should be returned.
result.put(ContentHandlerResult.KEY_DOCUMENT_SPARSE_TOTAL_PAGE_COUNT, 10);
return result;
}
VirtualViewer supports external references for CAD/DWG files. The external reference files must be returned as a
list of ExternalReference
objects.
Note: This feature is currently only supported when running the VirtualViewer server on Windows.
input
- ContentHandlerInput containing the following values:
Key | Type | Description |
---|---|---|
KEY_DOCUMENT_ID | java.lang.String | The key representing the document. Can be retrieved with String documentId = input.getDocumentId(); . |
KEY_CLIENT_INSTANCE_ID | java.lang.String | Custom configurable value used to pass data from client to content handler. If not set then will be
the session ID. Can be retrieved with String clientInstanceId = input.getClientInstanceId(); |
KEY_HTTP_SERVLET_REQUEST | javax.servlet.http.HttpServletRequest | Request that called this method. Can be retrieved with HttpServletRequest request = input.getHttpServletRequest(); |
KEY_SPARSE_PAGE_INDEX | Integer | The specific page index being requested. This parameter is used only for sparse documents. If
this parameter is null, the entire document should be returned, even for sparse documents. (For
sparse documents this should be in the form of a complete KEY_DOCUMENT_SPARSE_ELEMENTS list).
Can be retrieved with int pageIndex = input.getSparseRequestedPageNumber();
|
KEY_SPARSE_PAGE_COUNT | int | Suggested number of pages to return for a sparse document. This does not have to be respected.
Can be retrieved with int pageCount = input.getSparseRequestedPageCount();
|
Key | Type | Description |
---|---|---|
KEY_DOCUMENT_DISPLAY_NAME | String | The name VirtualViewer should display for this document. If omitted VirtualViewer will display the document key instead. |
KEY_DOCUMENT_CONTENT | byte[] | A byte array of the document content. Only one document content return parameter should be set. |
KEY_DOCUMENT_INPUT_STREAM | java.io.InputStream | An input stream of the document content. Only one document content return parameter should be set. |
KEY_DOCUMENT_FILE | java.io.File | A File object referencing the document content file. Using KEY_DOCUMENT_CONTENT or KEY_INPUT_STREAM is recommended for efficiency. Only one document content return parameter should be set. |
KEY_DOCUMENT_CONTENT_ELEMENTS | java.util.List | A list of content elements - byte arrays, input streams or File objects. They do not have to be in the same form, nor do the original files need to be the same image or document format (a content element list consisting of a JPEG byte array and a PDF input stream is acceptable). VirtualViewer will treat all of the content elements as if they formed one contiguous document. If a list containing only one content element is returned, it will behave exactly as the single-content element cases above. Only one document content return parameter should be set. |
KEY_DOCUMENT_SPARSE_ELEMENTS | java.util.List | A parameter required for sparse documents. A list of single-page content elements - byte arrays or input streams only. File objects are not supported. If one of the content elements is of a format that supports multiple pages, such as PDF, it must be one page. Any pages beyond the first will be ignored by VirtualViewer. Only one document content return parameter should be set. |
KEY_DOCUMENT_SPARSE_PAGE_INDEX | java.util.List | A parameter required for sparse documents. The zero-based page index at which the collection of returned pages start. For example, if page index 5 is requested and you are returning pages 5-8, this should equal 5. |
KEY_DOCUMENT_SPARSE_RETURN_PAGE_COUNT | java.util.List | A parameter required for sparse documents. The number of pages you are returning with this method. For example, if page index 5 is requested and you are returning pages 5-8, this should return 4. |
KEY_DOCUMENT_SPARSE_TOTAL_PAGE_COUNT | java.util.List | A parameter required for sparse documents. The total number of pages in the sparse document. This should be the same in each request for a given document. For example, when a 300-page-long document is requested, this should be 300 - regardless of how many pages are being returned for the request. |
KEY_EXTERNAL_REFERENCE_CONTENT_ELEMENTS | java.util.List<ExternalReference > |
A list of external references for CAD/DWG files. |
VirtualViewerAPIException
- if content handler throws exceptionContentHandlerResult saveDocumentContent(ContentHandlerInput input) throws VirtualViewerAPIException
input
- ContentHandlerInput containing the following values:
Key | Type | Description |
---|---|---|
KEY_DOCUMENT_CONTENT | byte[] | The document file content. Can be retrieved with byte[] documentContent= input.getDocumentContent(); . |
KEY_DOCUMENT_ID | java.lang.String | The key representing the document. Can be retrieved with String documentId = input.getDocumentId(); . |
KEY_CLIENT_INSTANCE_ID | java.lang.String | Custom configurable value used to pass data from client to content handler. If not set then will be
the session ID. Can be retrieved with String clientInstanceId = input.getClientInstanceId(); |
KEY_HTTP_SERVLET_REQUEST | javax.servlet.http.HttpServletRequest | Request that called this method. Can be retrieved with HttpServletRequest request = input.getHttpServletRequest(); |
Key | Type | Description |
---|---|---|
DOCUMENT_ID_TO_RELOAD | String | Optional return used to alert the client that the document key has been changed when saving. This could be used if the content handler decided to create a new document under a new key instead of updating the original document. |
VirtualViewerAPIException
- if content handler throws exceptionContentHandlerResult saveDocumentComponents(ContentHandlerInput input) throws VirtualViewerAPIException
input
- ContentHandlerInput containing the following values:
Key | Type | Description |
---|---|---|
KEY_DOCUMENT_CONTENT | byte[] |
The document file content. If null no changes need to be saved to the document.
Can be retrieved with byte[] documentContent= input.getDocumentContent(); .
|
KEY_ANNOTATION_LAYERS | com.snowbound.common.transport.AnnotationLayer[] |
All of the annotation layers for the document. Each layer should be updated if it layer.isNew() or
isModified() is true, and if a layer has been saved but is no longer present in the array it should be deleted.
Can be retrieved with AnnotationLayer[] annotationLayers= input.getAnnotationLayers(); .
|
KEY_BOOKMARK_CONTENT | byte[] |
The bookmark file content. If null no changes need to be saved to the bookmark file.
Can be retrieved with byte[] bookmarkContent= input.getBookmarkContent(); .
|
KEY_NOTES_CONTENT | byte[] |
The notes file content. If null no changes need to be saved to the notes file.
Can be retrieved with byte[] notesContent = input.getNotesContent(); .
|
KEY_WATERMARK_CONTENT | byte[] |
The watermark file content. If null no changes need to be saved to the watermark file.
Can be retrieved with byte[] watermarkContent = input.getWatermarkContent(); .
|
KEY_PAGE_COUNT | int | The number of pages in the document. Can be retrieved with int pageCount = input.getDocumentPageCount(); . |
KEY_DOCUMENT_FORMAT | int |
An integer code representing the document format. Can be retrieved along with a format information object with the following code:
|
KEY_DOCUMENT_ID | java.lang.String | The key representing the document. Can be retrieved with String documentId = input.getDocumentId(); . |
KEY_CLIENT_INSTANCE_ID | java.lang.String | Custom configurable value used to pass data from client to content handler. If not set then will be
the session ID. Can be retrieved with String clientInstanceId = input.getClientInstanceId(); |
KEY_HTTP_SERVLET_REQUEST | javax.servlet.http.HttpServletRequest | Request that called this method. Can be retrieved with HttpServletRequest request = input.getHttpServletRequest(); |
Key | Type | Description |
---|---|---|
DOCUMENT_ID_TO_RELOAD | String | Optional return used to alert the client that the document key has been changed when saving. This could be used if the content handler decided to create a new document under a new key instead of updating the original document. |
VirtualViewerAPIException
- if content handler throws exceptionContentHandlerResult saveDocumentComponentsAs(ContentHandlerInput input) throws VirtualViewerAPIException
input
- ContentHandlerInput containing the following values:
Key | Type | Description |
---|---|---|
KEY_DOCUMENT_CONTENT | byte[] |
The document file content. If null no changes need to be saved to the document.
Can be retrieved with byte[] documentContent= input.getDocumentContent(); .
|
KEY_ANNOTATION_LAYERS | com.snowbound.common.transport.AnnotationLayer[] |
All of the annotation layers for the document. If not null all layers should be saved for the
new document.
Can be retrieved with AnnotationLayer[] annotationLayers= input.getAnnotationLayers(); .
|
KEY_BOOKMARK_CONTENT | byte[] |
The bookmark file content. If null no bookmark file need be saved.
Can be retrieved with byte[] bookmarkContent= input.getBookmarkContent(); .
|
KEY_NOTES_CONTENT | byte[] |
The notes file content. If null no notes file need be saved.
Can be retrieved with byte[] notesContent = input.getNotesContent(); .
|
KEY_WATERMARK_CONTENT | byte[] |
The watermark file content. If null no watermark file need be saved.
Can be retrieved with byte[] watermarkContent = input.getWatermarkContent(); .
|
KEY_PAGE_COUNT | int | The number of pages in the document. Can be retrieved with int pageCount = input.getDocumentPageCount(); . |
KEY_DOCUMENT_FORMAT | int |
An integer code representing the document format. Can be retrieved along with a format information object with the following code:
|
KEY_DOCUMENT_ID | java.lang.String | A temporary key based on the original document's display name. Can be retrieved with String documentId = input.getDocumentId(); . |
KEY_CLIENT_INSTANCE_ID | java.lang.String | Custom configurable value used to pass data from client to content handler. If not set then will be
the session ID. Can be retrieved with String clientInstanceId = input.getClientInstanceId(); |
KEY_HTTP_SERVLET_REQUEST | javax.servlet.http.HttpServletRequest | Request that called this method. Can be retrieved with HttpServletRequest request = input.getHttpServletRequest(); |
Key | Type | Description |
---|---|---|
DOCUMENT_ID_TO_RELOAD | String | Optional return used to alert the client that the document key has been changed when saving. VirtualViewer will send a temporary document key in the input based on the original document's display name, but if that is being changed then this return value should be set. |
VirtualViewerAPIException
- if content handler throws exceptionCopyright © 2020 Snowbound Software Corporation. All rights reserved.