Enterprise Information Portal APIs

com.ibm.mm.beans
Class CMBDocumentServices

java.lang.Object
  |
  +--com.ibm.mm.beans.CMBDocumentServices
All Implemented Interfaces:
CMBBaseConstant, CMBDocumentRequestListener, java.util.EventListener, java.io.Serializable

public class CMBDocumentServices
extends java.lang.Object
implements CMBBaseConstant, CMBDocumentRequestListener, java.io.Serializable

The CMBDocumentServices bean provides services to render, convert, and manipulate the pages of one or more documents. It takes a CMBItem for a document and creates a CMBDocument object representing the document. Methods on CMBDocument then allow for conversion of the document or pages of the document. CMBDocumentServices manages pluggable engines which interpret the documents and render or convert the pages.

To use CMBDocumentServices:

An alternative way of using CMBDocumentServices is via events. CMBDocumentServices listens to CMBDocumentRequestEvents to perform services, and will generate CMBDocumentReplyEvents to signal the results of the requests. When used in this fashion, if an exception occurs, a CMBDocumentExceptionEvent will be generated rather than throwing an exception.

Summary of properties and events:

  imported properties   traceEnabled, defaulting off, will not veto
   exported properties   none
   standalone properties conversionProperties, dataManagement, documents,
                         engineProperties, preferredFormats, preferredPageFormats
   interested in events  CMBDocumentRequestEvent  - to perform functions
                         PropertyChangeEvent      - to import traceEnabled
   source of events      CMBDocumentReplyEvent    - to reply the request
                         CMBExceptionEvent        - to post exception
                         CMBTraceEvent            - to let logger trace
Supported Conversions

The following tables summarize the conversion supported by default (using the supplied conversion engines). Additional conversion capabilities can be plugged in using by creating classes that extend CMBDocumentEngine and registering them with CMBDocumentServices using setEngineProperties():

On Windows NT:
MIME Type Engine Paginated With
Annotations
Converted To
application/afp CMBODDocumentEngine Yes1 No text/html
application/afp CMBODDocumentEngine No No application/afp2
application/lin
application/ondemand line
CMBODDocumentEngine No No text/plain3
image/tiff
image/tif
image/gif
image/jpeg
text/plain
application/vnd.ibm.modcap
CMBMSTechDocumentEngine Yes Yes image/gif
image/jpeg

text/enriched
text/plain
text/richtext
text/rtf
image/gif
image/jpeg
image/bmp
image/pcx
text/html
application/vnd.lotus-1-2-3
application/vnd.ms-excel
application/wordperfect5.1
application/msword
application/vnd.lotus-wordpro
CMBMSTechInsoEngine Yes Yes image/gif or image/jpeg
text/url CMBJavaDocumentEngine No No text/html4

On AIX:
MIME Type Engine Paginated With
Annotations
Converted To
application/afp CMBODDocumentEngine No No application/afp2
image/tiff
image/tif
image/gif
image/jpeg
text/plain
application/vnd.ibm.modcap
CMBMSTechDocumentEngine Yes Yes image/gif
image/jpeg
image/gif
image/jpeg
CMBJavaDocumentEngine No No image/jpeg
text/url CMBJavaDocumentEngine No No text/html

Notes:

  1. The AFP2Web toolkit is used to perform paginated conversion to text/hml. This toolkit is not packaged with EIP. It is available separately.
  2. AFP to AFP conversion also concatenates segments of large object documents.
  3. Line data to plain text conversion also converts EBCDIC to ASCII.
  4. text/url is a special MIME type used to indicate that a plain text document contains a URL. CMBDocumentServices will convert the URL into a HTML document with an auto-forwarding link.

Specifying Conversion Preferences

There are three properties on CMBDocumentServices that are used together to determine the type of conversion that will occur for each document type:

The default for these properties have pagination and conversion to single pages for all document types if possible. Also, the preferred formats are those supported by most browsers.

Engine Properties

Individual document conversion engines may have special properties. These can be specified using the EngineProperties property. See the reference for each of the document engine classes for details on the specific properties supported by each engine.

The default value for EngineProperties:

When modifying engine properties, you'll need to perform getEngineProperties to get the default properties, then add values to the Properties object returned, and use setEngineProperties to update the properties. Otherwise, your settings will override the defaults.

Engine properties must be updated before using any other methods in CMBDocumentServices for the properties to take effect.

Since:
7.1
See Also:
CMBODDocumentEngine, CMBJavaDocumentEngine, Serialized Form

Fields inherited from interface com.ibm.mm.beans.CMBBaseConstant
ANNOTATION_MIME_TYPE, CMB_CLASS_ICM_DOC_MODEL, CMB_CLASS_ICM_DOC_PART, CMB_CLASS_ITEM, CMB_CLASS_RESOURCE_ITEM, CMB_CLASS_UNDEFINED, CMB_CONNTYPE_DYNAMIC, CMB_CONNTYPE_LOCAL, CMB_CONNTYPE_REMOTE, CMB_CONTENT_ATTRONLY, CMB_CONTENT_CHILDREN, CMB_CONTENT_ITEMTREE, CMB_CONTENT_LINKS_INBOUND, CMB_CONTENT_LINKS_OUTBOUND, CMB_CONTENT_YES, CMB_DATATYPE_COLLECTION, CMB_DATATYPE_COLLECTION_DDO, CMB_DATATYPE_COLLECTION_XDO, CMB_DATATYPE_DATAOBJECTBASE, CMB_DATATYPE_DATE, CMB_DATATYPE_DECIMAL, CMB_DATATYPE_DOUBLE, CMB_DATATYPE_FLOAT, CMB_DATATYPE_FSTRING, CMB_DATATYPE_ITEM, CMB_DATATYPE_ITEM_COLLECTION, CMB_DATATYPE_LONG, CMB_DATATYPE_OBJECT, CMB_DATATYPE_OBJECT_COLLECTION, CMB_DATATYPE_SHORT, CMB_DATATYPE_TIME, CMB_DATATYPE_TIMESTAMP, CMB_DATATYPE_UNDEFINED, CMB_DATATYPE_VSTRING, CMB_DSTYPE_CM, CMB_DSTYPE_DB2, CMB_DSTYPE_DES, CMB_DSTYPE_DJ, CMB_DSTYPE_DL, CMB_DSTYPE_DOMDOC, CMB_DSTYPE_FED, CMB_DSTYPE_FN, CMB_DSTYPE_IC, CMB_DSTYPE_ICM, CMB_DSTYPE_IP390, CMB_DSTYPE_JDBC, CMB_DSTYPE_OD, CMB_DSTYPE_VI400, CMB_EIP_LOGOUT, CMB_OBJTYPE_CMBITEM, CMB_OBJTYPE_CMBOBJECT, CMB_OP_AND, CMB_OP_BETWEEN, CMB_OP_CONTAINS_TEXT, CMB_OP_CONTAINS_TEXT_IN_CONTENT, CMB_OP_EQUAL, CMB_OP_GREATER, CMB_OP_GREATER_EQUAL, CMB_OP_IN, CMB_OP_LESS, CMB_OP_LESS_EQUAL, CMB_OP_LIKE, CMB_OP_NOT, CMB_OP_NOT_BETWEEN, CMB_OP_NOT_EQUAL, CMB_OP_NOT_IN, CMB_OP_NOT_LIKE, CMB_OP_OR, CMB_OP_UNDEFINED, CMB_QS_TYPE_COMBINED, CMB_QS_TYPE_DES, CMB_QS_TYPE_FEDERATED, CMB_QS_TYPE_IMAGE, CMB_QS_TYPE_PARAMETRIC, CMB_QS_TYPE_SQL, CMB_QS_TYPE_TEMPLATE, CMB_QS_TYPE_TEXT, CMB_QS_TYPE_UNKNOWN, CMB_QS_TYPE_XPATH, CMB_ST_SKIP_ALWAYS, CMB_ST_SKIP_NEVER, CMB_ST_SKIP_WITH_PROMPT, CMB_STATUS_FAILED, CMB_STATUS_OK, CMB_STATUS_RESULT_END, CMB_STATUS_RESULT_MORE, CMB_STATUS_RESULT_NEW, CMB_TIMESTAMP_UNDEFINED, CMB_TYPE_DOCUMENT, CMB_TYPE_FOLDER, CMB_TYPE_ITEM, CMB_TYPE_UNKNOWN, CMB_USERID_UNDEFINED, CMB_VERSION_CONTROL_ALWAYS_NEW, CMB_VERSION_CONTROL_BY_APP, CMB_VERSION_CONTROL_NEVER, CMB_VERSION_KEYWORD, CMB_VERSION_LATEST, CMB_VERSION_NEW, PROP_CACHE_ENABLED, PROP_CC2MIME_URL, PROP_CONNECTION, PROP_CONNECTION_TYPE, PROP_DATA_MANAGEMENT_ENABLED, PROP_DSTYPE, PROP_LOCAL_SERVER, PROP_NAME, PROP_NEW_PASSWORD, PROP_PASSWORD, PROP_PORT_NUMBER, PROP_QUERY_CALLBACK_THRESHOLD, PROP_QUERY_MAX_RESULTS, PROP_RESULT_PAGESIZE, PROP_RMI_HOSTNAME, PROP_SCHEMA_MANAGEMENT_ENABLED, PROP_SEARCH_ASYNCH, PROP_SEARCH_MULTI_CHARS_WILDCARD, PROP_SEARCH_PARAMETRIC_WILDCARD, PROP_SEARCH_SINGLE_CHAR_WILDCARD, PROP_SEARCH_SKIP_SERVER, PROP_SEARCH_TIMEOUT, PROP_SERVER_NAME, PROP_SV_CONNECTION_TYPE, PROP_SV_PORT_NUMBER, PROP_SV_RMI_HOSTNAME, PROP_TRACE_ENABLED, PROP_USERID
 
Constructor Summary
CMBDocumentServices()
          Constructor.
 
Method Summary
 void addCMBDocumentReplyListener(CMBDocumentReplyListener listener)
          Register a listener of CMBDocumentReplyEvents.
 void addCMBExceptionListener(CMBExceptionListener listener)
          Register a listener of CMBExceptionEvents.
 void addCMBTraceListener(CMBTraceListener listener)
          CMBTraceEvent registration method.
 void dropAllDocuments()
          Terminates processing of all documents by document services.
 void dropDocument(CMBDocument document)
          Terminates processing of a document by document services.
 CMBAnnotationServices getAnnotationServices()
          Returns the instance of CMBAnnotationServices.
 java.util.Properties getConversionProperties()
          Returns the conversion properties.
 CMBDataManagement getDataManagement()
          Returns the data management bean associated with this document services.
 CMBDocumentReplyEvent getDocumentReplyEvent()
          Returns the last document reply event fired.
 CMBDocument[] getDocuments()
          Returns the list of documents being processed.
 java.util.Properties getEngineProperties()
          Returns the engine properties.
 CMBExceptionEvent getExceptionEvent()
          Returns the last exception event fired.
 java.lang.String[] getPreferredFormats()
          Returns the preferred formats for converted documents.
 java.lang.String[] getPreferredPageFormats()
          Returns the preferred page formats for converted pages of documents.
 CMBStreamingDocServices getStreamingDocServices()
          Returns the instance of CMBStreamingDocServices.
 boolean getTraceEnabled()
          Returns true if tracing is enabled.
 CMBTraceEvent getTraceEvent()
          Returns the last trace event fired.
 CMBDocument loadDocument(CMBItem item)
          Initiates processing of a document by document services.
 void onCMBDocumentRequest(CMBDocumentRequestEvent evt)
          Handles document request events.
 void removeCMBDocumentReplyListener(CMBDocumentReplyListener listener)
          Unregister a listener of CMBDocumentReplyEvents.
 void removeCMBExceptionListener(CMBExceptionListener listener)
          Unregister a listener of CMBExceptionEvents.
 void removeCMBTraceListener(CMBTraceListener listener)
          CMBTraceEvent unregistration method.
 void setConversionProperties(java.util.Properties properties)
          Sets the conversion properties.
 void setDataManagement(CMBDataManagement dataManagement)
          Sets the data management bean associated with this document services.
 void setEngineProperties(java.util.Properties engineProperties)
          Sets the engine properties.
 void setPreferredFormats(java.lang.String[] formats)
          Sets the preferred formats for converted documents, in the order of most preferred to least preferred.
 void setPreferredPageFormats(java.lang.String[] pageFormats)
          Sets the preferred page formats for converted pages of documents, in the order of most preferred to least preferred.
 void setTraceEnabled(boolean traceEnabled)
          Sets tracing on the bean.
 void terminate()
          Terminates all the engines used by document services.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMBDocumentServices

public CMBDocumentServices()
Constructor.
Method Detail

getDataManagement

public CMBDataManagement getDataManagement()
Returns the data management bean associated with this document services.

setDataManagement

public void setDataManagement(CMBDataManagement dataManagement)
Sets the data management bean associated with this document services. The data management bean is used to retrieve all content and annotations for documents.
Parameters:
dataManagement - an instance of CMBDataManagement

getEngineProperties

public java.util.Properties getEngineProperties()
Returns the engine properties.
See Also:
setEngineProperties(Properties)

setEngineProperties

public void setEngineProperties(java.util.Properties engineProperties)
Sets the engine properties. These properties define the document engine classes to be loaded. Document engines provide conversion and rendering services for particular document types.
Parameters:
engineProperties - a Properties object defining the document engines to load and their initialization properties. The properties have the following names:
ENGINES=<.n>
Defines the number of engines.
ENGINE<.n>_CLASSNAME=
Defines the class (an extension of CMBDocumentEngine) implementing the engine.
ENGINE<.n>_<.propertyName>=<.propertyValue>
Defines a property specific to engine n. This property will appear in the properties passed to the engine (without the ENGINE<.n>_ prefix).
<.propertyName>=<.propertyValue>
All other properties not prefixed with ENGINE will be passed to all engines.
The default value for engine properties defines the default engines used for conversion. Therefore, to change engine properties, use getEngineProperties() to get the current engine properties, and add properties using properties.put().

getDocuments

public CMBDocument[] getDocuments()
Returns the list of documents being processed.

getPreferredFormats

public java.lang.String[] getPreferredFormats()
Returns the preferred formats for converted documents. The default is text/html, application/pdf, text/plain.

setPreferredFormats

public void setPreferredFormats(java.lang.String[] formats)
Sets the preferred formats for converted documents, in the order of most preferred to least preferred.
Parameters:
formats - the MIME types for the preferred formats.

getPreferredPageFormats

public java.lang.String[] getPreferredPageFormats()
Returns the preferred page formats for converted pages of documents. The default is text/html, image/gif, image/jpeg.

setPreferredPageFormats

public void setPreferredPageFormats(java.lang.String[] pageFormats)
Sets the preferred page formats for converted pages of documents, in the order of most preferred to least preferred.
Parameters:
formats - the MIME types for the preferred formats.

getConversionProperties

public java.util.Properties getConversionProperties()
Returns the conversion properties. This defines how document formats are converted. By default, all documents types are converted to pages.
See Also:
setConversionProperties(Properties)

setConversionProperties

public void setConversionProperties(java.util.Properties properties)
Sets the conversion properties. This defines how documents are converted. Conversion occurs when the write() methods on CMBDocument and CMBPage are used. It has the following format:
<.mimetype>.=document|page|none
mimetype is the MIME content type for the documents. The value is defined:
document
Convert the entire document to one of the preferred formats. Separate document pages will not be available. If conversion to a preferred format is not possible, CMBDocument.write() will return the document unconverted.
page
Convert pages of the document to one of the preferred page formats. If the document can be parsed and individual pages can be converted, they will be made available (through CMBDocument.getPages()). If pages cannot be converted, document conversion will still be available. If even that is not possible, CMBDocument.write() will return the document unconverted.
none
Do not provide any conversion of the document type. No document pages are available, and CMBDocument.write() returns the document unconverted.
By default, all document types are converted to pages.

getTraceEnabled

public boolean getTraceEnabled()
Returns true if tracing is enabled.

setTraceEnabled

public void setTraceEnabled(boolean traceEnabled)
Sets tracing on the bean.
Parameters:
traceEnabled - if true, tracing is enabled on the bean.

loadDocument

public CMBDocument loadDocument(CMBItem item)
                         throws CMBException,
                                CMBItemNotExistException,
                                CMBNoConnectionException,
                                CMBItemNotSetException,
                                CMBNoContentException,
                                java.lang.ClassNotFoundException,
                                java.lang.IllegalAccessException,
                                java.lang.InstantiationException,
                                java.lang.Exception
Initiates processing of a document by document services.
Parameters:
item - the CMBItem representing the document to be processed.
Returns:
an instance of CMBDocument for the document. If the document cannot be handled by document services, null is returned.

dropDocument

public void dropDocument(CMBDocument document)
Terminates processing of a document by document services.
Parameters:
document - the CMBDocument instance for the document being terminated. Any calls to methods on the document will fail after this call.

dropAllDocuments

public void dropAllDocuments()
Terminates processing of all documents by document services.

terminate

public void terminate()
Terminates all the engines used by document services. There is no need to call dropAllDocuments before, since this method will take care of this.

onCMBDocumentRequest

public void onCMBDocumentRequest(CMBDocumentRequestEvent evt)
Handles document request events. Upon completing the request, a CMBDocumentReplyEvent is emitted containing the results.
Specified by:
onCMBDocumentRequest in interface CMBDocumentRequestListener

addCMBTraceListener

public void addCMBTraceListener(CMBTraceListener listener)
CMBTraceEvent registration method.
Parameters:
listener - listener to be registered

removeCMBTraceListener

public void removeCMBTraceListener(CMBTraceListener listener)
CMBTraceEvent unregistration method.
Parameters:
listener - listener to be unregistered

addCMBDocumentReplyListener

public void addCMBDocumentReplyListener(CMBDocumentReplyListener listener)
Register a listener of CMBDocumentReplyEvents.
Parameters:
listener - listener to be registered.

removeCMBDocumentReplyListener

public void removeCMBDocumentReplyListener(CMBDocumentReplyListener listener)
Unregister a listener of CMBDocumentReplyEvents.
Parameters:
listener - listener to be unregistered.

addCMBExceptionListener

public void addCMBExceptionListener(CMBExceptionListener listener)
Register a listener of CMBExceptionEvents.
Parameters:
listener - listener to be registered.

removeCMBExceptionListener

public void removeCMBExceptionListener(CMBExceptionListener listener)
Unregister a listener of CMBExceptionEvents.
Parameters:
listener - listener to be unregistered.

getDocumentReplyEvent

public CMBDocumentReplyEvent getDocumentReplyEvent()
Returns the last document reply event fired. This is in support of visual building in builders that cannot handle event arguments.

getTraceEvent

public CMBTraceEvent getTraceEvent()
Returns the last trace event fired. This is in support of visual building in builders that cannot handle event arguments.
Returns:
a CMBTraceEvent

getExceptionEvent

public CMBExceptionEvent getExceptionEvent()
Returns the last exception event fired. This is in support of visual building in builders that cannot handle event arguments.

getStreamingDocServices

public CMBStreamingDocServices getStreamingDocServices()
Returns the instance of CMBStreamingDocServices. Creates one if needed.

getAnnotationServices

public CMBAnnotationServices getAnnotationServices()
Returns the instance of CMBAnnotationServices. Creates one if needed.

EIP JavaBeans

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