Package com.documentum.fc.client

# Interface IDfVersionPolicy

public interface IDfVersionPolicy
This interface provides version-related information about SysObjects. It provides the default version-related behavior of the Checkin component. Versions are governed by the following rules:

- Users must have at least Version permission on an object to create a major, minor, or branched version of the object.
- If the repository is running under folder security, creating a version of an object requires at least Write permission on all cabinets or folders in which the object is stored.
- Major and minor versions are possible for existing objects that are the most recent versions on a branch.
- Only existing objects can be branched.
- Objects can be branched only if they are not the most recent version.
- Users cannot create major or minor versions an object that is locked (checked out) by another user.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DF_BRANCH_VERSION`
  Represents an object's next possible branched version.
  `static final int`
  `DF_CANNOT_VERSION`
  Indicates that an object cannot be branched or saved with the same implicit version label.
  `static final int`
  `DF_NEXT_MAJOR`
  Represents an object's next major implicit version label.
  `static final int`
  `DF_NEXT_MINOR`
  Represents an object's next minor implicit version label.
  `static final int`
  `DF_SAME_VERSION`
  Represents an object's current implicit version label.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `canCheckinFromFile()`
  Indicates whether the object's content file can be overwritten by an external file when the object is checked in to the repository.
  `boolean`
  `canVersion(int toVersion)`
  Tests whether an object may be saved as the next major, minor, branch, or same version.
  `String`
  `getBranchLabel()`
  Returns the next possible branched version label of an object.
  `int`
  `getDefaultCheckinVersion()`
  Returns the default checkin version of an object.
  `String`
  `getLogComment()`
  Returns the log entry for an object.
  `String`
  `getNextMajorLabel()`
  Returns the next major implicit version label for an object.
  `String`
  `getNextMinorLabel()`
  Returns the next minor implicit version label for an object.
  `String`
  `getSameLabel()`
  Returns the current implicit version label of an object.
  `String`
  `getVersionSummary(String separator)`
  Returns all implicit and symbolic version labels associated with a SysObject.
  `boolean`
  `isDefaultRetainLockOnCheckin()`
  Indicates whether to retain the lock on an object after it is checked into the repository.

- ## Field Details

  - ### DF_NEXT_MAJOR

    static final int DF_NEXT_MAJOR
    Represents an object's next major implicit version label.
    See Also:
      - Constant Field Values

  - ### DF_NEXT_MINOR

    static final int DF_NEXT_MINOR
    Represents an object's next minor implicit version label.
    See Also:
      - Constant Field Values

  - ### DF_SAME_VERSION

    static final int DF_SAME_VERSION
    Represents an object's current implicit version label.
    See Also:
      - Constant Field Values

  - ### DF_BRANCH_VERSION

    static final int DF_BRANCH_VERSION
    Represents an object's next possible branched version.
    See Also:
      - Constant Field Values

  - ### DF_CANNOT_VERSION

    static final int DF_CANNOT_VERSION
    Indicates that an object cannot be branched or saved with the same implicit version label.
    See Also:
      - Constant Field Values

- ## Method Details

  - ### getNextMajorLabel

    String getNextMajorLabel() throws DfException
    Returns the next major implicit version label for an object.

    A version's implicit label is the numerical version label typically assigned to the object by the server. For more information about implicit labels and versioning, refer to Server Fundamentals.

    Returns:
      the next major implicit version label; `null` if the object is immutable.
    Throws:
      `DfException` - if the server returns an error.

  - ### getNextMinorLabel

    String getNextMinorLabel() throws DfException
    Returns the next minor implicit version label for an object.

    A version's implicit label is the numerical version label typically assigned to the object by the server. For more information about implicit labels and versioning, refer to Server Fundamentals.

    Returns:
      the next minor implicit version label; `null` if the object is immutable.
    Throws:
      `DfException` - if the server returns an error.

  - ### getSameLabel

    String getSameLabel() throws DfException
    Returns the current implicit version label of an object.

    A version's implicit label is the numerical version label typically assigned to the object by the server. For more information about implicit labels and versioning, refer to Server Fundamentals.

    Returns:
      the current implicit version label.
    Throws:
      `DfException` - if the server returns an error.

  - ### getBranchLabel

    String getBranchLabel() throws DfException
    Returns the next possible branched version label of an object.

    When a user creates a branched version, the server adds two more places to the version's current implicit version label. For example, if a user branches a version with the implicit label 1.2, the new branched version is assigned the label 1.2.1.0.

    For more information about branching and version labels, refer to Server Fundamentals.

    Returns:
      the next possible branched implicit version label; `null` if the object is not immutable.
    Throws:
      `DfException` - if the server returns an error.

  - ### getLogComment

    String getLogComment() throws DfException
    Returns the log entry for an object.

    When users check in an object, they can provide some text that is entered in the log_entry attribute of the object.

    Returns:
      the text of the log entry.
    Throws:
      `DfException` - if the server returns an error.

  - ### getVersionSummary

    String getVersionSummary(String separator) throws DfException
    Returns all implicit and symbolic version labels associated with a SysObject.

    Each SysObject has one implicit version label and may have one or more symbolic labels. For more information about an object's version labels, refer to Server Fundamentals.

    Parameters:
      `separator` - the symbol used to separate the version labels in the return value.
    Returns:
      a list of all the implicit and symbolic version labels for the SysObject, delimited by the symbol defined by the `separator` parameter.
    Throws:
      `DfException` - if the server returns an error.

  - ### canVersion

    boolean canVersion(int toVersion) throws DfException
    Tests whether an object may be saved as the next major, minor, branch, or same version.

    For definitions of major, minor, and branched versions, refer to Server Fundamentals.

    Parameters:
      `toVersion` - the integer representing the major, minor, branch, or same version label that you want to test. Valid integer values and the label test they represent are:

           Integer     Versioning Condition
           0           Next Major Version Label (DF_NEXT_MAJOR)
           1           Next Minor Version Label (DF_NEXT_MINOR)
           2           Same Version Label as Object (DF_SAME_VERSION)
           3           Next Branched Version Label (DF_BRANCH_VERSION)

    Returns:
      `true` if the object can be set to the version identified in `toVersion`; `false` if not.
    Throws:
      `DfException` - if the server returns an error.

  - ### getDefaultCheckinVersion

    int getDefaultCheckinVersion() throws DfException
    Returns the default checkin version of an object.

    When users check in an object, this method can provide a a default version selection for the user.

    For Documentum clients, the system-defined default is to check in the object as the next minor version.

    Returns:
      an integer representing the default checkin version of the object. Valid return values and their meanings are:

           Integer     Versioning Condition
           0           Next Major Version Label (DF_NEXT_MAJOR)
           1           Next Minor Version Label (DF_NEXT_MINOR)
           2           Same Version Label as Object (DF_SAME_VERSION)
           3           Next Branched Version Label (DF_BRANCH_VERSION)
           4           Object is Immutable (DF_CANNOT_VERSION)

    Throws:
      `DfException` - if the server returns an error.

  - ### isDefaultRetainLockOnCheckin

    boolean isDefaultRetainLockOnCheckin() throws DfException
    Indicates whether to retain the lock on an object after it is checked into the repository.

    The `checkin` method provides a boolean parameter used for retaining a lock after an object is checked in. If this flag is set to `true`, the checkin saves the object to the repository but does not release the lock on the object. The save overwrites the existing object in the repository. If the flag is set to `false`, users cannot overwrite the object in the repository and users are forced to version the object on checkin.

    The default value is `false`.

    Returns:
      `true` if a lock should be retained on the object after it is checked into the repository; `false` if not.
    Throws:
      `DfException` - if the server returns an error.
    See Also:
      - `IDfSysObject.checkin(boolean, java.lang.String)`

  - ### canCheckinFromFile

    boolean canCheckinFromFile() throws DfException
    Indicates whether the object's content file can be overwritten by an external file when the object is checked in to the repository.

    If this flag is `true`, users can choose to overwrite an object's content file with an external file when they check in the object.

    Returns:
      `true` if a checkin from an external file is allowed; `false` if not.
    Throws:
      `DfException` - if the server returns an error.