Add documentation for custom datatypes
diff --git a/customdatatypes.php b/customdatatypes.php
new file mode 100644
index 0000000..a0ac56f
--- /dev/null
+++ b/customdatatypes.php
@@ -0,0 +1,18 @@
+<?php require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/app.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/nav.class.php"); require_once($_SERVER['DOCUMENT_ROOT'] . "/eclipse.org-common/system/menu.class.php"); $App = new App(); $Nav = new Nav(); $Menu = new Menu(); include($App->getProjectCommon()); # All on the same line to unclutter the user's desktop'
+/*******************************************************************************
+ * Copyright (c) 2018
+ * 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:
+ *
+ *******************************************************************************/
+
+ $pageTitle = "Handling Custom EDataTypes";
+
+ $html = file_get_contents('pages/customdatatypes.html');
+ # Generate the web page
+ $App->generatePage($theme, $Menu, $Nav, $pageAuthor, $pageKeywords, $pageTitle, $html);
+?>
\ No newline at end of file
diff --git a/documentation.php b/documentation.php
index d6f5ef7..2705b10 100644
--- a/documentation.php
+++ b/documentation.php
@@ -22,10 +22,12 @@
<li><b><a href="libraryexample.php"
title="libraryexample.php"
rel="nofollow">Tutorial</a></b> - overview of Edapt using the library example</li>
- <li><b><a
- href="operations.php"
+ <li><b><a href="operations.php"
title="operations.php"
rel="nofollow">Operations</a></b> - get an overview of the reusable operations and their semantics</li>
+ <li><b><a href="customdatatypes.php"
+ title="customdatatypes.php"
+ rel="nofollow">Custom EDataTypes</a></b> - learn how to deal with custom EDataTypes when using Edapt</li>
</ul>
<h3>Presentations</h3>
diff --git a/pages/customdatatypes.html b/pages/customdatatypes.html
new file mode 100644
index 0000000..1f3d984
--- /dev/null
+++ b/pages/customdatatypes.html
@@ -0,0 +1,39 @@
+<div id="maincontent">
+<div id="midcolumn">
+<h1>Handling Custom EDataTypes</h1>
+<p>
+Edapt is a tool to migrate previously saved XMI-Files created using EMF (Eclipse Modeling Framework).
+A migration is required if the metamodel (Ecore) of the persisted entities (EObjects) in the file has changed due to model evolution.
+Edapt keeps a history of changes of an Ecore. This history is used to migrate models in XMI files.
+Edapt uses Dynamic EMF to load models from those files and migrates them to conform to the current metamodel version.
+</p><p>
+EMF offers EDataTypes for the most common Java types (String, Integer, ...) which can be used to type EAttributes.
+Moreover it is possible to specify custom EDataTypes which use a custom instance-class.
+When such a data type is specified and used in an EClass, EMF generates additional (de-)serialization code in the EFactory for the EPackage.
+To load and save XMI files with a model using those data type, custom code is required for (de-)serialization.
+</p><p>
+The alerted reader might have noticed that the usage of Dynamic EMF and custom datatypes don’t get along very well.
+Dynamic EMF always falls back to existing, generic EMF-classes, since no actual compiled classes are available for the model.
+So during (de)serialization Edapt uses EFactoryImpl which lacks all generated (and maybe even overridden and marked with @generated NOT) code.
+</p><p>
+In order to overcome this issue, Edapt offers the org.eclipse.emf.edapt.factories extension point, which allows to register a custom EFactory implementation for a nsURI, which is then used to (de-)serialize files which conform to the nsURI.
+</p><p>
+<hr/>
+<a>Listing 1</a> - Extension Point Registration
+<pre class="codebox">
+ <extension
+ point="org.eclipse.emf.edapt.factories">
+ <factory
+ class="library.edapt.LibraryFactoryImpl"
+ nsURI="http://library/v3">
+ </factory>
+ </extension>
+</pre>
+<hr/>
+</p><p>
+The easiest way to create such a custom factory for usage with Edapt is to subclass EFactoryImpl and to override createFromString(EDataType, String) and convertToString(EDataType, Object) respectively.
+Please note that eDataType.getClassifierID() does not necessarily give the same ids in a dynamic instance.
+The ids are generated and might vary. So it is not possible to simply copy the existing EFactory-code, but you have to adjust the switch() statements accordingly, e.g by identifying datatypes via the name attribute.
+</p>
+</div>
+</div>
\ No newline at end of file
