Working with Versioning-related Objects

This topic provides the following versioning-related code examples:

For examples on using security templates with document versions, see Working with Security Policies.

For an overview of versioning, see Versioning Concepts.

Adding Document Versions

The following Java and C# examples show how to add two versions to an existing document. (For examples on creating a new document, see Creating a Document Object.) You can create a version from a Document object (or any of its subclasses), or a VersionSeries object. In the examples, the first version is created from the Document object, on which the checkout method is called and from which the reservation object is retrieved. The second version is created from the VersionSeries object, which is retrieved from the Document object. Properties of the VersionSeries object are returned to print information about the versions.

Note that the first version is checked in as a minor version and has no content, whereas the second version is checked in as a major version and contains content. The autoClassify parameter of the checkin method specifies whether auto-classification should be enabled for the document. For more information on auto-classification, see Document Classification Concepts. For more information on adding content, see Document Content.

After a successful check-in, the reservation object becomes the new current version of the document. If versioning security templates exist and are enabled, the Content Engine will apply the appropriate template to the current document version and to any previous document versions whose VersionStatus state changes as a result of the check-in. See Security Policies for details on versioning security templates. For information on version status changes, see Checkin in the Content Engine Administration Help.

In addition, the values of a number of other properties change after a successful check-in. (The value of the document's Id property remains the same.) For example, the value of the IsReserved property for the current version, the previous version, and the VersionSeries object is set to false. The value of IsCurrentVersion is set to true for the current version, and set to false for the previous version. The value of ReservationType is unset. To retrieve these properties, see Working with Versioning Properties.

Java Example

// Add the first of two new versions.
// This version will have no content.
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}") );

// Check out the Document object and save it.
doc.checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null);
doc.save(RefreshMode.REFRESH);		

// Get the reservation object from the Document object.
Document reservation = (Document) doc.get_Reservation();

// Check in reservation object as minor version
reservation.checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MINOR_VERSION);
reservation.save(RefreshMode.REFRESH);
////////////////////////////////////////////////////////////////////

// Add the second of two new versions.
// This version will have content.
VersionSeries verSeries = doc.get_VersionSeries();

// Print information about new version 1 of 2
Versionable version = verSeries.get_CurrentVersion();
System.out.println("Status of current version: " + version.get_VersionStatus().toString() +
   "\n Number of current version: " + version.get_MajorVersionNumber() +"."+ version.get_MinorVersionNumber() );

// Check out the VersionSeries object and save it.
verSeries.checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null);
verSeries.save(RefreshMode.REFRESH);

// Get the reservation object from the VersionSeries object.
reservation = (Document) verSeries.get_Reservation();

// Add content to reservation object
File file = new File("C:\\officePolicy.doc");
try {
   //Create a ContentTransfer object
   ContentTransfer ctObject = Factory.ContentTransfer.createInstance();
   FileInputStream fileIS = new FileInputStream(file.getAbsolutePath());
   ContentElementList contentList = Factory.ContentTransfer.createList();
   ctObject.setCaptureSource(fileIS);
   // Add ContentTransfer object to list and set on reservation
   contentList.add(ctObject);
   reservation.set_ContentElements(contentList);
}
catch (Exception e)
{
   System.out.println(e.getMessage() );
}
 
// Check in reservation object as major version
reservation.checkin(null, CheckinType.MAJOR_VERSION);
reservation.save(RefreshMode.REFRESH);
 
// Print information about new version 2 of 2
version = verSeries.get_CurrentVersion();
System.out.println("Status of current version: " + version.get_VersionStatus().toString() +
   "\n Number of current version: " + version.get_MajorVersionNumber() +"."+ version.get_MinorVersionNumber() );

C# Example

// Add the first of two new versions.
// This version will have no content.
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}"));

// Check out the Document object and save it.
doc.Checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null);
doc.Save(RefreshMode.REFRESH);

// Get the reservation object from the Document object.
IDocument reservation = (IDocument)doc.Reservation;

// Check in reservation object as minor version
reservation.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MINOR_VERSION);
reservation.Save(RefreshMode.NO_REFRESH);
////////////////////////////////////////////////////////////////////

// Add the second of two new versions.
// This version will have content.
IVersionSeries verSeries = doc.VersionSeries;

// Print information about new version 1 of 2
IVersionable version = verSeries.CurrentVersion;
System.Console.WriteLine("Status of current version: " + version.VersionStatus.ToString() +
   "\n Number of current version: " + version.MajorVersionNumber +"."+ version.MinorVersionNumber );

// Check out the VersionSeries object and save it.
verSeries.Checkout(ReservationType.OBJECT_STORE_DEFAULT, null, null, null);
verSeries.Save(RefreshMode.REFRESH);

// Get the reservation object from the VersionSeries object.
reservation = (IDocument)verSeries.Reservation;

// Add content to reservation document
Stream fileStream = File.OpenRead(@"C:\\BootstrapConfigUtility.bat");
// Create ContentTransfer object
IContentTransfer ctObject = Factory.ContentTransfer.CreateInstance();
IContentElementList contentList = Factory.ContentTransfer.CreateList();
ctObject.SetCaptureSource(fileStream);
// Add ContentTransfer object to list and set on reservation
contentList.Add(ctObject);
reservation.ContentElements = contentList;

// Check in reservation object as major version
reservation.Checkin(AutoClassify.DO_NOT_AUTO_CLASSIFY, CheckinType.MAJOR_VERSION);
reservation.Save(RefreshMode.REFRESH);

// Print information about new version 2 of 2
version = verSeries.CurrentVersion;
System.Console.WriteLine("Status of current version: " + version.VersionStatus.ToString() +
   "\n Number of current version: " + version.MajorVersionNumber +"."+ version.MinorVersionNumber );

Canceling a Checkout

The following Java and C# examples show how to cancel a checkout on a document.

Java Example

// Create Document instance and check it out
Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, 
      new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}") );
doc.checkout(ReservationType.EXCLUSIVE, null, null, null);
doc.save(RefreshMode.REFRESH);

// Get the reservation object
Document reservation = (Document) doc.get_Reservation();

// Cancel checkout on Document object and
// save the reservation object
doc.cancelCheckout(); 
reservation.save(RefreshMode.REFRESH);

C# Example

// Create IDocument instance and check it out
IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, 
      new Id("{D6DCDE1F-EF67-4A2E-9CDB-391999BCE8E5}") );
doc.Checkout(ReservationType.EXCLUSIVE, null, null, null);
doc.Save(RefreshMode.REFRESH);

// Get the reservation object
IDocument reservation = (IDocument)doc.Reservation;

// Cancel checkout on IDocument object and
// save the reservation object
doc.CancelCheckout();
reservation.Save(RefreshMode.REFRESH);

Retrieving a VersionSeries Object

The following Java and C# examples show how to retrieve a VersionSeries object from a document. The VersionSeries object allows you to perform an action on all document versions collectively by issuing one call. In this example, the moveContent method moves the content for all the document versions to a different storage location.

Java Example

// Get document and put VersionSeries object in property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null)); 
Document doc = Factory.Document.fetchInstance(os, "{393472DA-7958-48CF-8C9F-7EA0E6B25678}",pf );

// Get VersionSeries object
VersionSeries verSeries = doc.get_VersionSeries();

// Get the storage area where you want to move the document content
FileStorageArea fsa = Factory.FileStorageArea.fetchInstance(os, new Id("{DE42374D-B04B-4F47-A62E-CAC9AC9A5719}"), null );

// Move content
verSeries.moveContent(fsa);
verSeries.save(RefreshMode.REFRESH);

C# Example

// Get document and put IVersionSeries object in property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null));
IDocument doc = Factory.Document.FetchInstance(os, "{393472DA-7958-48CF-8C9F-7EA0E6B25678}", pf);

// Get IVersionSeries object
IVersionSeries verSeries = doc.VersionSeries;

// Get the storage area where you want to move the document content
IFileStorageArea fsa = Factory.FileStorageArea.FetchInstance(os, new Id("{DE42374D-B04B-4F47-A62E-CAC9AC9A5719}"), null);

// Move content
verSeries.MoveContent(fsa);
verSeries.Save(RefreshMode.REFRESH);

Deleting a VersionSeries Object

The following Java and C# examples show how to delete a VersionSeries object. When the object is deleted, the document that contains the VersionSeries object is also deleted.

Java Example

// Get document and put VersionSeries object in property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null)); 
Document doc = Factory.Document.fetchInstance(os, "{3488C44F-D4BB-455F-AEED-553E9EADCC4E}", pf );

// Get VersionSeries object
VersionSeries verSeries = doc.get_VersionSeries();

// Delete VersionSeries object
verSeries.delete();
verSeries.save(RefreshMode.REFRESH);

C# Example

// Get document and put IVersionSeries object in property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSION_SERIES, null));
IDocument doc = Factory.Document.FetchInstance(os, "{3488C44F-D4BB-455F-AEED-553E9EADCC4E}", pf);

// Get VersionSeries object
IVersionSeries verSeries = doc.VersionSeries;

// Delete VersionSeries object
verSeries.Delete();
verSeries.Save(RefreshMode.REFRESH);

Working with Versioning Properties

The following Java and C# examples show how to retrieve properties from all of the versions of a Versionable object, in this case a document. The code gets the document's Versions property, iterates the VersionSet object, and prints numbering and status information about each version.

Java Example

// Get document and put Versionable object in property cache
PropertyFilter pf = new PropertyFilter();
pf.addIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSIONS, null)); 
Document doc = Factory.Document.fetchInstance(os, "{9B289B8A-DDD9-42DC-9D51-6B485509B68A}",pf );

// Return all document versions
VersionableSet versions = doc.get_Versions();
Versionable version;

// Iterate the set and print information about each version
Iterator iter = versions.iterator();
while (iter.hasNext() )
{
   version = (Versionable)iter.next();
   System.out.println("Status of version: " + version.get_VersionStatus().toString() +
      "\nNumber of current version: " + version.get_MajorVersionNumber() +"."+ version.get_MinorVersionNumber() +
      "\nIs reserved: " + version.get_IsReserved() +
      "\nIs current version: " + version.get_IsCurrentVersion() + 
      "\nIs frozen version: " + version.get_IsFrozenVersion() +
      "\n----------------------"
   );
}

C# Example

// Get document and put IVersionable object in property cache
PropertyFilter pf = new PropertyFilter();
pf.AddIncludeProperty(new FilterElement(null, null, null, PropertyNames.VERSIONS, null));
IDocument doc = Factory.Document.FetchInstance(os, "{9B289B8A-DDD9-42DC-9D51-6B485509B68A}", pf);

// Return all document versions
IVersionableSet versions = doc.Versions;
IVersionable version;

// Iterate the set and print information about each version
System.Collections.IEnumerator iter = versions.GetEnumerator();
while (iter.MoveNext() )
{
   version = (IVersionable)iter.Current; 
   System.Console.WriteLine("Status of version: " + version.VersionStatus.ToString() +
      "\nNumber of current version: " + version.MajorVersionNumber +"."+ version.MinorVersionNumber +
      "\nIs reserved: " + version.IsReserved +
      "\nIs current version: " + version.IsCurrentVersion + 
      "\nIs frozen version: " + version.IsFrozenVersion +
      "\n----------------------"
   );
}

Demoting an Object

The following Java and C# examples show how to use the demoteVersion method to demote a major version to a minor version. To successfully demote a document, the document must be the latest major version (the value of its VersionStatus property is RELEASED), must be the current version (IsCurrentVersion is true), and must not currently have a reservation on it (IsReserved is false).

After a successful call to demoteVersion, the Content Engine will apply the versioning security template (if it exists and is enabled) for the VersionStatus.IN_PROCESS state to the document being demoted. It will also apply the security template for the VersionStatus.RELEASED state (if one exists) to the previous major version. See Security Policies for more information on security templates. For more information on version status changes, see Checkin in the Content Engine Administration Help.

Java Example

Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}") );
doc.demoteVersion();
doc.save(RefreshMode.REFRESH);

C# Example

IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}"));
doc.DemoteVersion();
doc.Save(RefreshMode.REFRESH);

Promoting an Object

The following Java and C# examples show how to use the promoteVersion method to promote a current minor version to a released major version. To successfully promote a document, the document must be the latest minor version (the value of its VersionStatus property is IN_PROCESS) and must be the current version (IsCurrentVersion is true).

After a successful call to promoteVersion, the Content Engine will apply the versioning security template (if it exists and is enabled) for the VersionStatus.RELEASED to the document being promoted. It will also apply the Security template for the VersionStatus.SUPERSEDED state (if one exists) to the previous major version that is being superseded. See Security Policies for more information on security templates. For more information on version status changes, see Checkin in the Content Engine Administration Help.

Java Example

Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}") );
doc.promoteVersion();
doc.save(RefreshMode.REFRESH);

C# Example

IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}"));
doc.PromoteVersion();
doc.Save(RefreshMode.REFRESH);

Freezing Properties

The following Java and C# examples show how to use the freeze method to prevent changes to the custom properties of a checked-in document version.

Java Example

Document doc = Factory.Document.getInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}") );
doc.freeze();
doc.save(RefreshMode.REFRESH);

C# Example

IDocument doc = Factory.Document.GetInstance(os, ClassNames.DOCUMENT, new Id("{9B289B8A-DDD9-42DC-9D51-6B485509B68A}"));
doc.Freeze();
doc.Save(RefreshMode.REFRESH);