The Unified API provides a common superinterface for all persistent entities: CapObject. A CapObject can be thought of as being contained by a repository. Within that repository, it is made unique by an identifier. The available object classes have already been named in this text: folders and documents, users and groups, processes and tasks.

Folders and documents are jointly presented through the interface Content. Documents may exist in more than one Version. The Version and Content interfaces are subsumed under the ContentObject interface. Likewise, User and Group objects share a common superinterface Member and the interfaces Process, Task and WorkflowView are derived from the interface WorkflowObject. All of these interfaces extend CapObject.

Two CapObjects refer to the same persistent entity if they are equal as per Object.equals(Object). In general, there may be more than one Java object for the same persistent entity.

Caution

Never compare two objects of the Unified API using the == operator. This operator will typically return false even though two objects refer to the same persistent entity. Always use object equality instead.

CapObjects are also providing access to properties of that object. To that end, CapObject extends the interface CapStruct, which defines a generic abstraction of an entity with named properties of various types.

You can obtain either a map with all properties or individual property values using the getters of a CapStruct. When getting a map, an immutable snapshot of the object's properties is returned. When getting one property value multiple times, however, concurrent writes will be visible immediately.

All structs provide a struct type through the method getType(). The type is immutable and constitutes a model of the possible property values for the struct. Properties can themselves be of different types as will be described in Section 4.5, “Types”. There are typed getter methods for returning the current values of properties. If a typed getter is applied to a property with a different type, the Unified API specifies an automatic conversion in many cases. Please see the Javadoc of CapStruct for details. If there is no possible conversion algorithm, an exception is thrown.

When setting a property of a CapObject, make sure that you use a value that is appropriate for the property type used, because no automatic conversion takes place.

The values returned by a getter are always immutable. In the case of String or Integer objects this is obvious, but it is even true for collection-valued properties that return an instance of java.util.List. When you want to modify a collection-valued property, you have to create a new collection and set that entire collection as the new value. Modifying the returned value is not possible.

Having set any property of a CapObject, that change is not immediately made persistent on the server-side. Changes are collected until either an operation occurs that cannot be delayed or the method CapConnection.flush() is called on the current connection. See also Section 4.9, “Sessions” for details about the session handling.