Enterprise Information Portal APIs

com.ibm.mm.viewer
Class CMBDocumentEngine

java.lang.Object
  |
  +--com.ibm.mm.viewer.CMBDocumentEngine
All Implemented Interfaces:
CMBViewerConstants
Direct Known Subclasses:
CMBCMDocumentEngine, CMBCMDocumentEngineEx, CMBJavaDocumentEngine, CMBODDocumentEngine

public abstract class CMBDocumentEngine
extends java.lang.Object
implements CMBViewerConstants

CMBDocumentEngine is an abstract class that defines the interface any document engine implementation should extend. Document engines plug into CMBDocumentServices and provide rendering and translation support for different document types.

The methods are divided into the following categories:

  1. General methods. These are: initialize, terminate, isInitialized, canLoadDocument, loadDocument, canWriteDocument, writeDocument.
  2. Methods for paged documents. These are: canPaginate, getNumberOfPages, loadPage, dropPage, getPageWidth, getPageHeight, canWritePage, writePage, canWriteDocumentFromPages, writeDocumentFromPages, canProvidePageImage, getPageImage.
All document engine implementations must implement the general methods. The other methods are optional and only need to be implemented if documents of those types are supported.

Note: An abstract class was used rather than an interface in order to extend this interface in the future without requiring currently written document engines to be modified.

Since:
7.1

Fields inherited from interface com.ibm.mm.viewer.CMBViewerConstants
DEFAULT_PAGE_NUMBER, ROTATE_0, ROTATE_180, ROTATE_270, ROTATE_90
 
Constructor Summary
CMBDocumentEngine()
           
 
Method Summary
 boolean canEnhance(java.lang.Object hDocument, java.lang.String destMimeType)
          Returns true if the document pages can be enhanced when written in the specified format.
 boolean canInvert(java.lang.Object hDocument, java.lang.String destMimeType)
          Returns true if the document page colors can be inverted when written in the specified format.
 boolean canLoadDocument(java.lang.String mimeType)
          Returns true if the specified document type is handled by the engine.
 boolean canPaginate(java.lang.String mimeType)
          Returns true if the engine can convert documents of the specified MIME content type as pages.
 boolean canProvidePageImage(java.lang.String mimeType)
          Returns true if the engine can provide images of pages.
 boolean canRotate(java.lang.Object hDocument, java.lang.String destMimeType)
          Returns true if the document pages can be rotated when written in the specified format.
 boolean canShowAnnotations(java.lang.Object hDocument, java.lang.String destMimeType)
          Returns true if the document pages can be shown with annotations when written in the specified format.
 boolean canWriteDocument(java.lang.String sourceMimeType, java.lang.String destMimeType)
          Returns true if the specified document type can be written by the engine using the writeDocument method in the specified format.
 boolean canWriteDocumentFromPages(java.lang.String sourceMimeType, java.lang.String destMimeType)
          Returns true if a series of pages from the document can be written by the engine using the writePages method in the specified format.
 boolean canWritePage(java.lang.Object hPage, java.lang.String destMimeType)
          Returns true if a page of the document can be written by the engine using the writePage method in the specified format.
 boolean canWritePage(java.lang.String sourceMimeType, java.lang.String destMimeType)
          Returns true if a page of the document can be written by the engine using the writePage method in the specified format.
 void dropDocument(java.lang.Object hDocument)
          Terminates processing of a document by the document engine.
 void dropPage(java.lang.Object hPage)
          Terminates processing of a page.
 int getImageResolution(java.lang.Object hDocument)
          Returns the image resolution of the document in pixels per inch (ppi).
 int getNumberOfPages(java.lang.Object hDocument)
          Returns the number of pages in the document.
 double getPageHeight(java.lang.Object hPage)
          Returns the height of the page, in inches.
 java.awt.Image getPageImage(java.lang.Object hPage, int rotation, double scale, boolean enhance, boolean invert, boolean withAnnotations)
          Returns an image of the page.
 double getPageMaxScale(java.lang.Object hPage, java.lang.String destMimeType)
          Returns the maximum scale of document pages when written in the specified format.
 java.lang.String getPageMimeType(java.lang.Object hPage, java.lang.String[] preferredMimeTypes)
          Returns the engine's desired page format for writing the page.
 double getPageMinScale(java.lang.Object hPage, java.lang.String destMimeType)
          Returns the minimum scale of document pages when written in the specified format.
 java.lang.String getPageResourceMimeType(java.lang.Object hPage, java.lang.String resourceId)
          Returns the MIME content type for a linked resource of a written page.
 double getPageWidth(java.lang.Object hPage)
          Returns the width of the page, in inches.
abstract  void initialize(CMBDocumentEngineCallbacks callbacks, java.util.Properties properties)
          Initializes the document engine.
abstract  boolean isInitialized()
          Returns true if the initialize method has been called and the engine initialized successfully.
 java.lang.Object loadDocument(java.io.InputStream partStream, int partStreamSize, int numberOfParts, java.lang.String mimeType, java.io.InputStream annotationStream, java.io.InputStream resourceStream)
          Deprecated. Use loadDocument(InputStream, int, int, String, String, InputStream, InputStream) instead.
 java.lang.Object loadDocument(java.io.InputStream partStream, int partStreamSize, int numberOfParts, java.lang.String partMimeType, java.lang.String docMimeType, java.io.InputStream annotationStream, java.io.InputStream resourceStream)
          Initializes processing of a document by the document engine.
 java.lang.Object loadDocument(java.io.InputStream partStream, int numberOfParts, java.lang.String mimeType, java.io.InputStream annotationStream, java.io.InputStream resourceStream)
          Deprecated. Use loadDocument(InputStream, int, int, String, String, InputStream, InputStream) instead.
 java.lang.Object loadDocument(java.io.InputStream partStream, int numberOfParts, java.lang.String partMimeType, java.lang.String docMimeType, java.io.InputStream annotationStream, java.io.InputStream resourceStream)
          Deprecated. Use loadDocument(InputStream, int, int, String, String, InputStream, InputStream) instead.
 java.lang.Object loadPage(java.lang.Object hDocument, int page)
          Initialized processing of a page within the document.
abstract  void terminate()
          Terminates the engine.
 void writeDocument(java.lang.Object hDocument, java.lang.String destMimeType, java.io.OutputStream output)
          Writes the document to an output stream, in the specified format.
 void writeDocumentFromPages(java.lang.Object hDocument, int startingPage, int endingPage, java.lang.String destMimeType, java.io.OutputStream output, boolean withAnnotations)
          Writes the specified pages to an output stream in the specified format.
 void writePage(java.lang.Object hPage, int rotation, double scale, boolean enhance, boolean invert, boolean withAnnotations, java.io.OutputStream output, java.lang.String destMimeType)
          Writes the page to an output stream in the specified format.
 void writePage(java.lang.Object hPage, int rotation, double scale, boolean enhance, boolean invert, boolean withAnnotations, java.io.OutputStream output, java.lang.String destMimeType, java.lang.String resourcePrefix)
          Writes the page to an output stream in the specified format.
 void writePageResource(java.lang.Object hPage, java.lang.String resourceId, int rotation, double scale, boolean enhance, boolean invert, boolean withAnnotations, java.io.OutputStream output)
          Writes a linked page resource to the output stream specified.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMBDocumentEngine

public CMBDocumentEngine()
Method Detail

initialize

public abstract void initialize(CMBDocumentEngineCallbacks callbacks,
                                java.util.Properties properties)
Initializes the document engine. This method must be called before other methods on the document engine can be used.
Parameters:
callbacks - methods to get background forms and additional parts of a multi-part document.
properties - engine specific properties.

terminate

public abstract void terminate()
Terminates the engine. All documents and pages being processed are dropped. System resources are released.

isInitialized

public abstract boolean isInitialized()
Returns true if the initialize method has been called and the engine initialized successfully.

canLoadDocument

public boolean canLoadDocument(java.lang.String mimeType)
Returns true if the specified document type is handled by the engine.
The default implementation returns false in all cases.
Parameters:
mimeType - the MIME content type for the document type being tested.

loadDocument

public java.lang.Object loadDocument(java.io.InputStream partStream,
                                     int numberOfParts,
                                     java.lang.String mimeType,
                                     java.io.InputStream annotationStream,
                                     java.io.InputStream resourceStream)
                              throws java.io.IOException
Deprecated. Use loadDocument(InputStream, int, int, String, String, InputStream, InputStream) instead.

Initializes processing of a document by the document engine.
Parameters:
partStream - An input stream containing the data for the document. If the document is a multi-part document, this input stream contains the data for the first part of the document.
numberOfParts - the number of parts that compose the document. This will be 1 for a single-part document.
mimeType - the MIME content type of the first part.
annotationStream - An input stream containing the annotations for the document. This will only have data in those cases where the annotations are stored separately from the document. The format of the annotations is dependent on the tool that wrote the annotations. Only those formats understood by the document engine will be processed.
resourceStream - an InputStream containing engine specific resources.
Returns:
a unique object representing the document (a document handle). If the document cannot be loaded, null is returned.

loadDocument

public java.lang.Object loadDocument(java.io.InputStream partStream,
                                     int numberOfParts,
                                     java.lang.String partMimeType,
                                     java.lang.String docMimeType,
                                     java.io.InputStream annotationStream,
                                     java.io.InputStream resourceStream)
                              throws java.io.IOException
Deprecated. Use loadDocument(InputStream, int, int, String, String, InputStream, InputStream) instead.

Initializes processing of a document by the document engine.
Parameters:
partStream - An input stream containing the data for the document. If the document is a multi-part document, this input stream contains the data for the first part of the document.
partStreamSize - The size of the partStream of the first part of the document. For situations in which the part stream size is known, this api should be used. The size of the additional parts can be obtained using the CMBDocumentEngineCallbacks getPartSize() interface.The size should be greater than 0 to be valid.
numberOfParts - the number of parts that compose the document. This will be 1 for a single-part document.
partMimeType - the MIME content type of the first part.
docMimeType - the MIME content type of the document. For single-part documents, this is the same as the first part.
annotationStream - An input stream containing the annotations for the document. This will only have data in those cases where the annotations are stored separately from the document. The format of the annotations is dependent on the tool that wrote the annotations. Only those formats understood by the document engine will be processed.
resourceStream - an InputStream containing engine specific resources.
Returns:
a unique object representing the document (a document handle). If the document cannot be loaded, null is returned.

loadDocument

public java.lang.Object loadDocument(java.io.InputStream partStream,
                                     int partStreamSize,
                                     int numberOfParts,
                                     java.lang.String mimeType,
                                     java.io.InputStream annotationStream,
                                     java.io.InputStream resourceStream)
                              throws java.io.IOException
Deprecated. Use loadDocument(InputStream, int, int, String, String, InputStream, InputStream) instead.

Initializes processing of a document by the document engine.
Parameters:
partStream - An input stream containing the data for the document. If the document is a multi-part document, this input stream contains the data for the first part of the document.
partStreamSize - The size of the partStream of the first part of the document. For situations in which the part stream size is known, this api should be used. The size of the additional parts can be obtained using the CMBDocumentEngineCallbacks getPartSize() interface.The size should be greater than 0 to be valid.
numberOfParts - the number of parts that compose the document. This will be 1 for a single-part document.
mimeType - the MIME content type of the first part.
annotationStream - An input stream containing the annotations for the document. This will only have data in those cases where the annotations are stored separately from the document. The format of the annotations is dependent on the tool that wrote the annotations. Only those formats understood by the document engine will be processed.
resourceStream - an InputStream containing engine specific resources.
Returns:
a unique object representing the document (a document handle). If the document cannot be loaded, null is returned.

loadDocument

public java.lang.Object loadDocument(java.io.InputStream partStream,
                                     int partStreamSize,
                                     int numberOfParts,
                                     java.lang.String partMimeType,
                                     java.lang.String docMimeType,
                                     java.io.InputStream annotationStream,
                                     java.io.InputStream resourceStream)
                              throws java.io.IOException
Initializes processing of a document by the document engine.
Parameters:
partStream - An input stream containing the data for the document. If the document is a multi-part document, this input stream contains the data for the first part of the document.
partStreamSize - The size of the partStream of the first part of the document. For situations in which the part stream size is known, this api should be used. The size of the additional parts can be obtained using the CMBDocumentEngineCallbacks getPartSize() interface.The size should be greater than 0 to be valid.
numberOfParts - the number of parts that compose the document. This will be 1 for a single-part document.
partMimeType - the MIME content type of the first part.
docMimeType - the MIME content type of the document. For single-part documents, this is the same as the first part.
annotationStream - An input stream containing the annotations for the document. This will only have data in those cases where the annotations are stored separately from the document. The format of the annotations is dependent on the tool that wrote the annotations. Only those formats understood by the document engine will be processed.
resourceStream - an InputStream containing engine specific resources.
Returns:
a unique object representing the document (a document handle). If the document cannot be loaded, null is returned.

dropDocument

public void dropDocument(java.lang.Object hDocument)
Terminates processing of a document by the document engine.
The default implementation does nothing.
Parameters:
hDocument - the handle of the document, as returned from loadDocument.

canWriteDocument

public boolean canWriteDocument(java.lang.String sourceMimeType,
                                java.lang.String destMimeType)
Returns true if the specified document type can be written by the engine using the writeDocument method in the specified format.
The default implementation returns false in all cases.
Parameters:
sourceMimeType - the MIME content type for the source document.
destMimeType - the MIME content type for the document to be written.

writeDocument

public void writeDocument(java.lang.Object hDocument,
                          java.lang.String destMimeType,
                          java.io.OutputStream output)
                   throws java.io.IOException
Writes the document to an output stream, in the specified format.
Parameters:
hDocument - the handle of the document, as returned from loadDocument.
destMimeType - the MIME content type for the format that the document is to be written.
output - the output stream where the document is written.

canPaginate

public boolean canPaginate(java.lang.String mimeType)
Returns true if the engine can convert documents of the specified MIME content type as pages. This is typically the case when the document itself is formatted for printing, but is desirable in many cases because it enables functions in a viewer such as navigation by page and viewing of page thumbnails.
The default implementation returns false for all types.
Parameters:
mimeType - the MIME content type for the document type being tested.

getNumberOfPages

public int getNumberOfPages(java.lang.Object hDocument)
                     throws java.io.IOException
Returns the number of pages in the document.
Parameters:
hDocument - the handle of the document, as returned from loadDocument.

loadPage

public java.lang.Object loadPage(java.lang.Object hDocument,
                                 int page)
                          throws java.io.IOException
Initialized processing of a page within the document.
Parameters:
hDocument - the handle of the document, as returned from loadDocument.
page - the index of the page (zero is the first page)
Returns:
a unique object representing the page (the page handle). If the page cannot be loaded, null is returned.

dropPage

public void dropPage(java.lang.Object hPage)
Terminates processing of a page.
Parameters:
hPage - the handle of the page, as returned from loadPage.

getPageWidth

public double getPageWidth(java.lang.Object hPage)
Returns the width of the page, in inches. This is the width without rotation and scale=1.0.
Parameters:
hPage - the handle of the page, as returned from loadPage.

getPageHeight

public double getPageHeight(java.lang.Object hPage)
Returns the height of the page, in inches. This is the height without rotation and scale=1.0.
Parameters:
hPage - the handle of the page, as returned from loadPage.

canRotate

public boolean canRotate(java.lang.Object hDocument,
                         java.lang.String destMimeType)
Returns true if the document pages can be rotated when written in the specified format.
The default implementation returns false in all cases.
Parameters:
hDocument - the handle of the document, as returned from loadDocument
destMimeType - the MIME content of the page when written. If this is null, then the call is to query capabilities when providing page images.

getPageMinScale

public double getPageMinScale(java.lang.Object hPage,
                              java.lang.String destMimeType)
Returns the minimum scale of document pages when written in the specified format.
The default implementation returns 1.0 in all cases.
Parameters:
hPage - the handle of the page, as returned from loadPage
destMimeType - the MIME content of the page when written. If this is null, then the call is to query capabilities when providing page images.

getPageMaxScale

public double getPageMaxScale(java.lang.Object hPage,
                              java.lang.String destMimeType)
Returns the maximum scale of document pages when written in the specified format.
The default implementation returns 1.0 in all cases.
Parameters:
hPage - the handle of the document, as returned from loadPage
destMimeType - the MIME content of the page when written. If this is null, then the call is to query capabilities when providing page images.

canEnhance

public boolean canEnhance(java.lang.Object hDocument,
                          java.lang.String destMimeType)
Returns true if the document pages can be enhanced when written in the specified format.
The default implementation returns false in all cases.
Parameters:
hDocument - the handle of the document, as returned from loadDocument
destMimeType - the MIME content of the page when written. If this is null, then the call is to query capabilities when providing page images.

canInvert

public boolean canInvert(java.lang.Object hDocument,
                         java.lang.String destMimeType)
Returns true if the document page colors can be inverted when written in the specified format.
The default implementation returns false in all cases.
Parameters:
hDocument - the handle of the document, as returned from loadDocument
destMimeType - the MIME content of the page when written. If this is null, then the call is to query capabilities when providing page images.

canShowAnnotations

public boolean canShowAnnotations(java.lang.Object hDocument,
                                  java.lang.String destMimeType)
Returns true if the document pages can be shown with annotations when written in the specified format.
The default implementation returns false in all cases.
Parameters:
hDocument - the handle of the document, as returned from loadDocument
destMimeType - the MIME content of the page when written. If this is null, then the call is to query capabilities when providing page images.

canWritePage

public boolean canWritePage(java.lang.Object hPage,
                            java.lang.String destMimeType)
Returns true if a page of the document can be written by the engine using the writePage method in the specified format.
The default implementation returns false in all cases.
Parameters:
hPage - the handle of the page, as returned from loadPage.
destMimeType - the MIME content type for the page.

canWritePage

public boolean canWritePage(java.lang.String sourceMimeType,
                            java.lang.String destMimeType)
Returns true if a page of the document can be written by the engine using the writePage method in the specified format.
The default implementation returns false in all cases.
Parameters:
sourceMimeType - the MIME content type for the document.
destMimeType - the MIME content type for the page.

getPageMimeType

public java.lang.String getPageMimeType(java.lang.Object hPage,
                                        java.lang.String[] preferredMimeTypes)
Returns the engine's desired page format for writing the page.
If the engine implements the canWritePage(Object, String) method to return the desired output page format, that format is used to write the page. Otherwise, the page is written in the format chosen in order of preference from the preferred page formats.
Parameters:
hPage - the handle of the page, as returned from loadPage.
String[] - The preferred formats in the desired order that the page to be written into.

writePage

public void writePage(java.lang.Object hPage,
                      int rotation,
                      double scale,
                      boolean enhance,
                      boolean invert,
                      boolean withAnnotations,
                      java.io.OutputStream output,
                      java.lang.String destMimeType)
               throws java.io.IOException,
                      CMBDocumentEngineException
Writes the page to an output stream in the specified format.
Parameters:
hPage - the handle of the page, as returned from loadPage.
rotation - the rotation of the page. One of the constants ROTATE_0, ROTATE_90, ROTATE_180, or ROTATE_270.
scale - the scale for the page (1.0 is actual size)
enhance - if true, the page should be enhanced to improve text readability if possible.
invert - if true, the image should be color inverted.
output - the stream to write the page to.
destMimeType - the MIME content type for the format that the page is to be saved.

writePage

public void writePage(java.lang.Object hPage,
                      int rotation,
                      double scale,
                      boolean enhance,
                      boolean invert,
                      boolean withAnnotations,
                      java.io.OutputStream output,
                      java.lang.String destMimeType,
                      java.lang.String resourcePrefix)
               throws java.io.IOException,
                      CMBDocumentEngineException
Writes the page to an output stream in the specified format. This version also provides a resource prefix string, which should be used as the prefix of external resources (such as images) in the generated output. This is typically used for HTML output.
Parameters:
hPage - the handle of the page, as returned from loadPage.
rotation - the rotation of the page. One of the constants ROTATE_0, ROTATE_90, ROTATE_180, or ROTATE_270.
scale - the scale for the page (1.0 is actual size)
enhance - if true, the page should be enhanced to improve text readability if possible.
invert - if true, the image should be color inverted.
output - the stream to write the page to.
destMimeType - the MIME content type for the format that the page is to be saved.
resourcePrefix - the prefix to use on linked resources in the generated output page. (These are typically href's in HTML output.)

getPageResourceMimeType

public java.lang.String getPageResourceMimeType(java.lang.Object hPage,
                                                java.lang.String resourceId)
Returns the MIME content type for a linked resource of a written page.
Parameters:
hPage - the handle of the page, as returned from loadPage
resourceId - the identifier of the resource. For HTML generated pages, this is the suffix following the resourcePrefix specified when the page was generated.

writePageResource

public void writePageResource(java.lang.Object hPage,
                              java.lang.String resourceId,
                              int rotation,
                              double scale,
                              boolean enhance,
                              boolean invert,
                              boolean withAnnotations,
                              java.io.OutputStream output)
                       throws java.io.IOException,
                              CMBDocumentEngineException
Writes a linked page resource to the output stream specified.
Parameters:
hPage - the handle of the page, as returned from loadPage
resourceId - the identifier of the resource. For HTML generated pages, this is the suffix following the resourcePrefix specified when the page was generated.
rotation - the rotation of the page. One of the constants ROTATE_0, ROTATE_90, ROTATE_180, or ROTATE_270.
scale - the scale for the page (1.0 is actual size)
enhance - if true, the page should be enhanced to improve text readability if possible.
invert - if true, the image should be color inverted.
output - the stream to write the page resource to.

canWriteDocumentFromPages

public boolean canWriteDocumentFromPages(java.lang.String sourceMimeType,
                                         java.lang.String destMimeType)
Returns true if a series of pages from the document can be written by the engine using the writePages method in the specified format.
The default implementation returns false in all cases.
Parameters:
sourceMimeType - the MIME content type for the document.
destMimeType - the MIME content type for the page.

writeDocumentFromPages

public void writeDocumentFromPages(java.lang.Object hDocument,
                                   int startingPage,
                                   int endingPage,
                                   java.lang.String destMimeType,
                                   java.io.OutputStream output,
                                   boolean withAnnotations)
                            throws java.io.IOException
Writes the specified pages to an output stream in the specified format.
Parameters:
hDocument - the handle of the document, as returned from loadDocument.
startingPage - the index of the starting page (page 0 is the first page)
endingPage - the index of the ending page
destMimeType - the MIME content type for the format that the pages are to be saved.
output - the stream to write the page to.
withAnnotations - if true, then the pages should be saved with their annotations.

canProvidePageImage

public boolean canProvidePageImage(java.lang.String mimeType)
Returns true if the engine can provide images of pages. If false is returned, the getPageImage method is not implemented by the engine for documents of the indicated MIME content type.
The default implementation returns false in all cases.
Parameters:
mimeType - the MIME content type for the document type being tested.

getPageImage

public java.awt.Image getPageImage(java.lang.Object hPage,
                                   int rotation,
                                   double scale,
                                   boolean enhance,
                                   boolean invert,
                                   boolean withAnnotations)
Returns an image of the page.
Parameters:
hPage - the handle of the page, as returned from loadPage.
rotation - the rotation of the page. One of the constants ROTATE_0, ROTATE_90, ROTATE_180, or ROTATE_270.
scale - the scale for the page (1.0 is actual size)
enhance - if true, the page should be enhanced to improve text readability if possible.
invert - if true, the image should be color inverted.

getImageResolution

public int getImageResolution(java.lang.Object hDocument)
Returns the image resolution of the document in pixels per inch (ppi).
Parameters:
hDocument - the handle of the document, as returned from loadDocument.

EIP JavaBeans

(c) Copyright International Business Machines Corporation 1996, 2002. IBM Corp. All rights reserved.