An instance of a Document
class or any of its subclasses is a Versionable object; that is, the object can have multiple versions associated with it. You create an initial version when you create and check in a new document, and you create a new, additional version when you check out and check in the existing document. Among the actions that you can take with a Versionable
object is to freeze the custom properties of a version, promote a minor version to a major version, and demote a major version to a minor version. You can also retrieve a VersionSeries object, which represents the complete set of versions of a document. The VersionSeries
object allows you to perform an action on all document versions collectively by issuing one call, like simultaneously moving the content for all document versions to a different location. And, as a convenience, the VersionSeries
class contains some methods and properties also contained by the Versionable
class, allowing you to work with either object to perform certain actions.
This topic provides an overview of the following Content Engine versioning concepts:
For additional information on Content Engine versioning, see the versioning-related topics in the Content Engine Administration Help. For versioning code examples, see Working with Versioning-related Objects.
The Content Engine provides support for three levels of versioning: no versioning enabled, single-level versioning, and two-level versioning. A document's class specifies whether documents assigned to the class are versioning-enabled. A Content Engine system administrator can change the "supports versioning" setting for a class (in either direction). However, changing a class' setting does not affect existing documents. In other words, the versionability of a document is bound at the time the initial version is created and never changes. Also, changing a document's class (either by the system administrator or via the Content Engine Java API's changeClass method) does not change the versionability of the document.
If versioning is disabled for a class (and therefore for a document of this
class), it means that you cannot perform versioning-related operations on the
document (such as checking the document into and out of an object store). There
will be a VersionSeries
object associated with the document, but there will be just one document version
in the version series. To check whether a document is versioning-enabled, retrieve the object's IsVersioningEnabled
property from its Document
or VersionSeries
interface. For additional information on versioning-disabled documents, see
About enabling versioning in the Content Engine Administration Help.
With single-level versioning, all documents are released (major) documents.
Two-level versioning supports both minor and major document versions. (A minor
version is typically a draft document that is not yet complete and, therefore,
not ready for a wider distribution.) Note that, if versioning is enabled for
a class, then both one- and two-level versioning are also enabled (that is,
there is nothing to configure to enable one- or two-level versioning). Your
application exposes the minor version feature of two-level versioning by calling
the checkin
method with the CheckinType
parameter set to MINOR_VERSION
. For additional
information on one- and two-level versioning, see
One-level versioning and
Two-level versioning in the Content Engine Administration Help.
Each version series has a major and a minor version number associated with
it that reflect the current version numbers for the version series — regardless of whether your application exposes single-level versioning or two-level versioning. For example,
if you check in the initial version of a document as a major version, its major
version number will be 1 and its minor will be 0 (thus, when combined and separated
with a decimal point, you could display them as 1.0). These numbers are specified
in the MajorVersionNumber
and MinorVersionNumber
properties
for a Versionable object. In the Content Engine Administration Help, see the Version
numbering topic on how the Content Engine assigns initial values and when it increments
and decrements those values.
Each document version has a version status associated with it that reflects
whether the document is a reservation
object, a superseded document, or the current released document. If your
application exposes two-level versioning, then a document version could also
have a status of in-process. This status is specified in a Versionable object's
VersionStatus property
. For detailed definitions,
see
Version Status in the Content Engine Administration Help. For the effect on version status from document-related actions, see Versioning Actions.
As mentioned above, a document version has a status associated with it. Based on version status, security can automatically be applied to the various versions of a document. For example, you may want different access rights for the in-process version than for the superseded versions of a document. You control version security with the VersioningSecurityTemplate class. For more information on how the Content Engine APIs expose this functionality, see Security Policies.
There are also security considerations when performing operations on a reservation object, such as checking in a document and canceling a checkout.
When you create a new document or check out an existing document, the Content Engine
server creates a reservation object. This object essentially records the intention
to check in the document. A reservation object is not a separate class of object,
but rather is the new, unchecked-in version of the document. If a document is
a reservation object, the value of its VersionStatus
property is VersionableStatus.RESERVATION
.
A reservation object can be collaborative (anyone with appropriate permissions
can check in, modify, or delete the reservation), or exclusive (only the creator
of the reservation can check in, modify, or — with one exception, explained below — delete
the reservation). The default reservation behavior is defined at the object
store level via the ObjectStore object's DefaultReservationType
property. (Note
that when a new object store is created, this property is initialized to exclusive.)
An initial reservation object — the reservation object created when you create
a new document — uses the default reservation type. For an existing document,
you can specify whether a reservation should be collaborative, exclusive, or
use the default type when you call the checkout
method on
a Versionable
object.
For an exclusive reservation object, the Content Engine performs the check for the reservation owner before the normal security access checks; the reservation owner is not granted any additional rights by virtue of having created the reservation. No one but the reservation owner can change the reservation object's class, check in the reservation, or perform property modifications that require WRITE permission. The owner must also have the appropriate access rights to check in a document (RIGHT_MINOR_VERSION to check in a minor version, RIGHT_MAJOR_VERSION to check in a major version), Modifications to security properties, which require either WRITE_ACL or WRITE_OWNER permission, are allowed subject to the normal access checks. In addition, deleting the reservation object (by canceling a checkout) is disallowed except to the reservation owner and to anyone with WRITE_OWNER and DELETE permissions.
After you create a new document or check out an existing document, the returned reservation object initially has no content associated with it. If you want to associate one or more content elements with the document, you must set the content before you check in the document. Also, if you want to explicitly set the value of the Document object's MimeType property (as opposed to having the Content Engine automatically set its value), you must set the value before you check in the document. Note that you can file an initial reservation object into a folder.