Skip to main content
summaryrefslogtreecommitdiffstats
blob: 8046c111aa0f4c9c86b2cfae9104c2e98c80b312 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
/*
 * Copyright (c) 2015 Eike Stepper (Berlin, 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
 *
 * Contributors:
 *    Eike Stepper - initial API and implementation
 */
package org.eclipse.emf.cdo.doc.users;

import org.eclipse.emf.cdo.common.branch.CDOBranchPoint;
import org.eclipse.emf.cdo.common.id.CDOID;
import org.eclipse.emf.cdo.common.protocol.CDOProtocol;
import org.eclipse.emf.cdo.doc.online.CDOScalability;
import org.eclipse.emf.cdo.doc.online.EMFDeveloperGuide;
import org.eclipse.emf.cdo.doc.programmers.client.Doc02_PreparingModels;
import org.eclipse.emf.cdo.doc.programmers.client.Doc02_PreparingModels.Doc_CreatingEcore;
import org.eclipse.emf.cdo.doc.programmers.client.Doc02_PreparingModels.Doc_GeneratingModel;
import org.eclipse.emf.cdo.doc.programmers.client.Doc02_PreparingModels.Doc_MigratingManually;
import org.eclipse.emf.cdo.doc.users.Doc01_UserInterface.Doc_ProjectExplorerIntegration;
import org.eclipse.emf.cdo.doc.users.Doc01_UserInterface.Doc_SessionsView;
import org.eclipse.emf.cdo.doc.users.Doc02_ManagingRepositories.Doc_CreatingRepositories;
import org.eclipse.emf.cdo.doc.users.Doc02_ManagingRepositories.Doc_CreatingRepositories.Doc_LocalRepositories;
import org.eclipse.emf.cdo.doc.users.Doc02_ManagingRepositories.Doc_RepositoryShowIn.Doc_RepositoryShowInSystemExplorer;
import org.eclipse.emf.cdo.doc.users.Doc04_CheckingOut.Doc_CheckoutType.Doc_OfflineCheckouts;
import org.eclipse.emf.cdo.doc.users.Doc07_UsingModels.Doc_EditingModelElementsEditor;
import org.eclipse.emf.cdo.explorer.checkouts.CDOCheckout;
import org.eclipse.emf.cdo.explorer.repositories.CDORepository;
import org.eclipse.emf.cdo.server.IRepository;
import org.eclipse.emf.cdo.server.IStore;
import org.eclipse.emf.cdo.session.CDOSession;
import org.eclipse.emf.cdo.transaction.CDOTransaction;
import org.eclipse.emf.cdo.util.ReadOnlyException;
import org.eclipse.emf.cdo.view.CDOView;

import org.eclipse.emf.internal.cdo.CDOObjectImpl;

import org.eclipse.net4j.acceptor.IAcceptor;
import org.eclipse.net4j.connector.IConnector;
import org.eclipse.net4j.db.h2.H2Adapter;
import org.eclipse.net4j.tcp.ITCPConnector;

import org.eclipse.emf.ecore.EClass;
import org.eclipse.emf.ecore.EObject;
import org.eclipse.emf.ecore.EPackage;
import org.eclipse.emf.ecore.EPackage.Registry;
import org.eclipse.emf.spi.cdo.CDOSessionProtocol;

/**
 * Understanding the Technical Background
 * <p>
 * This article explains the relationship between the main concepts that are exposed in the
 * {@link Doc01_UserInterface CDO User Interface} and their underlying technical core concepts.
 * {@img tech-overview.png}
 * <p>
 * <b>Table of Contents</b> {@toc}
 *
 * @author Eike Stepper
 */
public class Doc09_TechnicalBackground
{
  /**
   * Technical Background of Model Elements
   * <p>
   * Model elements are {@link EObject EObjects}.
   * <p>
   * EObjects are instances of concrete {@link EClass EClasses}, sometimes referred to as model element types.
   * <p>
   * EClasses are contained by {@link EPackage EPackages}, often referred to as meta models and sometimes less specifically as just models.
   * <p>
   * EPackages are registered in the {@link Registry EPackage.Registry}.
   *
   * @see EMFDeveloperGuide
   */
  public class Doc_BackgroundModelElements
  {
    /**
     * Native Models
     * <p>
     * The term "native model" refers to an {@link EPackage} that is {@link Doc_GeneratingModel generated}
     * with some CDO-specific {@link Doc_MigratingManually options} to fully exploit CDO's unprecedented
     * characteristics with respect to scalability and performance.
     * <p>
     * Native model elements are lazily loaded when they are needed and automatically garbage-collected when they are no longer needed.
     * Repositories with native model elements can scale to arbitrary sizes. Clients may not be able to load all objects
     * of these large repositories at the same time, but they are able, for example, to iterate all objects of a large repository
     * without worrying about memory management.
     * <p>
     * Technically native model elements are instances of the Java class {@link CDOObjectImpl}.
     *
     * @see CDOScalability
     * @see Doc02_PreparingModels
     */
    public class Doc_BackgroundNativeModels
    {
    }

    /**
     * Legacy Models
     * <p>
     * Generating or regenerating an {@link EPackage} with the CDO-specific {@link Doc_MigratingManually options}
     * (as explained in {@link Doc_BackgroundNativeModels}) is not always possible, for example if an EPackage has already
     * been generated by a third party. In these cases the original generated EPackage can still be used with CDO;
     * and is then referred to as a "legacy model".
     * <p>
     * The integration of legacy models with CDO is based on CDOLegacyAdapters.
     * <p>
     * Legacy model elements are not loaded lazily and not automatically garbage-collected.
     */
    public class Doc_BackgroundLegacyModels
    {
    }

    /**
     * Dynamic Models
     * <p>
     * It is not strictly necessary for an {@link EPackage} to be generated into Java code to be used with CDO.
     * An EPackage can also be loaded dynamically at runtime (see {@link Doc_CreatingEcore} for an example of the
     * XML representation of an EPackage).
     * <p>
     * Technically dynamic model elements are instances of the Java class DynamicCDOObjectImpl.
     * <p>
     * Dynamic model elements share the characteristics of {@link Doc_BackgroundNativeModels native} model elements
     * with respect to enhanced scalability and performance,
     */
    public class Doc_BackgroundDynamicModels
    {
    }
  }

  /**
   * Technical Background of Repositories
   * <p>
   * The term "repository" is a slightly ambiguous in CDO, as it may refer to both a server-side / core-level {@link IRepository}
   * and a client-side / UI-level {@link CDORepository}.
   * <p>
   * An IRepository is a "real" repository backed by a physical database (of one of various {@link IStore forms)}. In production
   * such repositories typically exist in a CDO server
   * that provides remote access through one or more {@link ITCPConnector ITCPConnectors}.
   * The {@link org.eclipse.emf.cdo.doc.operators} explains how to configure and operate a CDO server.
   * <p>
   * A CDORepository is more of a {@link Doc_CreatingRepositories configured connection} to a "real" IRepository, which
   * is remembered across Eclipse sessions. In the case of a {@link Doc_LocalRepositories local repository} (connection)
   * an internal IRepository is created with an {@link H2Adapter H2} database {@link Doc_RepositoryShowInSystemExplorer stored on the local disk}.
   * <p>
   * Internally a {@link CDORepository#isConnected() connected} CDORepository maintains a single {@link CDOSession} to the underlying IRepository.
   * This session is shared by all {@link CDOView views} and {@link CDOTransaction transactions} of all {@link CDOCheckout checkouts}
   * from that CDORepository.
   *
   * @see Doc02_ManagingRepositories
   * @see Doc_BackgroundSessions
   */
  public class Doc_BackgroundRepositories
  {
  }

  /**
   * Technical Background of Checkouts
   * <p>
   * A {@link CDOCheckout} is not necessarily a physical copy of a repository on the local disk (only {@link Doc_OfflineCheckouts offline checkouts}
   * maintain a locally replicated repository copy). More generally they represent the following two aspects:
   * <ul>
   * <li> A reference to a configured {@link CDORepository} as a way to use the internal {@link CDOSession} of that CDORepository.
   * <li> The {@link CDOBranchPoint} information, i.e., {@link CDOBranchPoint#getBranch() branch} and {@link CDOBranchPoint#getTimeStamp() time stamp},
   *      that is needed to open {@link CDOView CDOViews} and {@link CDOTransaction CDOTransactions} on the shared CDOSession of
   *      the referenced CDORepository
   * </ul>
   * <p>
   * A CDOCheckout internally maintains a main CDOView that is, for example, used to provide the resources and model elements that
   * are displayed in the {@link Doc_ProjectExplorerIntegration Project Explorer}. As objects that are provided by CDOViews are read-only
   * any modification action on these objects, for example as offered in the various context menus or triggered by drag and drop events,
   * operates on {@link CDOView#getObject(EObject) transactional copies} of the objects in the context of a background thread.
   * <p>
   * Each {@link Doc_EditingModelElementsEditor model editor} opened on a resource or model element of a CDOCheckout typically
   * (but depending on the implementation of that editor) maintains its own CDOTransaction to isolate changes and locks from other
   * views and transactions. Typically the save action of a model editor delegates directly to the {@link CDOTransaction#commit(org.eclipse.core.runtime.IProgressMonitor) commit}
   * method of its associated CDOTransaction.
   */
  public class Doc_BackgroundCheckouts
  {
  }

  /**
   * Technical Background of Sessions
   * <p>
   * A {@link CDOSession} is the technical representation of a {@link CDOProtocol} connection to an {@link IRepository}.
   * On the transport level this connection is provided by an {@link IConnector} / {@link IAcceptor} pair.
   * {@img tech-sessions.png}
   *
   * @see Doc_SessionsView
   * @see Doc_BackgroundViews
   * @see Doc_BackgroundTransactions
   */
  public class Doc_BackgroundSessions
  {
  }

  /**
   * Technical Background of Views
   * <p>
   * A {@link CDOView} is a technical facility that provides a client application with all the models and model elements in a repository
   * for a specific {@link CDOBranchPoint#getTimeStamp() point in time} and in a specific {@link CDOBranchPoint#getBranch() branch}.
   * The model elements provided by a CDOView are {@link ReadOnlyException read-only}.
   * {@img tech-views.png}
   *
   * @see Doc_BackgroundSessions
   * @see Doc_BackgroundCheckouts
   */
  public class Doc_BackgroundViews
  {
  }

  /**
   * Technical Background of Transactions
   * <p>
   * A {@link CDOTransaction} is a technical facility that provides a client application with all the latest models
   * and model elements in a repository in a specific {@link CDOBranchPoint#getBranch() branch}.
   * The model elements provided by a CDOTransaction are writable.
   * Changes to these model elements must be {@link CDOTransaction#commit(org.eclipse.core.runtime.IProgressMonitor) committed} to make them
   * persistent in the repository and to distribute them to the views and transactions of other users.
   * {@img tech-transactions.png}
   *
   * @see Doc_BackgroundSessions
   * @see Doc_BackgroundCheckouts
   */
  public class Doc_BackgroundTransactions
  {
  }

  /**
   * Technical Background of the Compare Integration
   * <p>
   * With CDO both EMF Compare editors and EMF Merge editors are instrumented to utilize an optimized CDO mechanism in order to compute
   * matches in a very efficient and scalable way. This mechanism consists of special {@link CDOSessionProtocol#loadMergeData(org.eclipse.emf.cdo.spi.common.commit.CDORevisionAvailabilityInfo, org.eclipse.emf.cdo.spi.common.commit.CDORevisionAvailabilityInfo, org.eclipse.emf.cdo.spi.common.commit.CDORevisionAvailabilityInfo, org.eclipse.emf.cdo.spi.common.commit.CDORevisionAvailabilityInfo) client-server protocol}
   * and remote database queries to determine and deliver the {@link CDOID object IDs} that are involved in all changes
   * between two different {@link CDOBranchPoint CDOBranchPoints}. The response times depend on the implementation of the {@link IStore backend storage}.
   * The response time of the default implementation, the DBStore, scales more
   * with the sizes of the stored meta models (i.e., the number of concrete {@link EClass EClasses}) than with the sizes of the stored models
   * (i.e., the number of {@link EObject EObjects}).
   */
  public class Doc_BackgroundCompare
  {
  }
}

Back to the top