org.eclipse.emf.cdo.common.revision

## Interface CDORevisionManager

- All Superinterfaces:
    INotifier
  All Known Subinterfaces:
    InternalCDORevisionManager
  All Known Implementing Classes:
    DelegatingCDORevisionManager

      public interface CDORevisionManager
      extends INotifier

  Provides access to `revisions` in a CDO `repository` by demand loading and caching them.

  Revisions are generally queried by:

  - their object `ID` and
  - their `branch` plus either:
    - a timestamp or
    - a version

  If querying by timestamp it's also possible to ask for multiple revisions (identified by a list of object IDs) in one round trip (to the server if this revision manager is contained by a `session` or to the backend store if it is contained by a `repository`.

  Since:
    3.0
  Author:
    Eike Stepper
  No Implement
    This interface is not intended to be implemented by clients.
  No Extend
    This interface is not intended to be extended by clients.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `containsRevision(CDOID id, CDOBranchPoint branchPoint)` Returns `true` if the `revision cache` contains a `revision` with the given `ID` at the given `branch point` (branch + timestamp), `false` otherwise.
    `boolean` | `containsRevisionByVersion(CDOID id, CDOBranchVersion branchVersion)` Returns `true` if the `revision cache` contains a `revision` with the given `ID` at the given `branch version` (branch + version), `false` otherwise.
    `CDOBranchPointRange` | `getObjectLifetime(CDOID id, CDOBranchPoint branchPoint)`
    `EClass` | `getObjectType(CDOID id)` Returns the `type` of an object if a revision for that object is in the revision cache, `null` otherwise.
    `EClass` | `getObjectType(CDOID id, CDOBranchManager branchManagerForLoadOnDemand)` Returns the `type` of an object.
    `CDORevision` | `getRevision(CDOID id, CDOBranchPoint branchPoint, int referenceChunk, int prefetchDepth, boolean loadOnDemand)` Returns the `revision` with the given `ID` at the given `branch point` (branch + timestamp), optionally demand loading it if it is not already in the `cache`.
    `CDORevision` | `getRevisionByVersion(CDOID id, CDOBranchVersion branchVersion, int referenceChunk, boolean loadOnDemand)` Returns the `revision` with the given `ID` at the given `branch version` (branch + version), optionally demand loading it if it is not already in the `cache`.
    `java.util.List<CDORevision>` | `getRevisions(java.util.List<CDOID> ids, CDOBranchPoint branchPoint, int referenceChunk, int prefetchDepth, boolean loadOnDemand)` Returns the `revisions` with the given `IDs` at the given `branch point` (branch + timestamp), optionally demand loading them if they are not already in the `cache`.
    `void` | `handleRevisions(EClass eClass, CDOBranch branch, boolean exactBranch, long timeStamp, boolean exactTime, CDORevisionHandler handler)`

    - ### Methods inherited from interface org.eclipse.net4j.util.event.INotifier

      `addListener, getListeners, hasListeners, removeListener`

- - ### Method Detail

    - #### getObjectType

          EClass getObjectType(CDOID id)

      Returns the `type` of an object if a revision for that object is in the revision cache, `null` otherwise.

      Same as calling `getObjectType(id, null)`.

      See Also:
        `EObject.eClass()`, `getObjectType(CDOID, CDOBranchManager)`

    - #### getObjectType

          EClass getObjectType(CDOID id,
                               CDOBranchManager branchManagerForLoadOnDemand)

      Returns the `type` of an object.

      If no revision for that object is found in the revision cache the following is tried:

      1. If `branchManagerForLoadOnDemand` is not `null` the first revision of the object in the main branch is loaded from the server and its type is returned.
      2. Otherwise (i.e., if `branchManagerForLoadOnDemand` is `null` or the object does not exist) `null` is returned.

      A `branch manager` is required instead of just a boolean value to specify whether to demand-load or not because this revision manager must be able to access the `main branch` while demand-loading.

      Since:
        4.1
      See Also:
        `EObject.eClass()`, `getObjectType(CDOID)`

    - #### containsRevision

          boolean containsRevision(CDOID id,
                                   CDOBranchPoint branchPoint)

      Returns `true` if the `revision cache` contains a `revision` with the given `ID` at the given `branch point` (branch + timestamp), `false` otherwise.
      See Also:
        `getRevision(CDOID, CDOBranchPoint, int, int, boolean)`, `getRevisions(List, CDOBranchPoint, int, int, boolean)`

    - #### getRevision

          CDORevision getRevision(CDOID id,
                                  CDOBranchPoint branchPoint,
                                  int referenceChunk,
                                  int prefetchDepth,
                                  boolean loadOnDemand)

      Returns the `revision` with the given `ID` at the given `branch point` (branch + timestamp), optionally demand loading it if it is not already in the `cache`.
      Parameters:
        `referenceChunk` - The number of target `IDs` to load for each many-valued reference in the returned revision, or `CDORevision.UNCHUNKED` for all such list elements (IDs).
        `prefetchDepth` - The number of nested containment levels to load revisions for in one round trip. Use the symbolic constants `CDORevision.DEPTH_INFINITE` to prefetch all contained revisions or `CDORevision.DEPTH_NONE` to not prefetch anything. Only the explicitly requested revision is returned by this method. If additional revisions are prefetched they are placed in the revision cache to speed up subsequent calls to this method.
        `loadOnDemand` - If the requested revision is not contained in the revision cache it depends on this parameter's value whether the revision is loaded from the server or `null` is returned.
      See Also:
        `getRevisions(List, CDOBranchPoint, int, int, boolean)`, `getRevisionByVersion(CDOID, CDOBranchVersion, int, boolean)`

    - #### getRevisions

          java.util.List<CDORevision> getRevisions(java.util.List<CDOID> ids,
                                                   CDOBranchPoint branchPoint,
                                                   int referenceChunk,
                                                   int prefetchDepth,
                                                   boolean loadOnDemand)

      Returns the `revisions` with the given `IDs` at the given `branch point` (branch + timestamp), optionally demand loading them if they are not already in the `cache`.
      Parameters:
        `referenceChunk` - The number of target `IDs` to load for each many-valued reference in the returned revisions, or `CDORevision.UNCHUNKED` for all such list elements (IDs).
        `prefetchDepth` - The number of nested containment levels to load revisions for in one round trip. Use the symbolic constants `CDORevision.DEPTH_INFINITE` to prefetch all contained revisions or `CDORevision.DEPTH_NONE` to not prefetch anything. Only the explicitly requested revisions are returned by this method. If additional revisions are prefetched they are placed in the revision cache to speed up subsequent calls to this method.
        `loadOnDemand` - If one or more of the requested revisions is/are not contained in the revision cache it depends on this parameter's value whether the revision(s) is/are loaded from the server or `null` is placed in the list that is returned.
      See Also:
        `getRevision(CDOID, CDOBranchPoint, int, int, boolean)`

    - #### containsRevisionByVersion

          boolean containsRevisionByVersion(CDOID id,
                                            CDOBranchVersion branchVersion)

      Returns `true` if the `revision cache` contains a `revision` with the given `ID` at the given `branch version` (branch + version), `false` otherwise.
      See Also:
        `getRevisionByVersion(CDOID, CDOBranchVersion, int, boolean)`

    - #### getRevisionByVersion

          CDORevision getRevisionByVersion(CDOID id,
                                           CDOBranchVersion branchVersion,
                                           int referenceChunk,
                                           boolean loadOnDemand)

      Returns the `revision` with the given `ID` at the given `branch version` (branch + version), optionally demand loading it if it is not already in the `cache`.

      Prefetching of nested containment levels is not support by this method because the version of a particular revision can not serve as a reasonable baseline criterium for a consistent graph of multiple revisions.

      Parameters:
        `referenceChunk` - The number of target `IDs` to load for each many-valued reference in the returned revision, or `CDORevision.UNCHUNKED` for all such list elements (IDs).
        `loadOnDemand` - If the requested revision is not contained in the revision cache it depends on this parameter's value whether the revision is loaded from the server or `null` is returned.
      See Also:
        `getRevision(CDOID, CDOBranchPoint, int, int, boolean)`

    - #### getObjectLifetime

          CDOBranchPointRange getObjectLifetime(CDOID id,
                                                CDOBranchPoint branchPoint)

      Since:
        4.4

    - #### handleRevisions

          void handleRevisions(EClass eClass,
                               CDOBranch branch,
                               boolean exactBranch,
                               long timeStamp,
                               boolean exactTime,
                               CDORevisionHandler handler)

      Since:
        4.3

Copyright (c) 2004-2019 Eike Stepper (Loehne, Germany) and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html