Difference between revisions of "CDO/Client"

From Eclipsepedia

< CDO
Jump to: navigation, search
(Categories)
m (Resources: fixed typo)
 
(21 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
__TOC__
 +
<br>
 
==Introduction==
 
==Introduction==
  
Line 5: Line 7:
  
 
[[Image:CDOObject.png]]
 
[[Image:CDOObject.png]]
 
+
<br>
  
 
==CDOObject==
 
==CDOObject==
Line 24: Line 26:
  
 
The method names differ from the regular Java getter notation to make it less likely that name collisions with your model name space occur. To understand the details about the return types you should browse the JavaDoc.
 
The method names differ from the regular Java getter notation to make it less likely that name collisions with your model name space occur. To understand the details about the return types you should browse the JavaDoc.
 
+
<br>
  
 
===Categories===
 
===Categories===
Line 46: Line 48:
  
 
From a CDO perspective native objects are the most efficient and full featured ones. They are the only category that combine the user application contract and the CDO state machine contract in a single object instance. Whenever possible you should generate your models to produce subclasses of CDOObjectImpl! The following table compares some important characteristics of the different object categories:
 
From a CDO perspective native objects are the most efficient and full featured ones. They are the only category that combine the user application contract and the CDO state machine contract in a single object instance. Whenever possible you should generate your models to produce subclasses of CDOObjectImpl! The following table compares some important characteristics of the different object categories:
 +
  
 
{|border="1" cellspacing="0" cellpadding="4" width="60%" style="background:#FFFFDD"
 
{|border="1" cellspacing="0" cellpadding="4" width="60%" style="background:#FFFFDD"
Line 132: Line 135:
  
 
|}
 
|}
 +
<br>
  
==Client Infra Structure==
+
==Client Infrastructure==
  
CDOObjects do not just appear out of the dark. To create, load or access them you need, as usual in EMF, an instance of a Resource, here a CDOResource. The following diagram illustrates the CDO client infra structure concepts and their relation to CDOObjects:
+
CDOObjects do not just appear out of the dark. To create, load or access them you need, as usual in EMF, an instance of a Resource, here a CDOResource. The following diagram illustrates the CDO client infrastructure concepts and their relation to CDOObjects:
  
  
 
[[Image:InfraStructure.png]]
 
[[Image:InfraStructure.png]]
 
+
<br>
  
 
===Sessions===
 
===Sessions===
  
A CDOSession is your connection to a single repository on a CDO server. Before you can do anything with CDO you need to open a session. There are two ways to obtain a session:
+
A CDOSession is your connection to a single repository on a CDO server. Before you can do anything with CDO you need to open a session.
 +
 
 +
 
 +
[[Image:CDOSession.png]]
 +
 
 +
 
 +
There are two ways to obtain a session:
 
* If you already have an instance of a Net4j IConnector, which represents the physical connection to the server, at hand you can use the CDOUtil class:
 
* If you already have an instance of a Net4j IConnector, which represents the physical connection to the server, at hand you can use the CDOUtil class:
<pre>
+
 
 +
<source lang="java">
 
IConnector connector = ...;
 
IConnector connector = ...;
 
CDOSession session = CDOUtil.openSession(connector, "repo1");
 
CDOSession session = CDOUtil.openSession(connector, "repo1");
Line 152: Line 163:
 
...
 
...
 
session.close();
 
session.close();
</pre>
+
</source>
 +
 
 
* You can also use a Net4j IManagedContainer, for example an extension point based IPluginContainer. The advantage of this approach is that you can leave all the wiring and configuration of the various components to the container which uses factories and element processors that you can contribute centrally via extension points:
 
* You can also use a Net4j IManagedContainer, for example an extension point based IPluginContainer. The advantage of this approach is that you can leave all the wiring and configuration of the various components to the container which uses factories and element processors that you can contribute centrally via extension points:
<pre>
+
 
 +
<source lang="java">
 
CDOSession session = CDOSessionFactory.get(IPluginContainer.INSTANCE, "tcp://repos.company.com:2036/repo1");
 
CDOSession session = CDOSessionFactory.get(IPluginContainer.INSTANCE, "tcp://repos.company.com:2036/repo1");
 
...
 
...
 
session.close();
 
session.close();
</pre>
+
</source>
 +
 
 +
In CDO 3.0 you may need to use this instead:
 +
<source lang="java">
 +
import org.eclipse.emf.cdo.net4j.CDONet4jUtil;
 +
import org.eclipse.emf.cdo.net4j.CDOSessionConfiguration;
 +
import org.eclipse.emf.cdo.session.CDOSession;
 +
import org.eclipse.net4j.connector.IConnector;
 +
import org.eclipse.net4j.Net4jUtil;
 +
...
 +
 
 +
IConnector connector = Net4jUtil.getConnector(IPluginContainer.INSTANCE, "tcp://repos.company.com:2036");
 +
CDOSessionConfiguration sessionConfiguration = CDONet4jUtil.createSessionConfiguration();
 +
sessionConfiguration.setConnector(connector);
 +
sessionConfiguration.setRepositoryName(REPO_NAME);
 +
   
 +
CDOSession session = sessionConfiguration.openSession();
 +
...
 +
session.close();
 +
</source>
 +
 
 +
The API of CDOSession looks like:
 +
 
 +
<source lang="java">
 +
public interface CDOSession extends IContainer<CDOView>
 +
{
 +
  public int getSessionID();
 +
  public IFailOverStrategy getFailOverStrategy();
 +
  public IChannel getChannel();
 +
  public boolean isOpen();
 +
  public void close();
 +
 
 +
  public boolean isDisableLegacyObjects();
 +
  public void setDisableLegacyObjects(boolean disableLegacyObjects);
 +
 
 +
  public int getReferenceChunkSize();
 +
  public void setReferenceChunkSize(int referenceChunkSize);
 +
 
 +
  public String getRepositoryName();
 +
  public String getRepositoryUUID();
 +
 
 +
  public CDOPackageRegistry getPackageRegistry();
 +
  public CDOPackageManager getPackageManager();
 +
  public CDORevisionManager getRevisionManager();
 +
 
 +
  public CDOView[] getViews();
 +
 
 +
  public CDOTransaction openTransaction(ResourceSet resourceSet);
 +
  public CDOTransaction openTransaction();
 +
  public CDOView openView(ResourceSet resourceSet);
 +
  public CDOView openView();
 +
  public CDOAudit openAudit(ResourceSet resourceSet, long timeStamp);
 +
  public CDOAudit openAudit(long timeStamp);
 +
}
 +
</source>
  
 
===Views===
 
===Views===
  
 +
A CDOView is a partial, yet consistent view onto a model repository. It represents the parts of the overall object graph currently viewed by the client.
 +
 +
 +
[[Image:CDOViews.png]]
 +
 +
 +
Views, in contrast to sessions, are considered light weight entities in CDO, such that you can open and close them as often as you want. There are (nearly) no server side resources associated with a client side view. A CDOView can be seen of as the mediator between an EMF ResourceSet and the loaded objects' state which is managed by the CDORevisionManager of the CDOSession.
 +
 +
public interface CDOView extends INotifier
 +
{
 +
  public static final long UNSPECIFIED_DATE = CDORevision.UNSPECIFIED_DATE;
 +
  public static final int NO_PRELOAD = 1;
 +
 +
  public enum Type { TRANSACTION, READONLY, AUDIT }
 +
 +
  public int getViewID();
 +
  public Type getViewType();
 +
  public CDOSession getSession();
 +
  public ResourceSet getResourceSet();
 +
  public boolean isDirty();
 +
  public void close();
 +
 +
  public boolean isEnableInvalidationNotifications();
 +
  public void setEnableInvalidationNotifications(boolean on);
 +
 +
  public int getLoadRevisionCollectionChunkSize();
 +
  public void setLoadRevisionCollectionChunkSize(int loadRevisionCollectionChunkSize);
 +
 +
  public CDOResource getResource(String path);
 +
  public CDOObject getObject(CDOID id);
 +
  public CDORevision getRevision(CDOID id);
 +
  public boolean isObjectRegistered(CDOID id);
 +
}
 +
<br>
  
 
====Transactions====
 
====Transactions====
  
 +
Instances of '''CDOTransaction''' are the only views that permit ''read-write access'' to the contained resources and objects. All changes are recorded by a transaction until the application decides to either commit or roll back the transaction.
  
 +
CDOSession session = ...;
 +
CDOTransaction transaction = session.openTransaction();
 +
CDOResource resource = transaction.createResource("/path/to/resource");
 +
...
 +
transaction.commit();
 +
transaction.close();
 +
 +
You can also use a CDOTransaction with an existing EMF ResourceSet:
 +
 +
ResourceSet resourceSet = editingDomain.getResourceSet();
 +
CDOTransaction transaction = session.openTransaction(resourceSet);
 +
<br>
 +
 
====Read-Only Views====
 
====Read-Only Views====
  
 +
Instances of '''CDOView''' are by default ''floating'' views that permit ''read-only access'' to the contained resources and objects. They always show the latest changes of the repository.
 +
 +
CDOSession session = ...;
 +
CDOView view = session.openView();
 +
CDOResource resource = view.getResource("/path/to/resource");
 +
...
 +
view.close();
 +
 +
You can also use a CDOView with an existing EMF ResourceSet:
 +
 +
ResourceSet resourceSet = editingDomain.getResourceSet();
 +
CDOView view = session.openView(resourceSet);
 +
<br>
  
 
====Audit Views====
 
====Audit Views====
  
 +
As of CDO 3.0 there is no separate interface for audit views. Instead normal views (see [[#Read-Only Views|Read-Only Views]]) can be used to allow the application to look at ''historical state'' of the repository. They always show a consistent object graph at a particular point in time back in the past. To keep these object graphs consistent audit views only permit read-only access to the contained resources and objects.
 +
 +
CDOSession session = ...;
 +
CDOView audit = session.openView(new Date("2007-10-02 10:33").getTime());
 +
CDOResource resource = audit.getResource("/path/to/resource");
 +
...
 +
audit.close();
 +
 +
You can also use a CDOView with an existing EMF ResourceSet:
 +
 +
ResourceSet resourceSet = editingDomain.getResourceSet();
 +
CDOView audit = session.openAudit(resourceSet, timeStamp);
 +
<br>
  
 
===Resources===
 
===Resources===
 +
 +
In CDO and EMF all objects of the overall object graph are partitioned into ''resources'' which can be seen of as the named roots of a repository. Resources can be loaded into any view but they can only be created in a transactional view (see above). The resources used in CDO are CDOResources and they combine the characteristics of EMF Resources and CDOObjects, which, in turn, are EMF EObjects. You can work with a CDOResource like with any other EObject or CDOObject.
 +
 +
The resource URI of a CDOResource is of the form <code>cdo://authority/resource</code>, where <code>authority</code> is the name of the authority you have configured in your <code>cdo-config.xml</code> and <code>resource</code> is the name of a resource you have previously created in a transactional view.
 +
 +
You can use CDOUtil to convert between the URI form and the resource path:
 +
 +
String path = CDOUtil.extractResourcePath(URI.create("cdo:/res1"));
 +
URI uri = CDOUtil.createResourceURI("/res1");
 +
 +
You need to handle these URI specifics only if you decided to use the EMF API of Resource which you typically obtained through an EMF ResourceSet. The easiest way to use the extended API of CDOResource is calling <code>CDOView.getResource(String path)</code> or <code>CDOTransaction.createResource(String path)</code>, respectively. The most important non-transient feature of a resource is the ''contents'' collection that can be used like in pure EMF.
 +
 +
Since CDOResources are CDOObjects as well they can also have their own EMF proxy URI of the form <code>cdo:id</code>. You can use CDOUtil to extract the CDOID of a proxy URI:
 +
 +
CDOID id = CDOUtil.extractResourceID(URI.create("cdo:17463524"));
 +
<br>
  
 
----
 
----
 
Wikis: [[CDO]] | [[Net4j]] | [[EMF]] | [[Eclipse]]
 
Wikis: [[CDO]] | [[Net4j]] | [[EMF]] | [[Eclipse]]

Latest revision as of 11:18, 11 October 2012

Contents


[edit] Introduction

CDOObjects represent the object instances of the models that your application deals with. Internally each such object is managed by a singleton CDOStateMachine. The state machine accurately transits objects and trees of objects through the states TRANSIENT, NEW, CLEAN, DIRTY, PROXY and CONFLICT. When a CDOObject is in one of the persistent states NEW, CLEAN or DIRTY the state machine associates a CDORevision that carries the current values of the modeled structural features. All revisions created or used in a CDOSession are shared by the CDORevisionMnager of that session. CDOObjects are only known to the CDO client. Only revisions are subject to (network) transfers between client and server.


CDOObject.png

[edit] CDOObject

[edit] Interface

A CDOObject is basically an EObject with a handful of additional read-only features as the following java code shows:

public interface CDOObject extends EObject
{
  public CDOClass    cdoClass();
  public CDOID       cdoID();
  public CDOState    cdoState();
  public CDOView     cdoView();
  public CDOResource cdoResource();
  public CDORevision cdoRevision();
}

The method names differ from the regular Java getter notation to make it less likely that name collisions with your model name space occur. To understand the details about the return types you should browse the JavaDoc.

[edit] Categories

While a user application always deals with EObjects the internal CDOStateMachine interacts with InternalCDOObjects. Depending on how the EObjects relate to the InternalCDOObjects there are a handful of different categories of CDOObjects, that is, implementations of InternalCDOObject. The following type hierarchy shows an example with the shipped test model installed:


InternalCDOObject.png


The main categories are:

  • Native objects extend CDOObjectImpl and fall into three sub categories:
    • Generated native objects directly extend CDOObjectImpl and result from slightly modified GenModels
    • Dynamic native objects are of class DynamicCDOObjectImpl and result from dynamic models added to a session's package registry
    • Resources are of class CDOResourceImpl (which also implements CDOObject and thus EObject!)
  • Legacy objects extend EObjectImpl and fall into two sub categories to interface the CDOStateMachine:
    • Unwoven legacy objects interface the state machine via an EMF adapter of class CDOAdapterImpl
    • Woven legacy objects interface the state machine via an AspectJ inter type declaration of class CDOCallbackImpl
  • Meta objects are the EModelElements contained in a session's package registry. Although their state is immutable they interface the state machine via CDOMetaImpl instances so that they can be referenced from ordinary objects.


From a CDO perspective native objects are the most efficient and full featured ones. They are the only category that combine the user application contract and the CDO state machine contract in a single object instance. Whenever possible you should generate your models to produce subclasses of CDOObjectImpl! The following table compares some important characteristics of the different object categories:


Model Type Native Legacy Meta
Dynamic Generated Unwoven Woven
Development
Artifacts
Ecore Unaffected N/A
Genmodel N/A Slightly modified Unaffected
Instance Interface CDOObject EObject EModelObject
State Machine Interface CDOAdapter CDOCallback CDOMeta
Location of
Internal Values
class DynamicCDOObject Java Byte Code
store CDOObject N/A
view CDOAdapter CDOCallback CDOMeta
id CDOSession
state N/A
revision
resource
Location of
Model Values
per CDOState
TRANSIENT EObject
NEW CDORevision EObject
and
CDORevision
DIRTY
CLEAN EModelObject


[edit] Client Infrastructure

CDOObjects do not just appear out of the dark. To create, load or access them you need, as usual in EMF, an instance of a Resource, here a CDOResource. The following diagram illustrates the CDO client infrastructure concepts and their relation to CDOObjects:


InfraStructure.png

[edit] Sessions

A CDOSession is your connection to a single repository on a CDO server. Before you can do anything with CDO you need to open a session.


CDOSession.png


There are two ways to obtain a session:

  • If you already have an instance of a Net4j IConnector, which represents the physical connection to the server, at hand you can use the CDOUtil class:
IConnector connector = ...;
CDOSession session = CDOUtil.openSession(connector, "repo1");
session.setDisableLegacyObjects(...);
session.setReferenceChunkSize(...);
...
session.close();
  • You can also use a Net4j IManagedContainer, for example an extension point based IPluginContainer. The advantage of this approach is that you can leave all the wiring and configuration of the various components to the container which uses factories and element processors that you can contribute centrally via extension points:
CDOSession session = CDOSessionFactory.get(IPluginContainer.INSTANCE, "tcp://repos.company.com:2036/repo1");
...
session.close();

In CDO 3.0 you may need to use this instead:

import org.eclipse.emf.cdo.net4j.CDONet4jUtil;
import org.eclipse.emf.cdo.net4j.CDOSessionConfiguration;
import org.eclipse.emf.cdo.session.CDOSession;
import org.eclipse.net4j.connector.IConnector;
import org.eclipse.net4j.Net4jUtil;
...
 
IConnector connector = Net4jUtil.getConnector(IPluginContainer.INSTANCE, "tcp://repos.company.com:2036");
CDOSessionConfiguration sessionConfiguration = CDONet4jUtil.createSessionConfiguration();
sessionConfiguration.setConnector(connector);
sessionConfiguration.setRepositoryName(REPO_NAME);
 
CDOSession session = sessionConfiguration.openSession();
...
session.close();

The API of CDOSession looks like:

public interface CDOSession extends IContainer<CDOView>
{
  public int getSessionID();
  public IFailOverStrategy getFailOverStrategy();
  public IChannel getChannel();
  public boolean isOpen();
  public void close();
 
  public boolean isDisableLegacyObjects();
  public void setDisableLegacyObjects(boolean disableLegacyObjects);
 
  public int getReferenceChunkSize();
  public void setReferenceChunkSize(int referenceChunkSize);
 
  public String getRepositoryName();
  public String getRepositoryUUID();
 
  public CDOPackageRegistry getPackageRegistry();
  public CDOPackageManager getPackageManager();
  public CDORevisionManager getRevisionManager();
 
  public CDOView[] getViews();
 
  public CDOTransaction openTransaction(ResourceSet resourceSet);
  public CDOTransaction openTransaction();
  public CDOView openView(ResourceSet resourceSet);
  public CDOView openView();
  public CDOAudit openAudit(ResourceSet resourceSet, long timeStamp);
  public CDOAudit openAudit(long timeStamp);
}

[edit] Views

A CDOView is a partial, yet consistent view onto a model repository. It represents the parts of the overall object graph currently viewed by the client.


CDOViews.png


Views, in contrast to sessions, are considered light weight entities in CDO, such that you can open and close them as often as you want. There are (nearly) no server side resources associated with a client side view. A CDOView can be seen of as the mediator between an EMF ResourceSet and the loaded objects' state which is managed by the CDORevisionManager of the CDOSession.

public interface CDOView extends INotifier
{
  public static final long UNSPECIFIED_DATE = CDORevision.UNSPECIFIED_DATE;
  public static final int NO_PRELOAD = 1;

  public enum Type { TRANSACTION, READONLY, AUDIT }

  public int getViewID();
  public Type getViewType();
  public CDOSession getSession();
  public ResourceSet getResourceSet();
  public boolean isDirty();
  public void close();

  public boolean isEnableInvalidationNotifications();
  public void setEnableInvalidationNotifications(boolean on);

  public int getLoadRevisionCollectionChunkSize();
  public void setLoadRevisionCollectionChunkSize(int loadRevisionCollectionChunkSize);

  public CDOResource getResource(String path);
  public CDOObject getObject(CDOID id);
  public CDORevision getRevision(CDOID id);
  public boolean isObjectRegistered(CDOID id);
}


[edit] Transactions

Instances of CDOTransaction are the only views that permit read-write access to the contained resources and objects. All changes are recorded by a transaction until the application decides to either commit or roll back the transaction.

CDOSession session = ...;
CDOTransaction transaction = session.openTransaction();
CDOResource resource = transaction.createResource("/path/to/resource");
...
transaction.commit();
transaction.close();

You can also use a CDOTransaction with an existing EMF ResourceSet:

ResourceSet resourceSet = editingDomain.getResourceSet();
CDOTransaction transaction = session.openTransaction(resourceSet);


[edit] Read-Only Views

Instances of CDOView are by default floating views that permit read-only access to the contained resources and objects. They always show the latest changes of the repository.

CDOSession session = ...;
CDOView view = session.openView();
CDOResource resource = view.getResource("/path/to/resource");
...
view.close();

You can also use a CDOView with an existing EMF ResourceSet:

ResourceSet resourceSet = editingDomain.getResourceSet();
CDOView view = session.openView(resourceSet);


[edit] Audit Views

As of CDO 3.0 there is no separate interface for audit views. Instead normal views (see Read-Only Views) can be used to allow the application to look at historical state of the repository. They always show a consistent object graph at a particular point in time back in the past. To keep these object graphs consistent audit views only permit read-only access to the contained resources and objects.

CDOSession session = ...;
CDOView audit = session.openView(new Date("2007-10-02 10:33").getTime());
CDOResource resource = audit.getResource("/path/to/resource");
...
audit.close();

You can also use a CDOView with an existing EMF ResourceSet:

ResourceSet resourceSet = editingDomain.getResourceSet();
CDOView audit = session.openAudit(resourceSet, timeStamp);


[edit] Resources

In CDO and EMF all objects of the overall object graph are partitioned into resources which can be seen of as the named roots of a repository. Resources can be loaded into any view but they can only be created in a transactional view (see above). The resources used in CDO are CDOResources and they combine the characteristics of EMF Resources and CDOObjects, which, in turn, are EMF EObjects. You can work with a CDOResource like with any other EObject or CDOObject.

The resource URI of a CDOResource is of the form cdo://authority/resource, where authority is the name of the authority you have configured in your cdo-config.xml and resource is the name of a resource you have previously created in a transactional view.

You can use CDOUtil to convert between the URI form and the resource path:

String path = CDOUtil.extractResourcePath(URI.create("cdo:/res1"));
URI uri = CDOUtil.createResourceURI("/res1");

You need to handle these URI specifics only if you decided to use the EMF API of Resource which you typically obtained through an EMF ResourceSet. The easiest way to use the extended API of CDOResource is calling CDOView.getResource(String path) or CDOTransaction.createResource(String path), respectively. The most important non-transient feature of a resource is the contents collection that can be used like in pure EMF.

Since CDOResources are CDOObjects as well they can also have their own EMF proxy URI of the form cdo:id. You can use CDOUtil to extract the CDOID of a proxy URI:

CDOID id = CDOUtil.extractResourceID(URI.create("cdo:17463524"));



Wikis: CDO | Net4j | EMF | Eclipse