FileNet Content Services
Java Connector v3.0

com.filenet.wcm.api
Interface VersionableObject

All Superinterfaces:
BaseObject, java.io.Serializable, ValueObject
All Known Subinterfaces:
Document, Document, PublishTemplate, StoredSearch, VersionSeries, WorkflowDefinition

public interface VersionableObject
extends BaseObject

An object implementing the VersionableObject interface is an object that can be versioned; that is, multiple versions of the object can exist in a Content Services object store (library). A new version of an object is formed by a check-in operation.

The two BaseObject objects that implement this interface are the Document and VersionSeries objects. When operations defined on the VersionableObject interface are performed on the VersionSeries object, the operations are performed on the current document version of the version series (which is the most recently created document in the series).

Note that a Content Services system administrator can specify whether a document class is enabled for versioning. You can check the VersionSeries object to see if the object is enabled for versioning.

See Also:
CS Java Connector Developer's Guide

Field Summary
static java.lang.String APPLY_STATE_ID_IN_PROCESS
          Value of "{E76E4F72-545C-4180-97C1-8449883B83CF}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the InProcess state.
static java.lang.String APPLY_STATE_ID_RELEASED
          Value of "{95AD7AED-DFA0-4459-AE95-2CA2FC041602}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the Released state.
static java.lang.String APPLY_STATE_ID_RESERVATION
          Value of "{F9ED916D-CCB7-4D7E-8CC1-563F1692C67C}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the Reservation state.
static java.lang.String APPLY_STATE_ID_SUPERSEDED
          Value of "{A0A5A26E-D19F-4415-8451-6795386AD1BB}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the Superseded state.
static int RESERVATION_TYPE_COLLABORATIVE
          

Not Implemented in CS Java Connector v3.0.

static int RESERVATION_TYPE_DEFAULT
          

Not Implemented in CS Java Connector v3.0.

static int RESERVATION_TYPE_EXCLUSIVE
          

Not Implemented in CS Java Connector v3.0.

static int VERSION_STATUS_IN_PROCESS
          Value of 2; document version is in an in-process status.
static int VERSION_STATUS_RELEASED
          Value of 1; document version is in a released status.
static int VERSION_STATUS_RESERVATION
          Value of 3; document version is in a reservation status.
static int VERSION_STATUS_SUPERSEDED
          Value of 4; document version is in a superseded status.
 
Fields inherited from interface com.filenet.wcm.api.BaseObject
EXPORT_DEFAULT, EXPORT_ENCODED_CONTENT, EXPORT_FULL, EXPORT_OBJECT_ID, EXPORT_OBJECT_SECURITY, IMPORT_DEFAULT, IMPORT_OBJECT_ID, IMPORT_OWNER, IMPORT_PERMISSIONS, TYPE_ACTIVE_MARKING, TYPE_ANNOTATION, TYPE_ANY, TYPE_CBR_ENGINE_TYPE, TYPE_CHOICE, TYPE_CHOICELIST, TYPE_CLASS_SUBSCRIPTION, TYPE_CLASSDEFINITION, TYPE_CLASSDESCRIPTION, TYPE_COLUMN_DEFINITION, TYPE_COMPUTER, TYPE_CONTENT_CACHE_SERVICE, TYPE_CONTENT_MGR_SERVICE, TYPE_CONTENT_REFERENCE, TYPE_CONTENT_TRANSFER, TYPE_CUSTOMOBJECT, TYPE_DOCUMENT, TYPE_DOCUMENT_CLASSIFICATION_ACTION, TYPE_DOCUMENT_LIFECYCLE_ACTION, TYPE_DOCUMENT_LIFECYCLE_POLICY, TYPE_DOCUMENTSTATE, TYPE_DOMAIN, TYPE_DYNAMIC_REFERENTIAL_CONTAINMENT_RELATIONSHIP, TYPE_ENTIRENETWORK, TYPE_EVENT, TYPE_EVENT_ACTION, TYPE_FEATURE_ADD_ON, TYPE_FILESTORE, TYPE_FOLDER, TYPE_GROUP, TYPE_INSTANCE_SUBSCRIPTION, TYPE_LINK, TYPE_LOCALIZED_STRING, TYPE_MARKING_SET, TYPE_MULTIPLEVALUES, TYPE_OBJECT_STORE, TYPE_OBJECTSET, TYPE_OBJSTORE_SERVICE, TYPE_PERMISSION, TYPE_PROPERTY_DEFINITION, TYPE_PROPERTYDESCRIPTION, TYPE_PROPERTYDESCRIPTIONS, TYPE_PUBLISH_REQUEST, TYPE_PUBLISH_TEMPLATE, TYPE_READONLY_OBJECT_SET, TYPE_REALM, TYPE_REFERENTIAL_CONTAINMENT_RELATIONSHIP, TYPE_SECURITY_POLICY, TYPE_SECURITY_TEMPLATE, TYPE_STORAGE_POLICY, TYPE_STORED_SEARCH, TYPE_STYLE_TEMPLATE, TYPE_SUBSCRIPTION, TYPE_TABLE_DEFINITION, TYPE_TRANSIENT, TYPE_USER, TYPE_VERSIONSERIES, TYPE_WORKFLOW_CLASS_SUBSCRIPTION, TYPE_WORKFLOW_INSTANCE_SUBSCRIPTION, TYPE_WORKFLOWDEFINITION, TYPE_XML_PROPERTY_MAPPING_SCRIPT
 
Method Summary
 void cancelCheckout()
          Cancels the checkout of this VersionableObject object by deleting the reservation object associated with it.
 void checkin(boolean autoClassify)
          Checks in this VersionableObject object.
 void checkin(boolean autoClassify, boolean minorVersion)
          

Not Implemented in CS Java Connector v3.0.

 Document checkout()
          Checks out this VersionableObject object by creating a reservation object and returning a reference to it.
 Document checkout(int checkoutFlags)
          

Not Implemented in CS Java Connector v3.0.

 void demoteVersion()
          

Not Implemented in CS Java Connector v3.0.

 void freeze()
          

Not Implemented in CS Java Connector v3.0.

 Document getReservation()
          Returns the reservation object for this VersionableObject object's version series.
 Documents getVersions()
          Returns a collection of all document versions of this VersionableObject object that the user has permission to view.
 Documents getVersions(java.lang.String[] propNames)
          Returns a collection of all document versions of this VersionableObject object -- along with their requested properties -- that the user has permission to view.
 void promoteVersion()
          

Not Implemented in CS Java Connector v3.0.

 
Methods inherited from interface com.filenet.wcm.api.BaseObject
equals, exportObject, getClassId, getId, getName, getObjectStoreId, getObjectType, getSession, hashCode, thisBaseObject
 

Field Detail

VERSION_STATUS_RELEASED

public static final int VERSION_STATUS_RELEASED
Value of 1; document version is in a released status.

See Also:
Constant Field Values

VERSION_STATUS_IN_PROCESS

public static final int VERSION_STATUS_IN_PROCESS
Value of 2; document version is in an in-process status.

See Also:
Constant Field Values

VERSION_STATUS_RESERVATION

public static final int VERSION_STATUS_RESERVATION
Value of 3; document version is in a reservation status.

See Also:
Constant Field Values

VERSION_STATUS_SUPERSEDED

public static final int VERSION_STATUS_SUPERSEDED
Value of 4; document version is in a superseded status.

See Also:
Constant Field Values

APPLY_STATE_ID_RESERVATION

public static final java.lang.String APPLY_STATE_ID_RESERVATION
Value of "{F9ED916D-CCB7-4D7E-8CC1-563F1692C67C}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the Reservation state.

See Also:
Constant Field Values

APPLY_STATE_ID_IN_PROCESS

public static final java.lang.String APPLY_STATE_ID_IN_PROCESS
Value of "{E76E4F72-545C-4180-97C1-8449883B83CF}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the InProcess state.

See Also:
Constant Field Values

APPLY_STATE_ID_RELEASED

public static final java.lang.String APPLY_STATE_ID_RELEASED
Value of "{95AD7AED-DFA0-4459-AE95-2CA2FC041602}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the Released state.

See Also:
Constant Field Values

APPLY_STATE_ID_SUPERSEDED

public static final java.lang.String APPLY_STATE_ID_SUPERSEDED
Value of "{A0A5A26E-D19F-4415-8451-6795386AD1BB}"; unique identifier of the ApplyStateID for the Versioning Security Template used for the Superseded state.

See Also:
Constant Field Values

RESERVATION_TYPE_DEFAULT

public static final int RESERVATION_TYPE_DEFAULT

Not Implemented in CS Java Connector v3.0.

Value of 0; specifies a default reservation type, which is the configurable default (either collaborative or exclusive) for the object store.

See Also:
Constant Field Values

RESERVATION_TYPE_COLLABORATIVE

public static final int RESERVATION_TYPE_COLLABORATIVE

Not Implemented in CS Java Connector v3.0.

Value of 16; specifies a collaborative reservation type, which means that anyone with appropriate permissions can operate on the reservation.

See Also:
Constant Field Values

RESERVATION_TYPE_EXCLUSIVE

public static final int RESERVATION_TYPE_EXCLUSIVE

Not Implemented in CS Java Connector v3.0.

Value of 32; specifies an exclusive reservation type, which means that the reservation owner has exclusive rights to the reservation.

See Also:
Constant Field Values
Method Detail

checkout

public Document checkout()
Checks out this VersionableObject object by creating a reservation object and returning a reference to it. A checkout operation essentially reserves the right to check in the next version of a document in the document's version series. If the object implementing the VersionableObject interface is a VersionSeries object, then this method checks out the appropriate document in the version series.

To successfully check out a document, the document must be the current version (its IsCurrentVersion property is true), must not be already checked out (IsReserved is false), and its class must be versioning-enabled (IsVersioningEnabled is true). Also, the user must have appropriate access rights.

Note that the reservation object initially has no content associated with it. If you want to associate content with the checked-out document, you must set the content before you check the document back in. If you do not set any content before you check the document in, the new version of the document will not have any content associated with it.

After a successful call to checkout, the Content Services will apply the Versioning Security Template for the Reservation state (if it exists and is enabled) to the newly-created reservation object. The IsReserved property of this VersionableObject object is set to true. If the object implementing the VersionableObject interface is a VersionSeries object, the IsReserved property for the appropriate Document object is also set to true. Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the CS Java Connector to retrieve fresh data from the Content Services server.

Returns:
A Document object that represents the reservation object.

checkout

public Document checkout(int checkoutFlags)

Not Implemented in CS Java Connector v3.0.

Checks out this VersionableObject object by creating a reservation object of the specified type and returning a reference to it. A checkout operation essentially reserves the right to check in the next version of a document in the document's version series. If the object implementing the VersionableObject interface is a VersionSeries object, then this method checks out the appropriate document in the version series.

Specify the type of reservation to return in the checkoutFlags parameter using one of the RESERVATION_TYPE_ constants defined in this interface:

To successfully check out a document, the document must be the current version (its IsCurrentVersion property is true), must not be already checked out (IsReserved is false), and its class must be versioning-enabled (IsVersioningEnabled is true). Also, the user must have appropriate access rights (Permission.RIGHT_MINOR_VERSION to check out a minor version, Permission.RIGHT_MAJOR_VERSION to check out a released version).

Note that the reservation object initially has no content associated with it. If you want to associate content with the checked-out document, you must set the content before you check the document back in. If you do not set any content before you check the document in, the new version of the document will not have any content associated with it.

After a successful call to checkout, the Content Services will apply the Versioning Security Template for the Reservation state (if it exists and is enabled) to the newly-created reservation object. The IsReserved property of this VersionableObject object is set to true, and its ReservationType property is set to the appropriate type (collaborative or exclusive). If the object implementing the VersionableObject interface is a VersionSeries object, the IsReserved property for the appropriate Document object is also set to true. Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the Content Services Java Connector to retrieve fresh data from the Content Services server.

Parameters:
checkoutFlags - Specifies the type of reservation to return. Use one of the RESERVATION_TYPE_ constants defined in this interface.

Returns:
A Document object that represents the reservation object.


checkin

public void checkin(boolean autoClassify)
Checks in this VersionableObject object.

If the object implementing the VersionableObject interface is a Document object (or one of its subclasses), you call the checkin method on the Document object that represents the reservation object. If the object implementing the VersionableObject interface is a VersionSeries object, this method checks in the appropriate document in the version series (the document that represents the reservation object).

Before you check in a document that has content, you must set the content for the document by calling setContent.

After a successful check-in, the reservation object becomes the new current version of the document (its IsCurrentVersion property is set to true). Also, its VersionStatus property is set to VersionableObject.VERSION_STATUS_RELEASED. If the object implementing the VersionableObject interface is a VersionSeries object, its IsReserved property is set to false. Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the Content Services Java Connector to retrieve fresh data from the Content Services server.

Note that the Document interface's setContent method has a parameter you can set to check in a document after setting its content without making an additional roundtrip to the server.

Parameters:
autoClassify - Requires a boolean value; however, the value is ignored by the CS Java Connector.


checkin

public void checkin(boolean autoClassify,
                    boolean minorVersion)

Not Implemented in CS Java Connector v3.0.

Checks in this VersionableObject object. Specify true in the minorVersion parameter to check in a minor version; if false, this method checks in a major version.

If the object implementing the VersionableObject interface is a Document object (or one of its subclasses), you call the checkin method on the Document object that represents the reservation object. If the object implementing the VersionableObject interface is a VersionSeries object, this method checks in the appropriate document in the version series (the document that represents the reservation object).

If the reservation object is an exclusive reservation (the object's ReservationType property is set to VersionableObject.RESERVATION_TYPE_EXCLUSIVE), then to check in the document the user must be the reservation owner. (The value of the reservation object's Creator property is the reservation owner.) Regardless of whether the reservation object is an exclusive or a collaborative reservation, the user must also have the appropriate access rights to check in the document (Permission.RIGHT_MINOR_VERSION to check in a minor version, Permission.RIGHT_MAJOR_VERSION to check in a major version).

Before you check in a document that has content, you must set the content for the document by calling setContent if the content is stored in a Content Services server or setContentReference if the content is stored externally.

After a successful check-in, the reservation object becomes the new current version of the document (its IsCurrentVersion property is set to true). If the object implementing the VersionableObject interface is a VersionSeries object, its IsReserved property is set to false. Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the CS Java Connector to retrieve fresh data from the Content Services server.

The autoClassify parameter specifies whether the document should have automatic document classification enabled. (This feature is not supported for stored searches and publish templates.) If true, and if the Content Services server's system administrator has configured automatic document classification, the document will automatically be assigned the proper document class and populated with document metadata properties based on the document content (and, in the case of XML document classification, mapping rules from user-defined scripts).

The Content Services server's Classification Service uses a document's MIME type to determine if there is a Classifier capable of parsing the document. Before you call the checkin method, you can return a list of MIME types supported by Classifiers registered for an object store by calling the ObjectStore interface's getClassifierMimeTypes method, then test that a Classifier exists for the document's MIME type.

If you set the autoClassify parameter to true, the checkin operation changes the value of the document's ClassificationStatus property to 1 (classification pending); if set to false, the property is set to 0 (not classified).

Note that the Document interface's setContent method has a parameter you can set to check in a document after setting its content without making an additional roundtrip to the server.

Parameters:
autoClassify - true if automatic document classification should be enabled for the document; otherwise false. For a stored search or publish template, a setting of true is ignored and is automatically set to false.

minorVersion - true if the document should be checked in as a minor version; otherwise false.


cancelCheckout

public void cancelCheckout()
Cancels the checkout of this VersionableObject object by deleting the reservation object associated with it. The user must have appropriate permission on the reservation object to cancel the checkout.

If the object implementing the VersionableObject interface is a Document object, this method throws an exception if the document is not checked out or if the document is a newly-created object that has never been checked in.

If the object implementing the VersionableObject interface is a VersionSeries object, this method throws an exception if a document in the VersionSeries object is not checked out.

After a successful cancel-checkout operation, the IsReserved property for the object implementing the VersionableObject interface is set to false. Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the CS Java Connector to retrieve fresh data from the Content Services server.


getVersions

public Documents getVersions()
Returns a collection of all document versions of this VersionableObject object that the user has permission to view. If this VersionableObject object is checked out, the last element in the returned collection is the reservation object.

The following properties are returned with each document in the collection: idmDocCurVerNum, idmAddedByGroup, idmVerDocId, idmAnnotation, idmVerFileName, idmDateAdded, idmName, idmPublish, idmVWVersion, idmVerCheckoutPending, idmVerCheckinUser, idmSearch, idmCDBehaviorId,idmVerReclaimPending, idmVerPermanent, idmDocOwner, idmDocType, idmAddedByUser, idmDocProtected, idmComment, idmDateAccessed, idmId, idmVerAvailStat, idmDocCurVerDate,idmVerCreateDate, idmVerCD, idmVerId,idmFilterQuery,idmVerCsiStatus.

To return other properties, call the getVersions(propNames) form of this method.

Returns:
A Documents collection containing all the Document objects in this VersionableObject object's version series.

getVersions

public Documents getVersions(java.lang.String[] propNames)
Returns a collection of all document versions of this VersionableObject object -- along with their requested properties -- that the user has permission to view. If this VersionableObject object is checked out, the last element in the returned collection is the reservation object.

Specify the properties to return in the propNames array. If you specify a property and the property doesn't exist for this VersionableObject object, the property is ignored (no exception is thrown). If the propNames parameter is null or an empty array, this method retrieves an initial set of hard-coded properties. However, because this set can vary from release to release, we recommend you specify the properties your application requires in the propNames array.

Parameters:
propNames - A String array whose elements specify the symbolic names of the properties to retrieve. (If you pass in a null, you must first explicitly cast it to a String[] to avoid a compilation error.)

Returns:
A Documents collection containing all the Document objects in this VersionableObject object's version series.

getReservation

public Document getReservation()
Returns the reservation object for this VersionableObject object's version series. If the current version is not checked out, this method returns null.

Note that if you call this method on a Document object that is a reservation object, this method returns a reference to this same reservation object, but it will be a distinct instance of the object. To avoid this, check the value of Property.IS_RESERVED on the Document object before calling getReservation. If the property's value is true, you do not need to call getReservation because you already have the reservation object.

Returns:
A Document object that represents the reservation object for this VersionableObject object's version series; returns null if the current version is not checked out.


freeze

public void freeze()

Not Implemented in CS Java Connector v3.0.

Freezes this VersionableObject object, preventing further changes to properties (but not content) of the document version. (Note, however, that system-maintained properties of a frozen document version will continue to be updated by the system as necessary.) If the object implementing the VersionableObject interface is a VersionSeries object, this method freezes the current released version (or, if none exists, the current version) in the version series. If it is a Document object or a subclass (including PublishTemplate, StoredSearch, or WorkflowDefinition), you can freeze any document version but the object must be checked in. You cannot freeze a reservation object. After a successful call to freeze, the IsFrozenVersion property of the object representing the document version is set to true.

Once you freeze a version of an object, you cannot unfreeze it. To change the object's custom properties, you must create a new version of the object.


promoteVersion

public void promoteVersion()

Not Implemented in CS Java Connector v3.0.

Converts this VersionableObject object into a released major version. If the object implementing the VersionableObject interface is a VersionSeries object, this method promotes the appropriate document in the version series. To successfully promote a document, the document must be the latest minor version (its VersionStatus property is VersionableObject.VERSION_STATUS_IN_PROCESS) and must be the current version (IsCurrentVersion is true). Also, the user must have appropriate access rights (Permission.RIGHT_MAJOR_VERSION). Note that you can promote a frozen version as well as an object that is not versioning-enabled (in other words, the value of its IsVersioningEnabled property is false).

After a successful call to promoteVersion, the Content Services will apply the Versioning Security Template for the Released state (if it exists and is enabled) to the document being promoted. It will also apply the Security Template for the Superceded state to the previous major version that is being superceded. The MinorVersion property of this VersionableObject object is set to 0, the MajorVersion property is incremented, and the VersionStatus is set to VersionableObject.VERSION_STATUS_RELEASED. The VersionStatus property for the previous major version is set to VersionableObject.VERSION_STATUS_SUPERSEDED. Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the CS Java Connector to retrieve fresh data from the Content Services server.


demoteVersion

public void demoteVersion()

Not Implemented in CS Java Connector v3.0.

Demotes this VersionableObject object to a minor version. This method provides a way to demote the status of the latest major version to become a minor version if, for example, an error was found in the latest major version. This method changes the previous major version (if it exists) to become the current released major version, but does not delete any versions (including content) from the version series. This allows you to continue to have access to all version changes.

If the object implementing the VersionableObject interface is a VersionSeries object, this method demotes the appropriate document in the version series. To successfully demote a document, the document must be the latest major version (its VersionStatus property is VersionableObject.VERSION_STATUS_RELEASED), must be the current version (IsCurrentVersion is true), and the user must have appropriate access rights (Permission.RIGHT_MAJOR_VERSION). If the document has a reservation on it (IsReserved is true), this method will throw an exception. Note that you can demote a frozen version as well as an object that is not versioning-enabled (in other words, the value of its IsVersioningEnabled property is false).

After a successful call to demoteVersion, the Content Services will apply the Versioning Security Template for the In Process state (if it exists and is enabled) to the document being demoted. It will also apply the Security Template for the Released state to the previous major version (if one exists). Also, the following properties are considered stale and are removed from cache for this VersionableObject object:

A subsequent request for any of these properties causes the CS Java Connector to retrieve fresh data from the Content Services server.


FileNet Content Services
Java Connector v3.0