Working with Versioning-related Objects

The following code examples demonstrate versioning-related operations. For examples on using security templates with document versions, see Working with Security Policies. For an overview of versioning, see Versioning.

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.) 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 autoclassification is enabled for the document. For more information about autoclassification, see Document Classifications. For more information about 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 applies 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 );

Deleting Document Versions

The following Java and C# examples show how to delete a version from a document. The fetched document has five major versions. The code iterates the document versions and deletes the third one. If run a second time (after deletion of version 3), the code prints the following output:

Major = 5; Minor = 0
Major = 4; Minor = 0
Major = 2; Minor = 0
Major = 1; Minor = 0

Java Example



static PropertyFilter pf = new PropertyFilter();  
...
pf.addIncludeProperty(new FilterElement(null, null, null, "VersionSeries Id", null) );
Document doc = Factory.Document.fetchInstance(os, new Id("{91CD21FA-5F65-4D5B-AE3E-ECE529C7AC88}"),pf );   

// Get set of document versions from VersionSeries
VersionSeries vs = doc.get_VersionSeries();
VersionableSet vss = vs.get_Versions();

// Iterate versions and delete the third one.
Iterator vssiter = vss.iterator();
while (vssiter.hasNext()){
   Versionable ver = (Versionable)vssiter.next();
   System.out.println("Major = " + ver.get_MajorVersionNumber() + "; Minor = " + ver.get_MinorVersionNumber());
   if (ver.get_MajorVersionNumber().intValue() == 3){
      // To delete, cast the Versionable object to Document.
      Document verdoc = (Document) ver;
      verdoc.delete();
      verdoc.save(RefreshMode.REFRESH);
   }
}

C# Example



static PropertyFilter pf = new PropertyFilter();
...
pf.AddIncludeProperty(new FilterElement(null, null, null, "VersionSeries Id", null) );
IDocument doc = Factory.Document.FetchInstance(os, new Id("{91CD21FA-5F65-4D5B-AE3E-ECE529C7AC88}"),pf );

//Get the document versions from VersionSeries
IVersionSeries vs = doc.VersionSeries;
IVersionableSet vss = vs.Versions;

// Iterate versions and delete the third one.
foreach(IVersionable ver in vss)
{
    System.Console.WriteLine("Major = " + ver.MajorVersionNumber + "; Minor = " + ver.MinorVersionNumber);
    if (ver.MajorVersionNumber == 3){
       // To delete, cast the Versionable object to Document.
       IDocument verdoc = (IDocument) ver;
       verdoc.Delete();
       verdoc.Save(RefreshMode.REFRESH);
    }
}

Canceling a Checkout

The following Java and C# examples show how to cancel a check-out 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 of 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 that is being demoted. It also applies the security template for the VersionStatus.RELEASED state (if one exists) to the previous major version. For more information about security templates, see Security Policies. For more information about 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 applies the versioning security template (if it exists and is enabled) for the VersionStatus.RELEASED state to the document that is being promoted. It also applies the security template for the VersionStatus.SUPERSEDED state (if one exists) to the previous major version that is being superseded. For more information about security templates, see Security Policies. For more information about version status changes, see Checkin.

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);