Enterprise Information Portal APIs

com.ibm.mm.viewer.annotation
Class CMBAnnotationEngine

java.lang.Object
  |
  +--com.ibm.mm.viewer.annotation.CMBAnnotationEngine

public abstract class CMBAnnotationEngine
extends java.lang.Object

CMBAnnotationEngine is an abstract class that defines the interface any annotation engine implementation should extend. Annotation engines plug into CMBAnnotationServices and provide rendering and translation support for different annotation types.

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

Since:
8.1
See Also:
CMBAnnotationEngineCallbacks

Constructor Summary
CMBAnnotationEngine()
           
 
Method Summary
abstract  void addAnnotation(java.lang.Object hAnnotationSet, CMBPageAnnotation newPageAnnotation, int page)
          Called to add a single annotation object to the annotation set.
abstract  boolean canLoadAnnotationFormat(java.lang.String format)
          Checks if the engine can load a specific format.
abstract  boolean canSaveAnnotationFormat(java.lang.String srcFormat, java.lang.String destFormat)
          Checks if the engine can save the annotations from one format to another as specified.
abstract  void dropAnnotationSet(java.lang.Object hAnnotationSet)
          Terminates processing of an annotation set by the annotation engine.
abstract  CMBPageAnnotation[] getAnnotations(java.lang.Object hAnnotationSet)
          Gets the annotations that are currently loaded by the document.
abstract  boolean getPrivilege(java.lang.Object hAnnotationSet, int privilegeID)
          Gets the privileges for the annotation set.
abstract  java.lang.Class[] getSupportedAnnotations()
          Returns supported annotation types.
abstract  void initialize(CMBAnnotationEngineCallbacks callbacks, java.util.Properties properties)
          Initializes the annotations engine.
abstract  java.lang.Object loadAnnotationSet(java.io.InputStream annotationStream, java.lang.String format, int documentResolution, int numOfParts, int partNumber)
          Initializes processing of a group of annotations by the annotations engine.
abstract  void removeAnnotation(java.lang.Object hAnnotationSet, CMBPageAnnotation newPageAnnotation)
          Called to remove an annotation from the annotation set.
abstract  void removeAnnotationSet(java.lang.Object hAnnotationSet)
          Removes the annotation set by invoking the engine callbacks to remove the annotation blobs.
abstract  void reorderAnnotation(java.lang.Object hAnnotationSet, CMBPageAnnotation pageAnnotation, int location)
          Called to modify the order in which the annotations are stored in set.
abstract  void saveAnnotationSet(java.lang.Object hAnnotationSet, CMBPageAnnotation[] pageAnnotations)
          Saves the annotation set by invoking the engine callbacks to save the annotation blobs.
abstract  void terminate()
          Terminates the engine.
abstract  void updateAnnotation(java.lang.Object hAnnotationSet, CMBPageAnnotation pageAnnotation, int index)
          Called to update an existing annotation when its attributes change.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMBAnnotationEngine

public CMBAnnotationEngine()
Method Detail

initialize

public abstract void initialize(CMBAnnotationEngineCallbacks callbacks,
                                java.util.Properties properties)
Initializes the annotations engine. This method must be called before other methods on the annotation engine can be used.
Parameters:
callbacks - The methods to get additional annotations parts.
properties - The engine specific properties.

terminate

public abstract void terminate()
Terminates the engine. All annotations sets are dropped. System resources are released.

canLoadAnnotationFormat

public abstract boolean canLoadAnnotationFormat(java.lang.String format)
Checks if the engine can load a specific format. When used within EIP, the format that is passed in is the annotation mimetype for CM v8 or the datastore server type.
Parameters:
format - A string constant for the type of annotations requested.
Returns:
true If the specified annotation type is handled by this annotation engine. false otherwise.

canSaveAnnotationFormat

public abstract boolean canSaveAnnotationFormat(java.lang.String srcFormat,
                                                java.lang.String destFormat)
Checks if the engine can save the annotations from one format to another as specified.
Parameters:
sourceFormat - A string constant for the type of annotations. For ex.'application/vnd.ibm.modcap' for CM v8 annotations or a two letter representation of the server type 'DL','OD','V4',etc.
destFormat - A string constant for the type of annotations. E.g. 'DL' for CM v7 annotations.
Returns:
true If the specified annotations type can be written by the engine using the write method in the specified format. false otherwise.

getSupportedAnnotations

public abstract java.lang.Class[] getSupportedAnnotations()
Returns supported annotation types.
Returns:
Class[] An array of Class objects representing the CMBPageAnnotation(s) supported by this engine.

loadAnnotationSet

public abstract java.lang.Object loadAnnotationSet(java.io.InputStream annotationStream,
                                                   java.lang.String format,
                                                   int documentResolution,
                                                   int numOfParts,
                                                   int partNumber)
                                            throws java.io.IOException
Initializes processing of a group of annotations by the annotations engine.
Parameters:
annotationStream - An input stream containing the data for the annotations. If the annotation data is a multi-parted, this input stream contains the data for the first part of the annotation data.
format - A string constant for the type of annotations. For ex.'application/vnd.ibm.modcap' for CM v8 annotations or a two letter representation of the server type 'DL','OD','V4',etc.
documentResolution - The image resolution of the document that was loaded in pixels per inch.
numberOfParts - The number of parts that compose the entire set of annotations. This will be 1 for a single-part annotation group.
partNumber - The annotation part number that is loaded. First part is usually '0'.
Returns:
Object the handle to the annotation set that is loaded. If the annotations cannot be loaded, null is returned.

saveAnnotationSet

public abstract void saveAnnotationSet(java.lang.Object hAnnotationSet,
                                       CMBPageAnnotation[] pageAnnotations)
                                throws java.io.IOException
Saves the annotation set by invoking the engine callbacks to save the annotation blobs. The implementation of this method must call the addAnnotationPart() of the annotation engine callbacks if a null annotationStream was passed in to loadAnnotationSet(). This implies that a new annotation part must be added to the document. Otherwise, a call to updateAnnotationPart() must be made.
Parameters:
hAnnotationSet - The handle of the set of annotations, as returned from loadAnnotationSet.
pageAnnotations - The array of CMBPageAnnotation objects to be saved.

removeAnnotationSet

public abstract void removeAnnotationSet(java.lang.Object hAnnotationSet)
Removes the annotation set by invoking the engine callbacks to remove the annotation blobs.
Parameters:
hAnnotationSet - The handle to the annotation set, as returned from loadAnnotationSet.

dropAnnotationSet

public abstract void dropAnnotationSet(java.lang.Object hAnnotationSet)
Terminates processing of an annotation set by the annotation engine.
Parameters:
hAnnotationSet - The handle to the annotation set, as returned from loadAnnotationSet.

getAnnotations

public abstract CMBPageAnnotation[] getAnnotations(java.lang.Object hAnnotationSet)
Gets the annotations that are currently loaded by the document.
Parameters:
hAnnotationSet - The handle to the annotation set.
Returns:
CMBPageAnnotation[] An array containing all the CMBPageAnnotation objects.

getPrivilege

public abstract boolean getPrivilege(java.lang.Object hAnnotationSet,
                                     int privilegeID)
Gets the privileges for the annotation set.
Parameters:
hAnnotationSet - The handle of the set of annotations.
privilegeID - The privilege type
Returns:
boolean True if that privilege is allowed for this annotation set, False otherwise.

addAnnotation

public abstract void addAnnotation(java.lang.Object hAnnotationSet,
                                   CMBPageAnnotation newPageAnnotation,
                                   int page)
Called to add a single annotation object to the annotation set.
Parameters:
hAnnotationSet - The handle to the annotation set, as returned from loadAnnotationSet.
newPageAnnotation - The CMBPageAnnotation instance to be added.
page - The page to which the annotation is to be added.

removeAnnotation

public abstract void removeAnnotation(java.lang.Object hAnnotationSet,
                                      CMBPageAnnotation newPageAnnotation)
Called to remove an annotation from the annotation set.
Parameters:
hAnnotationSet - The handle to the annotation set, as returned from loadAnnotationSet.
newPageAnnotation - The CMBPageAnnotation instance to be removed.

reorderAnnotation

public abstract void reorderAnnotation(java.lang.Object hAnnotationSet,
                                       CMBPageAnnotation pageAnnotation,
                                       int location)
Called to modify the order in which the annotations are stored in set. This is useful for maintaining a Z-order for the annotations.
Parameters:
hAnnotationSet - The handle to the annotation set, as returned from loadAnnotationSet.
pageAnnotation - The CMBPageAnnotation instance to be reordered.
location - The new index of the annotation in the set.

updateAnnotation

public abstract void updateAnnotation(java.lang.Object hAnnotationSet,
                                      CMBPageAnnotation pageAnnotation,
                                      int index)
Called to update an existing annotation when its attributes change.
Parameters:
hAnnotationSet - The handle to the annotation set, as returned from loadAnnotationSet.
pageAnnotation - The CMBPageAnnotation instance to be updated.
index - The index of the annotation in the set.

EIP JavaBeans

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