14
Implementing Versioning in a Custom Application

This chapter explains how the Oracle Internet File System implements versioning, and introduces strategies for implementing versioning in a custom application.

This chapter covers the following topics:

• What Is Versioning?

• Versioning Classes

• Implementing Versioning Applications

• Sample Code

What Is Versioning?

Versioning is the systematic retention of changes made to an object throughout its life cycle. For example, versioning allows you to track all changes made to a document's content and attributes by recording who made the change, when, and in what sequence. You can keep backups of each "version" of the document as a record of what the document looked like at a particular point in time.

Versioning also allows you to manage authoring and publishing processes by enforcing business rules for how changes can be made to an object. With the Oracle 9iFS versioning object model, you can build applications to manage a variety of processes, including serial versioning, branched versioning, and parallel versioning.

• Serial Versioning. You can build a serial versioning application that enforces that versions are made to documents sequentially. You can ensure that only one author can edit a document at a time with check in/check out functionality. An author can check out the document to prevent other authors from updating the document while making changes. As the author edits the document, the changes can be stored temporarily until the new version is completed. When finished, the author can check in the new version of the document for other authors to use. Check-in/check-out functionality ensures that each author is working with the right version of the document and prevent multiple authors from overwriting each others' work.

• Branched Versioning. You can build a branched versioning application that allows multiple authors to make changes simultaneously. Each author's changes can be maintained in a separate branch. Subsequently, your application can merge the changes together.

• Parallel Versioning. You can track different series of versions separately. For example, there may be one series for all work-in-progress changes (e.g., versions 1.0, 1.1, 1.2, 1.3, 2.0), and another for the published versions (e.g., versions 1.0, 2.0).

Implementing versioning functionality requires a careful balance between user requirements and system resources. Documents are the most commonly versioned objects in a content management system. Versioning documents allows you to maintain a revision history for mission-critical documentation. However, storing each version of a document will have an impact on system performance and storage space.

Versioning Object Model

Oracle 9iFS provides a flexible versioning model capable of supporting a wide variety of processes for authoring and publishing information. Most PublicObjects can be versioned. PublicObjects are objects that Oracle 9iFS users can access, such as documents and folders. These objects descend from PublicObject in the Oracle 9iFS class hierarchy. By default, only the Document class is set to be versionable. If you plan to version other classes of objects, take into account the disk space and performance cost involved. For the purpose of illustration, this chapter focuses on how documents are versioned.

A nonversioned document in the repository is represented as an instance of the Document class, or a custom class that extends Document. The instance possesses structured information describing the document, such as Name, Owner, and CreationDate. These are represented as attributes on the Document class. Documents also possess unstructured content represented as an instance of ContentObject referenced by the ContentObject attribute on the Document class.

When a document is versioned, Oracle 9iFS creates three additional types of objects to manage all of the versions created during the document's life cycle: a Family, VersionSeries, and VersionDescription, illustrated in Figure 14-1.

Figure 14-1 Versioning Objects

Text description of the illustration obmodel.gif

• Family: When a Document is versioned, the Family Object represents the document, collecting all the versions created for the document.

• VersionSeries: The Family groups the versions into VersionSeries, which represent a series of sequential changes made to the document. Each version in a VersionSeries represents the state of the document at a particular point in time. The order of the versions in the VersionSeries represents the order in which changes were made to the document.

• VersionDescription: Within a VersionSeries, each version of the document is represented by a VersionDescription describing the context of the version within the series, such as its sequence number (such as 1, 2, 3). Each VersionDescription references the instance of Document that contains the attributes and content for that particular version of the document.

Out-of-the-box, Oracle 9iFS clients and protocols implement a serial versioning model. In this versioning model, a document's Family includes one VersionSeries that contains all of the document's versions. Each version must, therefore, be made sequentially, one after another.

This versioning model also makes it possible to build custom applications with more complex versioning paradigms, such as parallel or branched versioning, shown in Figure 14-2. A Family can contain multiple VersionSeries to represent separate sequences of changes that may have been made in parallel, and which may branch from and merge into one another.

Figure 14-2 Branched Versioning Model

Text description of the illustration compver.gif

Different VersionDescriptions in a VersionSeries can reference different classes of objects, therefore representing changes in the state of a document from one class to another. For example, the first version of a document may have been a RequirementsDocument (subclass of Document), which was changed into a DesignSpecification in the second version.

VersionDescriptions can also reference the same instance of Document. For example, a document may have a Work-In-Progress VersionSeries and a Published VersionSeries. The third version of the Work-In-Progress VersionSeries may represent the first version in the Published VersionSeries. In this case, the VersionDescriptions representing the third Work-In-Progress version and first Published version can reference the same instance of Document.

Versioning Classes

Oracle 9iFS provides a Java API with which you can build custom applications that implement versioning functionality. Table 14-1, "Document Attributes and Methods", Table 14-2, "Family Attributes and Methods", Table 14-3, "VersionSeries Attributes and Methods", and Table 14-4, "VersionDescription Attributes and Methods" list the key attributes and methods of each of the versioning classes in the Oracle 9iFS Java API. For a complete description of these classes, please refer to the Javadoc.

Document Class

Ultimately, all versions of a document are stored as instances of the Document class. When users modify a document, an application can enable the following actions:

1. Overwrite the current version of the document. To overwrite the changes, the application would modify the Document instance referenced by the VersionDescription for that version.

2. Store the user's changes temporarily. To temporarily store the changes, the application would create a new instance of Document and reference it in the PendingPublicObject attribute on the VersionSeries.

3. Create a new version of the document. To create a new version, the application would create a new VersionDescription in the VersionSeries which references a new Document instance containing the changes. If the changes had been stored temporarily, the Document instance referenced by the PendingPublicObject attribute could be used instead of creating a new Document instance.

The Document class has a set of key attributes to keep track of changes made to the document. Most of these attributes and methods, shown in Table 14-1, "Document Attributes and Methods", are inherited from the superclass PublicObject, and can be used to version other types of objects. In addition, the Document class provides attributes and methods for working with a document's content.

When a user makes changes to a document, the application can allow the user to replace the attribute values or content of the document without creating a new version of the document. To support this feature, the PublicObject possesses attributes to track the date and user who originally created and last modified the document. The PublicObject class also possesses a Family attribute, which makes it easy to locate the Family of a versioned document.

Table 14-1 Document Attributes and Methods

Attribute / Method	Purpose
Creator getCreator()	Store and retrieve the DirectoryUser who initially created this instance of the document (or PublicObject).
CreateDate getCreateDate()	Store and retrieve the date when the document was initially created.
Modifier getLastModifer()	Retrieve the DirectoryUser who last modified this instance of the document. Optionally, users can modify an instance of the document without versioning it. For example, a user can replace the content of an nonversioned document. Or, a user can update the value of an attribute on the document's first version.
LastModifiedDate getLastModifuDate()	Retrieve the date that this instance of the document was last modified.
Family getFamily()	Retrieve the Family object that represents the "living document." A document can only belong to one Family.
isVersioned()	Determine if the document has been versioned.
isVersionable()	Determine if the class is versionable.
lock() unlock()	Obtain and release locks on the document.
ContentObject getContentObject() getContentReader() getContentStream() setContent()	Store, retrieve, and update a document's content.

Family Class

When a document is versioned, Oracle 9iFS creates an instance of the Family class to manage all of the versions created for the document during its life cycle. A versioned document can belong to only one Family. The attributes and methods important for managing a family are shown in Table 14-2, "Family Attributes and Methods".

Table 14-2 Family Attributes and Methods

Attribute / Method	Purpose
PrimaryVersionSeries getPrimaryVersionSeries() setPrimaryVersionSeries()	Specify and access the primary version series for the document. Since a Family can contain multiple VersionSeries, the Family class possesses a PrimaryVersionSeries attribute to designate one of the VersionSeries as the one accessed by default for the document.
getResolvedPublicObject()	Access the version of the document that represents the current state of the "living document." For example, when a user double-clicks a versioned document to view its content, Oracle 9iFS returns the version specified in the DefaultVersionDescription attribute. If not specified, Oracle 9iFS returns the last version of the primary version series to represent the current state of a versioned document.
DefaultVersionDescription getDefaultVersionDescription() setDefaultVersionDescription()	A custom versioning application can use these attributes and methods to explicitly set the default version to be a version of the document other than the last version in the primary version series.

"Resolving Versioned Documents" describes in detail how getResolvedPublicObject(), DefaultVersionDescription, and PrimaryVersionSeries are used to resolve the current state of a versioned document.

VersionSeries Class

A VersionSeries represents a series of sequential changes (versions) made to a document. The attributes and methods for managing these changes are shown in Table 14-3, "VersionSeries Attributes and Methods".

Table 14-3 VersionSeries Attributes and Methods

Attribute / Method	Purpose
getFirstVersionDescription()	Access the first version in the version series.
LastVersionDescription getLastVersionDescription()	GetLastVersionDescription() Used to store and access the last version in the version series.
getVersionDescriptions() getVersionDescriptions(int index) getNextVersionDescription() getPreviousVersionDescription()	Access an array of all versions in the version series, a specific version in a version series, and the next or previous version in a version series.
DefaultVersionDescription getDefaultVersionDescription() setDefaultVersionDescription()	A custom versioning application can use these attributes and methods to explicitly set the default version to be a version of the document other than the last version in the primary version series.
Reservor ReservationDate ReservationComments reserveNext() unReserve() isReserved() isReservedByCurrentUser() getReservor() getReservationDate() getReservationComment()	Reserve and unreserve the VersionSeries so that other users won't create a new version in the series while a specific user is making changes. Oracle 9iFS keeps track of when and by whom the version series was reserved, and any comments the user may have provided.
WorkPath getWorkPath()	When a user is making changes to a document, the versioning application can allow the user to copy the document to the authoring client's local operating system. The WorkPath attribute can be used to track the path to the exported copy. NOTE: Oracle 9iFS clients and protocols do not use the WorkPath attribute to provide this functionality.
PendingPublicObject getPendingPublicObject() setPendingPublicObject()	Users who have reserved a version series can store modifications temporarily before checking in the changes as a new version. The changes are stored temporarily as another instance of PublicObject and referenced by the PendingPublicObject attribute.
newVersion()	Create a new version in the version series.
VersionLimit setVersionLimit()	The number of versions that is retained in the version series.

"Making a Document Versioned" describes in detail how these methods and attributes can be used to version a document.

VersionDescription Class

A VersionDescription describes a version of a document within the context of a version series. The attributes and methods for working with a specific version of a document are shown in Table 14-4, "VersionDescription Attributes and Methods".

Table 14-4 VersionDescription Attributes and Methods

Attribute / Method	Purpose
VersionSeries VersionNumber RevisionComment getVersionSeries() getVersionNumber() getRevisionComment()	Track the version series to which this version belongs, the sequence number assigned to the version within the version series, and any comments supplied by the user when creating the version.
VersionLabel getVersionLabel() setVersionLabel()	The VersionLabel attribute stores a custom label for the version in the version series. A versioning application can store a version label that complies with an organization's revision numbering scheme. For example, while Oracle 9iFS automatically numbers the versions with sequential integers (1, 2, 3), the organization may want to label the versions (Draft A, Draft B, Draft C, Release 1.0).
isLatestVersionDescription()	Determine if the version is the last version in the version series.
PublicObject getPublicObject()	Each version of a document is ultimately stored as an instance of the Document class. The PublicObject attribute on the VersionDescription references the document instance that constitutes that version. The getPublicObject() method is used to obtain the document, or PublicObject.

Implementing Versioning Applications

You can use the Oracle 9iFS versioning classes to provide versioning functionality in a custom application. For example, versioning applications can create a new version in three steps:

1. Check out the document.

2. Edit and save changes to the document in a temporary holding place.

3. Check in the changes as a new version of the document.

Figure 14-3 Steps for Creating a New Version

Text description of the illustration versio3.gif

To implement this functionality, the versioning application uses the following API calls:

1. The application calls the reserveNext() method on the document's VersionSeries object to prevent other users from making changes at the same time. The application sets the Reservor, ReservationDate, ReservationComments, and WorkPath attributes on the VersionSeries to provide users with information about who, why, and when it was reserved.

2. When the user edits the document, the application creates another instance of Document and references it in the VersionSeries PendingPublicObject attribute. The application calls the setContent() method on the Document instance to store the user's iterations temporarily before creating the new version of the document.

3. When changes are to be stored as a new version of the document, the application calls the newVersion() method to create a new VersionDescription and set the values for the new version's VersionLabel, RevisionComments, and PublicObject. It sets the PublicObject attribute on the new VersionDescription to reference the Document instance that was used to store the user's changes as the VersionSeries PendingPublicObject.

This section demonstrates how to use the Oracle 9iFS Java API to build a custom application with serial versioning functionality for documents by performing the following basic versioning tasks:

• Making a Document Versioned

• Checking Out a Document

• Holding Pending Changes

• Checking in a New Version

• Cancelling a Check Out on a Document

• Foldering a Versioned Document

• Resolving Versioned Documents

• Viewing the Document History

• Deleting a Specific Document Version

• Deleting a Versioned Document

Making a Document Versioned

By default, when a document is first created in Oracle 9iFS, it is not versioned. To allow users to version the document, your application must first create the infrastructure objects for a versioned document: Family, VersionSeries, and VersionDescription.

To make a document versioned, follow these steps:

1. Fetch the document.

2. (Optionally) Create a FamilyDefinition.

3. (Optionally) Create a VersionSeriesDefinition and specify that it belongs to the Family.

4. Create a VersionDescriptionDefinition and specify that it belongs to the VersionSeries and references the document.

5. Pass the VersionDescriptionDefinition to the LibrarySession to create the Family, VersionSeries, and VersionDescription objects for the document and return the VersionDescription.

6. From the VersionDescription object, you can access the other components of the versioned document.

You don't have to explictly create definitions for all four components of a versioned document (e.g., DocumentDefinition, VersionDescriptionDefinition, VersionSeriesDefintion, FamilyDefinition). Alternatively, you can use a VersionDescriptionDefinition which references the Document to be versioned. When the VersionDescriptionDefinition is passed to the LibrarySession, Oracle 9iFS will automatically create all four components of the versioned document. From these two definition objects, Oracle 9iFS can create the other components. Example 14-1 illustrates how to make a document versioned by explicitly defining all components. Example 14-2 illustrates how to uses a VersionDescriptionDefinition to implicitly create the components of a versioned document.

You can use the SecuringPublicObject attribute to control access to all components of a versioned document in one place. You can apply one component's AccessControlList to all components of the versioned document by referencing that component in the other components' SecuringPublicObject attribute. When the SecuringPublicObject attribute is set, Oracle 9iFS will automatically use the referenced object's AccessControlList to control access to the referencing object. When you make an existing document versioned, Oracle 9iFS will automatically set the SecuringPublicObject attribute on the Document, VersionDescription, and VersionSeries to reference the document's Family. When you create a new versioned document, you must explicitly set the SecuringPublicObject attribute, as illustrated in Example 14-2.

NOTE: To learn more about using the SecuringPublicObject attribute, see Chapter 15, "Security".

Example 14-1 Making a Document Versioned

1. Assume that the application has obtained the document.

   Document doc = ...
   
   

2. Optionally create the FamilyDefinition.

   FamilyDefinition fd = new FamilyDefinition ( session );
   fd.setAttribute( PublicObject.NAME_ATTRIBUTE ,
                    AttributeValue.newAttributeValue ( po.getName() ) );
   AccessControlList acl = doc.getAcl();
   fd.setAttribute(PublicObject.ACL_ATTRIBUTE,
                   AttributeValue.newAttributeValue(acl));
   
   

3. Optionally create VersionSeriesDefinition.

   VersionSeriesDefinition vsd = new VersionSeriesDefinition(session);
   vsd.setFamilyDefinition(fd);
   
   

4. Create VersionDescriptionDefinition.

   VersionDescriptionDefinition vdd = 
         new VersionDescriptionDefinition(session);
   vdd.setPublicObject(doc);
   vdd.setVersionSeriesDefinition(vsd);
   vdd.setOwnerBasedOnPublicObjectOption ( true );
   
   

5. Create the VersionDescription.

   VersionDescription vd = 
        (VersionDescription) session.createPublicObject(vdd);
   
   

6. Access the VersionSeries and Family from the VersionDescriptions.

   VersionSeries vs = vd.getVersionSeries();
   Family family = vs.getFamily();
   

Example 14-2 Creating a New Versioned Document

1. Create the DocumentDefinition.

   DocumentDefinition dd = new DocumentDefinition(session);
   dd.setAttribute(Document.NAME_ATTRIBUTE, 
      AttributeValue.newAttributeValue(docname));
   
   Collection formatColl = session.getFormatCollection();
   Format fmt = (Format) formatColl.getItems("Text");
   dd.setFormat(fmt);
   
   dd.setContent("A new versioned document.");
   
   Folder hf = session.getUser().getPrimaryUserProfile().getHomeFolder();
   dd.setAddToFolderOption(hf);
   
   

2. Create the VersionDescriptionDefinition.

   VersionDescriptionDefinition vdd = new VersionDescriptionDefinition(session);
   vdd.setAttribute(VersionDescription.NAME_ATTRIBUTE, 
       AttributeValue.newAttributeValue("Versioning1 VersionDescription"));
   vdd.setAttribute("VERSIONLABEL", 
       AttributeValue.newAttributeValue("Version 1.0"));
   vdd.setPublicObjectDefinition(dd);
   
   

3. Pass the VersionDescriptionDefinition to the LibrarySession to implicitly create the Document, VersionDescription, VersionSeries, and Family, and return the VersionDescription.

   VersionDescription vd = (VersionDescription)session.createPublicObject(vdd);
   
   

4. Use the VersionDescription to fetch the other components.

   Family f = vd.getFamily();
   VersionSeries vs = vd.getVersionSeries();
   Document d = (Document) vd.getResolvedPublicObject();
   
   

5. Set the SecuringPublicObject for the VersionDescription and VersionSeries to be the document's Family.

   d.setSecuringPublicObject(f);
   vd.setSecuringPublicObject(f);
   vs.setSecuringPublicObject(f);
   

Checking Out a Document

After making a document versioned, you can allow end users to check out the document. When a user checks out a document, other users cannot create new versions of the document.

To check out a document, follow these steps:

1. Fetch the document.

2. Verify that the document is versioned.

3. Fetch the VersionSeries in which the new version will be created.

4. Verify that the VersionSeries is not already reserved, and that the document's Family is not locked.

5. Reserve the VersionSeries by calling the reserveNext() method. The reserveNext() method reserves the VersionSeries to prevent other users from creating new versions in that series.

Example 14-3 Checking Out a Document

1. Assume that the application has already obtained the document.

   Document doc ...
   

2. Verify that the document is versioned.

   if (doc.isVersioned())
   {
   
   

3. Fetch the VersionSeries that will contain the new version. In this case, we will reserve the PrimaryVersionSeries.

       Family family = doc.getFamily();
       VersionSeries vs = family.getPrimaryVersionSeries();
   
   

4. Verify that the VersionSeries is not already reserved and that the document's Family is not locked.

       if (!vs.isReserved() && !family.isLocked())
       {
   
   

5. Reserve the VersionSeries by calling the reserveNext() method. The reserveNext() method reserves the VersionSeries to prevent other users from creating new versions in that series.

        vs.reserveNext(null,
                      "File Reserved By " + 
                       session.getDirectoryUser().getDistinguishedName());
       }
   }
   

Holding Pending Changes

When reserveNext() method is called to check out a document, the method also creates a new Document instance based on the last version of the document, and then sets the VersionSeries' PendingPublicObject attribute to that Document instance. The PendingPublicObject serves as a temporary holding place for all changes made to the document while it is checked out. Each iteration of the document is recorded in Oracle 9iFS as a Document instance and referenced by the PendingPublicObject attribute on the VersionSeries.

To hold pending changes your application can fetch and update the document referenced by the PendingPublicObject attribute with the following steps:

1. Fetch the document.

2. Verify that the document is versioned and fetch the VersionSeries.

3. Verify that the VersionSeries is reserved by the current user and fetch the PendingPublicObject.

4. Create a DocumentDefinition to hold the changes to the PendingPublicObject.

5. Update the PendingPublicObject with the changes.

Example 14-4 Holding Pending Changes

1. Assume that your application has already obtained the document.

   Document doc .....
   
   

2. Verify that the document is versioned and fetch the VersionSeries.

   if (doc.isVersioned())
   {
     Family.family = doc.getFamily();
     VersionSeries vs = family.getPrimaryVersionSeries();
   
   

3. Verify that the document is checked out by the current user and fetch the PendingPublicObject.

       if (vs.isReservedByCurrentUser() )
       {
           PublicObject ppo = vs.getPendingPublicObject();
   
   

4. Create a DocumentDefinition to hold the changes.

           DocumentDefinition dd = (DocumentDefinition) ppo.getDefinition();
           dd.setContent("Changed content.");
           
   

5. Update the PendingPublicObject with the changes.

           ppo.update(dd);
       }
   }
   

Checking in a New Version

When the author is finished making changes to the document, the changes can be checked in as a new version of the document. To check in the new document version, follow these steps:

1. Fetch the document.

2. Verify that the document is versioned and fetch the VersionSeries.

3. Verify that the VersionSeries is reserved by the current user and fetch the PendingPublicObject.

4. Verify that the PendingPublicObject is not null and create a VersionDescriptionDefinition for the new version.

5. Call the newVersion() method to create the new document version.

Example 14-5 Checking In a New Version

1. Assume that your application has already obtained the document.

   Document doc .....
   
   

2. Verify that the document is versioned and fetch the VersionSeries.

   if (doc.isVersioned())
   {
       Family family = doc.getFamily();
       VersionSeries vs = family.getPrimaryVersionSeries();
   
   

3. Verify that the document is checked out by the current user and fetch the PendingPublicObject.

       if (vs.isReservedByCurrentUser() )
       {
          PublicObject ppo = vs.getPendingPublicObject();
   
   

4. Verify that the PendingPublicObject is not null, and create a VersionDescriptionDefinition for the new version.

          if (ppo != null)
          {
             vdd = new VersionDescriptionDefinition( session );
             vdd.setAttribute(vd.REVISIONCOMMENT_ATTRIBUTE,
                 AttributeValue.newAttributeValue(
                  "Updated document to incorporate review comments."));
   

5. Create the new document version.

             vd = vs.newVersion(vdd);
          }
       }
   }
   
   

Cancelling a Check Out on a Document

At any time while the document is checked out, the user can cancel the check out. Cancelling a check out will discard the changes held temporarily in the PendingPublicObject and release the VersionSeries so that other users can check out the document.

To cancel a check out on a document, follow these steps:

1. Fetch the document.

2. Verify that the document is versioned and fetch the VersionSeries.

3. Verify that the VersionSeries is reserved by the current user.

4. Call the unReserve() method on the VersionSeries.

Example 14-6 Cancelling a Check Out on a Document

1. Assume that your application has already obtained the document.

   Document doc .....
   
   

2. Verify that the document is versioned and fetch the VersionSeries.

   if (doc.isVersioned())
   {
       Family family = doc.getFamily();
       VersionSeries vs = family.getPrimaryVersionSeries();
   
   

3. Verify that the document is checked out by the current user.

       if (vs.isReservedByCurrentUser() )
       {
   
   

4. Cancel the check out by calling the unReserve() method on the VersionSeries.

         vs.unReserve();
       }
   }
   

Viewing the Document History

After a document has been versioned, you can obtain a history of all changes made to the document, and access all retained document versions. To view the document's history, follow these steps:

1. Fetch the document.

2. Verify that the document is versioned and fetch the VersionSeries.

3. Fetch the VersionDescriptions in the VersionSeries and select the history information.

Example 14-7 Viewing the Document History

1. Assume that your application has already obtained the document.

   Document doc .....
   
   

2. Verify that the document is versioned and fetch the VersionSeries.

   if (doc.isVersioned())
   {
       Family family = doc.getFamily();
       VersionSeries vs = family.getPrimaryVersionSeries();
   

3. Fetch the VersionDescriptions in the VersionSeries and select the history information.

       VersionDescription[] versions = vs.getVersionDescriptions();
   
       Document docVersion;
       Date lastModifyDate;
       Long size;
       PublicObject version;
       String docVersionName, format, lastModifier, revisionComment;
       VersionDescription vd;
   
       for (int i = 0; i < versions.length; i++)
       {
         vd = versions[i];
         version = vd.getPublicObject();
         versionName = version.getName();
         lastModifier = version.getLastModifier().getName();
         lastModifyDate = version.getLastModifyDate();
         revisionComment = vd.getRevisionComment();s
   
         if (docVersion instanceof Document)
         {
           docVersion = (Document) version;
           format = docVersion.getFormat().getName();
           size = docVersion.getContentSize();
         }
       }
   }
   

Deleting a Specific Document Version

Since each version created is retained in the repository, versioning documents will have an impact on the storage space and performance of the system. You can allow end users to keep the repository lean by deleting unnecessary versions.

To delete a document version, follow these steps:

1. Fetch the VersionDescription for the version to be deleted.

2. Optionally verify that the VersionDescription is not the latest version before deleting.

3. Delete the VersionDescription.

Example 14-8 Deleting a Specific Document Version

1. Assume that your application has already obtained the VersionDescription for the version being deleted.

   VersionDescription vd .....
   
   

2. Optionally, verify that the VersionDescription is not the latest in the VersionSeries.

   if (!vd.isLatestVersionDescription())
   {
   

3. Delete the VersionDescription.

       vd.free();
   }
   

Deleting a Versioned Document

Deleting a versioned document is as easy as deleting a non-versioned document. When the free() method is called on a document's Family, Oracle 9iFS automatically deletes its versioning components, including the VersionSeries, VersionDescriptions, and all instances of Document that represent a version of the document.

Example 14-9 Deleting a Versioned Document

1. Assume that your application has already obtained the document's Family.

   Document doc .....
   Family family = doc.getFamily();
   
   

2. Verify that the family is not locked.

   if (!family.isLocked())
   {
   

3. Delete the family.

       family.free();
   }
   

Foldering a Versioned Document

Folders provide a way to organize and browse through the repository to access documents. When a nonversioned document is foldered, the folder directly references the document; that is, the instance of the Document class. However, when a document is versioned, the folder can reference any component of the versioned document: its Family, a VersionSeries, or a VersionDescription. This is useful for providing users with an easy way to access specific points in the document's life cycle for different purposes.

For example, a Release 1.0 Documentation Set folder was created to contain the documentation released with Oracle 9iFS 1.0. The folder references the specific version, Version 3, of the documentation delivered with that release. This is accomplished by foldering the VersionDescription that represents Version 3.

Example 14-10 Foldering a Specific Document Version

1. Obtain the VersionDescription for the document version to be foldered.

   VersionDescription vd = ...
   
   

2. Obtain the folder.

   Folder f = .....
   
   

3. Add the VersionDescription to the Folder.

   f.addItem(vd);
   
   

A Future Documentation folder may be created to contain the documentation set being developed for the next release of Oracle 9iFS. In this case, the folder references the Work-in-Progress VersionSeries. An author can access the document from here to obtain the latest version of the Work-in-Progress VersionSeries.

Example 14-11 Foldering a Specific VersionSeries

1. Obtain the folder.

   Folder f = ....
   
   

2. Obtain the VersionSeries to be foldered.

   Document doc = ....
   Family family = doc.getFamily();
   VersionSeries[] vss = family.getVersionSeries();
   
   int i;
   String vsName;
   VersionSeries vs;
   
   for (i = 0; i < vss.length; i++)
   {
     vs = vss[i];
     vsName = vs.getName();
   
     if (vsName equals ("Work-in-Progress"))
     {
   
   

3. Add the VersionSeries to the Folder.

       f.addItem(vs);
       break;
     }
   }
   
   

A Current Documentation folder may be created to make it easy for users to access the most recently published version of the documentation. This is accomplished by foldering the document's Family. General consumers can access the document version that are designated as the default version for the document's primary version series, the Published VersionSeries.

Example 14-12 Foldering a Document's Family

1. Obtain the folder.

   Folder f = ....
   
   

2. Obtain the document's Family.

   Document doc = ....
   Family family = doc.getFamily();
   
   

3. Add the Family to the Folder.

   f.addItem(f);
   
   

When you make a document versioned, you can update all folders containing the document to reference the document's Family. By referencing the document's family, you will be assured that end users will retrieve the most current version of the document, rather than the first version of the document.

Example 14-13 Updating Folders when Making a Document Versioned

1. Assume that the application has already obtained the document.

   Document doc = ....
   
   Make a document versioned.
   FamilyDefinition fd = new FamilyDefinition ( session );
   fd.setAttribute( PublicObject.NAME_ATTRIBUTE ,
                    AttributeValue.newAttributeValue ( po.getName() ) );
   AccessControlList acl = doc.getAcl();
   fd.setAttribute(PublicObject.ACL_ATTRIBUTE,
                   AttributeValue.newAttributeValue(acl));
   
   VersionSeriesDefinition vsd = new VersionSeriesDefinition(session);
   vsd.setFamilyDefinition(fd);
   
   VersionDescriptionDefinition vdd = 
         new VersionDescriptionDefinition(session);
   vdd.setPublicObject(doc);
   vdd.setVersionSeriesDefinition(vsd);
   vdd.setOwnerBasedOnPublicObjectOption ( true );
   

2. Begin a transaction.

   Transaction transaction = session.beginTransaction(); 
   
   

3. Start a try block to test the operations and catch any exceptions.

   try 
   {
      VersionDescription vd = 
        (VersionDescription) session.createPublicObject(vdd);
   
   

4. Get the document's Family.

      VersionSeries vs = vd.getVersionSeries();
      Family family = vs.getFamily();
   
   

5. Fetch all folders that reference document.

      Folder fldr;
      Folder[] fldrs = 
         doc.getFolderReferences();
   
   

6. Update each folder to reference the document's Family instead of the Document instance.

      for(i=0; i < fldrs.length; i++)
      {
         fldr = fldrs[i];
         fldr.removeItem(doc);
         fldr.addItem(family);
      }
   
      session.completeTransaction(transaction);
   }
   catch (IfsException e)
   {
     session.abortTransaction(transaction);
     throw e; 
   }
   

   
   
   
   
   
   
   Notes:
   
   
   
   
   
   
   "Resolving Versioned Documents" describes how Oracle 9iFS resolves which version of a document should be returned when accessed from VersionDescription, VersionSeries, or Family.
   
   
   Example 14-13 uses a transaction to ensure that all folders are updated when the document is versioned.  See Chapter 16, "Managing Sessions and Transactions" for instructions on how to use the transaction management capabilities of Oracle 9iFS.
   
    
   
   
   
   
   
   
   
   
   
   

Resolving Versioned Documents

When a user tries to view a versioned document, which of its versions should represent its current state? The Oracle 9iFS versioning model makes it possible to control how a document's current state is resolved. Furthermore, an application can configure a versioned document so that the document's state is resolved differently depending on which node in the versioning model is being accessed.

In the example illustrated by Figure 14-4, "Branched Versioning Model", an application can provide access to the officially released version of a Product Plan document in the Publications folder by foldering its Family object. When a user tries to view the content for the Product Plan via the Family object, Oracle 9iFS automatically returns the content of the last version of the Family's PrimaryVersionSeries, Published Series.

Figure 14-4 Branched Versioning Model

Text description of the illustration compver.gif

Oracle 9iFS provides a method, getResolvedPublicObject(), to automatically resolve which document represents the current state of a specific version (the VersionDescription), a particular series of versions (the VersionSeries), or the 'living document' (the Family). Certain attributes on the Family and VersionSeries can be used by an application to control how the document's state is resolved.

The getResolvedPublicObject() method employs the following logic when being used to resolve each component of a versioned document.

• VersionDescription. When the getResolvedPublicObject() method is called on a VersionDescription object, Oracle 9iFS returns the document referenced by the PublicObject attribute on the VersionDescription.

  In the example illustrated by Figure 14-4, "Branched Versioning Model", Version 2 of the Published Series resolves to the Design Spec referenced by its PublicObject attribute.

• VersionSeries. When the getResolvedPublicObject() method is called on a VersionSeries, Oracle 9iFS returns the resolved PublicObject for the VersionDescription referenced by the DefaultVersionDescription attribute on the VersionSeries. The DefaultVersionDescription attribute must be explicitly set by a versioning application. If this attribute has not been set, then Oracle 9iFS returns the resolved PublicObject for the VersionDescription referenced by LastVersionDescription attribute on the VersionSeries. The LastVersionDescription attribute is maintained by Oracle 9iFS to reference the last VersionDescription in the VersionSeries, and cannot be explicitly set.

  In the example illustrated by Figure 14-4, "Branched Versioning Model", the resolved PublicObject for the Internal Series VersionSeries is the Design Spec referenced by Version 3. However, if the Internal Series DefaultVersionDescription is set to Version 1, Oracle 9iFS returns the Requirements Spec.

• Family. When the getResolvedPublicObject() method is called on a document's Family, Oracle 9iFS returns the resolved PublicObject for the VersionDescription referenced by the DefaultVersionDescription attribute on the Family. The DefaultVersionDescription attribute must be explicitly set by a versioning application. If this attribute has not been set, then Oracle 9iFS returns the resolved PublicObject for the Family's PrimaryVersionSeries.

  In the example illustrated by Figure 14-4, "Branched Versioning Model", if Published Series were the PrimaryVersionSeries for Product Plan, then Oracle 9iFS returns the Design Spec referenced by Version 2. However, if the DefaultVersionDescription on the Product Plan was set to Version 3 of the Internal Series, Oracle 9iFS returns the Design Spec referenced by Version 3.

Example 14-14 demonstrates how to use the getResolvedPublicObject() method on each component of a versioned document.

Example 14-14 Resolving the PublicObject for a Versioned Document

1. Assume that the application has already obtained the document.

   Document doc = ....
   
   

2. Calling the getResolvedPublicObject() method on the Document instance will just return itself.

   PublicObject rpo = doc.getResolvedPublicObject();
   
   

3. Calling the getResolvedPublicObject() method on the document's Family will return the Document instance referenced by the last DefaultVersionDescription attribute on Family, or the DefaultVersionDescription on the PrimaryVersionSeries, or the last VersionDescription in the PrimaryVersionSeries.

   Family family = doc.getFamily();
   PublicObject rpo = family.getResolvedPublicObject();
   
   

4. Calling the getResolvedPublicObject() method on a VersionSeries will return the Document instance referenced by DefaultVersionDescription on the VersionSeries, or the LastVersionDescription in the VersionSeries.

   VersionSeries vs = doc.getVersionSeries();
   PublicObject rpo = vs.getResolvedPublicObject();
   
   

5. Calling the getResolvedPublicObject() method on a VersionDescription will return the Document instance referenced by VersionDescription.

   VersionDescription vd = vs.getLastVersionDescription();
   PublicObject rpo = vd.getResolvedPublicObject();
   

Sample Code

Oracle 9iFS is installed with sample code that helps you get started working with the Java API. The API sample code is located in the <ORACLE_HOME>/9ifs/samplecode/oracle/ifs/examples/devdoc/api directory.

Table 14-5 lists the API sample code that is relevant to this chapter.

Table 14-5 API Sample Code

Class	Usage
VersioningSample.java	Versions a document.