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:
// Create the Annotation object properties with the document.
com.filenet.wcm.api.Document doc; //this document has the annotation to be copied
com.filenet.wcm.api.Properties props = ObjectFactory.getProperties();
//Get the Annotation class property.
com.filenet.wcm.api.Property prop = ObjectFactory.getProperty(Property.ANNOTATED_OBJECT);
prop.setValue(doc);
props.add(prop);
// Get the annotation to be copied from the original document.
Annotation oldAnnotation; // get the annotation from the old document
Document d = oldAnnotation.getXMLDoc();
Element root = d.getDocumentElement();
Element propDesc = WcmXMLUtil.getChildElement(root, PROPDESC);
// Create a new Annotation object.
Annotation apiNote = (Annotation)objectStore.createObject(ClassDescription.ANNOTATION, props,
oldAnnotation.getPermissions());
String newGUID = apiNote.getId(); // Get the new ID.
// Set the new IDs and copy annotation content to a new document.
propDesc.setAttribute(F_ANNOTATEDID, newGUID);
propDesc.setAttribute(F_ID, newGUID);
apiNote.setContent(oldAnnotation.getContent());
For more conceptual information, see Annotations in the Content Engine Administration Help.