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
|
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.