Enterprise Information Portal APIs

com.ibm.mm.viewer.annotation
Class CMBAnnotationServices

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

public class CMBAnnotationServices
extends java.lang.Object

CMBAnnotationServices provides the main interfaces to the annotation services support in the java viewer toolkit. Loading, manipulating and saving annotation objects can be done using the annotation services independent of backends. The annotation data can be passed in as a stream and a suitable annotation engine can be plugged in to convert the annotation objects to CMBPageAnnotation instances. The annotations can then be manipulated and edited and saved back to the original format using the annotation engine. It uses the CMBAnnotationSet as a 'model' to represent the logical format of the annotation blob. It uses the CMBAnnotationView as a 'view' to handle the rendering of the annotations on a JComponent. It additionally internally uses a 'controller' that facilitates manipulation of the annotations graphically.

CMBAnnotationEngine is an abstract class that must be exended by any annotation engine implementation. CMBAnnotationServicesCallbacks and CMBAnnotationEngineCallbacks interfaces are utilized by the annotation engine to communicate with the application and annotation services. The default annotation engine provided with the annotation services is com.ibm.mm.viewer.msannotation.CMBMSTechAnnotationEngine. This engine currently understands annotation formats like "application/vnd.ibm.modcap", "DL" and "V4" only.

Since:
8.1
See Also:
CMBAnnotationEngine, CMBAnnotationServicesCallbacks, CMBAnnotationEngineCallbacks, CMBAnnotationView, CMBAnnotationSet

Constructor Summary
CMBAnnotationServices(CMBAnnotationServicesCallbacks callbacks)
          Constructs the annotation services.
 
Method Summary
 void addAnnotation(CMBPageAnnotation a)
          Adds the specified annotation to the current annotation set.
 void changeAnnotationProperties(CMBPageAnnotation anno)
          Pops up the properties dialog for the corresponding annotation.
 void dropAllAnnotationSets()
          Drops all the annotation sets that are currently being processed.
 void dropAnnotationSet(CMBAnnotationSet annSet)
          Drops the specified annotation set.
 CMBAnnotationSet[] getAllAnnotationSets()
          Returns the annotation sets being processed.
 CMBAnnotationSet getAnnotationSet(int index)
          Returns a particular annotation set for a document being processed.
 CMBAnnotationSet getAnnotationSet(java.lang.Object hItem)
          Returns the annotation set , given the handle to the annotation set.
 java.util.Properties getEngineProperties()
          Returns the engine properties.
 java.lang.Object getItemHandle(CMBAnnotationSet annSet)
          Returns the handle to the annotations given the annotation set.
 boolean getPrivilege(CMBAnnotationSet annoSet, int privilegeID)
          Gets privilege for annotationSet.
 CMBPageAnnotation getSelectedAnnotation()
          Gets the currently selected or active annotation.
 void hideAllAnnotations()
          Hides all the annotations from the current view.
 CMBAnnotationSet loadAnnotationSet(java.io.InputStream annotationStream, java.lang.String format, int documentResolution, int numOfParts, int partNumber)
          Loads the annotations from the annotation engines.
 CMBAnnotationView prepareAnnotationView(javax.swing.JComponent viewcomponent, CMBAnnotationSet annotationSet)
          Sets the view component for the annotations to be drawn on.
 void prepareToAddAnnotation(int annoType, int pageNumber)
          Prepares the annotation controller to create the annotation specified by the type.
 void prepareToAddAnnotation(int annoType, java.lang.String className, int pageNumber)
          Prepares the annotation controller to create a custom annotation type by specifying the fully qualified class name.
 void removeAnnotation(CMBPageAnnotation a)
          Removes the specified annotation from the current annotation set.
 void reorderAnnotation(CMBPageAnnotation a, int index)
          Reorders the specified annotation within the current list of annotations.
 void saveAllAnnotationSets()
          Saves all the current annotations.
 void saveAnnotationSet(CMBAnnotationSet annSet)
          Saves the currently loaded annotation set that the annotation services is working with.
 void setAnnotationView(CMBAnnotationView view, CMBAnnotationSet annoSet)
          Use this method to replace the annotation set for the view and the controller.
 void setCurrentPageNumber(int pageNumber)
          Sets the current page number for the annotation controller to keep track.
 void setEngineProperties(java.util.Properties engineProperties)
          Sets the engine properties.
 void setEraseMode()
          Sets the annotation editing in erase mode.
 void setIdleDrawingMode()
          Sets the annotation editing in idle mode.
 void setItemHandle(CMBAnnotationSet annSet, java.lang.Object handle)
          Saves the reference to the actual object used to retrieve the annotations.
 void setPopupMenu(java.lang.Object popupmenu)
          Sets the popup menu that is used as annotation popup menus.
 void showAllAnnotations()
          Shows all the annotations on the current view.
 void terminate()
          Terminates all the engines and drops all annotations.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

CMBAnnotationServices

public CMBAnnotationServices(CMBAnnotationServicesCallbacks callbacks)
Constructs the annotation services.
Parameters:
callbacks - The implementation of CMBAnnotationServicesCallbacks used to retrieve additional annotation parts.
Method Detail

getEngineProperties

public java.util.Properties getEngineProperties()
Returns the engine properties.

setEngineProperties

public void setEngineProperties(java.util.Properties engineProperties)
Sets the engine properties. These properties define the annotation engine classes to be loaded. Annotation engines provide conversion of particular annotation formats.
Parameters:
engineProperties - a Properties object defining the annotation engines to load and their initialization properties. The properties have the following names:
ANNOTATION_ENGINES=<.n>
Defines the number of engines.
ANNOTATION_ENGINE<.n>_CLASSNAME=
Defines the class (an extension of CMBAnnotationEngine) implementing the engine.
ANNOTATION_ENGINE<.n>_<.propertyName>=<.propertyValue>
Defines a property specific to engine n. This property will appear in the properties passed to the engine (without the ANNOTATION_ENGINE<.n>_ prefix).
<.propertyName>=<.propertyValue>
All other properties not prefixed with ANNOTATION_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().

getAllAnnotationSets

public CMBAnnotationSet[] getAllAnnotationSets()
Returns the annotation sets being processed.

getAnnotationSet

public CMBAnnotationSet getAnnotationSet(int index)
                                  throws java.lang.ArrayIndexOutOfBoundsException
Returns a particular annotation set for a document being processed.

loadAnnotationSet

public CMBAnnotationSet loadAnnotationSet(java.io.InputStream annotationStream,
                                          java.lang.String format,
                                          int documentResolution,
                                          int numOfParts,
                                          int partNumber)
                                   throws java.io.IOException,
                                          java.lang.ClassNotFoundException,
                                          java.lang.IllegalAccessException,
                                          java.lang.InstantiationException
Loads the annotations from the annotation engines.
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 such as 'DL','OD','V4'.
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:
CMBAnnotationSet The annotation set that is loaded. If the annotationStream contains valid annotation objects, this set will contain a list of CMBPageAnnotation objects. If the annotationStream passed in was null ( this is the case when the document does not have any annotation part ) then a empty CMBAnnotationSet is returned.

saveAllAnnotationSets

public void saveAllAnnotationSets()
Saves all the current annotations.

saveAnnotationSet

public void saveAnnotationSet(CMBAnnotationSet annSet)
Saves the currently loaded annotation set that the annotation services is working with.
Parameters:
annSet - the current annotation set.

dropAllAnnotationSets

public void dropAllAnnotationSets()
Drops all the annotation sets that are currently being processed.

dropAnnotationSet

public void dropAnnotationSet(CMBAnnotationSet annSet)
Drops the specified annotation set.
Parameters:
annSet - The annotation set to be removed.

setItemHandle

public void setItemHandle(CMBAnnotationSet annSet,
                          java.lang.Object handle)
Saves the reference to the actual object used to retrieve the annotations.
Parameters:
annotationSet - The annotationSet whose handle is being set
hAnnotationSet - The reference to the handle ( in the case of EIP, the CMBItem reference is used )

getItemHandle

public java.lang.Object getItemHandle(CMBAnnotationSet annSet)
Returns the handle to the annotations given the annotation set.
Parameters:
annotationSet - The annotationSet

getAnnotationSet

public CMBAnnotationSet getAnnotationSet(java.lang.Object hItem)
Returns the annotation set , given the handle to the annotation set.
Parameters:
hItem - The object reference that is used as a handle to the annotation set. In the case of EIP, this is the CMBItem reference.

getPrivilege

public boolean getPrivilege(CMBAnnotationSet annoSet,
                            int privilegeID)
Gets privilege for annotationSet.
Parameters:
annoSet - the annotationSet for which to get the privilege
privilegeID - the privilege ID for which the permissions need to be obtained
Returns:
true if the specified privilege is allowed false otherwise.

terminate

public void terminate()
Terminates all the engines and drops all annotations.

prepareToAddAnnotation

public void prepareToAddAnnotation(int annoType,
                                   int pageNumber)
Prepares the annotation controller to create the annotation specified by the type.
Parameters:
annoType - The type of the annotation as defined by the CMBAnnotationConstants. For example, ANN_ARROW, ANN_STAMP, etc.
pageNumber - The page number of the document where the annotation is being prepared to be created.

prepareToAddAnnotation

public void prepareToAddAnnotation(int annoType,
                                   java.lang.String className,
                                   int pageNumber)
Prepares the annotation controller to create a custom annotation type by specifying the fully qualified class name.
Parameters:
annoType - The type of the annotation as defined by the CMBAnnotationConstants. For example, ANN_ARROW, ANN_STAMP, etc. For custom annotation type, use ANN_CUSTOM.
className - The fully qualified class name of any custom page annotation
pageNumber - The page number of the document where the annotation is being prepared to be created.

setCurrentPageNumber

public void setCurrentPageNumber(int pageNumber)
Sets the current page number for the annotation controller to keep track.
Parameters:
int - the current page number of the document where the annotations are being edited.

setIdleDrawingMode

public void setIdleDrawingMode()
Sets the annotation editing in idle mode. Sets the cursor with the default cursor.

setEraseMode

public void setEraseMode()
Sets the annotation editing in erase mode. Subsequent mouse clicks will delete the annotation if the mouse point intersect with the annotation's bounding rectangle. For pen annotations, mouse drags erase segments of the pen.

getSelectedAnnotation

public CMBPageAnnotation getSelectedAnnotation()
Gets the currently selected or active annotation.
Returns:
CMBPageAnnotation The page annotation that is currently selected.

addAnnotation

public void addAnnotation(CMBPageAnnotation a)
Adds the specified annotation to the current annotation set.
Parameters:
a - The page annotation to be added.

removeAnnotation

public void removeAnnotation(CMBPageAnnotation a)
Removes the specified annotation from the current annotation set.
Parameters:
a - The page annotation to be removed.

reorderAnnotation

public void reorderAnnotation(CMBPageAnnotation a,
                              int index)
Reorders the specified annotation within the current list of annotations.
Parameters:
a - The page annotation to be reordered.

hideAllAnnotations

public void hideAllAnnotations()
Hides all the annotations from the current view.

showAllAnnotations

public void showAllAnnotations()
Shows all the annotations on the current view.

changeAnnotationProperties

public void changeAnnotationProperties(CMBPageAnnotation anno)
Pops up the properties dialog for the corresponding annotation.
Parameters:
anno - The annotation whose properties needs to be modified.

setPopupMenu

public void setPopupMenu(java.lang.Object popupmenu)
Sets the popup menu that is used as annotation popup menus.
Parameters:
popupmenu - the annotation popup menu.

prepareAnnotationView

public CMBAnnotationView prepareAnnotationView(javax.swing.JComponent viewcomponent,
                                               CMBAnnotationSet annotationSet)
Sets the view component for the annotations to be drawn on. This method prepares the 'model', 'view' and 'controller' used for annotation editing. Called to perform annotations editing interactively and must be called only once for an application. The same view component can then be used for rendering other documents by calling the setAnnotationView() of CMBAnnotationServices.
Parameters:
viewcomponent - The JComponent to draw the annotations on. This JComponent is used by the annotation view to render the annotations.
annotationSet - The model that contains the CMBPageAnnotations to be drawn.
Returns:
CMBAnnotationView The annotation view is created and returned.
See Also:
setAnnotationView( CMBAnnotationView view,CMBAnnotationSet annoSet )

setAnnotationView

public void setAnnotationView(CMBAnnotationView view,
                              CMBAnnotationSet annoSet)
Use this method to replace the annotation set for the view and the controller. The same annotation view and controller are used for viewing and rendering different annotation sets ( models).
Parameters:
view - The annotation view currently used for rendering annotations
annoSet - The model - the set of annotations loaded.

EIP JavaBeans

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