wt.vc
Class VersionControlHelper

java.lang.Object
  wt.vc.VersionControlHelper

All Implemented Interfaces:

Externalizable, Serializable

public final class VersionControlHelper
extends Object
implements Externalizable

Provides access to the VersionControlService Application Programming Interface (API) via the static reference VersionControlHelper.service and several helper methods. Only one of the helper methods makes server-side access: isReviseAllowed(wt.vc.Versioned, boolean).

This API includes static methods to make new iterations/versions, find the predecessor of an iteration/version, find all the iteration(s) of a version, and get cookie information. These methods can be categorized as locally and remotely invokeable. The local methods are getters of information, typically from cookies, that are held in the client or server. The remote methods serve as wrappers to services that promote server-side functionality to clients.

Supported API: true

Extendable: false

See Also:

Mastered, Iterated, Versioned, VersionControlService, Serialized Form

Field Summary

static VersionControlService

service Supported API: true

Method Summary

static Iterated	assignIterationBranch(Iterated iteration, long branchId, boolean latest) Assigns a branch id and latest flag on the given iterated object to the given branch id and latest flag.
static Iterated	assignIterationCreator(Iterated iteration, WTPrincipalReference creator) Assigns a creator on the given iterated object to the given principal.
static IterationIdentifier	firstIterationId(Iterated iteration) For the given Iterated object, return the First IterationIdentifier for the series Supported API: true
static long	getBranchIdentifier(Iterated iteration) Gets the value of the iteration's branch id typed as it is returned from the POM's OID pool.
static LocalizableMessage	getIterationDisplayIdentifier(String versionId, String oneOffVersionId, String iterationId) Using IdentityFactory methods gets the displayable identifier of a version or iteration of an object given the String values of the object's various identifiers.
static LocalizableMessage	getIterationDisplayIdentifier(Versioned version) Get the displayable identifier of the object's iteration.
static IterationIdentifier	getIterationIdentifier(Iterated iteration) Gets the series value of the iteration.
static WTPrincipalReference	getIterationModifier(Iterated iteration) Gets the creator/updater (reference) of the iteration.
static Iterated	getLatestIteration(Iterated iteration, boolean includeMarkedForDelete) Gets the "latest" iteration in the same branch as the given one.
static String	getNote(Iterated iteration) Gets the note explaining why the iteration was created.
static OneOffVersionIdentifier	getOneOffVersionIdentifier(OneOffVersioned version) Gets the series value of the version.
static SearchCondition	getSearchCondition(Class target, boolean latest) Gets a SearchCondition to be appended to a query to find object(s) of the target class that are the "latest" iteration(s).
static SearchCondition	getSearchCondition(Class target, long branchId) Gets a SearchCondition to be appended to a query to find object(s) of the target class that are in a branch.
static SearchCondition	getSearchCondition(Class target, Mastered master) Gets a SearchCondition to be appended to a query to find object(s) of the target class that belong to the same master.
static SearchCondition	getSearchCondition(Class target, WTCollection objects, boolean notIntheBranch) Gets a SearchCondition to be appended to a query to find object(s) of the target class that are in a branch.
static WTPrincipalReference	getVersionCreator(Iterated iteration) Gets the creator (reference) of the version.
static LocalizableMessage	getVersionDisplayIdentifier(Versioned version) Get the displayable identifier of the object's version.
static VersionIdentifier	getVersionIdentifier(Versioned version) Gets the series value of the version.
static boolean	hasPredecessor(Iterated iteration) Tests if the given iteration has a predecessor.
static void	incrementIterationId(Iterated iteration) For the given Iteration, Increment the IterationIdentifier of the Iteration.
static void	incrementVersionId(Versioned version) For the given Iteration, Increment the VersionIdentifier of the Iteration.
static boolean	isAOneOff(OneOffVersioned version) Returns true if the given version is a one-off version.
static boolean	isLatestIteration(Iterated iteration) Tests if the given iteration is the latest, or last one in the version branch.
static boolean	isReviseAllowed(Versioned version, boolean viewBranch) This method decides if a wt.vc.Versioned object can be revised.
static VersionIdentifier	newBranchVersionId(Versioned version) Returns a new Version Identifier on the next control branch.
static Mastered	newMasterFor(Iterated iteration) Constructs a new Mastered object for the given Iterated object using introspection to determine the appropriate master class for the iteration and reflection to invoke that master class's no-arg factory method.
static IterationIdentifier	nextIterationId(Iterated iteration) For the given Iteration, answer the next IterationIdentifier in the series Supported API: true
static VersionIdentifier	nextVersionId(Versioned version) For the given Iteration, answer the next VersionIdentifier in the series Supported API: true
static void	setIterationIdentifier(Iterated iteration, IterationIdentifier identifier) Sets the series value of the iteration.
static void	setIterationModifier(Iterated iteration, WTPrincipalReference creator) Sets the creator/updater of the iteration.
static void	setNote(Iterated iteration, String note) Sets the note explaining why the iteration was created.
static void	setVersionIdentifier(Versioned version, VersionIdentifier identifier) Sets the series value of the version.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

service

public static final VersionControlService service

Supported API: true

Method Detail

getLatestIteration

public static Iterated getLatestIteration(Iterated iteration,
                                          boolean includeMarkedForDelete)
                                   throws WTException,
                                          VersionControlException

Gets the "latest" iteration in the same branch as the given one. A check to see if the given iteration is the latest one is not made since it could be stale. Passing true for includeMarkedForDelete will attempt getting the latest iteratation even if marked for delete.

Supported API: true

Parameters:

iteration -

includeMarkedForDelete -

Returns:

Iterated

Throws:

WTException

VersionControlException

setVersionIdentifier

public static void setVersionIdentifier(Versioned version,
                                        VersionIdentifier identifier)
                                 throws WTException,
                                        VersionControlException,
                                        WTPropertyVetoException,
                                        SeriesIncrementInvalidException

Sets the series value of the version.

Supported API: true

Parameters:

version -

identifier -

Throws:

WTException

VersionControlException

WTPropertyVetoException

SeriesIncrementInvalidException

getVersionIdentifier

public static VersionIdentifier getVersionIdentifier(Versioned version)
                                              throws VersionControlException

Gets the series value of the version.

Supported API: true

Parameters:

version -

Returns:

VersionIdentifier

Throws:

VersionControlException

incrementVersionId

public static final void incrementVersionId(Versioned version)
                                     throws WTException,
                                            VersionControlException,
                                            WTPropertyVetoException,
                                            SeriesIncrementInvalidException

For the given Iteration, Increment the VersionIdentifier of the Iteration. This will set the VersionIdentifier with the new value.

Supported API: true

Parameters:

version -

Throws:

WTException

VersionControlException

WTPropertyVetoException

SeriesIncrementInvalidException

See Also:

nextVersion

nextVersionId

public static final VersionIdentifier nextVersionId(Versioned version)
                                             throws WTException,
                                                    VersionControlException,
                                                    WTPropertyVetoException,
                                                    SeriesIncrementInvalidException

For the given Iteration, answer the next VersionIdentifier in the series

Supported API: true

Parameters:

version -

Returns:

VersionIdentifier

Throws:

WTException

VersionControlException

WTPropertyVetoException

SeriesIncrementInvalidException

newBranchVersionId

public static final VersionIdentifier newBranchVersionId(Versioned version)
                                                  throws WTException,
                                                         VersionControlException,
                                                         WTPropertyVetoException

Returns a new Version Identifier on the next control branch.

Supported API: true

Parameters:

version -

Returns:

VersionIdentifier

Throws:

WTException

VersionControlException

WTPropertyVetoException

setIterationIdentifier

public static void setIterationIdentifier(Iterated iteration,
                                          IterationIdentifier identifier)
                                   throws WTException,
                                          VersionControlException,
                                          WTPropertyVetoException,
                                          SeriesIncrementInvalidException

Sets the series value of the iteration.

Supported API: true

Parameters:

iteration -

identifier -

Throws:

WTException

VersionControlException

WTPropertyVetoException

SeriesIncrementInvalidException

firstIterationId

public static final IterationIdentifier firstIterationId(Iterated iteration)
                                                  throws WTException,
                                                         VersionControlException,
                                                         WTPropertyVetoException

For the given Iterated object, return the First IterationIdentifier for the series

Supported API: true

Parameters:

iteration -

Returns:

IterationIdentifier

Throws:

WTException

VersionControlException

WTPropertyVetoException

getIterationIdentifier

public static IterationIdentifier getIterationIdentifier(Iterated iteration)
                                                  throws VersionControlException

Gets the series value of the iteration.

Supported API: true

Parameters:

iteration -

Returns:

IterationIdentifier

Throws:

VersionControlException

incrementIterationId

public static final void incrementIterationId(Iterated iteration)
                                       throws WTException,
                                              VersionControlException,
                                              WTPropertyVetoException,
                                              SeriesIncrementInvalidException

For the given Iteration, Increment the IterationIdentifier of the Iteration. This will set the IterationIdentifier with the new value.

Supported API: true

Parameters:

iteration -

Throws:

WTException

VersionControlException

WTPropertyVetoException

SeriesIncrementInvalidException

See Also:

nextIteration

nextIterationId

public static final IterationIdentifier nextIterationId(Iterated iteration)
                                                 throws WTException,
                                                        VersionControlException,
                                                        WTPropertyVetoException,
                                                        SeriesIncrementInvalidException

For the given Iteration, answer the next IterationIdentifier in the series

Supported API: true

Parameters:

iteration -

Returns:

IterationIdentifier

Throws:

WTException

VersionControlException

WTPropertyVetoException

SeriesIncrementInvalidException

getBranchIdentifier

public static long getBranchIdentifier(Iterated iteration)
                                throws VersionControlException

Gets the value of the iteration's branch id typed as it is returned from the POM's OID pool.

Supported API: true

Parameters:

iteration -

Returns:

long

Throws:

VersionControlException

setIterationModifier

public static void setIterationModifier(Iterated iteration,
                                        WTPrincipalReference creator)
                                 throws WTException,
                                        VersionControlException,
                                        WTPropertyVetoException

Sets the creator/updater of the iteration.

Supported API: true

Parameters:

iteration -

creator -

Throws:

WTException

VersionControlException

WTPropertyVetoException

getIterationModifier

public static WTPrincipalReference getIterationModifier(Iterated iteration)
                                                 throws VersionControlException,
                                                        WTException

Gets the creator/updater (reference) of the iteration.

Supported API: true

Parameters:

iteration -

Returns:

WTPrincipalReference

Throws:

VersionControlException

WTException

getVersionCreator

public static WTPrincipalReference getVersionCreator(Iterated iteration)
                                              throws VersionControlException,
                                                     WTException

Gets the creator (reference) of the version. This is the creator/updater of the very first iteration in the branch. This will query the database if the given iteration is not the first one in a branch.

Supported API: true

Parameters:

iteration -

Returns:

WTPrincipalReference

Throws:

VersionControlException

WTException

setNote

public static void setNote(Iterated iteration,
                           String note)
                    throws WTException,
                           VersionControlException,
                           WTPropertyVetoException

Sets the note explaining why the iteration was created.

Supported API: true

Parameters:

iteration -

note -

Throws:

WTException

VersionControlException

WTPropertyVetoException

getNote

public static String getNote(Iterated iteration)
                      throws VersionControlException

Gets the note explaining why the iteration was created.

Supported API: true

Parameters:

iteration -

Returns:

String

Throws:

VersionControlException

getSearchCondition

public static SearchCondition getSearchCondition(Class target,
                                                 Mastered master)
                                          throws VersionControlException,
                                                 QueryException

Gets a SearchCondition to be appended to a query to find object(s) of the target class that belong to the same master.

Supported API: true

Parameters:

target -

master -

Returns:

SearchCondition

Throws:

VersionControlException

QueryException

getSearchCondition

public static SearchCondition getSearchCondition(Class target,
                                                 long branchId)
                                          throws VersionControlException,
                                                 QueryException

Gets a SearchCondition to be appended to a query to find object(s) of the target class that are in a branch. Since the branch identifier is guaranteed to be unique within the system this criteria effectively will find all objects in the branch.

Supported API: true

Parameters:

target -

branchId -

Returns:

SearchCondition

Throws:

VersionControlException

QueryException

getSearchCondition

public static SearchCondition getSearchCondition(Class target,
                                                 boolean latest)
                                          throws VersionControlException,
                                                 QueryException

Gets a SearchCondition to be appended to a query to find object(s) of the target class that are the "latest" iteration(s).

For example, if the given boolean is false then all objects, except the latest iteration(s) will be returned. Otherwise, only the latest iteration(s) are returned.

Supported API: true

Parameters:

target -

latest -

Returns:

SearchCondition

Throws:

VersionControlException

QueryException

hasPredecessor

public static boolean hasPredecessor(Iterated iteration)

Tests if the given iteration has a predecessor.

Supported API: true

Parameters:

iteration -

Returns:

boolean

isLatestIteration

public static boolean isLatestIteration(Iterated iteration)

Tests if the given iteration is the latest, or last one in the version branch.

Supported API: true

Parameters:

iteration -

Returns:

boolean

isAOneOff

public static boolean isAOneOff(OneOffVersioned version)

Returns true if the given version is a one-off version.

Supported API: true

Parameters:

version -

Returns:

boolean

getOneOffVersionIdentifier

public static OneOffVersionIdentifier getOneOffVersionIdentifier(OneOffVersioned version)
                                                          throws VersionControlException

Gets the series value of the version.

Supported API: true

Parameters:

version -

Returns:

OneOffVersionIdentifier

Throws:

VersionControlException

newMasterFor

public static Mastered newMasterFor(Iterated iteration)
                             throws WTException

Constructs a new Mastered object for the given Iterated object using introspection to determine the appropriate master class for the iteration and reflection to invoke that master class's no-arg factory method.

Supported API: true

Parameters:

iteration -

Returns:

Mastered

Throws:

WTException

getSearchCondition

public static SearchCondition getSearchCondition(Class target,
                                                 WTCollection objects,
                                                 boolean notIntheBranch)
                                          throws VersionControlException,
                                                 QueryException,
                                                 WTException

Gets a SearchCondition to be appended to a query to find object(s) of the target class that are in a branch. Since the branch identifier is guaranteed to be unique within the system this criteria effectively will find all objects in the branch.

Supported API: true

Parameters:

target - Target Class

objects - Collection of Iterated objects for which the branch identifiers are used in the search condition.

notIntheBranch - Flag to represent NOT IN condition in the search condition.

Returns:

SearchCondition

Throws:

VersionControlException

QueryException

WTException

isReviseAllowed

public static boolean isReviseAllowed(Versioned version,
                                      boolean viewBranch)
                               throws WTException

This method decides if a wt.vc.Versioned object can be revised.

Supported API: true

Returns:

boolean that indicates if the object is available to be revised

Throws:

WTException

assignIterationCreator

public static Iterated assignIterationCreator(Iterated iteration,
                                              WTPrincipalReference creator)
                                       throws WTException,
                                              VersionControlException,
                                              WTPropertyVetoException

Assigns a creator on the given iterated object to the given principal. If the principal is null the current session principal is used. This method is only intended to be used when loading information into the iterated object before it is persisted. Otherwise, if it is already persistent an exception will occur.

Supported API: true

Parameters:

iteration -

creator -

Returns:

Iterated

Throws:

WTException

VersionControlException

WTPropertyVetoException

assignIterationBranch

public static Iterated assignIterationBranch(Iterated iteration,
                                             long branchId,
                                             boolean latest)
                                      throws WTException,
                                             VersionControlException,
                                             WTPropertyVetoException

Assigns a branch id and latest flag on the given iterated object to the given branch id and latest flag. This method is only intended to be used when loading information into the iterated object before it is persisted. Otherwise, if it is already persistent an exception will occur.

Supported API: true

Parameters:

iteration -

branchId -

latest -

Returns:

Iterated

Throws:

WTException

VersionControlException

WTPropertyVetoException

getVersionDisplayIdentifier

public static LocalizableMessage getVersionDisplayIdentifier(Versioned version)
                                                      throws VersionControlException

Get the displayable identifier of the object's version. The identifier for the version might be for example A or B for a Revision.

Supported API: true

Parameters:

version -

Returns:

LocalizableMessage

Throws:

VersionControlException

getIterationDisplayIdentifier

public static LocalizableMessage getIterationDisplayIdentifier(Versioned version)
                                                        throws VersionControlException

Get the displayable identifier of the object's iteration. The identifier for the iteration might be for example A.1 or A.2 after an Iteration.

Supported API: true

Parameters:

version -

Returns:

LocalizableMessage

Throws:

VersionControlException

getIterationDisplayIdentifier

public static LocalizableMessage getIterationDisplayIdentifier(String versionId,
                                                               String oneOffVersionId,
                                                               String iterationId)

Using IdentityFactory methods gets the displayable identifier of a version or iteration of an object given the String values of the object's various identifiers.

Supported API: true

Parameters:

versionId - - String value of a Versioned object's VersionIdentifier

oneOffVersionId - - String value of a OneOffVersioned object's OneOffVersionIdentifier

iterationId - - String value of a Versioned object's IterationIdentifier

Returns:

LocalizableMessage