f Obeo_Designer_Team_Server

Obeo Designer Team Server: User Guide

This guide explains how to launch, stop, manage and configure the Obeo Designer Team Server.
This server can be used to support the Collaborative Modeling features Sirius extension.

  1. Launch the Obeo Designer Team Server
    1. Activate tracing
    2. Obeo Designer Team Server as a service
  2. Stop the Obeo Designer Team Server
  3. Manage the Obeo Designer Team Server
    1. Export the database to an XML file
    2. Reset the database to a state described in XML file
    3. Managing Durable locks
      1. List Durable locks
      2. Deleting durable locks
    4. Other useful commands
  4. Modify the Obeo Designer Team Server Configuration
    1. Overview
    2. Configure the user connection on the Obeo Designer Team Server
    3. Structure of server configuration files
      1. Main part
      2. Repository declaration
  5. Define User-Permissions on the Obeo Designer Team Server
  6. Obeo Designer Team Server deployment recommendations
    1. Operating System
    2. Network
      1. Latency: Client and Team Server
      2. Latency: Team server and DB server
      3. Network stability
      4. Server isolation
    3. Scalability and size of models
    4. Disclaimer
  7. Migrate to an upper Obeo Designer Team version

Launch the Obeo Designer Team Server

This section explains how to launch the Obeo Designer Team Server.

If you don’t have Obeo Designer Team Server already, please contact us .

Once unarchived:

  • On Windows, simply launch the ObeoDesignerTeamServer.exe application.
  • On Linux, you can double-click on the ObeoDesignerTeamServer executable or type the command ./ObeoDesignerTeamServer inside a terminal.

An OSGi console will open, indicating that the Team Server is starting. Once the message [INFO] CDO server started has appeared, your server is started and available.

Once the server is started, you will be able to:

  • Manage it by exporting the database, deleting branches or durable locks...
  • Stop it cleanly.

When starting, the Obeo Designer Team Server uses the cdo-server.xml file in the configuration folder to determine the configuration of the CDO repository to launch. You can get further details about how to customize this server configuration here .

Activate tracing

It is possible to activate tracing of the Team Server operations (for debugging purposes). To do so:

  • Add "-debug" as first line of the ObeoDesignerTeamServer.ini file
  • Optional: edit the .options file to activate/deactivate tracing according to your need (e.g. setting org.eclipse.emf.cdo.server/debug.protocol to false will deactivate tracing of protocol-related operations)
  • Re-launch you server. Notice that if you want to store those traces you can redirect the output of your server by typing ./ObeoDesignerTeamServer > myLogFile.txt

Obeo Designer Team Server as a service

On Linux, you can launch Obeo Designer Team Server as a service with the command ./service-odts.sh start typed inside a terminal. The message «Starting Obeo Designer Team server: Ok» will indicate that the server as been properly started.

The service exposes the following commands: start, stop, restart and status.

Unlike the executable launch, the service will not open an OSGI console, if you want to be able use the OSGI commands documented in Manage the Obeo Designer Team Server, you will need to provide access to the OSGI console through telnet: edit ObeoDesignerTeamServer.ini to add the port under the –console argument.

Stop the Obeo Designer Team Server

To stop the Obeo Designer Team Server, enter the close instruction in the OSGi console. Once the message [INFO] CDO server stopped appeared, you server is closed.

If the server has been launched as a service, simply type the command ./service-odts.sh stop inside a terminal

Manage the Obeo Designer Team Server

Once launched , you will be able to execute commands in the Obeo Designer Team Server’s OSGi console to manage the server.

Export the database to an XML file

By executing the cdo export <repository-name> <export-file-location> command, the database will be exported as an XML file.

For example, if you did not change the default Server configuration , the command cdo export designer-server database_export.xml will export the current state of the database to the database_export.xml file in your Obeo Designer Team Server root folder.

Reset the database to a state described in XML file

You can reset the database to a state you previously saved thanks to the database export mechanism by executing the cdo import <repository-name> <export-file-location> command.

For example, if you previously exported your repository to an XML-file entitled database_export.xml (as detailed here ), the command cdo import designer-server database_export.xml will reset the database to the state described in the database_export.xml file.

Notice that this command should be used carefully, as the current database state will be deleted.

Managing Durable locks

List Durable locks

To list all durable locks acquired on the Team server, use the cdo locks <repository-name> [<username-prefix>] command.

For example, when using the cdo locks designer-server command with 2 users working on the server, we get the following informations :


89b3a187a4aa01c60266db98f5332b86787d6ca7a325620ac19ecc5e50334c57 The durable locking area ID
userID = user1 The ID of the user owning the durable locks
branch = Branch[id=0, name=MAIN]
timeStamp = *
readOnly = false
locks = {OID11=WRITE, OID30=WRITE} Here user1 has locked the elements with CDOIDs 11 and 30


4c5b48e2d4ce1d5d23943333a9486e20660cbd9b1593684c3015307d4362461a
userID = user2
branch = Branch[id=0, name=MAIN]
timeStamp = *
readOnly = false
locks = {OID5=WRITE} Here user2 has locked the element with CDOID 5


When using the optional <username-prefix> parameter, you can get the elements locked by the given user (for example cdo locks designer-server user1 will only return the first locking area).

Deleting durable locks

To delete durable locks, use the cdo deletelocks <repository-name> <durable-locking-area-id> command.

For example, in the example described above , cdo deletelocks designer-server 89b3a187a4aa01c60266db98f5332b86787d6ca7a325620ac19ecc5e50334c57 will delete all the locks obtained by user1.

Although this command can be useful if users left their representations locked for a long time-period and hence block other team members, use it very carefully.

Other useful commands

Here are the other OSGI commands you are able to execute on the Obeo Designer Team Server, ordered by relevance (you can get all the available commands by typing help in the OSGI console:

  • cdo sessions <repository-name> - lists all active CDOSessions and CDOTransactions of a repository
  • cdo branches <repository-name> - lists the branches defined on a repository
  • acceptors - lists all active acceptors, their connectors and channels
  • cdo packages <repository-name> - lists the EPackages registered on a repository
  • cdo list - lists all active repositories
  • elements - lists all managed elements
  • connectors - lists all active connectors and their channels

Modify the Obeo Designer Team Server Configuration

Overview

When launching, the Obeo Designer Team Server will launch a CDO Repository configured as specified in the configuration file cdo-server.xml (located in the configuration folder of the Obeo Designer Team Server).

If you want to customize the Obeo Designer Team Server configuration, you may want to start from one of the example configuration files located in the server-configuration-examples folder of the Obeo Designer Team Server. These examples present ways to customize the connection type (TCP or SSL), the authentication (none, through a property file, through LDAP).

Configure the user connection on the Obeo Designer Team Server

There are many kinds of possible user connections (see corresponding sections of the Collaborative Modeling Administrator guide availale in the integrated help of Obeo Designer Team Edition):

  • Collaborative server - Default: There is no authentication.
  • Collaborative server – Authenticated: Authentication is required. Users and passwords are managed in a file.
  • Define User-Permissions on the Obeo Designer Team Server
  • Collaborative server – Using LDAP: The LDAP can be used alternatively or in addition to Authenticated or User Profile connections.

Structure of server configuration files

The complete reference documentation describing the cdo-server.xml file structure is available on CDO wiki .
This section sums up the most interesting properties and usage advice.

Main part

A configuration file contains 2 main parts :

  • the protocol declaration (using the <acceptor> tag). The time being, Collaborative features of Obeo Designer supports TCP and SSL protocol.
  • the repository declaration (using the <repository> tag). This is this repository declaration that allows to specify which back-end should be used, and how it should be configured.

Repository declaration

Please note that many repository configuration options can not be changed anymore after the repository has been started the first time.

A repository should have a unique name, that will be used by the user to connect to it.

Declaring a repository is specifying:

  • the repository properties through the <property> tag: Does it support branching? Does it support auditing?...
  • the back-end configuration through the <store> tag: Should the server use H2 or another back-end? How should many-to-one references be mapped in the database?...
Properties of the <repository> element

You can set a property of the Repository inside the <repository> tag:

<repository name="designer-server">
	<property name="overrideUUID" value=""/>
	<property name="supportingBranches" value="false"/>

Here are the main properties of a Repository:

  • overrideUUID: allows to specify an unique identifier (UUID) for the repository. If not specified, a randomly generated UUID will be used (and changed on each restart. If "" is used, the repository name will be used as UUID.
  • supportingAudits: specifies whether the repository will support audit views or not. An audit is a view taking a date in parameter, showing a historical and read-only version of a repository. This option is active by default, but it is strongly recommended to deactivate it (for performance considerations), unless you explicitly have this functional need.

Please note that audit views are only supported by the DBStore and MemStore back-ends. In case of a DBStore, the used mapping strategy must also support audits.

  • supportingBranches: specifies whether the repository will support the creation and usage of branches below the always existing main branch or not. The time being, Obeo Designer supports but does not provide default UI for managing branches. Consequently, it is recommended to deactivate it (for performance considerations), unless you explicitly have this functional need.

Please note that branching are only supported by the DBStore and MemStore back-ends. In case of a DBStore, the used mapping strategy must also support branching.

  • supportingEcore: you should only activate this property when needing to store instances of the Ecore metamodel on the repository.
  • idGenerationLocation: specifies whether the repository will expect clients to generate IDs for new objects or whether it will ask the backend store to generate them. Valid values are STORE (default) or CLIENT. It is strongly advised to leave this property to its default value ( STORE).
Details of the store element

This element is used to configure the database in which the models will be stored.

We invite you to check the examples located in the server-configuration-examples of your Obeo Designer Team Server to get different examples of store configurations. These examples uses an H2 databases which is the database used to validated Sirius version and the only that is supported by Obeo. It is possible to use another database supported by CDO but there is no guarantee of stability/performances. Note that Obeo can assist if another database solution is required.

The type attribute corresponds to the type of a store factory that is contributed via the org.eclipse.emf.cdo.server.storeFactory extension point. The remaining attributes depend on the specified type attribute value. The following values are possible with the shipped distribution (subject to user supplied extension):

  • db: Store that connects via JDBC to a relational database and manages persistent revisions and models through a built-in O/R mapper, see CDO/DB Store. A DB store element can contain the following nested elements:
    • mappingStrategy
    • dbAdapter
    • dataSource
  • There are other stores that are supported by CDO. However, Obeo Designer Team only supports H2, as versions are validated using an H2 database. Using a different store can introduce stability or performance issues.
    • mem: Store without real persistence. A repository with a mem store can function properly as long as the the server is not restarted. No additional attributes are recognized.
    • hibernate: Store that uses Teneo/Hibernate
    • objectivity: Store that uses Objectivity/DB
    • mongodb: Store that uses MongoDB
    • db4o: Store that uses DB4O
  • connectionKeepAlivePeriod property: specifies, if the store is a DBStore, at what interval the store will issue an SQL statement to keep the connection to the database alive.
  • readerPoolCapacity property: specifies, if the store is a DBStore, the maximum number of store accessors (JDBC connections) to keep in the reader pool. The default value is 15.
  • writerPoolCapacity properrty: specifies, if the store is a DBStore, the maximum number of store accessors (JDBC connections) to keep in the writer pool. The default value is 15.
Details of the mappingStrategy element

This element is recognized by DB stores and defines the overall mapping strategy of the built-in O/R mapper.

The type attribute corresponds to the type of a mapping strategy factory that is contributed via the org.eclipse.emf.cdo.server.db.mappingStrategies extension point. The following values are possible with the shipped distribution:

  • horizontal: mapping strategy that creates one DB table per concrete model class. The following nested property elements are recognized:
    • toManyReferences: specifies how the built-in O/R mapper will handle to-many references (collections). The following values are recognized:
      • ONE_TABLE_PER_REFERENCE: Each to-many reference of the model will get its own DB table.
      • ONE_TABLE_PER_CLASS: All to-many references of a model class will share a single DB table.
      • ONE_TABLE_PER_PACKAGE: All to-many references of a model package will share a single DB table.
      • ONE_TABLE_PER_REPOSITORY: All to-many references of all model classes i the repository will share a single DB table.
      • LIKE_ATTRIBUTES: Collections will be serialized to a BLOB column in the same DB table that the attributes of the containing model class are stored in. This option is currently not supported.
    • toOneReferences: specifies how the built-in O/R mapper will handle to-one references. The following values are recognized:
      • LIKE_ATTRIBUTES: single references will be stored in a CDOID column in the same *** DB table that the attributes of the containing model class are stored in. This option is the default option.
      • LIKE_TO_MANY_REFERENCES: single references will be handled in the same way as specified for to-many references. This option is currently not supported.
    • maxTableNameLength: enables you to override the default value of the chosen DB adapter for the maximum length of table names.
    • maxFieldNameLength: enables you to override the default value of the chosen DB adapter for the maximum length of column names.
    • tableNamePrefix: specifies a common fixed prefix for all table names generated by this mapping strategy.
    • qualifiedNames: specifies whether generated package or class table names are qualified or not.
    • forceNamesWithID: specifies whether generated names are always suffixed with an internal ID or only in cases where the generated name absolutely needs mangling.
  • vertical: mapping strategy that creates one DB table per class in the model hierarchy. It has the same nested properties as the horizontal mapping strategy. Note: the vertical mapping strategy is not yet supported by CDO
Details of the dbAdapter element

Defines the IDBAdapter instance of the store. Please refer to the Net4j DB Framework wiki for details about DB adapters and SQL dialects.

The type attribute corresponds to the name of a DB adapter factory that is contributed via the org.eclipse.net4j.db.dbAdapters extension point. No additional attributes are recognized.

The DB adapter must match the database specified in the dataSource element.

Details of the dataSource element

Defines the DataSource instance of the store.

The class attribute corresponds to the fully qualified name of the data source class. Please refer to your DB manual for details about the supported data sources and their attributes.

Define User-Permissions on the Obeo Designer Team Server

It is possible to define permissions on the Server. If permissions are activated, then each user will have different READ and WRITE accesses on resources and elements. If an user does not have any WRITE permission on an element, it will be displayed with a grey padlock and edition will be forbidden.

Please refer to the Collaborative Modeling - Administrator Guide to learn how to configure and define user-specific permissions on your Server.

You can also use the example configuration located in the sever-configuration-examples/permissions-example/ folder.

Obeo Designer Team Server deployment recommendations

Operating System

The Obeo Designer Team server should be deployed on a Linux x86_64 system with a JRE x86_64 version 8 or later.

Network

Latency: Client and Team Server

It is recommended to provide a network with the lowest possible latency between the client and the server: in the order of 1 to 10 ms for a round-trip.

Latency: Team server and DB server

It is strongly recommended that the Team server and the DB server are located on the same physical server as latency between the Team server and DB server will impact greatly the overall performances of the solution. As such the best performing deployment is achieved by using the H2 database in embedded mode.

If there is a requirement on the database that prevents from using H2, make sure that the latency is as low as possible.

Network stability

VPN are not recommended (it is a latency factor) as well as other network elements that could drop connections which are more or less inactive. As such wireless connection are also not recommended as any loss of connectivity might lead to instability in the product and loss of data. However, if a network element of this kind is mandatory, an SSH tunnel could be used as a workaround to avoid client/server disconnections.

Server isolation

It is strongly discouraged to deploy the server on a public WAN. Obeo Designer should be the only way to edit the information stored in the database.

Scalability and size of models

Scability and performances are highly dependent on the design of the domain metamodel, the implementation of this metamodel and the Viewpoint Specification Models. The following figures are given with an Ecore model and the EcoreTools tooling which applies the Sirius best practices.

The minimum physical memory dedicated to the Team server is 4 GB for a deployment where the expected model size is in the order of 300 000 model elements. The heap memory available for the server should be increased to support bigger models 8GB should support 600 000 model elements.

The memory usage of the clients will increase when the model which is shared among the clients grows as such these resources might need to be increased for larger models with 8GB being expected for models with 600 000 elements (the exact value might vary depending on the amount of information each model element holds).

The latency of end user operations requiring a full analysis of the model increase as the model grow, this includes : opening and closing a project, deleting model elements and representations, launching a transformation or a code generation. Opening a project (and hence collecting the model from the network) might take up to 1 min for a model with 500K elements.

Models having 1 000 000 model elements are the considered the upper limit for a Collaborative Server deployement.

A given server is expected to be used by 10 to 20 users simultaneously depending on their level of activity.

Disclaimer

Notwithstanding what was stated previously, Obeo Designer and Obeo Designer Team products are not warranted to run without any error or interruption. Obeo does not make any warranty regarding the statements that are under the chapter «Obeo Designer Team Server deployment recommendations», this chapter is provided for information purposes.
You aknowledges and accepts the risks involved in using these products which could include without limitation, down time, loss of connectivity or data, system crashes, bad performances or performance degradation.

Migrate to an upper Obeo Designer Team version

This part will present how to migrate shared projects of an Obeo Designer Team (and the Obeo Designer Team Server) from version n to version n+1.

  • Step #1: Extract modeling projects out of the CDO repository
    • Using the Obeo Designer Team in version n, import locally every project that should be migrated to the new version, using the wizard File/Import.../Sirius/Modeling Project from Remote.
    • Export these project to a new archive for later use.
    • Once imports are finished, turn down the Obeo Designer Team Server in version n.
  • Step #2: Migrate VSM
    • Using the Obeo Designer Team in version n+1 , import the metamodel and VSM projects. Open the odesign file(s) from the VSM project(s). The migration is automatic. It will be done during the load of the odesign if needed without making it dirty. Therefore the migration result will be saved only if you make a manual modification, for example change the Id property of the Group root item, undo and save the editor(s).
    • The VSM projects being migrated, it can be repackaged as an update site as the version of the application for Obeo Designer Team version n+1.
  • Step #3: Migrate modeling projects
    • Install the update site of the application in version n+1, on an Obeo Designer Team version n+1 (or launch an Eclipse runtime if there is no update site).
    • Once installed (or the Eclipse runtime launched) import the modeling projects from Step #1.
    • Open each of the imported project to trigger the automatic migration.
    • Save and close the projects.
  • Step #4: Export modeling projects to the new version
    • Install Obeo Designer Team Server in version n+1.
    • Copy the server configuration file (cdo-server.xml) from Obeo Designer Team Server version n to the version n+1.
      • Check the release note of the version n+1 to identify if the configuration file should be updated (for instance a new tag for a new functionality).
      • If the new Obeo Designer Team Server uses the same database as in the previous version, this database has to be dropped.
    • Run Obeo Designer Team Server.
    • Export the migrated modeling projects from Step #3 using the wizard «File/Export.../Sirius/Shared Modeling Project from Local».