From 3259e9d702451eae8965688c62c167913c73df34 Mon Sep 17 00:00:00 2001 From: Eike Stepper Date: Fri, 25 Sep 2015 12:37:17 +0200 Subject: [297142] Provide more documentation https://bugs.eclipse.org/bugs/show_bug.cgi?id=297142--- .../operators/Doc01_ConfiguringRepositories.html | 2 +- .../html/operators/index.html | 4 +- .../html/users/Doc01_UserInterface.html | 2 +- .../html/users/Doc05_UsingCheckouts.html | 2 +- .../html/users/Doc06_UsingResources.html | 2 +- .../html/users/Doc07_UsingModels.html | 10 +- .../html/users/Doc08_Collaborating.html | 180 +++++++++++++++ .../html/users/Doc08_TechnicalBackground.html | 206 ----------------- .../html/users/Doc09_TechnicalBackground.html | 206 +++++++++++++++++ .../html/users/collaborating.png | Bin 0 -> 43951 bytes .../html/users/early-conflict.png | Bin 0 -> 11398 bytes .../org.eclipse.emf.cdo.doc/html/users/index.html | 31 ++- .../html/users/late-conflict.png | Bin 0 -> 23658 bytes .../html/users/pessimistic-locking.png | Bin 0 -> 31061 bytes .../operators/Doc01_ConfiguringRepositories.java | 2 +- .../emf/cdo/doc/users/Doc01_UserInterface.java | 2 +- .../emf/cdo/doc/users/Doc05_UsingCheckouts.java | 2 +- .../emf/cdo/doc/users/Doc06_UsingResources.java | 2 +- .../emf/cdo/doc/users/Doc07_UsingModels.java | 4 +- .../emf/cdo/doc/users/Doc08_Collaborating.java | 194 ++++++++++++++++ .../cdo/doc/users/Doc08_TechnicalBackground.java | 246 --------------------- .../cdo/doc/users/Doc09_TechnicalBackground.java | 246 +++++++++++++++++++++ .../eclipse/emf/cdo/doc/users/collaborating.png | Bin 0 -> 43951 bytes .../eclipse/emf/cdo/doc/users/early-conflict.png | Bin 0 -> 11398 bytes .../eclipse/emf/cdo/doc/users/late-conflict.png | Bin 0 -> 23658 bytes .../emf/cdo/doc/users/pessimistic-locking.png | Bin 0 -> 31061 bytes plugins/org.eclipse.emf.cdo.doc/toc.html | 3 +- plugins/org.eclipse.emf.cdo.doc/toc.xml | 3 +- plugins/org.eclipse.emf.cdo.releng/help/toc.html | 3 +- 29 files changed, 869 insertions(+), 483 deletions(-) create mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/Doc08_Collaborating.html delete mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/Doc08_TechnicalBackground.html create mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/Doc09_TechnicalBackground.html create mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/collaborating.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/early-conflict.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/late-conflict.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/html/users/pessimistic-locking.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/Doc08_Collaborating.java delete mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/Doc08_TechnicalBackground.java create mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/Doc09_TechnicalBackground.java create mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/collaborating.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/early-conflict.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/late-conflict.png create mode 100644 plugins/org.eclipse.emf.cdo.doc/src/org/eclipse/emf/cdo/doc/users/pessimistic-locking.png diff --git a/plugins/org.eclipse.emf.cdo.doc/html/operators/Doc01_ConfiguringRepositories.html b/plugins/org.eclipse.emf.cdo.doc/html/operators/Doc01_ConfiguringRepositories.html index 01b84ef44c..4f9d2b78ed 100644 --- a/plugins/org.eclipse.emf.cdo.doc/html/operators/Doc01_ConfiguringRepositories.html +++ b/plugins/org.eclipse.emf.cdo.doc/html/operators/Doc01_ConfiguringRepositories.html @@ -243,7 +243,7 @@ function windowTitle()
Specifies whether the repository will support the storage of instances of the Ecore (meta meta) model or not.
- With the advent of the legacy mode in CDO 3.0 you can store instances of any model in CDO repositories. + With the advent of the legacy mode in CDO 3.0 you can store instances of any model in CDO repositories. Whether these models have been generated for CDO or not only influences their characteristics (scalability, performance, etc.). As a consequence you can also store instances of the Ecore (meta meta) model in CDO Repositories. Since Ecore is always registered in all package registries the legacy mode would lead to the creation of mapped tables in many types of stores, diff --git a/plugins/org.eclipse.emf.cdo.doc/html/operators/index.html b/plugins/org.eclipse.emf.cdo.doc/html/operators/index.html index 81778117d7..2a47eb5d36 100644 --- a/plugins/org.eclipse.emf.cdo.doc/html/operators/index.html +++ b/plugins/org.eclipse.emf.cdo.doc/html/operators/index.html @@ -23,7 +23,7 @@ function windowTitle()
Operator's Guide |
- + |
@@ -71,7 +71,7 @@ function windowTitle()
+Collaborating in Real-Time |
+ + |
+ CDO supports real-time collaboration on models by transferring the changes that one user
+ commits
to the repository to all
+ other users connected to the same repository and transparently weaving those changes into their model copies.
+
+ With CDO the local model copies (in particular with online transactional checkouts) do not need to be + updated manually; they are automatically updated (almost) at the time they are changed by other users. +
+ As real-time collaboration relies on committing a transaction
it applies only to
+ online transactional checkouts and the editors
+ opened on online transactional models. Saving a model editor commits the underlying transaction.
+
+ The data integrity of the models and model elements in a repository is guaranteed by write locks
+ that are acquired per model element. Read locks
and write options
,
+ as well as durable locks
are supported by the core-level APIs
+ but not by the CDO Explorer's user interface.
+
+ Table of Contents
+
+ By default model elements are locked optimistically, that is, the CDO server implicitly acquires and releases locks while executing + a commit operation. These implicit locks are not visible to the committing user or any other user of the same repository. +
+ Optimistic locking provides for the highest possible degree of concurrency but it also comes with a non-zero risk of commit conflicts + that are only detected when a commit operation is executed by the CDO server and, as a consequence, rejected. Because of + Early Conflict Detection the risk of conflicts that are detected that late in the commit process is generally much lower + than, for example, in pure database-based applications. +
+ To completely eliminate the risk of commit conflicts Pessimistic Locking must be used. + +
+ As the local model copies of a user are automatically updated (almost) at the time they are changed by other users
+ CDO can anticipate the conflict potential of the local changes early, in particular before an attempt to commit these changes is even made.
+ The CDO Model Editor decorates such conflicting model elements with a red-colored font,
+ indicating that the underlying transaction
can not be successfully committed anymore.
+
+ Automatic Conflict Resolution and Interactive Conflict Resolution, if enabled, may have an impact on what exact types + of changes are considered a conflict. + +
+ Each time a local transaction is notified of a remote change by the CDO server and local conflicts are detected (see Early Conflict Detection) + these conflicts are categorized as being either trivial conflicts or non-trivial conflicts. Trivial conflicts are: +
features
on both sides (local and remote) of the same model element.
+ features
on both sides (local and remote) of the same model element.
+ + Trivial conflicts are merged automatically into the local transaction, i.e., no user interaction is involved. +
+ When non-trivial changes are detected, i.e., changes to the same single-valued feature
on both sides (local and remote)
+ of the same model element, automatic conflict resolution is suspended for all model elements until the next local commit operation.
+ During this period all incoming change notifications are accumulated and remembered for possible Interactive Conflict Resolution
+ at commit time.
+
+
+ If Automatic Conflict Resolution has detected non-trivial conflicts in a local transaction
and
+ an attempt is made to commit this transaction the following dialog pops up:
+
+ The dialog shows an overview of how many local model elements are added, changed, and removed. One of several conflict resolution + actions has to be selected by the user: +
+ Saving this merge editor commits the merged local transaction. Note that new non-trivial conflicts may have been detected + in the meantime, in which case interactive conflict resolution is triggered again. +
rolled back
and the local model copies
+ are automatically updated to their latest remote versions. As a result all local changes will be lost and eventually need to be
+ re-applied and committed again.
+ + Sometimes it seems not desirable to risk commit conflicts as they can occur with Optimistic Locking. + In these cases CDO supports the acquisition of explicit locks on selected models (see Tree Locking) and model elements. +
+ Pessimistic locking support consists of: +
+ Whether custom user interface components, such as model editors or views, support local actions and/or lock state visualization depends + on the implementation of those components. The CDO Model Editor's context menu offers lock actions for model elements that are not locked + by anyone and unlock actions for model elements that are locked by the current user. Both the CDO Model Editor and the + Project Explorer Integration support lock state visualization by decorating model elements that are locked by the current user + with a green lock icon (indicating that they can be modified) and model elements that are locked by other users with a red lock icon + (indicating that they can not be modified): +
+ +
+ Note that a CDO editor generally operates in the context of a separate transaction, in particular not in the context of the
+ read-only view
of the associated checkout, which explains why, in the screen shot above, both checkouts show the
+ locked model elements with a red lock icon decoration. In other words, while a model element is locked in a CDO editor it can not be
+ modified directly in the associated checkout via the Project Explorer.
+
+
+ Sometimes it is desirable to lock not just a single model element but to atomically lock the tree of model elements rooted at the + selected model element. The CDO Model Editor's context menu offers a Lock Tree action for model elements that are not locked by + anyone and an Unlock Tree action for model elements that are locked by the current user. + +
+ With automatic locking turned on for a particular transaction
write locks are automatically acquired
+ for model elements at the time these model elements are modified the first time.
+
+ Automatic locking is not yet supported for checkouts. + +
+ With automatic committing turned on for a particular transaction
that transaction is automatically committed
+ each time a model element is modified. This can be very useful when the primary purpose of a repository is to support real-time
+ collaboration between a number of users.
+
+ On the other hand with automatic committing multiple logically related changes are no longer + isolated in single composed commits. This can be especially undesirable in repositories with auditing or branching support + because the databases of these types of repositories monotonously grow with the number of commits. +
+ Automatic committing is not yet supported for checkouts. + +
+diff --git a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc01_UserInterface.html b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc01_UserInterface.html index 49f73c3261..c1636fc99c 100644 --- a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc01_UserInterface.html +++ b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc01_UserInterface.html @@ -233,7 +233,7 @@ function windowTitle()
diff --git a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc05_UsingCheckouts.html b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc05_UsingCheckouts.html index ec7f246fe6..5f26b61e82 100644 --- a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc05_UsingCheckouts.html +++ b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc05_UsingCheckouts.html @@ -430,7 +430,7 @@ function windowTitle() Updating an offline checkout is a remote operation.
See Also:
diff --git a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc06_UsingResources.html b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc06_UsingResources.html
index 23e5246096..8a2fed0bc8 100644
--- a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc06_UsingResources.html
+++ b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc06_UsingResources.html
@@ -32,7 +32,7 @@ function windowTitle()
consists of folders and different types of resources, all categorized as resource nodes
.
All modifications of the resource tree that are triggered in the Project Explorer
- are performed in a separate background transaction
, see Technical Background of Transactions for details.
+ are performed in a separate background transaction
, see Technical Background of Transactions for details.
Modifying the resource tree is only possible in checkouts that are not read-only, i.e., not in Online Historical Checkouts.
diff --git a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc07_UsingModels.html b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc07_UsingModels.html index 7ebaae0a45..96949fd872 100644 --- a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc07_UsingModels.html +++ b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc07_UsingModels.html @@ -23,14 +23,14 @@ function windowTitle()
Working with Models and Model Elements |
- + |
All modifications of model elements that are triggered in the Project Explorer
(as opposed to being triggered in a model editor)
- are performed in a separate background transaction
, see Technical Background of Transactions for details.
+ are performed in a separate background transaction
, see Technical Background of Transactions for details.
Modifying model elements is only possible in checkouts that are not read-only, i.e., not in Online Historical Checkouts.
@@ -60,7 +60,7 @@ function windowTitle() or an existing model element that can have children, opening the context menu and opening the New sub menu. This sub menu looks different depending on the type of the container. It is explained in the following two sub sections.
See Also:
@@ -151,10 +151,10 @@ function windowTitle()
All registered model editors open their own, separate transaction
, which is typically
committed
when the editor is saved.
- See Technical Background of Transactions for details on how transactions are typically used by editors.
+ See Technical Background of Transactions for details on how transactions are typically used by editors.
diff --git a/plugins/org.eclipse.emf.cdo.doc/html/users/Doc08_Collaborating.html b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc08_Collaborating.html new file mode 100644 index 0000000000..7ca0ea701f --- /dev/null +++ b/plugins/org.eclipse.emf.cdo.doc/html/users/Doc08_Collaborating.html @@ -0,0 +1,180 @@ + + + +
+
+ + + + + + + +
+