oracle.ifs.beans
Class VersionSeries

java.lang.Object
  |
  +--oracle.ifs.beans.LibraryObject
        |
        +--oracle.ifs.beans.TieLibraryObject
              |
              +--oracle.ifs.beans.PublicObject
                    |
                    +--oracle.ifs.beans.TiePublicObject
                          |
                          +--oracle.ifs.beans.VersionSeries

All Implemented Interfaces:

IfsEventHandler, LibraryObjectInterface, PublicObjectInterface, Traceable

Direct Known Subclasses:

TieVersionSeries

public class VersionSeries

extends TiePublicObject

The VersionSeries class is used to track revisions to a versioned public object as it changes over time. Each series tracks one set of linear changes by ordering instances of VersionDescription. A Family can have multiple VersionSeries, thus allowing for version branching or other non-linear version tracking. A VersionSeries has two special attributes, DefaultVersionDescription and LastVersionDescription. The defaultVersionDescription is fully updatable and can be used to designate a Published version in which people not actively working on a versioned object might be interested. The LastVersion is more useful for someone actively working on a versioned object; the last version might represent work in progress and as such might not be appropriate for a public audience. The last version is system maintaned.

If a DefaultVersionDescription is not set (is null) then a request for a resolved public object will be deferred to the last version description.

The VersionSeries class has methods to checkOut (aka reserveNext()), checkIn (aka newRevision) and cancelCheckOut (aka unReserve) a document belonging to this series. Invoking these methods can affect the lock state of the various versioning objects such as Family, VersionSeries etc. Prior to 9.0.3, the behavior was as follows:

• As part of a checkOut() operation, the Family, VersionSeries, Last VersionDescription and PublicObject are UserLocked.
• As part of a checkIn() operation, the Last VersionDescription and PublicObject (before the new version) are SoftLocked. This is to prevent previous versions from being modified.
• As part of a cancelCheckOut() operation, the Family, VersionSeries, Last VersionDescription and PublicObject are UnLocked.

Starting in 9.0.3, policies on the VersionSeries class or instance can be introduced which control what versioning objects are locked during these operations. This is fully customizable according to the needs of the application.

Out-of-the-box, there are six policies for the three versioning operations. The policy names and their semantics are defined below as static constants. To switch the policy associated with the VersionSeries class for a particular operation, find the policy by name that you wish to switch to from the PolicyBundle collection on the session. Associate the policy with the VersionSeries ClassObject or the instance by using LibraryObject.putPolicy(Policy po). Associating with the VersionSeries ClassObject affects all VersionSeries in the system while associating it with the instance only applies that policy for that instance.

To define a totally new policy with a custom semantic for a particular operation, construct a policy object using the API. Details on how to create a new policy are in the Developers guide. The "Operation" attribute of the new policy must be equal to the Operation for which you are trying to change the default policy. This is stored in the "Operation" attribute of the default Policy Object. The implementation for the policy must reside in the server side subclass of VersionSeries class i.e. S_TieVersionSeries or its subclass. The implementation method must also take a server side S_LibraryObjectDefinition as a parameter and be public. The implementation is dynamically invoked. <

For more details on Policies, refer to the documentation for the Policy class.
For a description of the various lock states, refer to the documentation for the LockObject class.

Field Summary

static java.lang.String	CLASS_NAME The class name for this class.
static java.lang.String	DEFAULTVERSIONDESCRIPTION_ATTRIBUTE The VersionDescription which will be used as the ResolvedPublicObject for this VersionSeries.
static java.lang.String	LASTVERSIONDESCRIPTION_ATTRIBUTE The last VersionDescription in this VersionSeries.
static java.lang.String	LOCK_ON_NEW_VERSION_POLICY_LOCK_ALL The out-of-the-box versioning policy for newVersion aka checkIn operation.
static java.lang.String	LOCK_ON_NEW_VERSION_POLICY_LOCK_NONE An alternate versioning policy for newVersion aka checkIn operation.
static java.lang.String	LOCK_ON_RESERVE_NEXT_POLICY_LOCK_ALL The out-of-the-box versioning policy for reserveNext aka checkOut operation.
static java.lang.String	LOCK_ON_RESERVE_NEXT_POLICY_LOCK_NONE An alternate versioning policy for reserveNext aka checkOut operation.
static java.lang.String	PENDINGPUBLICOBJECT_ATTRIBUTE Deprecated. iFS 9.0.3: this attribute will be removed in a future release
static java.lang.String	RESERVATIONCOMMENT_ATTRIBUTE The check-out comment stating the purpose of the reservation.
static java.lang.String	RESERVATIONDATE_ATTRIBUTE The date and time (in GMT) when the VersionSeries was reserved.
static java.lang.String	RESERVOR_ATTRIBUTE The DirectoryUser that has this VersionSeries reserved for the purpose of adding a new version.
static java.lang.String	UNLOCK_ON_UNRESERVE_POLICY_UNLOCK_ALL The out-of-the-box versioning policy for Unreserve aka cancelCheckOut operation.
static java.lang.String	UNLOCK_ON_UNRESERVE_POLICY_UNLOCK_NONE An alternate versioning policy for unReserve aka cancelCheckOut operation.
static java.lang.String	VERSIONLIMIT_ATTRIBUTE The limit of the number of versions which this VersionSeries should keep.
static java.lang.String	WORKPATH_ATTRIBUTE The location of a version's content on the client's local store.

Fields inherited from class oracle.ifs.beans.PublicObject

ACL_ATTRIBUTE, ADMINISTRATIONGROUP_ATTRIBUTE, CREATEDATE_ATTRIBUTE, CREATOR_ATTRIBUTE, DELETOR_ATTRIBUTE, DESCRIPTION_ATTRIBUTE, EXPIRATIONDATE_ATTRIBUTE, FAMILY_ATTRIBUTE, FLAGS_ATTRIBUTE, LASTMODIFIER_ATTRIBUTE, LASTMODIFYDATE_ATTRIBUTE, LOCKEDFORSESSION_ATTRIBUTE, LOCKOBJECT_ATTRIBUTE, LOCKSTATE_ATTRIBUTE, LOCKSTATE_HARDLOCK, LOCKSTATE_SESSIONLOCK, LOCKSTATE_SOFTLOCK, LOCKSTATE_UNLOCK, LOCKSTATE_USERLOCK, NAME_ATTRIBUTE, OWNER_ATTRIBUTE, POLICYBUNDLE_ATTRIBUTE, PROPERTYBUNDLE_ATTRIBUTE, RESOLVEDPUBLICOBJECT_ATTRIBUTE, SECURINGPUBLICOBJECT_ATTRIBUTE

Method Summary

VersionDescription	getDefaultVersionDescription() Returns the default version of this version series.
VersionDescription	getFirstVersionDescription() Returns the first VersionDescription of this series.
VersionDescription	getLastVersionDescription() Returns the last VersionDescription of this series.
VersionDescription	getNextVersionDescription(VersionDescription version) Returns the next VersionDescription of this series.
PublicObject	getPendingPublicObject() Deprecated. iFS 9.0.3: this attribute (and thus, this method) will be removed in a future release
VersionDescription	getPreviousVersionDescription(VersionDescription version) Returns the Version description previous to the one being passed by the user.
java.lang.String	getReservationComment() Returns the comment when this series was reserved, or null if this series is not reserved.
java.util.Date	getReservationDate() Returns the Date that this VersionSeries was reserved, null if not reserved.
DirectoryUser	getReservor() Returns the User that reserved this VersionSeries, null if not reserved
PublicObject	getResolvedPublicObject() Return the PublicObject to which this object resolves.
VersionDescription[]	getVersionDescriptions() Returns an array of all VersionDescriptions in this VersionSeries.
VersionDescription	getVersionDescriptions(int index) Returns the specified VersionDescription of this series.
VersionDescription[]	getVersionDescriptions(PublicObject version) Returns an array of VersionDescriptions which reference the versioned public object passed in (more than one VersionDescription can refer to the same PublicObject).
java.lang.String	getWorkpath() Returns the value for the local file path specified when this series was reserved.
void	handleEvent(IfsEvent event) Handles the specified event.
boolean	isReserved() Returns true if this VersionSeries is reserved by any user.
boolean	isReservedByCurrentUser() Returns true if this VersionSeries is reserved by the current user.
boolean	isVersioned() Returns false always.
VersionDescription	newVersion(VersionDescriptionDefinition vddef) Creates a new VersionDescription in this series from the specified VersionDescriptionDefinition.
void	reserveNext(java.lang.String contentPath, java.lang.String comment) Reserves the right to add the next version.
void	setDefaultVersionDescription(VersionDescription version) Set the Default Version Description of this series.
void	setPendingPublicObject(PublicObject po) Deprecated. iFS 9.0.3: this attribute (and thus, this method) will be removed in a future release
void	setVersionLimit(int limit) Sets the value of the VersionLimit attribute.
void	unReserve() Cancels the reservation.

Methods inherited from class oracle.ifs.beans.PublicObject

addCategory, addRelationship, checkEffectiveAccess, checkEffectiveAccess, copy, getAcl, getAllFolderPaths, getAllFolderPaths, getAnyFolderPath, getAnyFolderPath, getCategories, getCategories, getCategories, getCategories, getCreateDate, getCreator, getDefaultAccessLevel, getDescription, getEffectiveAccessLevel, getEffectiveAccessLevel, getExpirationDate, getFamily, getFlags, getFolderReferences, getFolderReferencesSortSpecification, getLastModifier, getLastModifyDate, getLeftwardRelationshipObjects, getLeftwardRelationshipObjects, getLeftwardRelationships, getLeftwardRelationships, getLockObject, getLockState, getLockStateLabel, getOwner, getPolicyBundle, getPropertyBundle, getRightwardRelationshipObjects, getRightwardRelationshipObjects, getRightwardRelationships, getRightwardRelationships, getSecuringPublicObject, grantAccess, hasNameAttribute, isLocked, isLockedForSession, isLockedForSessionByCurrentSession, isVersionable, lock, lock, lock, putPolicy, putProperty, putProperty, removeAllPolicies, removeAllProperties, removePolicy, removePolicy, removeProperty, removeRelationship, revokeAccess, revokeAllAccess, setAcl, setDescription, setExpirationDate, setFlags, setFolderReferencesSortSpecification, setOwner, setPolicyBundle, setPropertyBundle, setSecuringPublicObject, toLockStateLabel, toLockStateLabel, toLockStateLabel, unlock, updateLock

Methods inherited from class oracle.ifs.beans.LibraryObject

equals, free, free, getAttribute, getAttributeByUpperCaseName, getAttributes, getAttributesByUpperCaseNames, getClassId, getClassObject, getDefinition, getId, getLabel, getName, getSession, invokeServerMethod, isInstanceOf, isTraced, lookupInstanceLabel, postEvent, postEvent, renderAsReader, renderAsStream, setAttribute, setAttribute, setAttributes, setAttributes, setName, toString, trace, update

Methods inherited from interface oracle.ifs.common.LibraryObjectInterface

getId

Methods inherited from interface oracle.ifs.common.Traceable

getTraceLogger, isTraced, trace

Field Detail

CLASS_NAME

public static final java.lang.String CLASS_NAME

The class name for this class. Useful for methods that take a class name argument.

DEFAULTVERSIONDESCRIPTION_ATTRIBUTE

public static final java.lang.String DEFAULTVERSIONDESCRIPTION_ATTRIBUTE

The VersionDescription which will be used as the ResolvedPublicObject for this VersionSeries. If null, the ResolvedPublicObject for this VersionSeries will be the LastVersionDescription.

LASTVERSIONDESCRIPTION_ATTRIBUTE

public static final java.lang.String LASTVERSIONDESCRIPTION_ATTRIBUTE

The last VersionDescription in this VersionSeries.

RESERVOR_ATTRIBUTE

public static final java.lang.String RESERVOR_ATTRIBUTE

The DirectoryUser that has this VersionSeries reserved for the purpose of adding a new version. If the VersionSeries is not reserved, the Reservor is null.

RESERVATIONDATE_ATTRIBUTE

public static final java.lang.String RESERVATIONDATE_ATTRIBUTE

The date and time (in GMT) when the VersionSeries was reserved.

RESERVATIONCOMMENT_ATTRIBUTE

public static final java.lang.String RESERVATIONCOMMENT_ATTRIBUTE

The check-out comment stating the purpose of the reservation.

WORKPATH_ATTRIBUTE

public static final java.lang.String WORKPATH_ATTRIBUTE

The location of a version's content on the client's local store. WorkPath is a convenience attribute to allow clients to record the location of a version that has been checked out.

VERSIONLIMIT_ATTRIBUTE

public static final java.lang.String VERSIONLIMIT_ATTRIBUTE

The limit of the number of versions which this VersionSeries should keep. The VersionLimit is an advisory attribute to be used by an agent in VersionPurging operations. The Repository does not act on this attribute.

PENDINGPUBLICOBJECT_ATTRIBUTE

public static final java.lang.String PENDINGPUBLICOBJECT_ATTRIBUTE

Deprecated. iFS 9.0.3: this attribute will be removed in a future release

A PublicObject which allows incremental archiving of work in progress while a VersionSeries is reserved.

LOCK_ON_RESERVE_NEXT_POLICY_LOCK_ALL

public static final java.lang.String LOCK_ON_RESERVE_NEXT_POLICY_LOCK_ALL

The out-of-the-box versioning policy for reserveNext aka checkOut operation. This is the default policy associated out-of-the-box with the VersionSeries class.
The out-of-the-box policy will UserLock the Family, VersionSeries, Last VersionDescription and ResolvedPublicObject on checking out a Document.

LOCK_ON_NEW_VERSION_POLICY_LOCK_ALL

public static final java.lang.String LOCK_ON_NEW_VERSION_POLICY_LOCK_ALL

The out-of-the-box versioning policy for newVersion aka checkIn operation. This is the default policy associated out-of-the-box with the VersionSeries class.
The out-of-the-box policy will SoftLock the Last VersionDescription and PublicObject (before the new one) on checking in a Document. The repository uses the standard SystemLockObject "SystemSoftLock" to soft lock these objects. SystemLockObject is a LockObject that is name unique in the system.

See Also:

SystemLockObject

UNLOCK_ON_UNRESERVE_POLICY_UNLOCK_ALL

public static final java.lang.String UNLOCK_ON_UNRESERVE_POLICY_UNLOCK_ALL

The out-of-the-box versioning policy for Unreserve aka cancelCheckOut operation. This is the default policy associated out-of-the-box with the VersionSeries class.
The out-of-the-box policy will unlock the Family, VersionSeries, Last VersionDescription and PublicObject on canceling the reserveNext operation.

LOCK_ON_RESERVE_NEXT_POLICY_LOCK_NONE

public static final java.lang.String LOCK_ON_RESERVE_NEXT_POLICY_LOCK_NONE

An alternate versioning policy for reserveNext aka checkOut operation. Associating this policy with the VersionSeries class or instance will not lock any versioning objects as part of the check Out operation.

LOCK_ON_NEW_VERSION_POLICY_LOCK_NONE

public static final java.lang.String LOCK_ON_NEW_VERSION_POLICY_LOCK_NONE

An alternate versioning policy for newVersion aka checkIn operation. Associating this policy with the VersionSeries class or instance will not lock any versioning objects as part of the checkIn operation.

UNLOCK_ON_UNRESERVE_POLICY_UNLOCK_NONE

public static final java.lang.String UNLOCK_ON_UNRESERVE_POLICY_UNLOCK_NONE

An alternate versioning policy for unReserve aka cancelCheckOut operation. Associating this policy with the VersionSeries class or instance will not lock any versioning objects as part of the cancelCheckOut operation.

Method Detail

handleEvent

public void handleEvent(IfsEvent event)
                 throws IfsException

Handles the specified event.

Overrides:

handleEvent in class PublicObject

Parameters:

event - the event

Throws:

IfsException - if the operation fails

getReservationComment

public java.lang.String getReservationComment()
                                       throws IfsException

Returns the comment when this series was reserved, or null if this series is not reserved.

Overrides:

getReservationComment in class PublicObject

Returns:

the reservation comment.

Throws:

IfsException - if operation fails.

getDefaultVersionDescription

public VersionDescription getDefaultVersionDescription()
                                                throws IfsException

Returns the default version of this version series.

Returns:

the default version of this version series.

Throws:

IfsException - if operation fails.

setDefaultVersionDescription

public void setDefaultVersionDescription(VersionDescription version)
                                  throws IfsException

Set the Default Version Description of this series.

Parameters:

VersionDescription - the desired default VersionDescription.

Throws:

IfsException - if operation fails.

getVersionDescriptions

public VersionDescription[] getVersionDescriptions(PublicObject version)
                                            throws IfsException

Returns an array of VersionDescriptions which reference the versioned public object passed in (more than one VersionDescription can refer to the same PublicObject).

Parameters:

version - PublicObject version

Returns:

array of VersionDescriptions which contain the public object passed in.

Throws:

IfsException - if operation fails.

isReserved

public boolean isReserved()
                   throws IfsException

Returns true if this VersionSeries is reserved by any user.

Overrides:

isReserved in class PublicObject

Returns:

true if this VersionSeries is reserved by any user.

Throws:

IfsException - if operation fails.

isReservedByCurrentUser

public boolean isReservedByCurrentUser()
                                throws IfsException

Returns true if this VersionSeries is reserved by the current user.

Overrides:

isReservedByCurrentUser in class PublicObject

Returns:

true if this VersionSeries is reserved by the current user.

Throws:

IfsException - if operation fails.

getReservor

public DirectoryUser getReservor()
                          throws IfsException

Returns the User that reserved this VersionSeries, null if not reserved

Overrides:

getReservor in class PublicObject

Returns:

the User that reserved this VersionSeries, null if not reserved

Throws:

IfsException - if operation fails.

getReservationDate

public java.util.Date getReservationDate()
                                  throws IfsException

Returns the Date that this VersionSeries was reserved, null if not reserved.

Overrides:

getReservationDate in class PublicObject

Returns:

the Date that this VersionSeries was reserved, null if not reserved.

Throws:

IfsException - if operation fails.

getPendingPublicObject

public PublicObject getPendingPublicObject()
                                    throws IfsException

Deprecated. iFS 9.0.3: this attribute (and thus, this method) will be removed in a future release

Returns the pending PublicObject that will become the next version upon a newVersion() invocation.

Returns:

the pending PublicObject, or null if none.

Throws:

IfsException - if operation fails.

setPendingPublicObject

public void setPendingPublicObject(PublicObject po)
                            throws IfsException

Deprecated. iFS 9.0.3: this attribute (and thus, this method) will be removed in a future release

Sets the pending PublicObject that will become the next version upon a newVersion() invocation.

Parameters:

po - the new PublicObject that will become the next version upon a newVersion() invocation.

Throws:

IfsException - if operation fails.

getResolvedPublicObject

public PublicObject getResolvedPublicObject()
                                     throws IfsException

Return the PublicObject to which this object resolves. For the non version classes (for example, Document and Folder) this simply returns itself (this). For the version classes, (Family, VersionSeries, and VersionDescription), this will return a non version-class object as determined by the configuration of the instance of the version class.

This override exists to return the Pending PublicObject value if the caller is the Reservor of this VersionSeries; in all other cases, it defers to the imlementation in the superclass (PublicObject). NOTE the PendingPublicObject attribute is deprecated and will be removed in a future release

Overrides:

getResolvedPublicObject in class PublicObject

Returns:

PublicObject that this object resolves to

Throws:

IfsException - if operation fails.

See Also:

PublicObject.getResolvedPublicObject()

setVersionLimit

public void setVersionLimit(int limit)
                     throws IfsException

Sets the value of the VersionLimit attribute. This value is used for advisory purposes only, as is not acted upon by the core iFS server. It can be used in conjunction with (for example) a custom agent that may use this value to decide to delete old versions in this VersionSeries.

Equivalent to:

 AttributeValue av = AttributeValue.newAttributeValue(implementation);
 setAttribute(VERSIONLIMIT_ATTRIBUTE, av);

Parameters:

limit - the advisory version limit.

Throws:

IfsException - if the operation fails

getFirstVersionDescription

public VersionDescription getFirstVersionDescription()
                                              throws IfsException

Returns the first VersionDescription of this series.

Returns:

the first VersionDescription of this series.

Throws:

IfsException - if operation fails.

getLastVersionDescription

public VersionDescription getLastVersionDescription()
                                             throws IfsException

Returns the last VersionDescription of this series.

Returns:

the last VersionDescription of this series.

Throws:

IfsException - if operation fails.

getNextVersionDescription

public VersionDescription getNextVersionDescription(VersionDescription version)
                                             throws IfsException

Returns the next VersionDescription of this series.

Returns:

the next VersionDescription of this series.

Throws:

IfsException - if operation fails.

getPreviousVersionDescription

public VersionDescription getPreviousVersionDescription(VersionDescription version)
                                                 throws IfsException

Returns the Version description previous to the one being passed by the user.

Parameters:

version - some VersionDescription in the series

Returns:

the previous VersionDescription

Throws:

IfsException - if operation fails.

getWorkpath

public java.lang.String getWorkpath()
                             throws IfsException

Returns the value for the local file path specified when this series was reserved. This information is maintained as a convenience. It is not used (nor validated) by the server.

Returns:

the local work path, or null if not reserved.

Throws:

IfsException - if operation fails.

unReserve

public void unReserve()
               throws IfsException

Cancels the reservation. Resets the Reservation Comment and the WorkPath.

Overrides:

unReserve in class PublicObject

Throws:

IfsException - if operation fails.

newVersion

public VersionDescription newVersion(VersionDescriptionDefinition vddef)
                              throws IfsException

Creates a new VersionDescription in this series from the specified VersionDescriptionDefinition. Updates the LastVersionDescription attribute. Unreserves the series, resetting the Reservation Comment and WorkPath attributes.

Overrides:

newVersion in class PublicObject

Parameters:

vddef - VersionDescriptionDefinition

Returns:

the version description that was created

Throws:

IfsException - if operation fails.

reserveNext

public void reserveNext(java.lang.String contentPath,
                        java.lang.String comment)
                 throws IfsException

Reserves the right to add the next version. This locks the series against additional versions by anyone else. A locked VersionSeries cannot be deleted; Checking in or canceling checkout will unreserve the series. Path being passed as parameter, is for convenience only and is not used or validated.

Overrides:

reserveNext in class PublicObject

Parameters:

contentPath - path to local file of reserved content

Comment - Check in comment.

Throws:

IfsException - if operation fails.

getVersionDescriptions

public VersionDescription[] getVersionDescriptions()
                                            throws IfsException

Returns an array of all VersionDescriptions in this VersionSeries.

Returns:

all VersionDescriptions in this VersionSeries.

Throws:

IfsException - if operation fails.

getVersionDescriptions

public VersionDescription getVersionDescriptions(int index)
                                          throws IfsException

Returns the specified VersionDescription of this series.

Returns:

the specified VersionDescription of this series.

Throws:

IfsException - if operation fails.

isVersioned

public boolean isVersioned()
                    throws IfsException

Returns false always. This class of object is not versionable.

Overrides:

isVersioned in class PublicObject

Returns:

false always. This object is not versionable.

Throws:

IfsException - if operation fails.