Annotation

An Annotation object represents incidental information that can be attached to an object for annotating or footnoting that object. You can associate annotations with custom objects, documents, and folders (Containable objects). Annotations have the following characteristics:

• Like a document, an annotation is a content-carrying object that can have zero or more associated ContentElement objects. However, unlike a persisted document, whose content elements are frozen for a particular version, an annotation is nonversionable; its content elements can be added to or deleted from. For a code example, see Retrieving Annotations. For more information about content, see Document Content in the Content Engine Administration help.
• For a document, the easiest way to create a new annotation is with the document's createAnnotation method.

  For folders and custom objects, you use a Factory method to create a new Annotation object, then set its AnnotatedObject property to the folder or custom object to be annotated.

  For code examples, see Annotating a Document and Annotating a Folder.

• For a document with multiple content elements, you can specify on which of the document's content elements to apply an annotation.
• You can set multiple annotations on a document, folder, or custom object.
• You can set an instance of an Annotation object on only one document, folder, or custom object.
• An annotation's content can be moved from one StorageArea to another. For a code example, see Moving Content to a Different Storage Area.
• Because annotations are not versionable, annotation content persisted to a storage area that becomes closed is no longer available to be modified or deleted on that storage area. To modify the annotation content, you must first explicitly move it to an open storage area. (This behavior contrasts with the content of documents, which are versionable. You change the storage policy of the document class from a closed to an open storage area, and new versions of the content are automatically saved to the open storage area.)
• For annotations on documents, an annotation is associated with a single document version only; the annotation is not versioned or carried over when the document version is updated.
• You can modify and delete an annotation independently of its annotated object. However, you cannot create and persist an annotation separately from the object with which it is associated.
• If you delete an annotated object, its annotations are also deleted.
• An annotation is independently securable. Its default security comes from both its class and from its annotated object. An annotation can optionally have a security policy that is assigned to it. For more information, see Security Policies.
• Annotations can be searched for and retrieved from an ad hoc query. For more information, see Queries. The FileNet P8 -supplied applications, such as IBM® Content Navigator, do not support searching for indexed annotation text. Doing so requires a custom application. For more information, see Working with Annotation Objects.
• An annotation can subscribe to server-side events that fire when an action such as creating an annotation occurs. For more information, see Subscription Concepts.
• Operations on an annotation can be audited. For more information, see Auditing Concepts.
• An annotation can participate in a link relationship. For more information, see the Link interface.
• You can work with an annotation's ClassDescription object as you would work with the class descriptions associated with other Content Engine objects. For example, you can perform the following tasks:
  • Return default security for an object of the class. For example, when you create a new Annotation object, you might want to determine whether the default security is appropriate for your application or you might display the default security in a user interface and allow the user to change the security.
  • Return the ClassDescription object's property descriptions, which are metadata objects that describe the Annotation object's properties. For example, when you create an annotation you might want to include code for retrieving a specific annotation's ClassDescription object and check which custom properties are required to be set.
  • Return the ClassDescription object's properties. For example, you might want to return the ClassDescription object's DisplayName property to display in a user interface from which the user can select a class.
  • Configure the default storage area (the file system or database where content is stored).
  • Retrieve a collection of ClassDescription objects that contain the base class and all subclasses.
  • Subclass the base Annotation class by using the Administration Console for Content Platform Engine or the Content Engine APIs. Note that the property description settings of the new class apply to new instances of the class, but not to existing instances. For code examples, see Creating an Annotation Subclass.
• Derived from the Annotation class is the ISAnnotation subclass that supports Content Federation Services for Image Services. This subclass is installed with the CFS-IS Extensions feature add-on. For more information about Content Federation Services for Image Services, see the Content Federation Services for Image Services overview topic in Content Engine Administration.
• Although it is not recommended, it is possible to programmatically copy an annotation from one document to another. Because the copied annotation is unchanged from the original, its content element retains the F_ID and F_ANNOTATEDID values of the original annotation. For a user to be able to modify and save the copied annotation on the new document, your code must also update the copied annotation’s content element (annotation.xml) with new GUIDs for F_ID and F_ANNOTATEDID.

  The following Java™ code snippet illustrates, at a high level, how to programmatically copy the annotation content and reset the IDs. The code snippet is not a complete program and is not intended to be run as is; before you use this code snippet, you must modify it for your environment:

  static public void copyAnnotations(ObjectStore os, Document oldDoc, Document newDoc) {
    AnnotationSet oldAnnos = oldDoc.get_Annotations();
    Iterator<Annotation> annoIter = oldAnnos.iterator();
    while (annoIter.hasNext()) {
        Annotation oldAnno = annoIter.next();
        ContentElementList oldCEs = oldAnno.get_ContentElements();
        ContentElementList newCEs = Factory.ContentElement.createList();
  
      Iterator<ContentElement> ceIter = oldCEs.iterator();
      while (ceIter.hasNext()) {
          ContentElement ce = ceIter.next();
              if (ce instanceof ContentTransfer) {
                  InputStream is = ((ContentTransfer)ce).accessContentStream();
  
                ContentTransfer ctNew = Factory.ContentTransfer.createInstance();
                ctNew.setCaptureSource(is);
  
                     // TODO update F_ANNOTATEDID and F_ID in ctNew
  
              newCEs.add(ctNew);                    
          }                
      }
  
      // Create new Annotation with copied content and associate it to new document
          Annotation newAnno = Factory.Annotation.createInstance(os, oldAnno.get_ClassDescription().get_Id().toString());
          newAnno.set_Permissions(oldAnno.get_Permissions());
          newAnno.set_ContentElements(newCEs);
          newAnno.set_AnnotatedObject(newDoc);
          newAnno.save(RefreshMode.REFRESH, null);            
      }
  }
   

For more conceptual information, see Annotations in the Content Engine Administration Help.