diff options
116 files changed, 1896 insertions, 3771 deletions
diff --git a/packaging/org.eclipse.emf.compare.gendoc/.classpath b/packaging/org.eclipse.emf.compare.gendoc/.classpath new file mode 100644 index 000000000..b91af8066 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/.classpath @@ -0,0 +1,9 @@ +<?xml version="1.0" encoding="UTF-8"?> +<classpath> + <classpathentry kind="src" path="src"/> + <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/JavaSE-1.7"/> + <classpathentry kind="lib" path="lib/org.eclipse.jgit-3.2.0.201312181205-r.jar"/> + <classpathentry kind="lib" path="lib/org.eclipse.mylyn.wikitext.core_1.9.0.20131007-2055.jar" sourcepath="lib/org.eclipse.mylyn.wikitext.core.source_1.9.0.20131007-2055.jar"/> + <classpathentry kind="lib" path="lib/org.eclipse.mylyn.wikitext.mediawiki.core_1.9.0.20131007-2055.jar" sourcepath="lib/org.eclipse.mylyn.wikitext.mediawiki.core.source_1.9.0.20131007-2055.jar"/> + <classpathentry kind="output" path="bin"/> +</classpath> diff --git a/packaging/org.eclipse.emf.compare.gendoc/.externalToolBuilders/Runnable Jar Builder.launch b/packaging/org.eclipse.emf.compare.gendoc/.externalToolBuilders/Runnable Jar Builder.launch new file mode 100644 index 000000000..e1ec036eb --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/.externalToolBuilders/Runnable Jar Builder.launch @@ -0,0 +1,17 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<launchConfiguration type="org.eclipse.ant.AntBuilderLaunchConfigurationType"> +<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_AFTER_CLEAN_TARGETS" value="all,"/> +<stringAttribute key="org.eclipse.ant.ui.ATTR_ANT_MANUAL_TARGETS" value="clean,all,"/> +<booleanAttribute key="org.eclipse.ant.ui.ATTR_TARGETS_UPDATED" value="true"/> +<booleanAttribute key="org.eclipse.ant.ui.DEFAULT_VM_INSTALL" value="false"/> +<booleanAttribute key="org.eclipse.ant.uiSET_INPUTHANDLER" value="false"/> +<stringAttribute key="org.eclipse.debug.core.ATTR_REFRESH_SCOPE" value="${project}"/> +<booleanAttribute key="org.eclipse.debug.ui.ATTR_LAUNCH_IN_BACKGROUND" value="false"/> +<stringAttribute key="org.eclipse.jdt.launching.CLASSPATH_PROVIDER" value="org.eclipse.ant.ui.AntClasspathProvider"/> +<booleanAttribute key="org.eclipse.jdt.launching.DEFAULT_CLASSPATH" value="true"/> +<stringAttribute key="org.eclipse.jdt.launching.PROJECT_ATTR" value="org.eclipse.emf.compare.gendoc"/> +<stringAttribute key="org.eclipse.ui.externaltools.ATTR_LOCATION" value="${workspace_loc:/org.eclipse.emf.compare.gendoc/build.xml}"/> +<stringAttribute key="org.eclipse.ui.externaltools.ATTR_RUN_BUILD_KINDS" value="full,incremental,"/> +<booleanAttribute key="org.eclipse.ui.externaltools.ATTR_TRIGGERS_CONFIGURED" value="true"/> +<stringAttribute key="org.eclipse.ui.externaltools.ATTR_WORKING_DIRECTORY" value="${workspace_loc:/org.eclipse.emf.compare.gendoc}"/> +</launchConfiguration> diff --git a/packaging/org.eclipse.emf.compare.gendoc/.project b/packaging/org.eclipse.emf.compare.gendoc/.project new file mode 100644 index 000000000..a2da8dc60 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/.project @@ -0,0 +1,27 @@ +<?xml version="1.0" encoding="UTF-8"?> +<projectDescription> + <name>org.eclipse.emf.compare.gendoc</name> + <comment></comment> + <projects> + </projects> + <buildSpec> + <buildCommand> + <name>org.eclipse.jdt.core.javabuilder</name> + <arguments> + </arguments> + </buildCommand> + <buildCommand> + <name>org.eclipse.ui.externaltools.ExternalToolBuilder</name> + <triggers>full,incremental,</triggers> + <arguments> + <dictionary> + <key>LaunchConfigHandle</key> + <value><project>/.externalToolBuilders/Runnable Jar Builder.launch</value> + </dictionary> + </arguments> + </buildCommand> + </buildSpec> + <natures> + <nature>org.eclipse.jdt.core.javanature</nature> + </natures> +</projectDescription> diff --git a/packaging/org.eclipse.emf.compare.gendoc/.settings/org.eclipse.jdt.core.prefs b/packaging/org.eclipse.emf.compare.gendoc/.settings/org.eclipse.jdt.core.prefs new file mode 100644 index 000000000..7341ab168 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/.settings/org.eclipse.jdt.core.prefs @@ -0,0 +1,11 @@ +eclipse.preferences.version=1 +org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled +org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.7 +org.eclipse.jdt.core.compiler.codegen.unusedLocal=preserve +org.eclipse.jdt.core.compiler.compliance=1.7 +org.eclipse.jdt.core.compiler.debug.lineNumber=generate +org.eclipse.jdt.core.compiler.debug.localVariable=generate +org.eclipse.jdt.core.compiler.debug.sourceFile=generate +org.eclipse.jdt.core.compiler.problem.assertIdentifier=error +org.eclipse.jdt.core.compiler.problem.enumIdentifier=error +org.eclipse.jdt.core.compiler.source=1.7 diff --git a/packaging/org.eclipse.emf.compare.gendoc/build.xml b/packaging/org.eclipse.emf.compare.gendoc/build.xml new file mode 100644 index 000000000..e77d27288 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/build.xml @@ -0,0 +1,48 @@ +<?xml version="1.0"?> +<project name="org.eclipse.emf.compare.doc" default="default"> + <property name="src.dir" value="${basedir}/src"/> + <property name="lib.dir" value="${basedir}/lib"/> + <property name="build.dir" value="${basedir}/target"/> + <property name="classes.dir" value="${build.dir}/classes"/> + <fileset dir="${lib.dir}" id="compare-gendoc.jars"> + <include name="org.eclipse.jgit-3.2.0.201312181205-r.jar"/> + <include name="org.eclipse.mylyn.wikitext.core_1.9.0.20131007-2055.jar"/> + <include name="org.eclipse.mylyn.wikitext.mediawiki.core_1.9.0.20131007-2055.jar"/> + </fileset> + <path id="classpath"> + <fileset refid="compare-gendoc.jars"/> + <pathelement location="${classes.dir}"/> + <pathelement location="${src.dir}"/> + </path> + <target name="clean" description="remove all generated files"> + <delete dir="${build.dir}"/> + </target> + <!-- + Default target so that a command line build can + do more than one thing. +--> + <target name="default" depends="jar"/> + <target name="compile" description="compile Java source code"> + <mkdir dir="${classes.dir}"/> + <javac destdir="${classes.dir}" classpathref="classpath" debug="on" deprecation="on" includeAntRuntime="no" encoding="UTF-8"> + <src path="${src.dir}"/> + <compilerarg value="-Xlint:rawtypes"/> + <compilerarg value="-Xlint:unchecked"/> + </javac> + </target> + <target name="jar" depends="compile" description="build compare-gendoc.jar"> + <jar destfile="${build.dir}/compare-gendoc.jar" update="true"> + <zipfileset refid="compare-gendoc.jars"/> + <zipfileset src="${lib.dir}/jar-in-jar-loader.zip"/> + <fileset dir="${src.dir}" excludes="**/*.java"/> + <fileset dir="${classes.dir}"/> + <manifest> + <attribute name="Main-Class" value="org.eclipse.jdt.internal.jarinjarloader.JarRsrcLoader"/> + <attribute name="Rsrc-Main-Class" value="org.eclipse.emf.compare.doc.WikiTextToHTML"/> + <attribute name="Class-Path" value="."/> + <attribute name="Rsrc-Class-Path" value="./ org.eclipse.jgit-3.2.0.201312181205-r.jar org.eclipse.mylyn.wikitext.core_1.9.0.20131007-2055.jar org.eclipse.mylyn.wikitext.mediawiki.core_1.9.0.20131007-2055.jar"/> + </manifest> + </jar> + </target> + <target name="all" depends="jar"/> +</project> diff --git a/packaging/org.eclipse.emf.compare.gendoc/lib/jar-in-jar-loader.zip b/packaging/org.eclipse.emf.compare.gendoc/lib/jar-in-jar-loader.zip Binary files differnew file mode 100644 index 000000000..6ee121769 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/lib/jar-in-jar-loader.zip diff --git a/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.jgit-3.2.0.201312181205-r.jar b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.jgit-3.2.0.201312181205-r.jar Binary files differnew file mode 100644 index 000000000..172c4d4cd --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.jgit-3.2.0.201312181205-r.jar diff --git a/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.core.source_1.9.0.20131007-2055.jar b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.core.source_1.9.0.20131007-2055.jar Binary files differnew file mode 100644 index 000000000..52f4f0268 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.core.source_1.9.0.20131007-2055.jar diff --git a/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.core_1.9.0.20131007-2055.jar b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.core_1.9.0.20131007-2055.jar Binary files differnew file mode 100644 index 000000000..013fc5005 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.core_1.9.0.20131007-2055.jar diff --git a/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.mediawiki.core.source_1.9.0.20131007-2055.jar b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.mediawiki.core.source_1.9.0.20131007-2055.jar Binary files differnew file mode 100644 index 000000000..27924ed7b --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.mediawiki.core.source_1.9.0.20131007-2055.jar diff --git a/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.mediawiki.core_1.9.0.20131007-2055.jar b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.mediawiki.core_1.9.0.20131007-2055.jar Binary files differnew file mode 100644 index 000000000..a078aee37 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/lib/org.eclipse.mylyn.wikitext.mediawiki.core_1.9.0.20131007-2055.jar diff --git a/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/CustomMediaWikiLanguage.java b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/CustomMediaWikiLanguage.java new file mode 100644 index 000000000..ed3ea1870 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/CustomMediaWikiLanguage.java @@ -0,0 +1,54 @@ +/*******************************************************************************
+ * Copyright (c) 2013 Obeo.
+ * 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:
+ * Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.emf.compare.doc;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.eclipse.mylyn.internal.wikitext.mediawiki.core.block.TableOfContentsBlock;
+import org.eclipse.mylyn.wikitext.core.parser.markup.Block;
+import org.eclipse.mylyn.wikitext.core.parser.markup.MarkupLanguage;
+import org.eclipse.mylyn.wikitext.mediawiki.core.MediaWikiLanguage;
+
+/**
+ * @author <a href="mailto:mikael.barbero@obeo.fr">Mikael Barbero</a>
+ *
+ */
+public class CustomMediaWikiLanguage extends MediaWikiLanguage {
+
+ public CustomMediaWikiLanguage() {
+ super();
+ setName("CustomMediaWikiLanguage");
+ }
+
+ @Override
+ protected void addStandardBlocks(List<Block> blocks,
+ List<Block> paragraphBreakingBlocks) {
+ super.addStandardBlocks(blocks, paragraphBreakingBlocks);
+ CustomTableOfContentsBlock customTOCBlock = new CustomTableOfContentsBlock();
+ replaceTOCBlock(blocks, customTOCBlock);
+ replaceTOCBlock(paragraphBreakingBlocks, customTOCBlock);
+ }
+
+ private void replaceTOCBlock(List<Block> blocksList, CustomTableOfContentsBlock customTOCBlock) {
+ for (Block block : new ArrayList<>(blocksList)) {
+ if (block instanceof TableOfContentsBlock) {
+
+ blocksList.set(blocksList.indexOf(block), customTOCBlock);
+ }
+ }
+ }
+
+ @Override
+ public MarkupLanguage clone() {
+ return (CustomMediaWikiLanguage) super.clone();
+ }
+}
\ No newline at end of file diff --git a/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/CustomTableOfContentsBlock.java b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/CustomTableOfContentsBlock.java new file mode 100644 index 000000000..a4b3017d9 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/CustomTableOfContentsBlock.java @@ -0,0 +1,101 @@ +/*******************************************************************************
+ * Copyright (c) 2013 Obeo.
+ * 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:
+ * Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.emf.compare.doc;
+
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+import org.eclipse.mylyn.internal.wikitext.mediawiki.core.block.TableOfContentsBlock;
+import org.eclipse.mylyn.wikitext.core.parser.Attributes;
+import org.eclipse.mylyn.wikitext.core.parser.DocumentBuilder.BlockType;
+import org.eclipse.mylyn.wikitext.core.parser.outline.OutlineItem;
+import org.eclipse.mylyn.wikitext.core.parser.outline.OutlineParser;
+import org.eclipse.mylyn.wikitext.mediawiki.core.MediaWikiLanguage;
+
+/**
+ * @author <a href="mailto:mikael.barbero@obeo.fr">Mikael Barbero</a>
+ *
+ */
+public class CustomTableOfContentsBlock extends TableOfContentsBlock {
+
+ static final Pattern startPattern = Pattern.compile("\\s*__TOC__\\s*(.*?)"); //$NON-NLS-1$
+
+ private int blockLineNumber = 0;
+
+ private Matcher matcher;
+
+ protected void emitToc(OutlineItem item) {
+ if (item.getChildren().isEmpty()) {
+ return;
+ }
+ if ((item.getLevel() + 1) > maxLevel) {
+ return;
+ }
+ Attributes nullAttributes = new Attributes();
+
+ builder.beginBlock(BlockType.NUMERIC_LIST, new Attributes(null, null, "list-style: none", null)); //$NON-NLS-1$ //$NON-NLS-2$
+ for (OutlineItem child : item.getChildren()) {
+ builder.beginBlock(BlockType.LIST_ITEM, nullAttributes);
+ builder.link('#' + child.getId(), child.getLabel());
+ emitToc(child);
+ builder.endBlock();
+ }
+ builder.endBlock();
+ }
+
+ @Override
+ public int processLineContent(String line, int offset) {
+ if (blockLineNumber++ > 0) {
+ setClosed(true);
+ return 0;
+ }
+
+ if (!getMarkupLanguage().isFilterGenerativeContents()) {
+ OutlineParser outlineParser = new OutlineParser(new MediaWikiLanguage());
+ OutlineItem rootItem = outlineParser.parse(state.getMarkupContent());
+
+ builder.beginBlock(BlockType.DIV, new Attributes(null, "toc", null, null));
+ builder.beginHeading(3, new Attributes(null, "toc-title", null, null));
+ builder.characters("Table of Contents");
+ builder.endHeading();
+
+ if (rootItem.getChildren().size() == 1 && rootItem.getChildren().get(0).getLevel() == 1) {
+ emitToc(rootItem.getChildren().get(0));
+ } else {
+ emitToc(rootItem);
+ }
+
+ builder.endBlock();
+ }
+ int start = matcher.start(1);
+ if (start > 0) {
+ setClosed(true);
+ }
+ return start;
+ }
+
+ @Override
+ public boolean canStart(String line, int lineOffset) {
+ if (lineOffset == 0 && !getMarkupLanguage().isFilterGenerativeContents()) {
+ matcher = startPattern.matcher(line);
+ blockLineNumber = 0;
+ return matcher.matches();
+ } else {
+ matcher = null;
+ return false;
+ }
+ }
+
+ @Override
+ public CustomTableOfContentsBlock clone() {
+ return (CustomTableOfContentsBlock) super.clone();
+ }
+}
diff --git a/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/PrimaryTOCWriter.java b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/PrimaryTOCWriter.java new file mode 100644 index 000000000..2c6c09faa --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/PrimaryTOCWriter.java @@ -0,0 +1,110 @@ +/*******************************************************************************
+ * Copyright (c) 2013 Obeo.
+ * 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:
+ * Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.emf.compare.doc;
+
+import java.io.StringWriter;
+import java.io.Writer;
+import java.nio.file.Path;
+
+import org.eclipse.mylyn.wikitext.core.util.DefaultXmlStreamWriter;
+import org.eclipse.mylyn.wikitext.core.util.FormattingXMLStreamWriter;
+import org.eclipse.mylyn.wikitext.core.util.XmlStreamWriter;
+
+/**
+ * @author <a href="mailto:mikael.barbero@obeo.fr">Mikael Barbero</a>
+ *
+ */
+public class PrimaryTOCWriter {
+
+ private StringWriter primaryTOCOut;
+ private XmlStreamWriter primaryTOCWriter;
+
+ private StringWriter pluginOut;
+ private XmlStreamWriter pluginWriter;
+ private Path baseDir;
+
+ void startPrimaryTOC(Path indexHTMLFile, String title) {
+ baseDir = indexHTMLFile.getParent();
+ primaryTOCOut = new StringWriter(8096);
+ primaryTOCWriter = createXmlStreamWriter(primaryTOCOut);
+
+ pluginOut = new StringWriter(8096);
+ pluginWriter = createXmlStreamWriter(pluginOut);
+
+ primaryTOCWriter.writeStartDocument("UTF-8", "1.0");
+ primaryTOCWriter.writeStartElement("toc");
+ primaryTOCWriter.writeAttribute("topic", indexHTMLFile.toString());
+ primaryTOCWriter.writeAttribute("label", title);
+
+ pluginWriter.writeStartDocument("UTF-8", "1.0");
+ pluginWriter.writeLiteral("\n<?eclipse version=\"3.2\"?>\n");
+ pluginWriter.writeStartElement("plugin");
+
+ pluginWriter.writeStartElement("extension");
+ pluginWriter.writeAttribute("point", "org.eclipse.help.toc");
+
+ pluginWriter.writeEmptyElement("toc");
+ pluginWriter.writeAttribute("file", "help/toc.xml");
+ pluginWriter.writeAttribute("primary", "true");
+
+ pluginWriter.writeEndElement();
+
+ pluginWriter.writeStartElement("extension");
+ pluginWriter.writeAttribute("point", "org.eclipse.help.toc");
+
+ }
+
+ void endPrimaryTOC() {
+ primaryTOCWriter.writeEndElement();
+ primaryTOCWriter.writeEndDocument();
+ primaryTOCWriter.close();
+
+ pluginWriter.writeEndElement();
+ pluginWriter.writeEndElement();
+ pluginWriter.writeEndDocument();
+ pluginWriter.close();
+ }
+
+ void startTopic(String label, Path href) {
+ primaryTOCWriter.writeStartElement("topic");
+ primaryTOCWriter.writeAttribute("label", label);
+
+ if (href != null) {
+ primaryTOCWriter.writeAttribute("href", href.toString());
+ }
+ }
+
+ void createLink(Path linkedTOC) {
+ primaryTOCWriter.writeStartElement("link");
+ primaryTOCWriter.writeAttribute("toc", baseDir.resolve(linkedTOC).toString());
+ primaryTOCWriter.writeEndElement();
+
+ pluginWriter.writeEmptyElement("toc");
+ pluginWriter.writeAttribute("file", baseDir.resolve(linkedTOC).toString());
+ }
+
+ void endTopic() {
+ primaryTOCWriter.writeEndElement();
+ }
+
+ String getPrimaryTOCContent() {
+ return primaryTOCOut.toString();
+ }
+
+ String getPluginContent() {
+ return pluginOut.toString();
+ }
+
+ protected XmlStreamWriter createXmlStreamWriter(Writer out) {
+ XmlStreamWriter writer = new DefaultXmlStreamWriter(out);
+ return new FormattingXMLStreamWriter(writer);
+ }
+}
diff --git a/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/WikiTextToHTML.java b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/WikiTextToHTML.java new file mode 100644 index 000000000..597c1d974 --- /dev/null +++ b/packaging/org.eclipse.emf.compare.gendoc/src/org/eclipse/emf/compare/doc/WikiTextToHTML.java @@ -0,0 +1,598 @@ +/*******************************************************************************
+ * Copyright (c) 2013 Obeo.
+ * 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:
+ * Obeo - initial API and implementation
+ *******************************************************************************/
+package org.eclipse.emf.compare.doc;
+
+import java.io.BufferedOutputStream;
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.io.FileOutputStream;
+import java.io.IOException;
+import java.io.OutputStreamWriter;
+import java.io.StringWriter;
+import java.io.UnsupportedEncodingException;
+import java.io.Writer;
+import java.lang.reflect.InvocationTargetException;
+import java.lang.reflect.Method;
+import java.nio.charset.Charset;
+import java.nio.file.FileSystem;
+import java.nio.file.FileSystems;
+import java.nio.file.FileVisitResult;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.PathMatcher;
+import java.nio.file.SimpleFileVisitor;
+import java.nio.file.StandardCopyOption;
+import java.nio.file.attribute.BasicFileAttributes;
+import java.util.ArrayList;
+import java.util.Calendar;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.eclipse.jgit.api.DescribeCommand;
+import org.eclipse.jgit.api.Git;
+import org.eclipse.jgit.api.errors.GitAPIException;
+import org.eclipse.jgit.lib.Repository;
+import org.eclipse.jgit.storage.file.FileRepositoryBuilder;
+import org.eclipse.mylyn.internal.wikitext.core.parser.builder.DefaultSplittingStrategy;
+import org.eclipse.mylyn.internal.wikitext.core.parser.builder.NoSplittingStrategy;
+import org.eclipse.mylyn.internal.wikitext.core.parser.builder.SplitOutlineItem;
+import org.eclipse.mylyn.internal.wikitext.core.parser.builder.SplittingHtmlDocumentBuilder;
+import org.eclipse.mylyn.internal.wikitext.core.parser.builder.SplittingOutlineParser;
+import org.eclipse.mylyn.internal.wikitext.core.parser.builder.SplittingStrategy;
+import org.eclipse.mylyn.internal.wikitext.core.validation.StandaloneMarkupValidator;
+import org.eclipse.mylyn.wikitext.core.parser.MarkupParser;
+import org.eclipse.mylyn.wikitext.core.parser.builder.HtmlDocumentBuilder;
+import org.eclipse.mylyn.wikitext.core.parser.markup.MarkupLanguage;
+import org.eclipse.mylyn.wikitext.core.parser.outline.OutlineItem;
+import org.eclipse.mylyn.wikitext.core.parser.util.MarkupToEclipseToc;
+import org.eclipse.mylyn.wikitext.core.util.XmlStreamWriter;
+import org.eclipse.mylyn.wikitext.core.validation.ValidationProblem;
+import org.eclipse.mylyn.wikitext.core.validation.ValidationProblem.Severity;
+
+/**
+ * @author <a href="mailto:mikael.barbero@obeo.fr">Mikael Barbero</a>
+ *
+ */
+public class WikiTextToHTML {
+
+ private static final String TOC = "__TOC__\n\n";
+
+ private static final FileSystem DEFAULT_FS = FileSystems.getDefault();
+
+ private static final boolean FORMAT_OUTPUT = true;
+
+ private static final Charset UTF_8 = Charset.forName("UTF-8");
+
+ private static final String MEDIA_WIKI = "MediaWiki";
+
+ private MarkupLanguage markupLanguage;
+
+ private boolean navigationImages = false;
+
+ private String title;
+
+ private boolean emitDoctype = false;
+
+ private boolean multipleOutputFiles;
+
+ private String copyrightNotice;
+
+ private boolean xhtmlStrict;
+
+ private String prependImagePrefix;
+
+ private String defaultAbsoluteLinkTarget;
+
+ private String linkRel;
+
+ private boolean suppressBuiltInCssStyles;
+
+ private boolean useInlineCssStyles;
+
+ private String htmlDoctype;
+
+ private List<Stylesheet> stylesheets;
+ private List<Stylesheet> helpStylesheets = new ArrayList<>();
+ private List<Stylesheet> websiteStylesheets = new ArrayList<>();
+
+ private PrimaryTOCWriter primaryTOCWriter = new PrimaryTOCWriter();
+
+ private Path sourceFolder;
+
+ private List<Path> foldersToCopy;
+
+ private Path targetRootFolder;
+
+ private Path targetWebsiteFolder;
+
+ private Path targetHelpFolder;
+
+ private boolean genEclipseHelp;
+
+ private boolean genWebsite;
+
+ private static java.util.Date NOW = Calendar.getInstance().getTime();
+
+ public static void main(String[] args) throws Exception {
+ WikiTextToHTML wikiTextToHTML = new WikiTextToHTML();
+ wikiTextToHTML.run(args);
+ }
+
+ public void run(String[] args) throws Exception {
+ processCommandLineArgs(args);
+
+ if (targetRootFolder == null) {
+ System.err.println("Error: unable to find -location argument");
+ usage();
+ System.exit(1);
+ }
+ if (!genEclipseHelp && !genWebsite) {
+ System.err.println("Error: you must at least provide a -eclipsehelp or a -website option");
+ usage();
+ System.exit(1);
+ }
+
+ markupLanguage = new CustomMediaWikiLanguage();
+ markupLanguage.setInternalLinkPattern("{0}");
+
+ Stylesheet ss1 = new Stylesheet();
+ ss1.setUrl("/help/topic/org.eclipse.emf.compare.doc/help/resources/bootstrap.css");
+ helpStylesheets.add(ss1);
+ Stylesheet ss2 = new Stylesheet();
+ ss2.setUrl("/help/topic/org.eclipse.emf.compare.doc/help/resources/custom.css");
+ helpStylesheets.add(ss2);
+
+ ss1 = new Stylesheet();
+ ss1.setUrl("resources/bootstrap.css");
+ websiteStylesheets.add(ss1);
+ ss2 = new Stylesheet();
+ ss2.setUrl("resources/custom.css");
+ websiteStylesheets.add(ss2);
+
+ sourceFolder = DEFAULT_FS.getPath("src");
+ foldersToCopy = new ArrayList<>();
+ foldersToCopy.add(targetRootFolder.resolve(sourceFolder).resolve("images"));
+ foldersToCopy.add(targetRootFolder.resolve(sourceFolder).resolve("resources"));
+
+ targetWebsiteFolder = DEFAULT_FS.getPath("target", "website").resolve(gitDescribe());
+ targetHelpFolder = DEFAULT_FS.getPath("help");
+
+ if (genEclipseHelp) {
+ primaryTOCWriter.startPrimaryTOC(targetHelpFolder.resolve("index.html"), "EMF Compare Documentation");
+ }
+
+ final PathMatcher mediawikiPattern = DEFAULT_FS.getPathMatcher("glob:**/*.mediawiki");
+
+ Files.walkFileTree(targetRootFolder.resolve(sourceFolder), new SimpleFileVisitor<Path>() {
+ @Override
+ public FileVisitResult visitFile(Path markupPath, BasicFileAttributes attrs) throws IOException {
+ if (mediawikiPattern.matches(markupPath)) {
+ processFile(sourceFolder, targetWebsiteFolder, targetHelpFolder, markupPath);
+ }
+ return FileVisitResult.CONTINUE;
+ }
+
+ @Override
+ public FileVisitResult visitFileFailed(Path file, IOException exc) throws IOException {
+ System.err.println("Failed to visit " + file);
+ exc.printStackTrace();
+ return FileVisitResult.CONTINUE;
+ }
+
+ /**
+ * {@inheritDoc}
+ * @see java.nio.file.SimpleFileVisitor#preVisitDirectory(java.lang.Object, java.nio.file.attribute.BasicFileAttributes)
+ */
+ @Override
+ public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) throws IOException {
+ if (genEclipseHelp && !dir.equals(targetRootFolder.resolve(sourceFolder)) && !foldersToCopy.contains(dir)) {
+ if (dir.resolve("index.mediawiki").toFile().exists()) {
+ primaryTOCWriter.startTopic(getTitle(dir), dir.resolve("index.html"));
+ } else {
+ primaryTOCWriter.startTopic(getTitle(dir), null);
+ }
+ }
+ return FileVisitResult.CONTINUE;
+ }
+
+ /**
+ * {@inheritDoc}
+ * @see java.nio.file.SimpleFileVisitor#postVisitDirectory(java.lang.Object, java.io.IOException)
+ */
+ @Override
+ public FileVisitResult postVisitDirectory(Path dir, IOException exc) throws IOException {
+ if (genEclipseHelp && !dir.equals(targetRootFolder.resolve(sourceFolder)) && !foldersToCopy.contains(dir)) {
+ primaryTOCWriter.endTopic();
+ }
+ return FileVisitResult.CONTINUE;
+ }
+ });
+
+ if (genEclipseHelp) {
+ primaryTOCWriter.endPrimaryTOC();
+ writeStringToFile(primaryTOCWriter.getPrimaryTOCContent(), targetRootFolder.resolve(targetHelpFolder).resolve("toc.xml"));
+ writeStringToFile(primaryTOCWriter.getPluginContent(), targetRootFolder.resolve("plugin.xml"));
+ }
+
+ for (Path folder : foldersToCopy) {
+ if (genWebsite)
+ copy(folder, targetRootFolder.resolve(targetWebsiteFolder).resolve(folder.getFileName()), "glob:**/*");
+ if (genEclipseHelp)
+ copy(folder, targetRootFolder.resolve(targetHelpFolder).resolve(folder.getFileName()), "glob:**/*");
+ }
+ }
+
+ /**
+ *
+ */
+ private void usage() {
+ System.out.println("Usage: wikiTextToHTML -location path [-eclipsehelp] [-website]");
+ }
+
+ private void processCommandLineArgs(String[] args) throws Exception {
+ if (args == null)
+ throw new Exception("No argument provided");
+ for (int i = 0; i < args.length; i++) {
+ String option = args[i];
+ String arg = "";
+ if (i == args.length - 1 || args[i + 1].startsWith("-")) {//$NON-NLS-1$
+ // do nothgin
+ } else {
+ arg = args[++i];
+ }
+
+ if (option.equalsIgnoreCase("-location")) { //$NON-NLS-1$
+ targetRootFolder = DEFAULT_FS.getPath(arg);
+ }
+
+ if (option.equalsIgnoreCase("-eclipsehelp")) { //$NON-NLS-1$
+ genEclipseHelp = true;
+ }
+
+ if (option.equalsIgnoreCase("-website")) { //$NON-NLS-1$
+ genWebsite = true;
+ }
+ }
+ }
+
+ private String getTitle(Path path) {
+ String filename = path.getFileName().toString();
+ int lastIndexOf = filename.lastIndexOf('.');
+ if (lastIndexOf >= 0) {
+ filename = filename.substring(0, lastIndexOf);
+ }
+ String[] split = filename.split("-");
+
+ StringBuilder sb = new StringBuilder();
+ for (int i = 0; i < split.length; i++) {
+ String str = split[i].trim();
+ if (str.length() > 0) {
+ if (i == 0) {
+ char firstChar = str.charAt(0);
+ sb.append(Character.toUpperCase(firstChar));
+ sb.append(str.substring(1));
+ } else {
+ sb.append(str);
+ }
+ sb.append(' ');
+ }
+ }
+ return sb.toString().trim();
+ }
+
+ private void processFile(final Path sourceFolder,
+ final Path targetWebsiteFolder,
+ final Path targetHelpFolder, Path markupPath)
+ throws IOException, FileNotFoundException,
+ UnsupportedEncodingException {
+ System.out.println("Processing " + markupPath);
+
+ Path relativeMarkupPath = targetRootFolder.resolve(sourceFolder).relativize(markupPath);
+
+ Path targetHTML = targetWebsiteFolder.resolve(changeFilename(relativeMarkupPath, ".html"));
+
+ Path relativeTOCPath = changeFilename(relativeMarkupPath, "toc-", ".xml");
+ Path targetTOC = targetHelpFolder.resolve(relativeTOCPath);
+ Path targetHelp = targetHelpFolder.resolve(changeFilename(relativeMarkupPath, ".html"));
+
+ if (genWebsite) {
+ mkdirs(targetRootFolder.resolve(targetHTML));
+ } else if (genEclipseHelp) {
+ mkdirs(targetRootFolder.resolve(targetTOC));
+ mkdirs(targetRootFolder.resolve(targetHelp));
+ }
+
+ String markupContent = new String(Files.readAllBytes(markupPath), UTF_8);
+
+ String markupContentWithTOC = markupContent.replaceFirst("=(.*)=", "=EMF Compare — $1=\n\nVersion " + gitDescribe() +"\n\n__TOC__\n\n") +
+ "\n\nPart of [index.html EMF Compare Documentation]" +
+ "\n\nVersion " + gitDescribe() +
+ "\n\nLast updated " + NOW;
+
+
+ if (performValidation(markupPath, markupContent)) {
+ // for website
+ if (genWebsite) {
+ stylesheets = websiteStylesheets;
+ genHTML(getTitle(targetHTML), markupContentWithTOC, targetRootFolder.resolve(targetHTML));
+ }
+
+ // for eclipse help
+ if (genEclipseHelp) {
+ stylesheets = helpStylesheets;
+ genHTML(getTitle(targetHTML), markupContent, targetRootFolder.resolve(targetHelp));
+
+
+ final PathMatcher indexPattern = DEFAULT_FS.getPathMatcher("glob:**/index.mediawiki");
+ if (!indexPattern.matches(markupPath)) {
+ genTOC(getTitle(targetHelp), markupContent, targetRootFolder.resolve(targetTOC), targetHelp);
+ primaryTOCWriter.startTopic(getTitle(targetHelp), targetHelp);
+ primaryTOCWriter.createLink(relativeTOCPath);
+ primaryTOCWriter.endTopic();
+ }
+ }
+ }
+ }
+
+
+ private void mkdirs(Path file) {
+ File parentFile = file.getParent().toFile();
+ if (!parentFile.exists()) {
+ file.getParent().toFile().mkdirs();
+ }
+ }
+
+ private Path changeFilename(Path source, String newFileExtension) {
+ return changeFilename(source, "", newFileExtension);
+ }
+
+ private Path changeFilename(Path source, String prefix, String newFileExtension) {
+ String filename = source.getFileName().toString();
+ int lastIndexOf = filename.lastIndexOf(".");
+ String newFileName = prefix + filename.substring(0, lastIndexOf) + newFileExtension;
+ return source.resolveSibling(newFileName);
+ }
+
+ private void genTOC(String name, String markupContent, Path targetToc, Path targetHTML) throws IOException, UnsupportedEncodingException, FileNotFoundException {
+ MarkupToEclipseToc toEclipseToc = new MarkupToEclipseToc() {
+ public String createToc(OutlineItem root) {
+ StringWriter out = new StringWriter(8096);
+
+ XmlStreamWriter writer = createXmlStreamWriter(out);
+
+ writer.writeStartDocument("utf-8", "1.0"); //$NON-NLS-1$ //$NON-NLS-2$
+
+ if (copyrightNotice != null) {
+ writer.writeComment(copyrightNotice);
+ }
+
+ Method method = null;
+ try {
+ method = MarkupToEclipseToc.class.getDeclaredMethod("emitToc", XmlStreamWriter.class, List.class);
+ method.setAccessible(true);
+ } catch (NoSuchMethodException | SecurityException | IllegalArgumentException e) {
+ throw new RuntimeException(e);
+ }
+
+ if (root.getChildren().size() == 1 && root.getChildren().get(0).getLevel() == 1) {
+ OutlineItem innerRoot = root.getChildren().get(0);
+ writer.writeStartElement("toc"); //$NON-NLS-1$
+ writer.writeAttribute("topic", getHtmlFile() + "#" + innerRoot.getId()); //$NON-NLS-1$
+ writer.writeAttribute("label", innerRoot.getLabel()); //$NON-NLS-1$
+ try {
+ method.invoke(this, writer, innerRoot.getChildren());
+ } catch (IllegalAccessException | IllegalArgumentException | InvocationTargetException e) {
+ throw new RuntimeException(e);
+ }
+ } else {
+ writer.writeStartElement("toc"); //$NON-NLS-1$
+ writer.writeAttribute("topic", getHtmlFile()); //$NON-NLS-1$
+ writer.writeAttribute("label", root.getLabel()); //$NON-NLS-1$
+ try {
+ method.invoke(this, writer, root.getChildren());
+ } catch (IllegalAccessException | IllegalArgumentException | InvocationTargetException e) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ writer.writeEndElement(); // toc
+
+ writer.writeEndDocument();
+ writer.close();
+
+ return out.toString();
+ }
+ };
+ toEclipseToc.setMarkupLanguage(markupLanguage.clone());
+ toEclipseToc.setHtmlFile(targetHTML.toString());
+ toEclipseToc.setBookTitle(name);
+ String tocContents = toEclipseToc.parse(markupContent);
+
+ writeStringToFile(tocContents, targetToc);
+ }
+
+ private void writeStringToFile(String content, Path path) throws UnsupportedEncodingException, FileNotFoundException, IOException {
+ try(Writer writer = new OutputStreamWriter(new BufferedOutputStream(new FileOutputStream(path.toFile())), "UTF-8")) {
+ writer.write(content);
+ }
+ }
+
+ private void genHTML(String name, String markupContent, Path htmlOutputFile) throws IOException, FileNotFoundException {
+ try (Writer writer = new OutputStreamWriter(new BufferedOutputStream(new FileOutputStream(htmlOutputFile.toFile())), UTF_8)) {
+ HtmlDocumentBuilder builder = new HtmlDocumentBuilder(writer, FORMAT_OUTPUT);
+ for (Stylesheet stylesheet : stylesheets) {
+ HtmlDocumentBuilder.Stylesheet builderStylesheet;
+
+ if (stylesheet.url != null) {
+ if (stylesheets == websiteStylesheets) {
+ Path stylesheetPath = DEFAULT_FS.getPath(stylesheet.url);
+ Path targetStylesheetPath = targetRootFolder.resolve(targetWebsiteFolder.resolve(stylesheetPath));
+ Path relativeStylesheetPath = htmlOutputFile.getParent().relativize(targetStylesheetPath);
+ builderStylesheet = new HtmlDocumentBuilder.Stylesheet(relativeStylesheetPath.toString());
+ } else {
+ builderStylesheet = new HtmlDocumentBuilder.Stylesheet(stylesheet.url);
+ }
+ } else {
+ builderStylesheet = new HtmlDocumentBuilder.Stylesheet(stylesheet.file);
+ }
+ builder.addCssStylesheet(builderStylesheet);
+
+ if (!stylesheet.attributes.isEmpty()) {
+ for (Map.Entry<String, String> attr : stylesheet.attributes.entrySet()) {
+ builderStylesheet.getAttributes().put(attr.getKey(), attr.getValue());
+ }
+ }
+ }
+
+ builder.setTitle(title == null ? name.toString() : title);
+ builder.setEmitDtd(emitDoctype);
+ if (emitDoctype && htmlDoctype != null) {
+ builder.setHtmlDtd(htmlDoctype);
+ }
+ builder.setUseInlineStyles(useInlineCssStyles);
+ builder.setSuppressBuiltInStyles(suppressBuiltInCssStyles);
+ builder.setLinkRel(linkRel);
+ builder.setDefaultAbsoluteLinkTarget(defaultAbsoluteLinkTarget);
+ builder.setPrependImagePrefix(prependImagePrefix);
+ builder.setXhtmlStrict(xhtmlStrict);
+ builder.setCopyrightNotice(copyrightNotice);
+
+ SplittingStrategy splittingStrategy = multipleOutputFiles
+ ? new DefaultSplittingStrategy()
+ : new NoSplittingStrategy();
+ SplittingOutlineParser outlineParser = new SplittingOutlineParser();
+ outlineParser.setMarkupLanguage(markupLanguage.clone());
+ outlineParser.setSplittingStrategy(splittingStrategy);
+ SplitOutlineItem item = outlineParser.parse(markupContent);
+ item.setSplitTarget(htmlOutputFile.toFile().getName());
+ SplittingHtmlDocumentBuilder splittingBuilder = new SplittingHtmlDocumentBuilder();
+ splittingBuilder.setRootBuilder(builder);
+ splittingBuilder.setOutline(item);
+ splittingBuilder.setRootFile(htmlOutputFile.toFile());
+ splittingBuilder.setNavigationImages(navigationImages);
+ splittingBuilder.setFormatting(FORMAT_OUTPUT);
+
+ MarkupParser parser = new MarkupParser();
+ parser.setMarkupLanguage(markupLanguage);
+ parser.setBuilder(splittingBuilder);
+ parser.parse(markupContent);
+ }
+ }
+
+ private String gitDescribe() {
+ FileRepositoryBuilder builder = new FileRepositoryBuilder();
+ try {
+ Repository repo = builder.setWorkTree(new File("."))
+ .readEnvironment() // scan environment GIT_* variables
+ .findGitDir() // scan up the file system tree
+ .build();
+ Git git = new Git(repo);
+ DescribeCommand command = git.describe();
+ return command.call();
+ } catch (IOException e) {
+ new RuntimeException(e);
+ } catch (GitAPIException e) {
+ new RuntimeException(e);
+ }
+ return "";
+ }
+
+ private void copy(final Path sourceFolder,
+ final Path targetFolder, String pattern) throws IOException {
+ final PathMatcher imageMatcher = DEFAULT_FS.getPathMatcher(pattern);
+ Files.walkFileTree(sourceFolder, new SimpleFileVisitor<Path>() {
+ @Override
+ public FileVisitResult visitFile(Path sourcePath, BasicFileAttributes attrs) throws IOException {
+ if (imageMatcher.matches(sourcePath)) {
+ String targetFile = sourcePath.toString().replace(sourceFolder.toString(), targetFolder.toString());
+ Path targetPath = DEFAULT_FS.getPath(targetFile);
+ targetPath.getParent().toFile().mkdirs();
+ Files.copy(sourcePath, targetPath, StandardCopyOption.REPLACE_EXISTING);
+ }
+ return FileVisitResult.CONTINUE;
+ }
+ });
+ }
+
+ /**
+ * Returns true if valid (may have warning).
+ * @param source
+ * @param markupContent
+ * @return
+ */
+ private boolean performValidation(Path source, String markupContent) {
+ StandaloneMarkupValidator markupValidator = StandaloneMarkupValidator.getValidator(MEDIA_WIKI);
+
+ List<ValidationProblem> problems = markupValidator.validate(markupContent);
+
+ int errorCount = 0;
+ for (ValidationProblem problem : problems) {
+ String messageLevel = problem.getSeverity().name();
+ if (problem.getSeverity() == Severity.ERROR) {
+ errorCount++;
+ }
+ System.out.println(String.format("%s: %s:%s %s", messageLevel, source.toString(), problem.getOffset(), problem.getMessage())); //$NON-NLS-1$
+ }
+
+ return errorCount == 0;
+ }
+
+ public static class Stylesheet {
+ private File file;
+
+ private String url;
+
+ private final Map<String, String> attributes = new HashMap<>();
+
+ public File getFile() {
+ return file;
+ }
+
+ public void setFile(File file) {
+ this.file = file;
+ }
+
+ public String getUrl() {
+ return url;
+ }
+
+ public void setUrl(String url) {
+ this.url = url;
+ }
+
+ public void addConfiguredAttribute(Attribute attribute) {
+ attributes.put(attribute.getName(), attribute.getValue());
+ }
+ }
+
+ public static class Attribute {
+ private String name;
+
+ private String value;
+
+ public String getName() {
+ return name;
+ }
+
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ public String getValue() {
+ return value;
+ }
+
+ public void setValue(String value) {
+ this.value = value;
+ }
+ }
+}
diff --git a/plugins/org.eclipse.emf.compare.doc/.classpath b/plugins/org.eclipse.emf.compare.doc/.classpath deleted file mode 100644 index c83506765..000000000 --- a/plugins/org.eclipse.emf.compare.doc/.classpath +++ /dev/null @@ -1,6 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<classpath> - <classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER/org.eclipse.jdt.internal.debug.ui.launcher.StandardVMType/J2SE-1.5"/> - <classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/> - <classpathentry kind="output" path="bin"/> -</classpath> diff --git a/plugins/org.eclipse.emf.compare.doc/.project b/plugins/org.eclipse.emf.compare.doc/.project index 91a9907e2..facb041f9 100644 --- a/plugins/org.eclipse.emf.compare.doc/.project +++ b/plugins/org.eclipse.emf.compare.doc/.project @@ -6,11 +6,6 @@ </projects> <buildSpec> <buildCommand> - <name>org.eclipse.jdt.core.javabuilder</name> - <arguments> - </arguments> - </buildCommand> - <buildCommand> <name>org.eclipse.pde.ManifestBuilder</name> <arguments> </arguments> @@ -20,15 +15,8 @@ <arguments> </arguments> </buildCommand> - <buildCommand> - <name>org.eclipse.pde.api.tools.apiAnalysisBuilder</name> - <arguments> - </arguments> - </buildCommand> </buildSpec> <natures> <nature>org.eclipse.pde.PluginNature</nature> - <nature>org.eclipse.jdt.core.javanature</nature> - <nature>org.eclipse.pde.api.tools.apiAnalysisNature</nature> </natures> </projectDescription> diff --git a/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.core.resources.prefs b/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.core.resources.prefs index 54e87c033..99f26c020 100644 --- a/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.core.resources.prefs +++ b/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.core.resources.prefs @@ -1,4 +1,2 @@ eclipse.preferences.version=1 -encoding//doc/developer/Logical\ Model.html=utf-8 -encoding//doc/overview/Overview.html=utf-8 encoding/<project>=UTF-8 diff --git a/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.jdt.core.prefs b/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.jdt.core.prefs deleted file mode 100644 index af0f20f97..000000000 --- a/plugins/org.eclipse.emf.compare.doc/.settings/org.eclipse.jdt.core.prefs +++ /dev/null @@ -1,7 +0,0 @@ -eclipse.preferences.version=1 -org.eclipse.jdt.core.compiler.codegen.inlineJsrBytecode=enabled -org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.5 -org.eclipse.jdt.core.compiler.compliance=1.5 -org.eclipse.jdt.core.compiler.problem.assertIdentifier=error -org.eclipse.jdt.core.compiler.problem.enumIdentifier=error -org.eclipse.jdt.core.compiler.source=1.5 diff --git a/plugins/org.eclipse.emf.compare.doc/META-INF/MANIFEST.MF b/plugins/org.eclipse.emf.compare.doc/META-INF/MANIFEST.MF index 9d1f24539..9f5ce295d 100644 --- a/plugins/org.eclipse.emf.compare.doc/META-INF/MANIFEST.MF +++ b/plugins/org.eclipse.emf.compare.doc/META-INF/MANIFEST.MF @@ -7,6 +7,4 @@ Bundle-Vendor: %providerName Bundle-Localization: plugin Bundle-ActivationPolicy: lazy Eclipse-LazyStart: true -Bundle-RequiredExecutionEnvironment: J2SE-1.5 -Require-Bundle: org.eclipse.ui.cheatsheets, - org.eclipse.help +Require-Bundle: org.eclipse.help diff --git a/plugins/org.eclipse.emf.compare.doc/build-doc.xml b/plugins/org.eclipse.emf.compare.doc/build-doc.xml deleted file mode 100644 index 722dfe212..000000000 --- a/plugins/org.eclipse.emf.compare.doc/build-doc.xml +++ /dev/null @@ -1,42 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - Copyright (c) 2013 Obeo - 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: - Obeo - Initial API and implementation ---> -<project name="org.eclipse.emf.compare.doc" default="generate-html"> - <property name="wikitext.standalone" value="${user.home}/.local/ant" description="Path to the WikiText standalone JARs" /> - - <path id="wikitext.classpath"> - <fileset dir="${wikitext.standalone}"> - <include name="org.eclipse.mylyn.wikitext.*core*.jar" /> - </fileset> - </path> - - <taskdef classpathref="wikitext.classpath" resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties" /> - - <target name="generate-html" description="Generate Eclipse help from Mediawiki source"> - <wikitext-to-html markupLanguage="MediaWiki" formatOutput="true" internallinkpattern="{0}"> - <fileset dir="${basedir}"> - <include name="doc/**/*.mediawiki" /> - </fileset> - <stylesheet url="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css" /> - <stylesheet url="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css" /> - </wikitext-to-html> - </target> - - <target name="generate-site-html" description="Generate Eclipse help from Mediawiki source"> - <wikitext-to-html markupLanguage="MediaWiki" formatOutput="true" internallinkpattern="{0}"> - <fileset dir="${basedir}"> - <include name="doc/**/*.mediawiki" /> - </fileset> - <stylesheet url="/emf/compare/doc/resources/bootstrap.css" /> - <stylesheet url="/emf/compare/doc/resources/custom.css" /> - </wikitext-to-html> - </target> -</project> diff --git a/plugins/org.eclipse.emf.compare.doc/build.properties b/plugins/org.eclipse.emf.compare.doc/build.properties index 223d797fe..72f3ca9be 100644 --- a/plugins/org.eclipse.emf.compare.doc/build.properties +++ b/plugins/org.eclipse.emf.compare.doc/build.properties @@ -8,10 +8,8 @@ # Contributors: # Obeo - initial API and implementation ################################################################################# -bin.includes = plugin.xml,\ - about.html,\ - META-INF/,\ - plugin.properties,\ - .,\ - doc/ -src.includes = doc/ +src.includes = help/,\ + plugin.xml +bin.includes = help/,\ + plugin.xml,\ + META-INF/ diff --git a/plugins/org.eclipse.emf.compare.doc/build.xml b/plugins/org.eclipse.emf.compare.doc/build.xml deleted file mode 100644 index 4ea615669..000000000 --- a/plugins/org.eclipse.emf.compare.doc/build.xml +++ /dev/null @@ -1,138 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -Copyright (c) 2006, 2012 Obeo. -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: - Obeo - initial API and implementation ---> -<project name="org.eclipse.emf.compare.doc" default="build.jars" basedir="."> - - <property file="${buildDirectory}/finalPluginsVersions.properties"/> - <property name="pluginVersion" value="${org.eclipse.emf.compare.doc}"/> - - - <property name="plugin" value="org.eclipse.emf.compare"/> - <property name="docPlugin" value="org.eclipse.emf.compare.doc"/> - - <property name="filesToInclude" value="META-INF/**,about.html,about.ini,about.mappings,about.properties,modeling*.png,plugin.xml,plugin.properties,doc.zip,*.xml,index/**,tutorials/**,images/**,html/**,references/**"/> - <property name="filesToExclude" value="**/*.dnx"/> - - <!-- Compiler settings. --> - <property name="javacFailOnError" value="false"/> - <property name="javacDebugInfo" value="on"/> - <property name="javacVerbose" value="true"/> - <property name="javacSource" value="1.5"/> - <property name="javacTarget" value="1.5"/> - <property name="compilerArg" value=""/> - <path id="path_bootclasspath"> - <fileset dir="${java.home}/lib"> - <include name="*.jar"/> - </fileset> - </path> - <property name="bootclasspath" refid="path_bootclasspath"/> - - <property name="bundleJavacSource" value="${javacSource}"/> - <property name="bundleJavacTarget" value="${javacTarget}"/> - <property name="bundleBootClasspath" value="${bootclasspath}"/> - <property name="basews" value="${ws}"/> - <property name="baseos" value="${os}"/> - <property name="basearch" value="${arch}"/> - <property name="basenl" value="${nl}"/> - - <target name="init" depends="properties"> - <condition property="pluginTemp" value="${buildTempFolder}/plugins"> - <isset property="buildTempFolder"/> - </condition> - <property name="pluginTemp" value="${basedir}"/> - <condition property="build.result.folder" value="${pluginTemp}/${docPlugin}"> - <isset property="buildTempFolder"/> - </condition> - <property name="build.result.folder" value="${basedir}"/> - <property name="temp.folder" value="${basedir}/temp.folder"/> - <property name="plugin.destination" value="${basedir}"/> - </target> - - <target name="properties" if="eclipse.running"> - <property name="build.compiler" value="org.eclipse.jdt.core.JDTCompilerAdapter"/> - - </target> - - <target name="build.update.jar" depends="init" description="Build the plug-in: ${plugin} for an update site."> - <delete dir="${temp.folder}"/> - <mkdir dir="${temp.folder}"/> - <antcall target="build.jars"/> - <antcall target="gather.bin.parts"> - <param name="destination.temp.folder" value="${temp.folder}/"/> - </antcall> - <zip destfile="${plugin.destination}/${docPlugin}_${pluginVersion}.jar" basedir="${temp.folder}/${docPlugin}_${pluginVersion}" filesonly="false" whenempty="skip" update="false"/> - <delete dir="${temp.folder}"/> - </target> - - <target name="build.jars" depends="init" description="Build all the jars for the plug-in: ${docPlugin}."> - <!-- Execute a shell script that will create an ant javadoc script and then run it for us --> - <exec executable="sh"> - <arg value="build/antJavadoc.sh"/> - <arg value="${eclipse.home}/../eclipse"/> - </exec> - <!-- - <antcall target="build.index"/> - --> - - </target> - - <target name="build.index" depends="init" description="Builds search index for the plug-in" if="eclipse.running"> - <help.buildHelpIndex manifest="plugin.xml" destination="."/> - </target> - - <target name="build.sources" depends="init"> - </target> - <target name="gather.bin.parts" depends="init" if="destination.temp.folder"> - <mkdir dir="${destination.temp.folder}/${docPlugin}_${pluginVersion}"/> - <copy todir="${destination.temp.folder}/${docPlugin}_${pluginVersion}" failonerror="true" overwrite="false"> - <fileset dir="${basedir}" - includes="${filesToInclude}" - excludes="${filesToExclude}"/> - </copy> - <eclipse.versionReplacer - path="${destination.temp.folder}/${docPlugin}_${pluginVersion}" - version="${pluginVersion}"/> - </target> - - <target name="build.zips" depends="init"> - </target> - - <target name="gather.sources" depends="init" if="destination.temp.folder"> - </target> - - <target name="gather.logs" depends="init" if="destination.temp.folder"> - </target> - - <target name="clean" depends="init" description="Clean the plug-in: ${docPlugin} of all the zips, jars and logs created."> - <delete file="${plugin.destination}/${docPlugin}_${pluginVersion}.jar"/> - <delete file="${plugin.destination}/${docPlugin}_${pluginVersion}.zip"/> - <delete dir="${temp.folder}"/> - </target> - - <target name="zip.plugin" depends="init" description="Create a zip containing all the elements for the plug-in: ${docPlugin}."> - <delete dir="${temp.folder}"/> - <mkdir dir="${temp.folder}"/> - <antcall target="build.jars"/> - <antcall target="build.sources"/> - <antcall target="gather.bin.parts"> - <param name="destination.temp.folder" value="${temp.folder}/"/> - </antcall> - <antcall target="gather.sources"> - <param name="destination.temp.folder" value="${temp.folder}/"/> - </antcall> - <delete> - <fileset dir="${temp.folder}" includes="**/*.bin.log" /> - </delete> - <zip destfile="${plugin.destination}/${docPlugin}_${pluginVersion}.zip" basedir="${temp.folder}" filesonly="true" whenempty="skip" update="false"/> - <delete dir="${temp.folder}"/> - </target> - -</project> diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Architecture.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/Architecture.html deleted file mode 100644 index 6dce34369..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Architecture.html +++ /dev/null @@ -1,211 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Architecture</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Architecture">Architecture</h1> - <h2 id="Comparison_Process">Comparison Process</h2> - <p> - <div class="thumb middle"> - <div class="thumbinner" style="width:802px;"> - <a href="./../images/EMF_Compare_Process_Full.png" class="image"> - <img class="thumbimage" width="800" align="middle" border="0" src="./../images/EMF_Compare_Process_Full.png"/> - </a> - </div> - </div> - </p> - <p>This is the overview of the comparison process as a whole. Each of the six phases of the comparison process of EMF Compare are briefly defined on the - <a href="./../overview/Overview.html" title="./../overview/Overview.html">Overview</a>, and a much more in-depth explanation will be given below, in our explanations of the - <a href="./Default%20Behavior%20and%20Extensibility.html" title="./Default%20Behavior%20and%20Extensibility.html">default behavior</a> of EMF Compare. - </p> - <h2 id="Project_Architecture">Project Architecture</h2> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_2_Architecture.png"/> - </p> - <p>EMF Compare is built on top of the Eclipse platform. We depend on the Eclipse Modeling Framework (EMF), the Eclipse Compare framework and, finally, Eclipse Team, the framework upon which the repository providers (EGit, CVS, Subversive...) are built.</p> - <p>The EMF Compare extensions target specific extensions of the modeling framework: UML, the Graphical Modeling Framework (and its own extensions, papyrus, ecoretools, ...).</p> - <p>Whilst we are built atop bricks that are tightly coupled with the eclipse platform, it should be noted that the core of EMF Compare can be run in a standalone application with no runtime dependencies towards Eclipse; as can EMF itself.</p> - <h2 id="The_Comparison_Model">The Comparison Model</h2> - <p>EMF Compare uses a single model, which root is a - <i>Comparison</i> object, to represent all of the information regarding the comparison: matched objects, matched resources, detected differences, links between these references, etc. The root - <i>Comparison</i> is created at the beginning of the Match process, and will undergo a set of successive refinings during the remainder of the Comparison: Diff, Equivalence, Dependencies... will all add their own information to the - <i>Comparison</i>. - </p> - <p>So, how exactly is represented all of the information the Comparison model can hold, and how to make sense of it all?</p> - <h3 id="Match">Match</h3> - <p>A - <i>Match</i> element is how we represent that the - <i>n</i> compared versions have elements that are basically the same. For example, if we are comparing two different versions - <i>v1</i> and - <i>v2</i> of a given model which look like: - </p> - <table border="1" cellpadding="5" cellspacing="0"> - <tr> - <th align="center">Master</th> - <th align="center">Borrowables</th> - </tr> - <tr> - <td> - <img align="middle" border="0" src="./../images/v1.png"/> - </td> - <td> - <img align="middle" border="0" src="./../images/v2.png"/> - </td> - </tr> - </table> - <p>Comparing these two models, we'll have a Comparison model containing three matches:</p> - <ol> - <li>library <-> library</li> - <li>Book <-> Novel</li> - <li>title <-> title</li> - </ol> - <p>In other words, the comparison model contains an aggregate of the two or three compared models, in the form of - <i>Match</i> elements linking the elements of all versions together. Differences will then be detected on these - <i>Match</i> and added under them, thus allowing us to know both: - </p> - <ul> - <li>what the difference is (for example, "attribute name has been changed from - <i>Book</i> to - <i>Novel</i>"), and - </li> - <li>what the original elements were.</li> - </ul> - <h3 id="Diff">Diff</h3> - <p> - <i>Diff</i> elements are created during the differencing process in order to represent the actual modifications that can be detected within the source model(s). The - <i>Diff</i> concept itself is only there as the super-class of the three main kind of differences EMF Compare can detect in a model, namely - <i>ReferenceChange</i>, - <i>AttributeChange</i> and - <i>ResourceAttachmentChange</i>. We'll go back to these three sub-classes in a short while. - </p> - <p>Whatever their type, the differences share a number of common elements:</p> - <ul> - <li>a parent - <i>match</i>: differences are detected on a given - <i>Match</i>. Having a difference basically means that one of the elements paired through this - <i>Match</i> differs from its "reference" side (see - <i>source</i> description below). - </li> - <li>a - <i>source</i>: differences are detected on one side of their match. The source really only holds meaning in three-way comparisons, where a difference can be detected in either right or left. All differences detected through two-way comparisons have their source in the left side. This is because we always compare according to a "reference" side. During two-way comparisons, the reference side is the right: differences will always be detected on the left side as compared with the right side. During three-way comparisons though, differences can be detected on either left or right side as compared with their common ancestor; but never as compared to themselves (in other words, this is - <i>roughly</i> equivalent to two two-way comparisons, first the left as compared to the origin, then the right as compared to the origin). - </li> - <li>a current - <i>state</i>: all differences start off in their initial - <i>unresolved</i> state. The user can then choose to: - <ul> - <li>merge the difference (towards either right or left, applying or reverting the difference in the process), in which case the difference becomes - <i>merged</i>, or - </li> - <li>discard it, thus marking the change as - <i>discarded</i>. For example, if there is a conflicting edit of a textual attribute, the user can decide that neither right nor left are satisfying, and instead settle for a mix of the two. - </li> - </ul> - </li> - <li>a - <i>kind</i>: this is used by the engine to describe the type of difference it detected. Differences can be of four general types: - <ul> - <li> - <i>Add</i>: There are two distinct things that EMF Compare considers as an "addition". First, adding a new element within the values of a - <b>multi-valued feature</b> is undeniably an addition. Second, any change in a - <b>containment reference</b>, even if that reference is mono-valued, that represents a "new" element in the model is considered to be an addition. Note that this second case is an exception to the rule for - <i>change</i> differences outlined below. - </li> - <li> - <i>Delete</i>: this is used as the counterpart of - <i>add</i> differences, and it presents the same exception for - <b>mono-valued containment references</b>. - </li> - <li> - <i>Change</i>: any modification to a - <b>mono-valued feature</b> is considered as a - <i>change</i> difference by the engine. Take note that containment references are an exception to this rule: no - <i>change</i> will ever be detected on those. - </li> - <li> - <i>Move</i>: once again, two distinct things are represented as - <i>move</i> differences in the comparison model. First, - <b>reordering</b> the values of a multi-valued feature is considered as a series of MOVE: one difference for each moved value (EMF Compare computes the smallest number of differences needed between the two sides' values). Second, moving an object from - <b>one container to another</b> (changing the containing feature of the EObject) will be detected as a - <i>move</i>. - </li> - </ul> - </li> - </ul> - <p>In order to ensure that the model stays coherent through individual merge operations, we've also decided to link differences together through a number of associations and references. For example, there are times when one difference cannot be merged without first merging another, or some differences which are exactly equivalent to one another. In no specific order:</p> - <ul> - <li> - <i>dependency</i>: EMF Compare uses two oppposite references in order to track dependencies between differences. Namely, - <i>requires</i> and - <i>requiredBy</i> represent the two ends of this association. If the user has added a package - <i>P1</i>, then added a new Class - <i>C1</i> within this package, we will detect both differences. However the addition of - <i>C1</i> cannot be merged without first adding its container - <i>P1</i>. In such a case, the addition of - <i>C1</i> - <b>requires</b> the addition of - <i>P1</i>, and the later is - <b>requiredBy</b> the former. - </li> - <li> - <i>refinement</i>: this link is mainly used by extensions of EMF Compare in order to create high-level differences to hide the complexity of the comparison model. For example, this is used by the UML extension of EMF Compare to tell that the three differences "adding an association - <i>A1</i>", "adding a property - <i>P1</i> in association - <i>A1</i>" and "adding a property - <i>P2</i> in association - <i>A1</i>" is actually one single high-level difference, "adding an association - <i>A1</i>". This high-level difference is - <b>refinedBy</b> the others, which all - <b>refines</b> it. - </li> - <li> - <i>equivalence</i>: this association is used by the comparison engine in order to link together differences which are equivalent in terms of merging. For example, Ecore has a concept of - <b>eOpposite</b> references. Updating one of the two sides of an - <i>eOpposite</i> will automatically update the other. In such an event, EMF Compare will detect both sides as an individual difference. However, merging one of the two will trigger the update of the other side of the - <i>eOpposite</i> as well. In such cases, the two differences are set to be - <i>equivalent</i> to one another. Merging one difference part of an equivalence relationship will automatically mark all of the others as - <i>merged</i> (see - <i>state</i> above). - </li> - <li> - <i>implication</i>: implications are a special kind of "directed equivalence". A difference D1 that is linked as "implied by" another D2 means that merging D1 requires us to merge D1 instead. In other words, D2 will be automatically merged if we merge D1, but D1 will not be automatically merged if we merge D2. Implications are mostly used with UML models, where subsets and supersets may trigger such linked changes. - </li> - <li> - <i>conflict</i>: during three-way comparisons, we compare two versions of a given model with their common ancestor. We can thus detect changes that were made in either left or right side (see the description of - <i>source</i> above). However, there are cases when changes in the left conflict with changes in the right. For example, a class named "Book" in the origin model can have been renamed to "Novel" in the left model whereas it has been renamed to "Essay" in the right model. In such a case, the two differences will be marked as being in conflict with one another. - </li> - </ul> - <p>As mentionned above, there are only three kind of differences that we will detect through EMF Compare, which will be sufficient for all use cases. - <i>ReferenceChange</i> differences will be detected for every value of a reference for which we detect a change. Either the value was added, deleted, or moved (within the reference or between distinct references). - <i>AttributeChange</i> differences are the same, but for attributes instead of references. Lastly, the - <i>ResourceAttachmentChange</i> differences, though very much alike the ReferenceChanges we create for containment references, are specifically aimed at describing changes within the roots of one of the compared resources. - </p> - <h3 id="Conflict">Conflict</h3> - <p> - <b>Conflict</b> will only be detected during three-way comparisons. There can only be "conflicts" when we are comparing two different versions of a same model along with their common ancestor. In other words, we need to able to compare two versions of a common element with a "reference" version of that element. - </p> - <p>There are many different kinds of conflicts; to name a few:</p> - <ul> - <li>changing an element on one side (in any way, for example, renaming it) whilst that element has been removed from the other side</li> - <li>changing the same attribute of an element on both sides, to different values (for example, renaming "Book" to "Novel" on the left while be renamed "Book" to "Essay" on the right)</li> - <li>creating a new reference to an element on one side whilst it had been deleted from the other side</li> - </ul> - <p>Conflicts can be of two kinds. We call - <i>PSEUDO</i> conflict a conflict where the two sides of a comparison have changed as compared to their common ancestor, but where the two sides are actually now equal. In other words, the end result is that the left is now equal to the right, even though they are both different from their ancestor. This is the opposite of - <i>REAL</i> conflict where the value on all three sides is different. In terms of merging, pseudo conflicts do not need any particular action, whilst real conflicts actually need resolution. - </p> - <p>There can be more than two differences conflicting with each other. For example, the deletion of an element from one side will most likely conflict with a number of differences from the other side.</p> - <h3 id="Equivalence">Equivalence</h3> - <p>EMF Compare uses - <b>Equivalence</b> elements in order to link together a number of differences which can ultimately be considered to be the same. For example, ecore's - <i>eOpposite</i> references will be maintained in sync with one another. As such, modifying one of the two references will automatically update the second one accordingly. The manual modification and the automatic update are two distinct modifications of the model, resulting in two differences detected. However, merging any of these two differences will automatically merge the other one. Therefore both are marked as being equivalent to each other. - </p> - <p>There can be more than two differences equivalent with each other; in which case all will be added to a single - <i>Equivalence</i> object, representing their relations. - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Architecture.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/developer/Architecture.mediawiki deleted file mode 100644 index 98fc0d36c..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Architecture.mediawiki +++ /dev/null @@ -1,91 +0,0 @@ -= Architecture = - -== Comparison Process == - -[[Image:./../images/EMF_Compare_Process_Full.png|thumb|center|800px]] - -This is the overview of the comparison process as a whole. Each of the six phases of the comparison process of EMF Compare are briefly defined on the [[./../overview/Overview.html|Overview]], and a much more in-depth explanation will be given below, in our explanations of the [[./Default%20Behavior%20and%20Extensibility.html|default behavior]] of EMF Compare. - -== Project Architecture == - -[[Image:./../images/EMF_Compare_2_Architecture.png|center]] - -EMF Compare is built on top of the Eclipse platform. We depend on the Eclipse Modeling Framework (EMF), the Eclipse Compare framework and, finally, Eclipse Team, the framework upon which the repository providers (EGit, CVS, Subversive...) are built. - -The EMF Compare extensions target specific extensions of the modeling framework: UML, the Graphical Modeling Framework (and its own extensions, papyrus, ecoretools, ...). - -Whilst we are built atop bricks that are tightly coupled with the eclipse platform, it should be noted that the core of EMF Compare can be run in a standalone application with no runtime dependencies towards Eclipse; as can EMF itself. - -== The Comparison Model == -EMF Compare uses a single model, which root is a ''Comparison'' object, to represent all of the information regarding the comparison: matched objects, matched resources, detected differences, links between these references, etc. The root ''Comparison'' is created at the beginning of the Match process, and will undergo a set of successive refinings during the remainder of the Comparison: Diff, Equivalence, Dependencies... will all add their own information to the ''Comparison''. - -So, how exactly is represented all of the information the Comparison model can hold, and how to make sense of it all? - -===Match=== - -A ''Match'' element is how we represent that the ''n'' compared versions have elements that are basically the same. For example, if we are comparing two different versions ''v1'' and ''v2'' of a given model which look like: - -{| border="1" cellpadding="5" cellspacing="0" align="center" -|- -! align="center" | Master -! align="center" | Borrowables -|- -| [[Image:./../images/v1.png|center]] -| [[Image:./../images/v2.png|center]] -|} - -Comparing these two models, we'll have a Comparison model containing three matches: - -# library <-> library -# Book <-> Novel -# title <-> title - -In other words, the comparison model contains an aggregate of the two or three compared models, in the form of ''Match'' elements linking the elements of all versions together. Differences will then be detected on these ''Match'' and added under them, thus allowing us to know both: - -* what the difference is (for example, "attribute name has been changed from ''Book'' to ''Novel''"), and -* what the original elements were. - -=== Diff === - -''Diff'' elements are created during the differencing process in order to represent the actual modifications that can be detected within the source model(s). The ''Diff'' concept itself is only there as the super-class of the three main kind of differences EMF Compare can detect in a model, namely ''ReferenceChange'', ''AttributeChange'' and ''ResourceAttachmentChange''. We'll go back to these three sub-classes in a short while. - -Whatever their type, the differences share a number of common elements: -* a parent ''match'': differences are detected on a given ''Match''. Having a difference basically means that one of the elements paired through this ''Match'' differs from its "reference" side (see ''source'' description below). -* a ''source'': differences are detected on one side of their match. The source really only holds meaning in three-way comparisons, where a difference can be detected in either right or left. All differences detected through two-way comparisons have their source in the left side. This is because we always compare according to a "reference" side. During two-way comparisons, the reference side is the right: differences will always be detected on the left side as compared with the right side. During three-way comparisons though, differences can be detected on either left or right side as compared with their common ancestor; but never as compared to themselves (in other words, this is ''roughly'' equivalent to two two-way comparisons, first the left as compared to the origin, then the right as compared to the origin). -* a current ''state'': all differences start off in their initial ''unresolved'' state. The user can then choose to: -** merge the difference (towards either right or left, applying or reverting the difference in the process), in which case the difference becomes ''merged'', or -** discard it, thus marking the change as ''discarded''. For example, if there is a conflicting edit of a textual attribute, the user can decide that neither right nor left are satisfying, and instead settle for a mix of the two. -* a ''kind'': this is used by the engine to describe the type of difference it detected. Differences can be of four general types: -** ''Add'': There are two distinct things that EMF Compare considers as an "addition". First, adding a new element within the values of a '''multi-valued feature''' is undeniably an addition. Second, any change in a '''containment reference''', even if that reference is mono-valued, that represents a "new" element in the model is considered to be an addition. Note that this second case is an exception to the rule for ''change'' differences outlined below. -** ''Delete'': this is used as the counterpart of ''add'' differences, and it presents the same exception for '''mono-valued containment references'''. -** ''Change'': any modification to a '''mono-valued feature''' is considered as a ''change'' difference by the engine. Take note that containment references are an exception to this rule: no ''change'' will ever be detected on those. -** ''Move'': once again, two distinct things are represented as ''move'' differences in the comparison model. First, '''reordering''' the values of a multi-valued feature is considered as a series of MOVE: one difference for each moved value (EMF Compare computes the smallest number of differences needed between the two sides' values). Second, moving an object from '''one container to another''' (changing the containing feature of the EObject) will be detected as a ''move''. - -In order to ensure that the model stays coherent through individual merge operations, we've also decided to link differences together through a number of associations and references. For example, there are times when one difference cannot be merged without first merging another, or some differences which are exactly equivalent to one another. In no specific order: - -* ''dependency'': EMF Compare uses two oppposite references in order to track dependencies between differences. Namely, ''requires'' and ''requiredBy'' represent the two ends of this association. If the user has added a package ''P1'', then added a new Class ''C1'' within this package, we will detect both differences. However the addition of ''C1'' cannot be merged without first adding its container ''P1''. In such a case, the addition of ''C1'' '''requires''' the addition of ''P1'', and the later is '''requiredBy''' the former. -* ''refinement'': this link is mainly used by extensions of EMF Compare in order to create high-level differences to hide the complexity of the comparison model. For example, this is used by the UML extension of EMF Compare to tell that the three differences "adding an association ''A1''", "adding a property ''P1'' in association ''A1''" and "adding a property ''P2'' in association ''A1''" is actually one single high-level difference, "adding an association ''A1''". This high-level difference is '''refinedBy''' the others, which all '''refines''' it. -* ''equivalence'': this association is used by the comparison engine in order to link together differences which are equivalent in terms of merging. For example, Ecore has a concept of '''eOpposite''' references. Updating one of the two sides of an ''eOpposite'' will automatically update the other. In such an event, EMF Compare will detect both sides as an individual difference. However, merging one of the two will trigger the update of the other side of the ''eOpposite'' as well. In such cases, the two differences are set to be ''equivalent'' to one another. Merging one difference part of an equivalence relationship will automatically mark all of the others as ''merged'' (see ''state'' above). -* ''implication'': implications are a special kind of "directed equivalence". A difference D1 that is linked as "implied by" another D2 means that merging D1 requires us to merge D1 instead. In other words, D2 will be automatically merged if we merge D1, but D1 will not be automatically merged if we merge D2. Implications are mostly used with UML models, where subsets and supersets may trigger such linked changes. -* ''conflict'': during three-way comparisons, we compare two versions of a given model with their common ancestor. We can thus detect changes that were made in either left or right side (see the description of ''source'' above). However, there are cases when changes in the left conflict with changes in the right. For example, a class named "Book" in the origin model can have been renamed to "Novel" in the left model whereas it has been renamed to "Essay" in the right model. In such a case, the two differences will be marked as being in conflict with one another. - -As mentionned above, there are only three kind of differences that we will detect through EMF Compare, which will be sufficient for all use cases. ''ReferenceChange'' differences will be detected for every value of a reference for which we detect a change. Either the value was added, deleted, or moved (within the reference or between distinct references). ''AttributeChange'' differences are the same, but for attributes instead of references. Lastly, the ''ResourceAttachmentChange'' differences, though very much alike the ReferenceChanges we create for containment references, are specifically aimed at describing changes within the roots of one of the compared resources. - -=== Conflict === - -'''Conflict''' will only be detected during three-way comparisons. There can only be "conflicts" when we are comparing two different versions of a same model along with their common ancestor. In other words, we need to able to compare two versions of a common element with a "reference" version of that element. - -There are many different kinds of conflicts; to name a few: -* changing an element on one side (in any way, for example, renaming it) whilst that element has been removed from the other side -* changing the same attribute of an element on both sides, to different values (for example, renaming "Book" to "Novel" on the left while be renamed "Book" to "Essay" on the right) -* creating a new reference to an element on one side whilst it had been deleted from the other side - -Conflicts can be of two kinds. We call ''PSEUDO'' conflict a conflict where the two sides of a comparison have changed as compared to their common ancestor, but where the two sides are actually now equal. In other words, the end result is that the left is now equal to the right, even though they are both different from their ancestor. This is the opposite of ''REAL'' conflict where the value on all three sides is different. In terms of merging, pseudo conflicts do not need any particular action, whilst real conflicts actually need resolution. - -There can be more than two differences conflicting with each other. For example, the deletion of an element from one side will most likely conflict with a number of differences from the other side. - -=== Equivalence === - -EMF Compare uses '''Equivalence''' elements in order to link together a number of differences which can ultimately be considered to be the same. For example, ecore's ''eOpposite'' references will be maintained in sync with one another. As such, modifying one of the two references will automatically update the second one accordingly. The manual modification and the automatic update are two distinct modifications of the model, resulting in two differences detected. However, merging any of these two differences will automatically merge the other one. Therefore both are marked as being equivalent to each other. - -There can be more than two differences equivalent with each other; in which case all will be added to a single ''Equivalence'' object, representing their relations. diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Core Concepts.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/Core Concepts.html deleted file mode 100644 index 30843c97c..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Core Concepts.html +++ /dev/null @@ -1,53 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Core Concepts</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Core_Concepts">Core Concepts</h1> - <h2 id="Proxy_Resolution">Proxy Resolution</h2> - <p>When cross-referencing objects from another resource, EMF may use proxies instead of the actual object. As long as you do not access the element in question, EMF does not need to load the resource in which it is contained. The proxy is kind of a placeholder that tells EMF what resource should be loaded, and which of this resource's objects referenced, when we actually need to access its value.</p> - <p>Proxy resolution is generally transparent, but a lot of tools based on EMF do not consider these proxies as first-class citizens: they simply resolve it without considering that it might not be needed. On the other hand, EMF Compare will never resolve proxies except for those strictly necessary. Whatever the phase of comparison, we strive to never hold the whole model in memory.</p> - <p>The - <a href="./Default%20Behavior%20and%20Extensibility.html#Model_Resolving" title="./Default%20Behavior%20and%20Extensibility.html#Model Resolving">initial resolution phase</a> is the most intensive in terms of proxy resolution and I/O operations. Though we will never hold the whole logical model in memory at any given time, we do resolve all cross-references of the compared resources, on all sides of the comparison. Since the logical model may be located in a lot of different files on disk, it might also be very heavy in memory if loaded at once. However, even if EMF Compare does resolve all fragments composing that logical model, it also unloads them as soon as the cross-references are registered. In other words, what we create is a dependency graph between the resources, not a loaded model. Afterwards, we only reload in memory those resources that have actually changed, and can thus contain differences. There will be proxies between these "changed" resources and the unchanged ones we have decided not to reload, but EMF Compare will never resolve these proxies again (and, in fact, will prevent their resolving from other tools). - </p> - <p>At the time of writing, the user interface will never resolve any proxies either. This might change in the future for a better user experience since proxies usually end up displayed in strange manners.</p> - <h2 id="Equality_Helper">Equality Helper</h2> - <p>The equality helper is a very central concept of EMF Compare. Of course, EMF Compare's aim is to be able to compare objects together, objects which comparison is not trivial and cannot be done through a mere "equal or not" concept. However, we still need to be able to compare these objects at all time and, whenever possible, without a full-fledged comparison.</p> - <p>The equality helper will be used in all phases of the comparison, from matching to merging (please see the - <a href="./../overview/Overview.html" title="./../overview/Overview.html">overview</a> for a bird's eye view of the different comparison phases, or their detailled descriptions down below). The matching phase is precisely the time when EMF Compare is trying to match two-by-two the elements from one side to the elements from the other side. As such, we do not have -yet- the knowledge of whichi element matches with which other. However, for all subsequent phases, the equality helper will rely on information from the comparison itself (the - <i>Match</i> elements) to make a fail-fast test for element 'equality'. - </p> - <p>When we do not have this information, the equality helper will resort to less optimal algorithms. For any object that is not an EMF EObject, we will use strict equality through - <i>==</i> and - <i>Object#equals()</i> calls. One of the cause for EMF Compare failing to match attribute values together is in fact the lack of implementation of the - <i>equals</i> method on custom datatypes (see the - <a href="./../faq/FAQ.html#Custom_data_types_are_always_marked_as_modified_by_EMF_Compare" title="./../faq/FAQ.html#Custom data types are always marked as modified by EMF Compare">FAQ</a> for more on that particular issue). - </p> - <p>Note that the equality helper will be used extensively, and that any performance hit or improvement here will make a huge difference for the whole comparison process. Likewise, any mistake you make when implementing a custom equality helper will introduce a lot of bugs.</p> - <h2 id="Comparison_Scope">Comparison Scope</h2> - <p>As seen above, EMF Compare consider proxies as real citizens of the EMF realm. This mainly shows in the matching mechanism. EMF Compare uses a scoping mechanism to determine which elements should be matched together, and which others should be ignored. Any element that is outside of the comparison scope will be ignored by the comparison engine and left alone (if it is a proxy, it won't even be loaded). This also means that we won't really have a way to compare these proxy (or otherwise out-of-scope values) when the Diff process encounters them.</p> - <p>For example, an element that is outside of the comparison scope, but referenced by another element which - <i>is</i> in the scope will need specific comparison means: we've ignored it during the matching phase, so we don't know which 'out-of-scope' element corresponds to which 'other out-of-scope' element. Consider the following: in the first model, a package - <i>P1</i> contains another package - <i>P2</i>. In the right, a package - <i>P1' '' contains a package ''P2' ''. We've told EMF Compare that ''P2</i> and - <i>P2' '' are out of the comparison scope. Now how do we determine that the reference from ''P1</i> to - <i>P2</i> has changed (or, in this example, that it did not change)? - </p> - <p>This is a special case that is handled by the IEqualityHelper. Specifically, when such cases are encountered, EMF Compare falls back to using the URI of the two objects to check for equality. This behavior can be changed by customizing the IEqualityHelper (see - <a href="Core%20Concepts.html#Equality_Helper">above</a>). - </p> - <p>By default, the only thing that EMF Compare considers "out of scope" are Ecore's "EGenericType" elements. These are usually meaningless as far as comparison is concerned (as they are located in derived references and will be merged along with their "true" difference anyway). Please take note that, when used from the user interface, EMF Compare will narrow down the scope even further through the resolution of the - <a href="./Logical%20Model.html" title="./Logical%20Model.html">logical model</a> and determining which resources are actually candidates for differences. - </p> - <p>The comparison scope provides EMF Compare with information on the content of ResourceSets, Resources or EObjects, according to the entry point of the comparison. Take note that - <b>the scope is only used during the matching phase</b>. The differencing phase only uses the result of the matching phase to proceed. - </p> - <h2 id="Longest_Common_Subsequence">Longest Common Subsequence</h2> - <p>PENDING description of the algorithm, why do we use it, references</p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Core Concepts.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/developer/Core Concepts.mediawiki deleted file mode 100644 index 29e3d0024..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Core Concepts.mediawiki +++ /dev/null @@ -1,37 +0,0 @@ -= Core Concepts = - -== Proxy Resolution == - -When cross-referencing objects from another resource, EMF may use proxies instead of the actual object. As long as you do not access the element in question, EMF does not need to load the resource in which it is contained. The proxy is kind of a placeholder that tells EMF what resource should be loaded, and which of this resource's objects referenced, when we actually need to access its value. - -Proxy resolution is generally transparent, but a lot of tools based on EMF do not consider these proxies as first-class citizens: they simply resolve it without considering that it might not be needed. On the other hand, EMF Compare will never resolve proxies except for those strictly necessary. Whatever the phase of comparison, we strive to never hold the whole model in memory. - -The [[./Default%20Behavior%20and%20Extensibility.html#Model Resolving|initial resolution phase]] is the most intensive in terms of proxy resolution and I/O operations. Though we will never hold the whole logical model in memory at any given time, we do resolve all cross-references of the compared resources, on all sides of the comparison. Since the logical model may be located in a lot of different files on disk, it might also be very heavy in memory if loaded at once. However, even if EMF Compare does resolve all fragments composing that logical model, it also unloads them as soon as the cross-references are registered. In other words, what we create is a dependency graph between the resources, not a loaded model. Afterwards, we only reload in memory those resources that have actually changed, and can thus contain differences. There will be proxies between these "changed" resources and the unchanged ones we have decided not to reload, but EMF Compare will never resolve these proxies again (and, in fact, will prevent their resolving from other tools). - -At the time of writing, the user interface will never resolve any proxies either. This might change in the future for a better user experience since proxies usually end up displayed in strange manners. - -== Equality Helper == - -The equality helper is a very central concept of EMF Compare. Of course, EMF Compare's aim is to be able to compare objects together, objects which comparison is not trivial and cannot be done through a mere "equal or not" concept. However, we still need to be able to compare these objects at all time and, whenever possible, without a full-fledged comparison. - -The equality helper will be used in all phases of the comparison, from matching to merging (please see the [[./../overview/Overview.html|overview]] for a bird's eye view of the different comparison phases, or their detailled descriptions down below). The matching phase is precisely the time when EMF Compare is trying to match two-by-two the elements from one side to the elements from the other side. As such, we do not have -yet- the knowledge of whichi element matches with which other. However, for all subsequent phases, the equality helper will rely on information from the comparison itself (the ''Match'' elements) to make a fail-fast test for element 'equality'. - -When we do not have this information, the equality helper will resort to less optimal algorithms. For any object that is not an EMF EObject, we will use strict equality through ''=='' and ''Object#equals()'' calls. One of the cause for EMF Compare failing to match attribute values together is in fact the lack of implementation of the ''equals'' method on custom datatypes (see the [[./../faq/FAQ.html#Custom data types are always marked as modified by EMF Compare|FAQ]] for more on that particular issue). - -Note that the equality helper will be used extensively, and that any performance hit or improvement here will make a huge difference for the whole comparison process. Likewise, any mistake you make when implementing a custom equality helper will introduce a lot of bugs. - -== Comparison Scope == - -As seen above, EMF Compare consider proxies as real citizens of the EMF realm. This mainly shows in the matching mechanism. EMF Compare uses a scoping mechanism to determine which elements should be matched together, and which others should be ignored. Any element that is outside of the comparison scope will be ignored by the comparison engine and left alone (if it is a proxy, it won't even be loaded). This also means that we won't really have a way to compare these proxy (or otherwise out-of-scope values) when the Diff process encounters them. - -For example, an element that is outside of the comparison scope, but referenced by another element which ''is'' in the scope will need specific comparison means: we've ignored it during the matching phase, so we don't know which 'out-of-scope' element corresponds to which 'other out-of-scope' element. Consider the following: in the first model, a package ''P1'' contains another package ''P2''. In the right, a package ''P1' '' contains a package ''P2' ''. We've told EMF Compare that ''P2'' and ''P2' '' are out of the comparison scope. Now how do we determine that the reference from ''P1'' to ''P2'' has changed (or, in this example, that it did not change)? - -This is a special case that is handled by the IEqualityHelper. Specifically, when such cases are encountered, EMF Compare falls back to using the URI of the two objects to check for equality. This behavior can be changed by customizing the IEqualityHelper (see [[#Equality Helper|above]]). - -By default, the only thing that EMF Compare considers "out of scope" are Ecore's "EGenericType" elements. These are usually meaningless as far as comparison is concerned (as they are located in derived references and will be merged along with their "true" difference anyway). Please take note that, when used from the user interface, EMF Compare will narrow down the scope even further through the resolution of the [[./Logical%20Model.html|logical model]] and determining which resources are actually candidates for differences. - -The comparison scope provides EMF Compare with information on the content of ResourceSets, Resources or EObjects, according to the entry point of the comparison. Take note that '''the scope is only used during the matching phase'''. The differencing phase only uses the result of the matching phase to proceed. - -== Longest Common Subsequence == - -PENDING description of the algorithm, why do we use it, references diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Default Behavior and Extensibility.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/Default Behavior and Extensibility.html deleted file mode 100644 index 07a1a5181..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Default Behavior and Extensibility.html +++ /dev/null @@ -1,375 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Default Behavior and Extensibility</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Default_Behavior_and_Extensibility">Default Behavior and Extensibility</h1> - <p>All main components of EMF Compare have been designed for extensibility. Some are only extensible when comparing models through your own actions, some can be customized globally for a given kind of model or metamodel... We'll outline the customization options of all 6 comparison phases in this section. (Any dead link? Report them on the - <a href="http://www.eclipse.org/forums/index.php/f/164/">forum</a>!) - </p> - <h2 id="Model_Resolving">Model Resolving</h2> - <p>PENDING description of the phase, extensibility (use of the modelProviders extension point, custom ext point of compare)</p> - <h2 id="Match">Match</h2> - <p>Before we can compute differences between two versions of a same Object, we must determine which are actually the "same" Object. For example, let's consider that my first model contains a Package P1 which itself contains a class C1; and that my second model contains a package P1 which contains a class C1. It may seem obvious for a human reader that "P1" and "C1" are the same object in both models. However, since their features might have changed in-between the two versions (for example, the "C1" might now be abstract, or it could have been converted to an Interface), this "equality" is not that obvious for a computer.</p> - <p>The goal of the "Match" phase is to discover which of the objects from model 2 match with which objects of model 1. In other words, this is when we'll say that two objects are one and the same, and that any difference between the two sides of this couple is actually a difference that should be reported as such to the user.</p> - <p>By default, EMF Compare browses through elements that are within the scope, and matches them through their identifier if they have one, r through a distance mechanism for all elements that have none. If the scope contains resources, EMF Compare will first match those two-by-two before browsing through all of their contained objects.</p> - <p>EMF Compare "finds" the identifier of given object through a basic function that can be found in - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/eobject/IdentifierEObjectMatcher.java#n268">IdentifierEObjectMatcher.DefaultIDFunction</a>. In short, if the object is a proxy, its identifier is its URI fragment. Otherwise its functional ID (in ecore, an attribute that serves as an identifier) takes precedence over its XMI ID (the identifier it was given in the XMI file). If the object is not a proxy and has neither functional nor XMI identifier, then the default behavior will simply pass that object over to the proximity algorithms so that it can be matched through its distance with other objects. - </p> - <p>PENDING: brief description of the proximity algorithm</p> - <p>This behavior can be customized in a number of ways.</p> - <h3 id="Overriding_the_Match_engine">Overriding the Match engine</h3> - <p>The most powerful (albeit most cumbersome) customization you can implement is to override the match engine EMF Compare uses. To this end you can either [ - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/IMatchEngine.java">http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/IMatchEngine.java</a> implement the whole contract, - <i>IMatchEngine</i>], in which case you will have to carefully follow the javadoc's recommandations, or extend the [ - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java">http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java</a> default implementation, - <i>DefaultMatchEngine</i>]. - </p> - <p>A custom match engine can be used for your model comparison needs:</p> - <pre class="source-java">// for standalone usage -IMatchEngine.Factory.Registry registry = MatchEngineFactoryRegistryImpl.createStandaloneInstance(); -// for OSGi (IDE, RCP) usage -// IMatchEngine.Factory.Registry registry = EMFCompareRCPPlugin.getMatchEngineFactoryRegistry(); -final IMatchEngine customMatchEngine = new MyMatchEngine(...); -IMatchEngine.Factory engineFactory = new MatchEngineFactoryImpl() { - public IMatchEngine getMatchEngine() { - return customMatchEngine; - } -}; -engineFactory.setRanking(20); // default engine ranking is 10, must be higher to override. -registry.add(engineFactory); -EMFCompare.builder().setMatchEngineFactoryRegistry(registry).build().compare(scope); - -</pre> - <h3 id="Changing_how_resources_are_matched">Changing how resources are matched</h3> - <p>By default, the logic EMF Compare uses to match resources together is very simple: if two resources have the same name (strict equality on the name, without considering folders), they match. When this is not sufficient, EMF Compare will look at the XMI ID of the resources' root(s). If the two resources share at least one root with an equal XMI ID, they match.</p> - <p>This can be changed only by implementing your own subclass of the DefaultMatchEngine and overriding its resource matcher. The method of interest here is - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java#n319">DefaultMatchEngine#createResourceMatcher()</a>. - </p> - <h3 id="Defining_custom_identifiers">Defining custom identifiers</h3> - <p>In some cases, there might be ways to identify your objects via the use of "identifiers" that cannot be identified as such by the default mechanism. For example, you might want each of your objects to be matched through their name alone, or through the composition of their name and their type... This can be achieved through code by simply redefining the function EMF Compare uses to find the ID of an object. The following code will tell EMF Compare that the identifier of all "MyEObject" elements is their name, and that any other element should go through the default behavior.</p> - <pre class="source-java">Function<EObject, String> idFunction = new Function<EObject, String>() { - public String apply(EObject input) { - if (input instanceof MyEObject) { - return ((MyEObject)input).getName(); - } - // a null return here tells the match engine to fall back to the other matchers - return null; - } -}; -// Using this matcher as fall back, EMF Compare will still search for XMI IDs on EObjects -// for which we had no custom id function. -IEObjectMatcher fallBackMatcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.WHEN_AVAILABLE); -IEObjectMatcher customIDMatcher = new IdentifierEObjectMatcher(fallBackMatcher, idFunction); - -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - -IMatchEngine matchEngine = new DefaultMatchEngine(customIDMatcher, comparisonFactory); -IMatchEngine.Factory.Registry registry = MatchEngineFactoryRegistryImpl.createStandaloneInstance(); -// for OSGi (IDE, RCP) usage -// IMatchEngine.Factory.Registry registry = EMFCompareRCPPlugin.getMatchEngineFactoryRegistry(); -engineFactory.setRanking(20); // default engine ranking is 10, must be higher to override. -registry.add(engineFactory); -EMFCompare.builder().setMatchEngineFactoryRegistry(registry).build().compare(scope); - -</pre> - <h3 id="Ignoring_identifiers">Ignoring identifiers</h3> - <p>There are some cases where you do not want the identifiers of your elements to be taken into account when matching the objects. This can easily be done when calling for comparisons programmatically:</p> - <p> - <b>Through code</b> - </p> - <pre class="source-java">IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - -IMatchEngine matchEngine = new DefaultMatchEngine(matcher , comparisonFactory); -EMFCompare.builder().setMatchEngine(matchEngine).build().compare(scope); - -</pre> - <p> - <b>From the user interface</b> - </p> - <p>PENDING: preference page</p> - <h3 id="Refine_the_default_Match_result">Refine the default Match result</h3> - <p>If you are happy with most of what the default behavior does, but would like to refine some of it, you can do so by post-processing the result of the match phase. The original models are only used when matching, and will never be queried again afterwards. All remaining phases are incremental refinings of the "Comparison" model that's been created by the matching phase.</p> - <p>As such, you can impact all of the differencing process through this. Within this post-processing implementation, you can:</p> - <ul> - <li>Remove - <i>Match</i> elementsno difference will be detected on those: neither additions, nor deletions, nor conflicts... They'll simply be entirely ignored by the remaining process. Do note that elements for which we have no match will be considered "distinct" by the innards of EMF Compare: if a couple "B<->B'" references a couple "C<->C'" through one of their references, but you have removed the - <i>Match</i> "C<->C'", we will consider that this reference has been "changed" from C to C' and this difference within the references of B will be shown as such. - </li> - <li>Add new - <i>Match</i> elementthe new couples of elements will be considered by the remaining comparison process and difference may be detected on them. - </li> - <li>Change existing - <i>Match</i> elementsunmatched elements have two or three associated - <i>Match</i> objects. For example if you are comparing three version of a model which all contain a different version of a given package, and all three version change the name of this package: version 1 has package "P1", version 2 has package "P2" and version three has package "P3". This package is actually the same, but EMF Compare did not manage to match it. We will thus have three - <i>Match</i> objects: one that references "P1" as - <i>left</i>, one that references "P2" as - <i>right</i> and one that references "P3" as - <i>origin</i>.You may remove two of those three elements and change the third one so that it references P1 as - <i>left</i>, P2 as - <i>right</i> and P3 as - <i>origin</i>. In such a case, those three will be considered to Match for the remainder of the comparison process. Make sure that there are not two different - <i>Match</i> referencing the same object though, as this would yield unspecified results. - </li> - </ul> - <p>Defining a custom post-processor requires you to implement - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/postprocessor/IPostProcessor.java">IPostProcessor</a> and registering this sub-class against EMF Compare. The latter can be done via either an extension point, in which case it will be considered for - <b>all</b> comparisons on models that match its enablement, or programmatically if you only want it active for your own actions: - </p> - <p> - <b>Through code</b> - </p> - <p>The following registers a post-processor for all UML models. This post-processor will not be triggered if there are no UML models (matching the given namespace URI) within the compared scope.</p> - <pre class="source-java">IPostProcessor customPostProcessor = new CustomPostProcessor(); -IPostProcessor.Descriptor descriptor = new BasicPostProcessorDescriptorImpl(customPostProcessor, Pattern.compile("http://www.eclipse.org/uml2/\\d\\.0\\.0/UML"), null); - -PostProcessor.Registry registry = new PostProcessorDescriptorRegistryImpl(); -registry.put(CustomPostProcessor.class.getName(), descriptor); -Comparison comparison = EMFCompare.builder().setPostProcessorRegistry(registry).build().compare(scope); - -</pre> - <p> - <b>Through extension point</b> - </p> - <p>This accomplishes the exact same task, but it registers the post-processor globally. Any comparison through EMF Compare on a scope that contains models matching the given namespace URI will trigger that post-processor.</p> - <pre class="source-xml"><extension point="org.eclipse.emf.compare.rcp.postProcessor"> - <postProcessor class="my.package.CustomPostProcessor"> - <nsURI value="http://www.eclipse.org/uml2/\\d\\.0\\.0/UML"> - </nsURI> - </postProcessor> - -</pre> - <h2 id="Diff">Diff</h2> - <p>Now that the Matching phase has completed and that we know how our objects are coupled together, EMF Compare no longer requires the two (or three) input models. It will no longer iterate over them or the comparison's input scope. From this point onward, only the result of our comparison, the - <i>Comparison</i> object, will be refined through the successive remaining phases, starting by the - <b>Diff</b>. - </p> - <p>The goal of this phase is to iterate over all of our - <i>Match</i> elements, be they unmatched (only one side has this object), couples (two of the three sides contain this object) or trios (all three sides have this object) and compute any difference that may appear between the sides. For example, an object that is only on one side of the comparison is an object that has been added, or deleted. But a couple might also represent a deletion: during three way comparisons, if we have an object in the common ancestor (origin) and in the left side, but not in the right side, then it has been deleted from the right version. However, this latter example might also be a conflict: we have determined that the object has been removed from the right side... but there might also be differences between the original version and the "left" version. - </p> - <p>The differencing phase does not care about conflicts though: all it does is refine the comparison to tell that this particular - <i>Match</i> has - <i>n</i> diffs: one - <i>DELETE</i> difference on the right side, and - <i>n</i> differences on the left. Detecting conflicts between these differences will come at a later time, during the conflict resolution phase. - </p> - <p>Customizations of this phase usually aim at ignoring specific differences.</p> - <h3 id="Overriding_the_Diff_engine">Overriding the Diff engine</h3> - <p>As is the case for the Match phase, the most powerful customization you can implement for the differencing process is to override the diff engine EMF Compare uses. To this end you can either [ - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffEngine.java">http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffEngine.java</a> implement the whole contract, - <i>IDiffEngine</i>], in which case you will have to carefully follow the javadoc's recommandations, or extend the [ - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DefaultDiffEngine.java">http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DefaultDiffEngine.java</a> default implementation, - <i>DefaultDiffEngine</i>]. - </p> - <p>A custom diff engine can then be used for your comparisons:</p> - <pre class="source-java">IDiffEngine customDiffEngine = new MyDiffEngine(...); -EMFCompare.builder().setDiffEngine(customDiffEngine).build().compare(scope); - -</pre> - <h3 id="Changing_the_FeatureFilter">Changing the FeatureFilter</h3> - <p>One of the differencing engine's responsibilities is to iterate over all features of a given object in order to check for potential differences on its value(s). However, there are some features that we decide do ignore by default: derived features, transient features... or some features on which we would like to check for ordering changes even though they are marked as non-ordered.</p> - <p>The logic to determine whether a feature should be checked for differences has been extracted into its own class, and is quite easy to alter. For example, if you would like to ignore the - <i>name</i> feature of your elements or never detect any ordering change: - </p> - <pre class="source-java">IDiffProcessor diffProcessor = new DiffBuilder(); -IDiffEngine diffEngine = new DefaultDiffEngine(diffProcessor) { - @Override - protected FeatureFilter createFeatureFilter() { - return new FeatureFilter() { - @Override - protected boolean isIgnoredReference(Match match, EReference reference) { - return reference == EcorePackage.Literals.ENAMED_ELEMENT__NAME || - super.isIgnoredReference(match, reference); - } - - @Override - public boolean checkForOrderingChanges(EStructuralFeature feature) { - return false; - } - }; - } -}; -EMFCompare.builder().setDiffEngine(diffEngine).build().compare(scope); - -</pre> - <p>You could also - <a href="Default%20Behavior%20and%20Extensibility.html#Changing_the_Diff_Processor">change the diff processor</a> to achieve a similar goal. The difference between the two approaches is that changing the - <i>FeatureFilter</i> will ignore the structural feature altogether, whereas replacing the diff processor would let EMF Compare check the feature and detect that diff, but ignore the notification that there is a change. - </p> - <h3 id="Changing_the_Diff_Processor">Changing the Diff Processor</h3> - <p>The diff engine browses over all of the objects that have been matched, and checks all of their features in order to check for changes between the two (or three) versions' feature values. When it detects a change, it delegates all of the corresponding information to its associated - <i>Diff Processor</i>, which is in charge of actually creating the - <i>Diff</i> object and appending it to the resulting - <i>Comparison</i>. - </p> - <p>Replacing the - <i>Diff Processor</i> gives you a simple entry point to ignore some of the differences the default engine detects, or to slightly alter the - <i>Diff</i> information. You might want to ignore the differences detected on some references for example. Or you might want to react to the detected diff without actually creating the - <i>Comparison</i> model... The implementation is up to you. You can either reimplement the - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffProcessor.java">whole contract</a> or extend the default implementation, [ - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DiffBuilder.java">http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DiffBuilder.java</a> - <i>DiffBuilder</i>] - </p> - <p>Here is a simple example that provides EMF Compare with a diff processor that will ignore all differences detected on the "name" attribute of our objects, yet keep the default behavior for all other differences.</p> - <pre class="source-java">IDiffProcessor customDiffProcessor = new DiffBuilder() { - @Override - public void attributeChange(Match match, EAttribute attribute, Object value, DifferenceKind kind, DifferenceSource source) { - if (attribute != EcorePackage.Literals.ENAMED_ELEMENT__NAME) { - super.attributeChange(match, attribute, value, kind, source); - } - } -}; - -IDiffEngine diffEngine = new DefaultDiffEngine(customDiffProcessor); -EMFCompare.builder().setDiffEngine(diffEngine).build().compare(scope); - -</pre> - <h3 id="Refine_the_default_Diff_result">Refine the default Diff result</h3> - <p>The last possibility offered by EMF Compare to alter the result of the differencing phase is to post-process it. The remaining comparison phases -equivalence detection, detection of dependencies between diffs and conflict detection- all use the result of the Diff engine and refine it even further. As such, all of these phases can be impacted through the refining of the Diff result.</p> - <p>Example uses of the post-processing would include:</p> - <ul> - <li>Remove - <i>Diff</i> elementsIf you'd rather code your logic to ignore differences here as a post-process instead of changing the - <i>FeatureFilter</i> or - <i>IDiffProcessor</i>. Though that is not the best way to ignore differences, it can still be done here. - </li> - </ul> - <ul> - <li>Add new - <i>Diff</i> elementsIf you want to create new differences without implementing a whole differencing engine, new differences can still be created here as a post-process. You will need to implement the iteration over model elements and specific checks yourself though. This workaround can also be used to create new differences that the default differencing engine does not know. - </li> - </ul> - <ul> - <li>Alter the detected differencesIf some of the differences have been detected in a way you do not like, and you did not use a custom - <i>IDiffProcessor</i> to change the - <i>Diff</i> information, you can do so here. - </li> - </ul> - <p>The post-processor for the diff engine is implemented exactly in the same way as for the match engine post-processors (the interface and extension point are the same). Please refer to - <a href="Default%20Behavior%20and%20Extensibility.html#Refine_the_default_Match_result">Refining the Match result</a>. - </p> - <h2 id="Equivalences">Equivalences</h2> - <p>Now that the Differencing phase has ended, we've computed all of the individual differences within the compared models. However, all of these differences are still isolated, we now need to determine if there are any connections between them.</p> - <p>An - <i>equivalence</i> is one kind of potential connections between differences. For example, Ecore has a concept of - <i>eOpposite</i> references, which be maintained in sync with one another. Modifying one of the two references will automatically update the other side of the opposition accordingly. Both the manual modification and the automatic update are considered as distinct modifications of the model when looking at it after the fact, resulting in two differences detected. However, merging any of these two differences will automatically merge the other one. Therefore, both are marked as being - <i>equivalent</i> to each other. - </p> - <p>Though that is an example with two, more than two differences can be considered equivalent with each other. When we merge one difference, all of the other diffs that have been marked as being equivalent to it will be marked as - <i>MERGED</i>, though no actual work needs to be done to merge them : EMF will have automatically updated them when merging the first. - </p> - <p>Do note that EMF Compare detects and understand two different kind of relations that could be considered "equivalences". Described above are plain equivalences, when merging one of the differences will automatically update the model in such a way that all other sides of the equivalence are redundant and automatically merged. However, equivalences might not always be that easy. Let's take for example the case of UML : UML has concepts of - <i>subset</i> and - <i>superset</i> references. Adding an object into a subset will automatically update the related superset so that it also contains the added element. However, adding that same element to the superset will _not_ automatically update the related subset. - </p> - <p>This can be seen as a "directional" equivalence, where one difference D1 - <i>implies</i> another D2, but is not - <i>implied by</i> D2. Implications will be detected at the same time as the equivalences, but they do not use an - <i>Equivalence</i> element, they are filled under the - <i>Diff#implies</i> reference instead. - </p> - <h3 id="Refine_the_default_equivalences">Refine the default equivalences</h3> - <p>This phase does not offer as many customization options as the previous ones; though post-processing should be enough for most needs. All of the phases that come after the differencing are further refinements of the comparison model, totally independent from one another. From here, any client of the API can refine the comparison model any way he'd like to, even by removing all of the default results.</p> - <p>A few examples of customizations that could be made from here :</p> - <ul> - <li>Partly break existing equivalencesYou can modify the equivalences we've detected by default by removing elements from individual differences' equivalences (Diff#getEquivalence()) or by changing the - <i>Equivalence</i> elements directly. - </li> - <li>Remove existing - <i>Equivalence</i> elementsIf you'd rather remove the - <i>Equivalence</i> elements altogether, it can also be done from here without impact down the line. The individual differences will be merged individually (potentially twice if EMF automatically updates the references) if the mergers do not have this to tell them what's equivalent to what. - </li> - <li>Detect your own equivalencesIf you have specific rules on your metamodel or implementation that make some differences redundant or otherwise fully equivalent to one another, you can add your own equivalences from here.</li> - </ul> - <p>The post-processor for the equivalence detection engine is implemented exactly in the same way as for the match engine post-processors (the interface and extension point are the same). Please refer to - <a href="Refine_the_default_Match_result" title="Refine the default Match result">Refining the Match result</a>. - </p> - <h2 id="Requirements">Requirements</h2> - <p>A requirement will be used to deal with structural constraints (to prevent dangling references or objects without parent) and to insure the model integrity. - A difference requires other ones if the merge of this one needs the other ones not to "break" the model. - The merge of a difference involves the merge of the required differences. All these differences will be merged by EMF Compare. - For example, the add of a reference requires the add of the referenced object and the add of the object containing this reference.</p> - <table border="1" cellpadding="1" cellspacing="1"> - <tr> - <th align="center">Change kind</th> - <th align="center">Reference kind to a graphical object</th> - <th align="left"> Requires:</th> - </tr> - <tr> - <td align="center" rowspan="2">ADD</td> - <td align="center">content</td> - <td> ADD of its container - <br/> DELETE of the origin value on the same containment mono-valued reference - </td> - </tr> - <tr> - <td align="center">reference</td> - <td> ADD of the target object - <br/> ADD of the source object e.g. The ADD of a reference to the target or source of an edge requires the ADD of the edge itself and the ADD of the target and source objects, the ADD of a reference to the semantic object from a graphical one requires the ADD of the graphical and semantic object. - </td> - </tr> - <tr> - <td align="center">DELETE</td> - <td align="center">content</td> - <td> DELETE of the outgoing references and contained objects - <br/> DELETE/CHANGE of the incoming references - <br/> MOVE of the contained objects - </td> - </tr> - <tr> - <td align="center">MOVE</td> - <td align="center">content</td> - <td> ADD of the new container of the object - <br/> MOVE of the new container of the object - </td> - </tr> - <tr> - <td align="center">CHANGE</td> - <td align="center">reference permutation</td> - <td> ADD of the target object</td> - </tr> - </table> - <p>Requirements can be added during a post-process.</p> - <h2 id="Refinement">Refinement</h2> - <p>A refinement enables to group a set of unit differences into a macroscopic change. - - <br/>A unit difference refines a macroscopic one if it belongs to this macroscopic change. In other words, a macroscopic change is refined by a set of unit differences. - - <br/>The merge of a macroscopic change involves the merge of the refining differences. All these differences will be merged by EMF Compare. - - <br/>The use of the refinement allows to improve (simplify) the reading of the comparison from a business viewpoint, to accelerate the manual merging for the end-user and to insure some consistency. - - <br/>For example, the add of an association, in UML, is refined by the add of the UML Association itself but also the add of the UML properties with the update of references... - </p> - <p>Refinement can be added during a post-process.</p> - <h2 id="Conflicts">Conflicts</h2> - <p>PENDING description of the phase, extensibility options (post-process)</p> - <h2 id="Merging">Merging</h2> - <h3 id="Which_references_are_followed_during_merging">Which references are followed during merging</h3> - <table border="1"> - <tr> - <th> </th> - <th>Merge from Left to Right</th> - <th>Merge from Right to Left</th> - </tr> - <tr> - <th>Source = Left</th> - <td align="center">requires </td> - <td align="center">requiredBy </td> - </tr> - <tr> - <th>Source = Right</th> - <td align="center">requiredBy </td> - <td align="center">requires </td> - </tr> - </table> - <p>PENDING how to provide custom mergers, override existing ones?</p> - <h2 id="User_Interface">User Interface</h2> - <p>PENDING customize display of custom differences, add custom menu entries, add groups, add filters, add export options, provide custom content viewer</p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Default Behavior and Extensibility.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/developer/Default Behavior and Extensibility.mediawiki deleted file mode 100644 index ce48a4a91..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Default Behavior and Extensibility.mediawiki +++ /dev/null @@ -1,329 +0,0 @@ -= Default Behavior and Extensibility = - -All main components of EMF Compare have been designed for extensibility. Some are only extensible when comparing models through your own actions, some can be customized globally for a given kind of model or metamodel... We'll outline the customization options of all 6 comparison phases in this section. (Any dead link? Report them on the [http://www.eclipse.org/forums/index.php/f/164/ forum]!) - -== Model Resolving == - -PENDING description of the phase, extensibility (use of the modelProviders extension point, custom ext point of compare) - -== Match == - -Before we can compute differences between two versions of a same Object, we must determine which are actually the "same" Object. For example, let's consider that my first model contains a Package P1 which itself contains a class C1; and that my second model contains a package P1 which contains a class C1. It may seem obvious for a human reader that "P1" and "C1" are the same object in both models. However, since their features might have changed in-between the two versions (for example, the "C1" might now be abstract, or it could have been converted to an Interface), this "equality" is not that obvious for a computer. - -The goal of the "Match" phase is to discover which of the objects from model 2 match with which objects of model 1. In other words, this is when we'll say that two objects are one and the same, and that any difference between the two sides of this couple is actually a difference that should be reported as such to the user. - -By default, EMF Compare browses through elements that are within the scope, and matches them through their identifier if they have one, r through a distance mechanism for all elements that have none. If the scope contains resources, EMF Compare will first match those two-by-two before browsing through all of their contained objects. - -EMF Compare "finds" the identifier of given object through a basic function that can be found in [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/eobject/IdentifierEObjectMatcher.java#n268 IdentifierEObjectMatcher.DefaultIDFunction]. In short, if the object is a proxy, its identifier is its URI fragment. Otherwise its functional ID (in ecore, an attribute that serves as an identifier) takes precedence over its XMI ID (the identifier it was given in the XMI file). If the object is not a proxy and has neither functional nor XMI identifier, then the default behavior will simply pass that object over to the proximity algorithms so that it can be matched through its distance with other objects. - -PENDING: brief description of the proximity algorithm - -This behavior can be customized in a number of ways. - -=== Overriding the Match engine === - -The most powerful (albeit most cumbersome) customization you can implement is to override the match engine EMF Compare uses. To this end you can either [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/IMatchEngine.java implement the whole contract, ''IMatchEngine''], in which case you will have to carefully follow the javadoc's recommandations, or extend the [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java default implementation, ''DefaultMatchEngine'']. - -A custom match engine can be used for your model comparison needs: - -<source lang="java"> -// for standalone usage -IMatchEngine.Factory.Registry registry = MatchEngineFactoryRegistryImpl.createStandaloneInstance(); -// for OSGi (IDE, RCP) usage -// IMatchEngine.Factory.Registry registry = EMFCompareRCPPlugin.getMatchEngineFactoryRegistry(); -final IMatchEngine customMatchEngine = new MyMatchEngine(...); -IMatchEngine.Factory engineFactory = new MatchEngineFactoryImpl() { - public IMatchEngine getMatchEngine() { - return customMatchEngine; - } -}; -engineFactory.setRanking(20); // default engine ranking is 10, must be higher to override. -registry.add(engineFactory); -EMFCompare.builder().setMatchEngineFactoryRegistry(registry).build().compare(scope); -</source> - -=== Changing how resources are matched === - -By default, the logic EMF Compare uses to match resources together is very simple: if two resources have the same name (strict equality on the name, without considering folders), they match. When this is not sufficient, EMF Compare will look at the XMI ID of the resources' root(s). If the two resources share at least one root with an equal XMI ID, they match. - -This can be changed only by implementing your own subclass of the DefaultMatchEngine and overriding its resource matcher. The method of interest here is [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java#n319 DefaultMatchEngine#createResourceMatcher()]. - -=== Defining custom identifiers === - -In some cases, there might be ways to identify your objects via the use of "identifiers" that cannot be identified as such by the default mechanism. For example, you might want each of your objects to be matched through their name alone, or through the composition of their name and their type... This can be achieved through code by simply redefining the function EMF Compare uses to find the ID of an object. The following code will tell EMF Compare that the identifier of all "MyEObject" elements is their name, and that any other element should go through the default behavior. - -<source lang="java"> -Function<EObject, String> idFunction = new Function<EObject, String>() { - public String apply(EObject input) { - if (input instanceof MyEObject) { - return ((MyEObject)input).getName(); - } - // a null return here tells the match engine to fall back to the other matchers - return null; - } -}; -// Using this matcher as fall back, EMF Compare will still search for XMI IDs on EObjects -// for which we had no custom id function. -IEObjectMatcher fallBackMatcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.WHEN_AVAILABLE); -IEObjectMatcher customIDMatcher = new IdentifierEObjectMatcher(fallBackMatcher, idFunction); - -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - -IMatchEngine matchEngine = new DefaultMatchEngine(customIDMatcher, comparisonFactory); -IMatchEngine.Factory.Registry registry = MatchEngineFactoryRegistryImpl.createStandaloneInstance(); -// for OSGi (IDE, RCP) usage -// IMatchEngine.Factory.Registry registry = EMFCompareRCPPlugin.getMatchEngineFactoryRegistry(); -engineFactory.setRanking(20); // default engine ranking is 10, must be higher to override. -registry.add(engineFactory); -EMFCompare.builder().setMatchEngineFactoryRegistry(registry).build().compare(scope); -</source> - -=== Ignoring identifiers === - -There are some cases where you do not want the identifiers of your elements to be taken into account when matching the objects. This can easily be done when calling for comparisons programmatically: - -'''Through code''' - -<source lang="java"> -IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - -IMatchEngine matchEngine = new DefaultMatchEngine(matcher , comparisonFactory); -EMFCompare.builder().setMatchEngine(matchEngine).build().compare(scope); -</source> - -'''From the user interface''' - -PENDING: preference page - -=== Refine the default Match result === - -If you are happy with most of what the default behavior does, but would like to refine some of it, you can do so by post-processing the result of the match phase. The original models are only used when matching, and will never be queried again afterwards. All remaining phases are incremental refinings of the "Comparison" model that's been created by the matching phase. - -As such, you can impact all of the differencing process through this. Within this post-processing implementation, you can: -* Remove ''Match'' elements -: no difference will be detected on those: neither additions, nor deletions, nor conflicts... They'll simply be entirely ignored by the remaining process. Do note that elements for which we have no match will be considered "distinct" by the innards of EMF Compare: if a couple "B<->B'" references a couple "C<->C'" through one of their references, but you have removed the ''Match'' "C<->C'", we will consider that this reference has been "changed" from C to C' and this difference within the references of B will be shown as such. -* Add new ''Match'' element -: the new couples of elements will be considered by the remaining comparison process and difference may be detected on them. -* Change existing ''Match'' elements -: unmatched elements have two or three associated ''Match'' objects. For example if you are comparing three version of a model which all contain a different version of a given package, and all three version change the name of this package: version 1 has package "P1", version 2 has package "P2" and version three has package "P3". This package is actually the same, but EMF Compare did not manage to match it. We will thus have three ''Match'' objects: one that references "P1" as ''left'', one that references "P2" as ''right'' and one that references "P3" as ''origin''. -: You may remove two of those three elements and change the third one so that it references P1 as ''left'', P2 as ''right'' and P3 as ''origin''. In such a case, those three will be considered to Match for the remainder of the comparison process. Make sure that there are not two different ''Match'' referencing the same object though, as this would yield unspecified results. - -Defining a custom post-processor requires you to implement [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/postprocessor/IPostProcessor.java IPostProcessor] and registering this sub-class against EMF Compare. The latter can be done via either an extension point, in which case it will be considered for '''all''' comparisons on models that match its enablement, or programmatically if you only want it active for your own actions: - -'''Through code''' - -The following registers a post-processor for all UML models. This post-processor will not be triggered if there are no UML models (matching the given namespace URI) within the compared scope. - -<source lang="java"> -IPostProcessor customPostProcessor = new CustomPostProcessor(); -IPostProcessor.Descriptor descriptor = new BasicPostProcessorDescriptorImpl(customPostProcessor, Pattern.compile("http://www.eclipse.org/uml2/\\d\\.0\\.0/UML"), null); - -PostProcessor.Registry registry = new PostProcessorDescriptorRegistryImpl(); -registry.put(CustomPostProcessor.class.getName(), descriptor); -Comparison comparison = EMFCompare.builder().setPostProcessorRegistry(registry).build().compare(scope); -</source> - -'''Through extension point''' - -This accomplishes the exact same task, but it registers the post-processor globally. Any comparison through EMF Compare on a scope that contains models matching the given namespace URI will trigger that post-processor. - -<source lang="xml"> -<extension point="org.eclipse.emf.compare.rcp.postProcessor"> - <postProcessor class="my.package.CustomPostProcessor"> - <nsURI value="http://www.eclipse.org/uml2/\\d\\.0\\.0/UML"> - </nsURI> - </postProcessor> -</source> - -== Diff == - -Now that the Matching phase has completed and that we know how our objects are coupled together, EMF Compare no longer requires the two (or three) input models. It will no longer iterate over them or the comparison's input scope. From this point onward, only the result of our comparison, the ''Comparison'' object, will be refined through the successive remaining phases, starting by the '''Diff'''. - -The goal of this phase is to iterate over all of our ''Match'' elements, be they unmatched (only one side has this object), couples (two of the three sides contain this object) or trios (all three sides have this object) and compute any difference that may appear between the sides. For example, an object that is only on one side of the comparison is an object that has been added, or deleted. But a couple might also represent a deletion: during three way comparisons, if we have an object in the common ancestor (origin) and in the left side, but not in the right side, then it has been deleted from the right version. However, this latter example might also be a conflict: we have determined that the object has been removed from the right side... but there might also be differences between the original version and the "left" version. - -The differencing phase does not care about conflicts though: all it does is refine the comparison to tell that this particular ''Match'' has ''n'' diffs: one ''DELETE'' difference on the right side, and ''n'' differences on the left. Detecting conflicts between these differences will come at a later time, during the conflict resolution phase. - -Customizations of this phase usually aim at ignoring specific differences. - -=== Overriding the Diff engine === - -As is the case for the Match phase, the most powerful customization you can implement for the differencing process is to override the diff engine EMF Compare uses. To this end you can either [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffEngine.java implement the whole contract, ''IDiffEngine''], in which case you will have to carefully follow the javadoc's recommandations, or extend the [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DefaultDiffEngine.java default implementation, ''DefaultDiffEngine'']. - -A custom diff engine can then be used for your comparisons: - -<source lang="java"> -IDiffEngine customDiffEngine = new MyDiffEngine(...); -EMFCompare.builder().setDiffEngine(customDiffEngine).build().compare(scope); -</source> - -=== Changing the FeatureFilter === - -One of the differencing engine's responsibilities is to iterate over all features of a given object in order to check for potential differences on its value(s). However, there are some features that we decide do ignore by default: derived features, transient features... or some features on which we would like to check for ordering changes even though they are marked as non-ordered. - -The logic to determine whether a feature should be checked for differences has been extracted into its own class, and is quite easy to alter. For example, if you would like to ignore the ''name'' feature of your elements or never detect any ordering change: - -<source lang="java"> -IDiffProcessor diffProcessor = new DiffBuilder(); -IDiffEngine diffEngine = new DefaultDiffEngine(diffProcessor) { - @Override - protected FeatureFilter createFeatureFilter() { - return new FeatureFilter() { - @Override - protected boolean isIgnoredReference(Match match, EReference reference) { - return reference == EcorePackage.Literals.ENAMED_ELEMENT__NAME || - super.isIgnoredReference(match, reference); - } - - @Override - public boolean checkForOrderingChanges(EStructuralFeature feature) { - return false; - } - }; - } -}; -EMFCompare.builder().setDiffEngine(diffEngine).build().compare(scope); -</source> - -You could also [[#Changing the Diff Processor|change the diff processor]] to achieve a similar goal. The difference between the two approaches is that changing the ''FeatureFilter'' will ignore the structural feature altogether, whereas replacing the diff processor would let EMF Compare check the feature and detect that diff, but ignore the notification that there is a change. - -=== Changing the Diff Processor === - -The diff engine browses over all of the objects that have been matched, and checks all of their features in order to check for changes between the two (or three) versions' feature values. When it detects a change, it delegates all of the corresponding information to its associated ''Diff Processor'', which is in charge of actually creating the ''Diff'' object and appending it to the resulting ''Comparison''. - -Replacing the ''Diff Processor'' gives you a simple entry point to ignore some of the differences the default engine detects, or to slightly alter the ''Diff'' information. You might want to ignore the differences detected on some references for example. Or you might want to react to the detected diff without actually creating the ''Comparison'' model... The implementation is up to you. You can either reimplement the [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffProcessor.java whole contract] or extend the default implementation, [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DiffBuilder.java ''DiffBuilder''] - -Here is a simple example that provides EMF Compare with a diff processor that will ignore all differences detected on the "name" attribute of our objects, yet keep the default behavior for all other differences. - -<source lang="java"> -IDiffProcessor customDiffProcessor = new DiffBuilder() { - @Override - public void attributeChange(Match match, EAttribute attribute, Object value, DifferenceKind kind, DifferenceSource source) { - if (attribute != EcorePackage.Literals.ENAMED_ELEMENT__NAME) { - super.attributeChange(match, attribute, value, kind, source); - } - } -}; - -IDiffEngine diffEngine = new DefaultDiffEngine(customDiffProcessor); -EMFCompare.builder().setDiffEngine(diffEngine).build().compare(scope); -</source> - -=== Refine the default Diff result === - -The last possibility offered by EMF Compare to alter the result of the differencing phase is to post-process it. The remaining comparison phases -equivalence detection, detection of dependencies between diffs and conflict detection- all use the result of the Diff engine and refine it even further. As such, all of these phases can be impacted through the refining of the Diff result. - -Example uses of the post-processing would include: - -* Remove ''Diff'' elements -: If you'd rather code your logic to ignore differences here as a post-process instead of changing the ''FeatureFilter'' or ''IDiffProcessor''. Though that is not the best way to ignore differences, it can still be done here. - -* Add new ''Diff'' elements -: If you want to create new differences without implementing a whole differencing engine, new differences can still be created here as a post-process. You will need to implement the iteration over model elements and specific checks yourself though. This workaround can also be used to create new differences that the default differencing engine does not know. - -* Alter the detected differences -: If some of the differences have been detected in a way you do not like, and you did not use a custom ''IDiffProcessor'' to change the ''Diff'' information, you can do so here. - -The post-processor for the diff engine is implemented exactly in the same way as for the match engine post-processors (the interface and extension point are the same). Please refer to [[#Refine the default Match result|Refining the Match result]]. - -== Equivalences == - -Now that the Differencing phase has ended, we've computed all of the individual differences within the compared models. However, all of these differences are still isolated, we now need to determine if there are any connections between them. - -An ''equivalence'' is one kind of potential connections between differences. For example, Ecore has a concept of ''eOpposite'' references, which be maintained in sync with one another. Modifying one of the two references will automatically update the other side of the opposition accordingly. Both the manual modification and the automatic update are considered as distinct modifications of the model when looking at it after the fact, resulting in two differences detected. However, merging any of these two differences will automatically merge the other one. Therefore, both are marked as being ''equivalent'' to each other. - -Though that is an example with two, more than two differences can be considered equivalent with each other. When we merge one difference, all of the other diffs that have been marked as being equivalent to it will be marked as ''MERGED'', though no actual work needs to be done to merge them : EMF will have automatically updated them when merging the first. - -Do note that EMF Compare detects and understand two different kind of relations that could be considered "equivalences". Described above are plain equivalences, when merging one of the differences will automatically update the model in such a way that all other sides of the equivalence are redundant and automatically merged. However, equivalences might not always be that easy. Let's take for example the case of UML : UML has concepts of ''subset'' and ''superset'' references. Adding an object into a subset will automatically update the related superset so that it also contains the added element. However, adding that same element to the superset will _not_ automatically update the related subset. - -This can be seen as a "directional" equivalence, where one difference D1 ''implies'' another D2, but is not ''implied by'' D2. Implications will be detected at the same time as the equivalences, but they do not use an ''Equivalence'' element, they are filled under the ''Diff#implies'' reference instead. - -=== Refine the default equivalences === - -This phase does not offer as many customization options as the previous ones; though post-processing should be enough for most needs. All of the phases that come after the differencing are further refinements of the comparison model, totally independent from one another. From here, any client of the API can refine the comparison model any way he'd like to, even by removing all of the default results. - -A few examples of customizations that could be made from here : -* Partly break existing equivalences -: You can modify the equivalences we've detected by default by removing elements from individual differences' equivalences (Diff#getEquivalence()) or by changing the ''Equivalence'' elements directly. -* Remove existing ''Equivalence'' elements -: If you'd rather remove the ''Equivalence'' elements altogether, it can also be done from here without impact down the line. The individual differences will be merged individually (potentially twice if EMF automatically updates the references) if the mergers do not have this to tell them what's equivalent to what. -* Detect your own equivalences -: If you have specific rules on your metamodel or implementation that make some differences redundant or otherwise fully equivalent to one another, you can add your own equivalences from here. - -The post-processor for the equivalence detection engine is implemented exactly in the same way as for the match engine post-processors (the interface and extension point are the same). Please refer to [[Refine the default Match result|Refining the Match result]]. - -== Requirements == - -A requirement will be used to deal with structural constraints (to prevent dangling references or objects without parent) and to insure the model integrity. -A difference requires other ones if the merge of this one needs the other ones not to "break" the model. -The merge of a difference involves the merge of the required differences. All these differences will be merged by EMF Compare. -For example, the add of a reference requires the add of the referenced object and the add of the object containing this reference. - -{| cellspacing="1" cellpadding="1" border="1" -|- -! align="center" | Change kind -! align="center" | Reference kind to a graphical object -! align="left" | Requires: -|- -| rowspan="2" align="center" | ADD -| align="center" | content -| ADD of its container<br> DELETE of the origin value on the same containment mono-valued reference -|- -| align="center" | reference -| ADD of the target object<br> ADD of the source object e.g. The ADD of a reference to the target or source of an edge requires the ADD of the edge itself and the ADD of the target and source objects, the ADD of a reference to the semantic object from a graphical one requires the ADD of the graphical and semantic object. -|- -| align="center" | DELETE -| align="center" | content -| DELETE of the outgoing references and contained objects<br> DELETE/CHANGE of the incoming references<br> MOVE of the contained objects -|- -| align="center" | MOVE -| align="center" | content -| ADD of the new container of the object<br> MOVE of the new container of the object -|- -| align="center" | CHANGE -| align="center" | reference permutation -| ADD of the target object -|} - - -Requirements can be added during a post-process. - -== Refinement == - -A refinement enables to group a set of unit differences into a macroscopic change. -<br>A unit difference refines a macroscopic one if it belongs to this macroscopic change. In other words, a macroscopic change is refined by a set of unit differences. -<br>The merge of a macroscopic change involves the merge of the refining differences. All these differences will be merged by EMF Compare. -<br>The use of the refinement allows to improve (simplify) the reading of the comparison from a business viewpoint, to accelerate the manual merging for the end-user and to insure some consistency. -<br>For example, the add of an association, in UML, is refined by the add of the UML Association itself but also the add of the UML properties with the update of references... - -Refinement can be added during a post-process. - -== Conflicts == - -PENDING description of the phase, extensibility options (post-process) - -== Merging == - -=== Which references are followed during merging === - -{| border="1" -|- -! -! Merge from Left to Right -! Merge from Right to Left -|- -! Source = Left -| align="center" | requires -| align="center" | requiredBy -|- -! Source = Right -| align="center" | requiredBy -| align="center" | requires -|} - - -PENDING how to provide custom mergers, override existing ones? - -== User Interface == - -PENDING customize display of custom differences, add custom menu entries, add groups, add filters, add export options, provide custom content viewer diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/EMF Compare Developer Guide.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/EMF Compare Developer Guide.html deleted file mode 100644 index edcf25da2..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/EMF Compare Developer Guide.html +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>EMF Compare Developer Guide</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="EMF_Compare_Developer_Guide">EMF Compare Developer Guide</h1> - <p>You will find the following sections:</p> - <ul> - <li> - <a href="Architecture.html" title="Architecture.html">Architecture</a> - </li> - <li> - <a href="Core%20Concepts.html" title="Core%20Concepts.html">Core Concepts</a> - </li> - <li> - <a href="Default%20Behavior%20and%20Extensibility.html" title="Default%20Behavior%20and%20Extensibility.html">Default Behavior and Extensibility</a> - </li> - <li> - <a href="Using%20The%20Compare%20APIs.html" title="Using%20The%20Compare%20APIs.html">Using The Compare APIs</a> - </li> - </ul> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/EMF Compare Developer Guide.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/developer/EMF Compare Developer Guide.mediawiki deleted file mode 100644 index dff62cacb..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/EMF Compare Developer Guide.mediawiki +++ /dev/null @@ -1,7 +0,0 @@ -= EMF Compare Developer Guide = - -You will find the following sections: -* [[Architecture.html|Architecture]] -* [[Core%20Concepts.html|Core Concepts]] -* [[Default%20Behavior%20and%20Extensibility.html|Default Behavior and Extensibility]] -* [[Using%20The%20Compare%20APIs.html|Using The Compare APIs]] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/How To Open Compare Dialog With Comparison.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/How To Open Compare Dialog With Comparison.html deleted file mode 100644 index 4e109f5f9..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/How To Open Compare Dialog With Comparison.html +++ /dev/null @@ -1,111 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>How To Open Compare Dialog With Comparison</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="How_To_Open_Compare_Dialog_With_Comparison">How To Open Compare Dialog With Comparison</h1> - <p>This is only valid since release 2.1M4. </p> - <p>In this page you will learn how to open a dialog displaying the result of a comparison. </p> - <h2 id="Preparing_the_input">Preparing the input</h2> - <p>The first thing to do is to choose an EMF Compare sub-implementation of the class of - <a href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareEditorInput.html">CompareEditorInput</a>. - </p> - <p>Two implementations are provided: </p> - <ul> - <li> - <i>ComparisonEditorInput</i>, that should be use when you want to display a pre-computed Comparison (the results of EMFCompare). - </li> - <li> - <i>ComparisonScopeEditorInput</i>, that should be use when you want to open the compare editor or dialog and to let it perform the comparison. - </li> - </ul> - <p>Both are available from the - <b>org.eclipse.emf.compare.ide.ui</b> plug-in, in the package - <b>org.eclipse.emf.compare.ide.ui.internal.editor</b>. This is still provisional API so we may break it any time. - </p> - <h2 id="Preparing_the_configuration">Preparing the configuration</h2> - <p>When instantiating an EMF Compare specific implementation of CompareEditorInput, you have to give it at least three paramaters:</p> - <ul> - <li>a - <a href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareConfiguration.html">CompareConfiguration</a>. This is a standard CompareConfiguration (no specific implementation needed) so you just instantiated it like this: - </li> - </ul> - <pre class="source-java">CompareConfiguration configuration = new CompareConfiguration(); - -</pre> - <ul> - <li>an EMFCompareEditingDomain. It is not an implementation of - <a href="http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/edit/domain/EditingDomain.html">EditingDomain</a> from EMF. It shares similar concepts (it has a command stack, it can create some commands) but is much simpler. You can create it through the factory method: - </li> - </ul> - <pre class="source-java">// ancestor may be null -ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor); - -</pre> - <p>You can even give your own command(s) stack(s) if you need to know about executed merge commands. </p> - <ul> - <li>An - <a href="http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/common/notify/AdapterFactory.html">AdapterFactory</a> used by the framework to adapt EObjects to be nicely displayed. Most of the time, a - <a href="http://download.eclipse.org/modeling/emf/emf/javadoc/2.5.0/org/eclipse/emf/edit/provider/ComposedAdapterFactory.html">ComposedAdapterFactory</a> with the global registry is sufficient as created in the example below: - </li> - </ul> - <pre class="source-java">AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE); - -</pre> - <p>Depending on the choosen sub-implementation of CompareEditorInput, you may need to provide additional parameters.</p> - <h3 id="ComparisonEditorInput">ComparisonEditorInput</h3> - <p>You must provide a Comparison object, the result of the comparison computation of EMFCompare.</p> - <pre class="source-java">EMFCompare comparator = EMFCompare.builder().build(); -Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor)); - -</pre> - <h3 id="ComparisonScopeEditorInput">ComparisonScopeEditorInput</h3> - <p>You must provide the comparator (instance of EMFCompare) and the scope of the comparison.</p> - <pre class="source-java">EMFCompare comparator = EMFCompare.builder().build(); -IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor); - -</pre> - <h2 id="Opening_the_compare_UI">Opening the compare UI</h2> - <p>Then, you can call the black magic method from Eclipse Compare framework. You have two choices. You may either open the compare UI wihtin a modal dialog or within an editor. Just call one of the two following methods: </p> - <ul> - <li> - <a href="http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fapi%2Forg%2Feclipse%2Fcompare%2FCompareUI.html&anchor=openCompareEditorOnPage(org.eclipse.compare.CompareEditorInput,%20org.eclipse.ui.IWorkbenchPage)">CompareUI.openCompareEditorOnPage(CompareEditorInput, IWorkbenchPage)</a>, to open an editor. - </li> - <li> - <a href="http://help.eclipse.org/juno/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/compare/CompareUI.html#openCompareDialog(org.eclipse.compare.CompareEditorInput)">CompareUI.openCompareDialog(CompareEditorInput)</a>, to open a modal dialog. - </li> - </ul> - <h2 id="End-to-end_examples">End-to-end examples</h2> - <h3 id="With_pre-computed_comparison">With pre-computed comparison</h3> - <pre class="source-java">public void compare(Notifier left, Notifier right, Notifier ancestor) { - EMFCompare comparator = EMFCompare.builder().build(); - Comparison comparison = comparator.compare(EMFCompare.createDefaultScope(left, right, ancestor)); - - ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor); - AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE); - CompareEditorInput input = new ComparisonEditorInput(new CompareConfiguration(), comparison, editingDomain, adapterFactory); - - CompareUI.openCompareDialog(input); // or CompareUI.openCompareEditor(input); -} - -</pre> - <h3 id="With_a_comparison_scope">With a comparison scope</h3> - <pre class="source-java">public void compare(Notifier left, Notifier right, Notifier ancestor) { - EMFCompare comparator = EMFCompare.builder().build(); - IComparisonScope scope = EMFCompare.createDefaultScope(left, right, ancestor)); - - ICompareEditingDomain editingDomain = EMFCompareEditingDomain.create(left, right, ancestor); - AdapterFactory adapterFactory = new ComposedAdapterFactory(ComposedAdapterFactory.Descriptor.Registry.INSTANCE); - CompareEditorInput input = new ComparisonScopeEditorInput(new CompareConfiguration(), - editingDomain, adapterFactory, comparator, scope); - - CompareUI.openCompareDialog(input); // or CompareUI.openCompareEditor(input); -} - -</pre> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Logical Model.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/Logical Model.html deleted file mode 100644 index cc4028ff0..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Logical Model.html +++ /dev/null @@ -1,304 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Logical Model</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Logical_Model">Logical Model</h1> - <h2 id="What_is_a_logical_model_.3F">What is a logical model ?</h2> - <p>We name "logical model" a set of - <b>physical resources</b> that form a coherent business-related model. For example, we could say that a given Java class forms a coherent logical model only when it is linked with all of its imported classes. - </p> - <p>In the case of EMF, we name a - <i>logical resource</i> (or - <i>model</i>) the EMF resource loaded in memory, as opposed to a - <i>physical resource</i> (or - <i>file</i>) that is merely the serialization of this model on disk. A given EMF model can reference a number of other models, and it will be incoherent, or even sometimes corrupted, if these other models are not loaded in memory. In EMF, a given model can be serialized as a single file, - <i>fragmented</i> in multiple files on disk, or - <i>reference</i> multiple files. The logical model is only coherent when the whole set of its physical files is accessible. - </p> - <p>If we take it in reverse, a logical model is a set of elements that reference each other :</p> - <table> - <tr> - <td align="center"> - <img align="middle" border="1" src="./../images/Logical_Model.png"/> - </td> - </tr> - <tr> - <td align="center">A Logical Model is a set of inter-related elements.</td> - </tr> - </table> - <p>When these elements are serialized on disk, they may be split across multiple files, as long as the references between these files can be resolved :</p> - <table> - <tr> - <td align="center"> - <img align="middle" border="1" src="./../images/Logical_Model_Split.png"/> - </td> - </tr> - <tr> - <td align="center">Logical Model split in the files - <i>A</i>, - <i>B</i>, - <i>C</i>, - <i>D</i>, - <i>E</i>, - <i>F</i> and - <i>G</i>. - </td> - </tr> - </table> - <h2 id="Eclipse_Team">Eclipse Team</h2> - <p>The Eclipse Team project (referred as "Team" in this document) provides an API named "model providers". This API allows implementers to define the semantics of what is a "logical model" in his case. In short, it allows us to link any number of physical resources to a given "starting" file.</p> - <p>Technically, this is done through an extension point that can be implemented by anyone and that will adapt a file (a workspace - <i>IResource</i>) to a set of files (a Team - <i>ResourceTraversal</i>). The model providers can be queried by anyone who calls actions on workspace files in order to determine if this action can be done against a single file or if it should be executed against a set of files. - </p> - <h2 id="Limitations">Limitations</h2> - <p>Team only provides the API to define logical models. It is then the responsibility of its clients to properly query the model provider when calling an action. In the context of EMF Compare, we are interested in the "compare" actions. These actions are contributed by the repository providers (CVS, EGit, Subversive, Subclipse, Clearcase...). It is their responsibility, within the code of these actions, to query the model providers in order to determine if the selected files can be compared alone... or if they need to be compared along with a set of others.</p> - <ul> - <li>The CVS plugin does not consistently use it. For example, when using "compare with > latest from HEAD" on a file that is part of a logical model, it will 'see' the logical model and open the "synchronize" perspective instead of a compare editor : this is what's expected. However, when the user, from the synchronization view, asks to see the differences (right-click then select 'open in compare editor')... CVS will not query the logical model, comparing the file alone (see also - <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=345415">bug 345415</a>). - </li> - <li>The EGit, Subversive and Subclipse plugins never query the model providers for any comparison action.</li> - </ul> - <h1 id="EMF_Compare">EMF Compare</h1> - <p>In the case of EMF Compare, the above limitations were a show-stopper. EMF models cannot simply be reduced to single files as that would totally break their consistency when trying to merge them.</p> - <h2 id="Chosen_solution">Chosen solution</h2> - <p>EMF Compare now uses its own implementation aiming at this same goal, that we named - <i>synchronization model</i>. In short, instead of expecting the repository providers to query the model providers, EMF Compare will take the file (or set of files) that it is fed and expand it to the full logical model by querying the synchronization model. - </p> - <p>This custom implementation also allows us to not only resolve the whole logical model of a given physical file, but also to determine which - <b>parts</b> of this model should be included in the comparison scope. Indeed, under the semantics of EMF, if we can determine that two physical files are binary identical in their two distinct revisions, then we also know that the part of the logical model they represent are identical themselves. There would be no need to compare them. This allows us to save both time and memory, killing two birds with one stone. - </p> - <h2 id="How_it_works">How it works</h2> - <p>When the user selects a file - <i>A</i> in his workspace and asks to compare it with a remote revision (for example, the "latest from HEAD"), the repository provider (CVS in this case) fetches the remote content of - <i>A</i> in the selected revision (we'll call it - <i>A</i>'). Once the remote revision fetched, the repository provider considers his work finished and feeds EMF Compare the two files (A and A') and lets it begin his own work. This is fine and dandy when the logical model of A only spans a single file ... but if A references another file B, then the comparison will not be coherent as EMF Compare operates on the logical model, not on its serialized form. - </p> - <p>Thus, EMF Compare will not immediately launch the comparison of the files it is fed. Before any further work, it will query the synchronization model with these files in order to expand them to their whole logical model.</p> - <ul> - <li>In the case of a local file (A), it will load it as an EMF - <i>Resource</i> and resolve all of its cross references. During the resolution process, we'll be able to track all of the "other" files required by the "starting point" A. In the example above, we'll end up with a set containing both A and B. - </li> - <li>In the case of a remote file (A'), it will try and load the streamed revision of the resource, then query the repository provider for the other files needed by A' in the correct revision. A revision is deemed "correct" if it precedes (or is equal to) the revision of A' that we have initially been fed. This will lead us to a set containing A' and B'.</li> - </ul> - <p>Once the full logical model is resolved, EMF Compare can properly do the comparison work. Since we know of all fiels that compose our model, we'll also be able to safely merge differences without compromising the coherence of the whole.</p> - <p>However, even if we can launch EMF Compare at this point, the synchronization model also offers us one more possibility. EMF models can span thousands of physical files sometimes amounting to such a huge number of elements that it would not fit into the machine's memory if we tried to load it as a whole. The synchronization model knows how to retrieve the content of all of these files; it can also be used to - <i>minimize</i> the set to only those which really did change. Indeed, we consider that files that are binary identical wield yield fragments of the logical model that will also be strictly identical. By removing these "identical" fragments, we can drastically limit the size of the logical model we'll load into memory, compacting it to a size that will fit before we launch the comparison on the remaining fragments. - </p> - <p>In other words, the synchronization model allows us to compare models with a time and memory cost that is relative to the size of the actual changeset instead of having it depend on the input models size.</p> - <h3 id="Example">Example</h3> - <p>Let's consider the following sample :</p> - <table border="1" cellpadding="5" cellspacing="0"> - <tr> - <th align="center" colspan="2">Origin</th> - </tr> - <tr> - <td align="center" colspan="2"> - <img align="middle" border="0" src="./../images/EMFC_Logic_origin.png"/> - </td> - </tr> - <tr> - <th align="center">Left</th> - <th align="center">Right</th> - </tr> - <tr> - <td> - <img align="middle" border="0" src="./../images/EMFC_Logic_left.png"/> - </td> - <td> - <img align="middle" border="0" src="./../images/EMFC_Logic_right.png"/> - </td> - </tr> - </table> - <p>Each of the three sides is an EMF model composed of 7 fragments. - <i>Origin</i> is the common ancestor of - <i>left</i> and - <i>right</i>. The blue-colored fragments are those that actually present differences (so D and G have been modified in the "left" copy while only B has been modified in the "right" copy). - </p> - <p>In order to compare these three models together, we would normally need to load all 21 fragments in memory. However, with the help of the synchronization model we can narrow it down to the modified fragments only. What we'll really load, then, are the following fragments for each three sides :</p> - <p> - <img align="middle" border="0" src="./../images/EMFC_Logic_loaded_fragments.png"/> - </p> - <p>In other words, we are actually only loading 9 fragments out of the initial 21. This amounts to 58% less memory usage if we consider all fragments to be of equal "weight". And this is only for small models; the ratio of saved memory really going up for extremely large models. Of course, all of these objects that we are not loading in memory are all objects that we no longer need to compare, bringing an incredible performance boost along with the memory gain.</p> - <h3 id="Some_numbers">Some numbers</h3> - <p>When we got EMF Compare 1.3 out, we did some performance snapshots of what we had on some UML models with known counts of elements. Here were the specifications of the structure of the three test models. "fragments" are the number of fragmented files, the rest are the UML elements contained by the samples (spread out within the fragments) :</p> - <table border="1" cellspacing="0"> - <tr> - <th> </th> - <th>Small</th> - <th>Nominal</th> - <th>Large</th> - </tr> - <tr> - <td>Fragments</td> - <td>99</td> - <td>399</td> - <td>947</td> - </tr> - <tr> - <td>Size on disk (MB)</td> - <td>1.37</td> - <td>8.56</td> - <td>49.9</td> - </tr> - <tr></tr> - <tr> - <td>Packages</td> - <td>97</td> - <td>389</td> - <td>880</td> - </tr> - <tr> - <td>Classes</td> - <td>140</td> - <td>578</td> - <td>2169</td> - </tr> - <tr> - <td>Primitive Types</td> - <td>581</td> - <td>5370</td> - <td>17152</td> - </tr> - <tr> - <td>Data Types</td> - <td>599</td> - <td>5781</td> - <td>18637</td> - </tr> - <tr> - <td>State Machines</td> - <td>55</td> - <td>209</td> - <td>1311</td> - </tr> - <tr> - <td>States</td> - <td>202</td> - <td>765</td> - <td>10156</td> - </tr> - <tr> - <td>Dependencies</td> - <td>235</td> - <td>2522</td> - <td>8681</td> - </tr> - <tr> - <td>Transitions</td> - <td>798</td> - <td>3106</td> - <td>49805</td> - </tr> - <tr> - <td>Operations</td> - <td>1183</td> - <td>5903</td> - <td>46029</td> - </tr> - <tr> - <td> - <b>Total element count</b> - </td> - <td>3890</td> - <td>24623</td> - <td>154820</td> - </tr> - </table> - <p>Following are the time and memory required to compare each of the model sizes (the model is copied, randomly modified, then the copy is compared with its original) with two versions of EMF Compare. The 'old' 1.3, and the 2.1 that fully uses the logical model capabilities.</p> - <h4 id="EMF_Compare_1.3">EMF Compare 1.3</h4> - <p>Note that these were "CPU time" measures : we used a Java profiler to measure the duration of the comparison process, without regard to the actual wall time : we measured the time that the CPU was active during this process. As EMF Compare 1 was not multi-threaded, this means that these figures are slightly lower than the time actually perceived by the user for the same action. (See - <a href="http://en.wikipedia.org/wiki/Wall_clock_time">Wall Time</a> and - <a href="http://en.wikipedia.org/wiki/System_time">System Time</a> on wikipedia.) - </p> - <table border="1" cellspacing="0"> - <tr> - <th> </th> - <th>Small</th> - <th>Nominal</th> - <th>Large</th> - </tr> - <tr> - <td>Time (seconds)</td> - <td>6</td> - <td>22</td> - <td>125</td> - </tr> - <tr> - <td>Maximum Heap (MB)</td> - <td>555</td> - <td>1019</td> - <td>2100</td> - </tr> - </table> - <p>These figures could be broken down in the following three main phases : </p> - <p> - <img align="middle" border="0" src="./../images/EMFC_1.3_Perf_Breakdown.png"/> - </p> - <p>This meant that the memory management of EMF Compare was really limiting as soon as we were dealing with large models (more than 2GB of heap space needed to load models that "weigh" 50 MB on disk). Furthermore, the main time sink was the differencing process, and that could also be narrowed down to the fact that there were plainly too many object to compare : for two-way comparisons, we were loading the model twice, for three-way comparisons, three instances of the model were loaded in memory. Not only that, but we were iterating twice on all models (one for matching, one for differencing).</p> - <p>The full report can be downloaded from - <a href="http://www.eclipse.org/emf/compare/doc/compare_scalability.pdf">here</a>. - </p> - <h4 id="EMF_Compare_2.1">EMF Compare 2.1</h4> - <p>Note that these are "wall time" measures : we used a stopwatch to time the duration of the comparison, from a click on the "compare with > each other" action to the opening of the comparison editor.</p> - <table border="1" cellspacing="0"> - <tr> - <th> </th> - <th>Small</th> - <th>Nominal</th> - <th>Large</th> - </tr> - <tr> - <td>Time (seconds)</td> - <td>5</td> - <td>13</td> - <td>48</td> - </tr> - <tr> - <td>Maximum Heap (MB)</td> - <td>262</td> - <td>318</td> - <td>422</td> - </tr> - </table> - <p>These figures can be broken down in 5 main phases :</p> - <ol> - <li>Model Resolving : From a given "starting point" (in the example above, fragment - <i>A</i>), finding all other fragments required for the comparison of the whole logical model. - </li> - <li>Scope Narrowing : From the set of fragments composing the logical model, finding those that actually - <i>can</i> present differences ( - <i>B</i>, - <i>D</i> and - <i>G</i> in the above example), then loading these fragments in memory. - </li> - <li>Matching : Iterating over the two (or three) loaded logical models in order to map elements together two-by-two (or three-by-three).</li> - <li>Differencing : The matching phase told us which elements were matching together (Class C1 in the left logical model with Class C1' in the right logical model for example). The differencing phase will try and determine whether those two elements are equal or if they present differences (for example, the name of the class changed from - <i>C1</i> to - <i>C1</i>') - </li> - <li>Post-processing : Now that we know all differences between the models, we still need to determine equivalences -two differences that represent the same change (for example, differences on opposite references)-, requirements -a difference depends on another (for example, the addition of a class C1 in package P1 depends on the addition of package P1)-, conflicts -a conflictual change has been made in the - <i>left</i> and - <i>right</i> models as compared to the origin... - </li> - </ol> - <p> - <img align="middle" border="0" src="./../images/EMFC_2.1_Perf_Breakdown.png"/> - </p> - <p>Okay, this graph does not leave much to interpretation. The model resolving time totally dwarfs the other comparison phases. That was actually our aim for EMF Compare 2 : - <i>model resolving</i> represents the bulk of the I/O operations of EMF Compare, and we aimed at reducing the actual comparison to the utmost minimum time. So not only are we greatly improving the memory cost (only 400MB of heap space to compare something that required more than 2GB with EMF Compare 1), but we also reduced the comparison time (and the scalability) to a great extent. - </p> - <h2 id="Limitations_2">Limitations</h2> - <p>The use of our own implementation effectively allows us to bypass some of the aforementioned limitations since we no longer rely on the repository providers in our specific case.</p> - <p>However, if we can enforce the coherence of the models during the comparison, this approach still does not take into account the other aspects of collaboration with models. Even if comparing and merging two linked models is fine, it is still the repository provider's responsibility to query Team's model providers in order to "commit", "push", or even "replace" the models as a whole instead of acting on single physical files. Thus, most of the limitations mentioned above still hold, though we fixed those that applied to comparison actions.</p> - <h2 id="Improvement_Axes">Improvement Axes</h2> - <p>As shown with the - <a href="Logical%20Model.html#EMF_Compare_2.1">above graphs</a>, the most important remaining time sink is the resolution of the logical model. This is partly due to the I/O operations performed during this phase, but first and foremost it is due to the parsing of the XMI representation of the files we used (UML fragments) as EMF models. EMF Compare needs to actually load all fragments of the logical model as EMF model fragments in order to determine their cross-resource references, which represent other parts of the logical model that will need in turn. This phase could be improved by parsing the raw XMI data to find all of these cross-resource references without parsing the actual EMF elements of which they are a part. - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Using The Compare APIs.html b/plugins/org.eclipse.emf.compare.doc/doc/developer/Using The Compare APIs.html deleted file mode 100644 index aa56d2aad..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Using The Compare APIs.html +++ /dev/null @@ -1,229 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Using The Compare APIs</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Using_The_Compare_APIs">Using The Compare APIs</h1> - <p>The main entry point of EMF Compare is the - <i>org.eclipse.emf.compare.EMFCompare</i> class. It is what should be used in order to configure and launch a comparison. That is not all though. Once you have compared two models, you want to query the differences, maybe merge some of them, display the comparison result in the comparison editor... The following section will list the main entry points for each of these actions, along with a brief description of what can be done and what should be avoided. - </p> - <p>Most of these examples are set-up as "standalone" examples, and will include extra instructions for IDE use: pay attention to the environment in which you are using EMF Compare. Are you using it from an Eclipse plugin, in which case you'd like all of the extra features provided through extension points and contribution to be available to you? Or are you using it from a standalone environment, in which case you'd need to reduce the dependencies to the bare minimum and avoid OSGi-related code and extensions?</p> - <h2 id="Compare_two_models">Compare two models</h2> - <h3 id="Loading_your_models">Loading your models</h3> - <p>Whether you wish to compare two or three models, the first thing you need is to load them. We won't detail in-depth how to do that as this is standard EMF practice, you might want to look at EMF tutorial for detailled instructions on this point. Here, we'll use a simple method that loads an xmi file at a given URL into a resourceSet, expecting the given URL to be an absolute file URL:</p> - <pre class="source-java">public void load(String absolutePath, ResourceSet resourceSet) { - URI uri = URI.createFileURI(absolutePath); - - resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); - - // Resource will be loaded within the resource set - resourceSet.getResource(uri, true); -} - -</pre> - <h3 id="Creating_the_comparison_scope">Creating the comparison scope</h3> - <p>EMF Compare uses a scoping mechanism to determine which elements should be compared, and which others should be ignored. Any element that is outside of the comparison scope will be ignored by the comparison engine and left alone (if it is a proxy, it won't even be loaded). As such, extra care should be taken to determine the proper scope of the comparison or customize the IEqualityHelper to handle the specific elements you remove from the scope. Refer to the - <a href="./Core%20Concepts.html#Comparison_Scope" title="./Core%20Concepts.html#Comparison Scope">appropriate section</a> above for more on the scoping mechanism. - </p> - <p>By default, the only thing that EMF Compare considers "out of scope" are Ecore's "EGenericType" elements. These are usually meaningless as far as comparison is concerned (as they are located in derived references and will be merged along with their "true" difference anyway). Other than that, Please note that EMF Compare will leave unresolved proxies alone: more on this can be found in the - <a href="./Core%20Concepts.html#Proxy_Resolution" title="./Core%20Concepts.html#Proxy Resolution">related section</a>. - </p> - <p>The default scope can be easily created through:</p> - <pre class="source-java">IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2); - -</pre> - <h3 id="Configuring_the_comparison">Configuring the comparison</h3> - <p>EMF Compare can be customized in a number of ways, the most important of which were described - <a href="./Default%20Behavior%20and%20Extensibility.html" title="./Default%20Behavior%20and%20Extensibility.html">above</a>. Most of them re-use the same entry point, the - <i>org.eclipse.emf.compare.EMFCompare</i> class. We won't customize much here, please see the afore-mentionned section for extensibility means. - </p> - <p>All we will tell EMF Compare is not to use identifiers, and rely on its proximity algorithms instead (after all, we're comparing plain XMI files):</p> - <pre class="source-java">IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - -IMatchEngine.Factory matchEngineFactory = new MatchEngineFactoryImpl(matcher, comparisonFactory); -matchEngineFactory.setRanking(20); -IMatchEngine.Factory.Registry matchEngineRegistry = new MatchEngineFactoryRegistryImpl(); -matchEngineRegistry.add(factory); - -EMFCompare comparator = EMFCompare.builder().setMatchEngineFactoryRegistry(matchEngineRegistry).build(); - - -</pre> - <h3 id="Putting_it_all_together">Putting it all together</h3> - <p>The following takes two input xmi files, loads them in their own resource sets, then calls the comparison without using identifiers:</p> - <pre class="source-java">public Comparison compare(File model1, File model2) { - // Load the two input models - ResourceSet resourceSet1 = new ResourceSetImpl(); - ResourceSet resourceSet2 = new ResourceSetImpl(); - String xmi1 = "path/to/first/model.xmi"; - String xmi2 = "path/to/second/model.xmi"; - load(xmi1, resourceSet1); - load(xmi2, resourceSet2); - - // Configure EMF Compare - IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); - IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - IMatchEngine.Factory matchEngineFactory = new MatchEngineFactoryImpl(matcher, comparisonFactory); - matchEngineFactory.setRanking(20); - IMatchEngine.Factory.Registry matchEngineRegistry = new MatchEngineFactoryRegistryImpl(); - matchEngineRegistry.add(matchEngineFactory); - EMFCompare comparator = EMFCompare.builder().setMatchEngineFactoryRegistry(matchEngineRegistry).build(); - - // Compare the two models - IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2); - return comparator.compare(scope); -} - -private void load(String absolutePath, ResourceSet resourceSet) { - URI uri = URI.createFileURI(absolutePath); - - resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); - - // Resource will be loaded within the resource set - resourceSet.getResource(uri, true); -} - -</pre> - <h3 id="Comparing_from_an_Eclipse_plugin">Comparing from an Eclipse plugin</h3> - <p>The above example is for standalone usage, and as such will require extra work if you wish to compare UML models, benefit from EMF Compare extensions, provide your own mergers... The following represents the same example, but uses IDE-specific utilities (can you spot the two differences?):</p> - <pre class="source-java">public Comparison compare(File model1, File model2) { - // Load the two input models - ResourceSet resourceSet1 = new ResourceSetImpl(); - ResourceSet resourceSet2 = new ResourceSetImpl(); - String xmi1 = "path/to/first/model.xmi"; - String xmi2 = "path/to/second/model.xmi"; - load(xmi1, resourceSet1); - load(xmi2, resourceSet2); - - // Configure EMF Compare - IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); - IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - IMatchEngine matchEngine = new DefaultMatchEngine(matcher, comparisonFactory); - IMatchEngine.Factory.Registry matchEngineRegistry = EMFCompareRCPPlugin.getDefault().getMatchEngineFactoryRegistry(); - IPostProcessor.Descriptor.Registry<String> postProcessorRegistry = EMFCompareRCPPlugin.getDefault().getPostProcessorRegistry(); - EMFCompare comparator = EMFCompare.builder() - .setMatchEngineFactoryRegistry(matchEngineRegistry) - .setPostProcessorRegistry(postProcessorRegistry) - .build(); - - // Compare the two models - IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2); - return comparator.compare(scope); -} - -private void load(String absolutePath, ResourceSet resourceSet) { - URI uri = URI.createFileURI(absolutePath); - - // Resource will be loaded within the resource set - resourceSet.getResource(uri, true); -} - -</pre> - <h2 id="Query_the_differences">Query the differences</h2> - <p>Once you have the result of a comparison (in the form of a - <i>Comparison</i> object), what you are interested in are most likely the differences between your models. We will detail the merging process later on it its own section, but before anything we need to retrieve the list of differences of interest. Within the Comparison model, differences are spread under the elements on which they've been detected, more precisely, under the - <i>Match</i> of the element on which they were detected. - </p> - <p>Let's use a complex example as reference. Consider the three following models:</p> - <table border="1" cellpadding="5" cellspacing="0"> - <tr> - <th align="center" colspan="2">Origin</th> - </tr> - <tr> - <td align="center" colspan="2"> - <img align="middle" border="0" src="./../images/EMF_Compare_Origin_Model.png"/> - </td> - </tr> - <tr> - <th align="center">Left</th> - <th align="center">Right</th> - </tr> - <tr> - <td> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_Master.png"/> - </td> - <td> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_5.png"/> - </td> - </tr> - </table> - <h3 id="All_differences">All differences</h3> - <p>What we need is usually to retrieve the list of - <i>all</i> differences, wherever they were detected, or whatever their source (the left model, or the right model). Instead of iterating all over the Comparison model to collect them, you can use: - </p> - <pre class="source-java">List<Diff> differences = comparison.getDifferences(); - -</pre> - <h3 id="Differences_related_to_element_X">Differences related to element X</h3> - <p>Sometimes, we need to retrieve all of the differences that were detected on (or that are related to) a given model element. For example, with the above example, we might want to retrieve the list of all differences that relate to - <i>Borrowable</i>. Well, there are a number of them, which can all be collected through: - </p> - <pre class="source-java">// borrowable is a reference on the like-named EObject -List<Diff> differencesOnBorrowable = comparison.getDifferences(borrowable); - -</pre> - <p>This will return a list containing a number of differences:</p> - <ul> - <li> - <i>Borrowable</i> has been added in the right model - </li> - <li> - <i>copies</i> has been added to reference - <i>ownedProperties</i> of Borrowable - </li> - <li> - <i>Borrowable</i> has been added to the generalization reference of - <i>Book</i> - </li> - <li> - <i>Borrowable</i> has been added as the - <i>borrowed</i> target of an association with - <i>Person</i> - </li> - </ul> - <p>In other words, this method will return differences - <b>under</b> the target (here, - <i>copies</i> has been added), as well as differences which - <b>changed value</b> is the target. - </p> - <h3 id="Filtering_differences">Filtering differences</h3> - <p>EMF Compare depends on guava for many of its internals. A number of "common" difference filtering predicates have been extracted to the - <i>org.eclipse.emf.compare.utils.EMFComparePredicates</i> utility class. Using this class, it is trivial to filter the list of differences so as to keep only those we are interested in. For example, what if we wish to retrieve the list of all - <b>non-conflictual</b> differences that originate from the - <b>left</b> side? (This is the case when you use the "copy all non-conflicting from left to right" action from the comparison editor for example.) - </p> - <pre class="source-java">// Construct the predicate -Predicate<? super Diff> predicate = and(fromSide(DifferenceSource.LEFT), not(hasConflict(ConflictKind.REAL, ConflictKind.PSEUDO)); -// Filter out the diff that do not satisfy the predicate -Iterable<Diff> nonConflictualDifferencesFromLeft = filter(comparison.getDifferences(), predicate); - -</pre> - <p>Note that for clarity, we've made static references to a number of methods here. This particular snippet requires the following imports:</p> - <pre class="source-java">import static com.google.common.base.Predicates.and; -import static com.google.common.base.Predicates.not; -import static com.google.common.collect.Iterables.filter; -import static org.eclipse.emf.compare.utils.EMFComparePredicates.fromSide; -import static org.eclipse.emf.compare.utils.EMFComparePredicates.hasConflict; - -</pre> - <p>We strongly encourage you to look around more in these classes: - <i>Predicates</i> provides a number of basic, general-purpose predicates while - <i>EMFComparePredicates</i> provides EMF Compare specific predicates used throughout both core and user-interface of EMF Compare. - </p> - <h2 id="Merge_differences">Merge differences</h2> - <p>PENDING how to re-implement - <i>copyDiff</i> and - <i>copyAllNonConflicting</i> - </p> - <p>entry points: org.eclipse.emf.compare.merge.IMerger and org.eclipse.emf.compare.merge.IBatchMerger</p> - <h2 id="Open_a_compare_editor">Open a compare editor</h2> - <p>PENDING description of the need (dialog and editor), link to - <a href="./How%20To%20Open%20Compare%20Dialog%20With%20Comparison" title="./How%20To%20Open%20Compare%20Dialog%20With%20Comparison">appropriate page</a> - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Using The Compare APIs.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/developer/Using The Compare APIs.mediawiki deleted file mode 100644 index 8609d1728..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Using The Compare APIs.mediawiki +++ /dev/null @@ -1,207 +0,0 @@ -= Using The Compare APIs = - -The main entry point of EMF Compare is the ''org.eclipse.emf.compare.EMFCompare'' class. It is what should be used in order to configure and launch a comparison. That is not all though. Once you have compared two models, you want to query the differences, maybe merge some of them, display the comparison result in the comparison editor... The following section will list the main entry points for each of these actions, along with a brief description of what can be done and what should be avoided. - -Most of these examples are set-up as "standalone" examples, and will include extra instructions for IDE use: pay attention to the environment in which you are using EMF Compare. Are you using it from an Eclipse plugin, in which case you'd like all of the extra features provided through extension points and contribution to be available to you? Or are you using it from a standalone environment, in which case you'd need to reduce the dependencies to the bare minimum and avoid OSGi-related code and extensions? - -== Compare two models == - -=== Loading your models === - -Whether you wish to compare two or three models, the first thing you need is to load them. We won't detail in-depth how to do that as this is standard EMF practice, you might want to look at EMF tutorial for detailled instructions on this point. Here, we'll use a simple method that loads an xmi file at a given URL into a resourceSet, expecting the given URL to be an absolute file URL: - -<source lang="java"> -public void load(String absolutePath, ResourceSet resourceSet) { - URI uri = URI.createFileURI(absolutePath); - - resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); - - // Resource will be loaded within the resource set - resourceSet.getResource(uri, true); -} -</source> - -=== Creating the comparison scope === - -EMF Compare uses a scoping mechanism to determine which elements should be compared, and which others should be ignored. Any element that is outside of the comparison scope will be ignored by the comparison engine and left alone (if it is a proxy, it won't even be loaded). As such, extra care should be taken to determine the proper scope of the comparison or customize the IEqualityHelper to handle the specific elements you remove from the scope. Refer to the [[./Core%20Concepts.html#Comparison Scope|appropriate section]] above for more on the scoping mechanism. - -By default, the only thing that EMF Compare considers "out of scope" are Ecore's "EGenericType" elements. These are usually meaningless as far as comparison is concerned (as they are located in derived references and will be merged along with their "true" difference anyway). Other than that, Please note that EMF Compare will leave unresolved proxies alone: more on this can be found in the [[./Core%20Concepts.html#Proxy Resolution|related section]]. - -The default scope can be easily created through: - -<source lang="java"> -IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2); -</source> - -=== Configuring the comparison === - -EMF Compare can be customized in a number of ways, the most important of which were described [[./Default%20Behavior%20and%20Extensibility.html|above]]. Most of them re-use the same entry point, the ''org.eclipse.emf.compare.EMFCompare'' class. We won't customize much here, please see the afore-mentionned section for extensibility means. - -All we will tell EMF Compare is not to use identifiers, and rely on its proximity algorithms instead (after all, we're comparing plain XMI files): - -<source lang="java"> -IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - -IMatchEngine.Factory matchEngineFactory = new MatchEngineFactoryImpl(matcher, comparisonFactory); -matchEngineFactory.setRanking(20); -IMatchEngine.Factory.Registry matchEngineRegistry = new MatchEngineFactoryRegistryImpl(); -matchEngineRegistry.add(factory); - -EMFCompare comparator = EMFCompare.builder().setMatchEngineFactoryRegistry(matchEngineRegistry).build(); - -</source> - -=== Putting it all together === - -The following takes two input xmi files, loads them in their own resource sets, then calls the comparison without using identifiers: - -<source lang="java"> -public Comparison compare(File model1, File model2) { - // Load the two input models - ResourceSet resourceSet1 = new ResourceSetImpl(); - ResourceSet resourceSet2 = new ResourceSetImpl(); - String xmi1 = "path/to/first/model.xmi"; - String xmi2 = "path/to/second/model.xmi"; - load(xmi1, resourceSet1); - load(xmi2, resourceSet2); - - // Configure EMF Compare - IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); - IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - IMatchEngine.Factory matchEngineFactory = new MatchEngineFactoryImpl(matcher, comparisonFactory); - matchEngineFactory.setRanking(20); - IMatchEngine.Factory.Registry matchEngineRegistry = new MatchEngineFactoryRegistryImpl(); - matchEngineRegistry.add(matchEngineFactory); - EMFCompare comparator = EMFCompare.builder().setMatchEngineFactoryRegistry(matchEngineRegistry).build(); - - // Compare the two models - IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2); - return comparator.compare(scope); -} - -private void load(String absolutePath, ResourceSet resourceSet) { - URI uri = URI.createFileURI(absolutePath); - - resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); - - // Resource will be loaded within the resource set - resourceSet.getResource(uri, true); -} -</source> - -=== Comparing from an Eclipse plugin === - -The above example is for standalone usage, and as such will require extra work if you wish to compare UML models, benefit from EMF Compare extensions, provide your own mergers... The following represents the same example, but uses IDE-specific utilities (can you spot the two differences?): - -<source lang="java"> -public Comparison compare(File model1, File model2) { - // Load the two input models - ResourceSet resourceSet1 = new ResourceSetImpl(); - ResourceSet resourceSet2 = new ResourceSetImpl(); - String xmi1 = "path/to/first/model.xmi"; - String xmi2 = "path/to/second/model.xmi"; - load(xmi1, resourceSet1); - load(xmi2, resourceSet2); - - // Configure EMF Compare - IEObjectMatcher matcher = DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); - IComparisonFactory comparisonFactory = new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); - IMatchEngine matchEngine = new DefaultMatchEngine(matcher, comparisonFactory); - IMatchEngine.Factory.Registry matchEngineRegistry = EMFCompareRCPPlugin.getDefault().getMatchEngineFactoryRegistry(); - IPostProcessor.Descriptor.Registry<String> postProcessorRegistry = EMFCompareRCPPlugin.getDefault().getPostProcessorRegistry(); - EMFCompare comparator = EMFCompare.builder() - .setMatchEngineFactoryRegistry(matchEngineRegistry) - .setPostProcessorRegistry(postProcessorRegistry) - .build(); - - // Compare the two models - IComparisonScope scope = EMFCompare.createDefaultScope(resourceSet1, resourceSet2); - return comparator.compare(scope); -} - -private void load(String absolutePath, ResourceSet resourceSet) { - URI uri = URI.createFileURI(absolutePath); - - // Resource will be loaded within the resource set - resourceSet.getResource(uri, true); -} -</source> - -== Query the differences == - -Once you have the result of a comparison (in the form of a ''Comparison'' object), what you are interested in are most likely the differences between your models. We will detail the merging process later on it its own section, but before anything we need to retrieve the list of differences of interest. Within the Comparison model, differences are spread under the elements on which they've been detected, more precisely, under the ''Match'' of the element on which they were detected. - -Let's use a complex example as reference. Consider the three following models: - -{| border="1" cellpadding="5" cellspacing="0" align="center" -|- -! colspan="2" align="center" | Origin -|- -| colspan="2" align="center" | [[Image:./../images/EMF_Compare_Origin_Model.png|center]] -|- -! align="center" | Left -! align="center" | Right -|- -| [[Image:./../images/EMF_Compare_Use_Compare_Master.png|center]] -| [[Image:./../images/EMF_Compare_Use_Compare_5.png|center]] -|} - -=== All differences === - -What we need is usually to retrieve the list of ''all'' differences, wherever they were detected, or whatever their source (the left model, or the right model). Instead of iterating all over the Comparison model to collect them, you can use: - -<source lang="java"> -List<Diff> differences = comparison.getDifferences(); -</source> - -=== Differences related to element X === - -Sometimes, we need to retrieve all of the differences that were detected on (or that are related to) a given model element. For example, with the above example, we might want to retrieve the list of all differences that relate to ''Borrowable''. Well, there are a number of them, which can all be collected through: - -<source lang="java"> -// borrowable is a reference on the like-named EObject -List<Diff> differencesOnBorrowable = comparison.getDifferences(borrowable); -</source> - -This will return a list containing a number of differences: - -* ''Borrowable'' has been added in the right model -* ''copies'' has been added to reference ''ownedProperties'' of Borrowable -* ''Borrowable'' has been added to the generalization reference of ''Book'' -* ''Borrowable'' has been added as the ''borrowed'' target of an association with ''Person'' - -In other words, this method will return differences '''under''' the target (here, ''copies'' has been added), as well as differences which '''changed value''' is the target. - -=== Filtering differences === - -EMF Compare depends on guava for many of its internals. A number of "common" difference filtering predicates have been extracted to the ''org.eclipse.emf.compare.utils.EMFComparePredicates'' utility class. Using this class, it is trivial to filter the list of differences so as to keep only those we are interested in. For example, what if we wish to retrieve the list of all '''non-conflictual''' differences that originate from the '''left''' side? (This is the case when you use the "copy all non-conflicting from left to right" action from the comparison editor for example.) - -<source lang="java"> -// Construct the predicate -Predicate<? super Diff> predicate = and(fromSide(DifferenceSource.LEFT), not(hasConflict(ConflictKind.REAL, ConflictKind.PSEUDO)); -// Filter out the diff that do not satisfy the predicate -Iterable<Diff> nonConflictualDifferencesFromLeft = filter(comparison.getDifferences(), predicate); -</source> - -Note that for clarity, we've made static references to a number of methods here. This particular snippet requires the following imports: - -<source lang="java"> -import static com.google.common.base.Predicates.and; -import static com.google.common.base.Predicates.not; -import static com.google.common.collect.Iterables.filter; -import static org.eclipse.emf.compare.utils.EMFComparePredicates.fromSide; -import static org.eclipse.emf.compare.utils.EMFComparePredicates.hasConflict; -</source> - -We strongly encourage you to look around more in these classes: ''Predicates'' provides a number of basic, general-purpose predicates while ''EMFComparePredicates'' provides EMF Compare specific predicates used throughout both core and user-interface of EMF Compare. - -== Merge differences == - -PENDING how to re-implement ''copyDiff'' and ''copyAllNonConflicting'' - -entry points: org.eclipse.emf.compare.merge.IMerger and org.eclipse.emf.compare.merge.IBatchMerger - -== Open a compare editor == - -PENDING description of the need (dialog and editor), link to [[./How%20To%20Open%20Compare%20Dialog%20With%20Comparison|appropriate page]] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/faq/FAQ.html b/plugins/org.eclipse.emf.compare.doc/doc/faq/FAQ.html deleted file mode 100644 index 27532a4f8..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/faq/FAQ.html +++ /dev/null @@ -1,184 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>FAQ</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <p>This FAQ will be aimed at EMF Compare 2 and subsequent versions. Since this version largely differs from the previous 1.* stream, answers related to version 1 cannot apply in most case.</p> - <h1 id="Users">Users</h1> - <h4 id="Which_files_should_be_compared_via_EMF_Compare_.3F">Which files should be compared via EMF Compare ?</h4> - <p> - <b>Q</b> : My model is compared as a text-file, how can EMF compare know the files it should handle ? - </p> - <p> - <b>A</b> : EMF Compare will be triggered for any files that is recognized as an EMF model. There is no specific content-type for EMF Compare; any content-type that has the ecore XMI type as its base will be recognized as a file which comparison should be done with EMF Compare. - </p> - <p>You may add your own extension using the <tt>Preferences view / General / Content-types</tt> and adding your file extension in the "XMI" content-type. </p> - <p> - <img border="0" src="./../images/EMF_Compare_XMI_Content_Type.png"/> - </p> - <h4 id="How_to_force_text_comparison.3F">How to force text comparison?</h4> - <p> - <b>Q</b> : uml, ecore and emfdiff models are "locked" as model files in the aforementioned "EMF Compare" content-type. I want to compare two uml files as text, is there a way to do so? - </p> - <p> - <b>A</b> : There is no way to - <b>force</b> textual comparison of EMF files. You can, however, switch back to a plain text comparison through the drop-down menu that is diplayed between the two halves of the compare editor : - </p> - <p> - <img border="0" src="./../images/EMF_Compare_Text_Comparison.png"/> - </p> - <h4 id="EMF_Compare_compatibility_.3F">EMF Compare compatibility ?</h4> - <p> - <b>Q</b> : Which Java/Eclipse versions can EMF Compare run on? - </p> - <p> - <b>A</b> : EMF Compare is built against JDK 1.5 and makes use of the features it introduced such as foreach and generics. It is therefore incompatible with a JDK < 1.5. EMF Compare can also be used with both JDK 1.6 and JDK 1.7. - </p> - <p>We strive to keep the - <a href="./../overview/Overview.html#Compatibility" title="./../overview/Overview.html#Compatibility">compatibility chart</a> updated so that you can determine which version of EMF Compare can be used in conjunction with your Eclipse of choice. - </p> - <h4 id="Where_can_I_find_EMF_Compare_.3F">Where can I find EMF Compare ?</h4> - <p> - <b>Q</b> : Where can I download the latest version of EMF Compare? - </p> - <p> - <b>A</b> : The - <a href="./../user/Getting%20Started.html#Installing_EMF_Compare" title="./../user/Getting%20Started.html#Installing EMF Compare">Installation instruction</a> present a set of update sites useable to install. - The - <a href="http://www.eclipse.org/emf/compare/downloads/">Download page</a> lists more specific update sites if you wish to try one of the latest integration builds. - </p> - <h1 id="Developers">Developers</h1> - <h2 id="How_can_I_programmatically_add_my_model_file_extension_in_EMF_Compare_so_that_it_is_called_automatically_.3F">How can I programmatically add my model file extension in EMF Compare so that it is called automatically ?</h2> - <p> - <b>Q</b> : How can I programatically add my model file extension to EMF Compare so that it is called automatically ? - </p> - <p> - <b>A</b> : You can do so using the exore XMI content-type, here is a sample from a plugin.xml: - </p> - <pre class="source-xml"><extension - point="org.eclipse.core.contenttype.contentTypes"> - <file-association - content-type="org.eclipse.emf.ecore.xmi" - file-extensions="uml" - file-names="*"/> -</extension> - -</pre> - <h2 id="How_can_I_use_EMF_Compare_programmatically_.3F">How can I use EMF Compare programmatically ?</h2> - <p> - <b>Q</b> : How can I use EMF Compare programmatically, to compare either files or "in-memory" objects? - </p> - <p> - <b>A</b> : Many samples of how to compare objects can be found within - <a href="http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare.tests">the unit tests of EMF Compare</a> (see also - <a href="EMF_Compare/Contributor_Guide#Checking_out_the_code" title="EMF_Compare/Contributor_Guide#Checking_out_the_code">how to checkout the source code</a>). Here is a sample that should cover the basic use case (the class with this method should have a dependency towards the - <i>org.eclipse.emf.compare</i> plugin) : - </p> - <pre class="source-java">public void compare(File model1, File model2) { - URI uri1 = URI.createFileURI("path/to/first/model.xmi"); - URI uri2 = URI.createFileURI("path/to/second/model.xmi"); - - Resource.Factory.Registry.INSTANCE.getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); - - ResourceSet resourceSet1 = new ResourceSetImpl(); - ResourceSet resourceSet2 = new ResourceSetImpl(); - - resourceSet1.getResource(uri1, true); - resourceSet2.getResource(uri2, true); - - IComparisonScope scope = new DefaultComparisonScope(resourceSet1, resourceSet2); - Comparison comparison = EMFCompare.builder().build().compare(scope); - - List<Diff> differences = comparison.getDifferences(); - // Let's merge every single diff - IMerger.Registry mergerRegistry = new IMerger.RegistryImpl(); - IBatchMerger merger = new BatchMerger(mergerRegistry); - merger.copyAllLeftToRight(differences, new BasicMonitor()); -} - -</pre> - <h2 id="Can_EMF_Compare_be_used_standalone_.3F">Can EMF Compare be used standalone ?</h2> - <p> - <b>Q</b> : Is EMF Compare able to compare "in-memory" objects, and can it be run without Eclipse ? - </p> - <p> - <b>A</b>: Yes, the core of EMF Compare is developed primarily for standalone, the integration with Eclipse being built on top of that. All of the classes and utilities located in the - <i>org.eclipse.emf.compare</i> plugin are pure Java with no dependency towards Eclipse, and can thus safely be used within a Java application running outside of Eclipse. - </p> - <p>The following is the minimal set of dependencies you will need for EMF Compare.</p> - <pre>* org.eclipse.emf.common 2.5 or higher -* org.eclipse.emf.ecore 2.5 or higher -* org.eclipse.emf.ecore.xmi 2.5 or higher -* org.eclipse.emf.compare 2.0 or higher -* com.google.guava 11.0 (EMF Compare should also be compatible with Guava 12, 13 and 14 as far as we tested our integration) -</pre> - <h2 id="Custom_data_types_are_always_marked_as_modified_by_EMF_Compare">Custom data types are always marked as modified by EMF Compare</h2> - <p> - <b>Q</b> : A model based on a custom meta-model always shows elements of a custom data type as being changed. How can I have EMF Compare behave correctly? - </p> - <p> - <b>A</b> : The differencing process of EMF Compare is based on equality helpers. For data types, this depends upon the return value of these data types' - <i>equals(Object)</i> method. It will thus fail to determine whether two objects match if their - <i>equals(Object)</i> methods has not been overriden in the custom data type's instance class. Remember to also override - <i>hashCode()</i> when overriding - <i>equals(Object)</i>. A Typical example of this is - <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=226152">bug 226152</a>. - </p> - <p>Another way around this problem would be to contribute your own equality helper to EMF Compare so that it knows how to compare these kind of data types. That could be done through the EMFCompare builder :</p> - <pre class="source-java">IEqualityHelperFactory helperFactory = new DefaultEqualityHelperFactory() { - @Override - public org.eclipse.emf.compare.utils.IEqualityHelper createEqualityHelper() { - final Cache<EObject, URI> cache = EqualityHelper.createDefaultCache(getCacheBuilder()); - return new EqualityHelper(cache) { - @Override - public boolean matchingValues(Object object1, Object object2) { - if (object1 instanceof MyDataType && object2 instanceof MyDataType) { - // custom code - } - return super.matchingValues(object1, object2); - } - }; - } -}; -IComparisonFactory comparisonFactory = new DefaultComparisonFactory(helperFactory); -Comparison comparison = EMFCompare.builder().setMatchEngine(new DefaultMatchEngine(DefaultMatchEngine - .createDefaultEObjectMatcher(UseIdentifiers.WHEN_AVAILABLE), comparisonFactory)).build().compare(scope); - -</pre> - <h2 id="Can_I_programmatically_open_a_comparison_editor_or_dialog_.3F">Can I programmatically open a comparison editor or dialog ?</h2> - <p> - <b>Q</b> : I need to call EMF Compare programmatically from within my own plugin, but I'd like to be able to show my users a comparison editor. Is there a way? - </p> - <p> - <b>A</b> : Since EMF Compare 2.1.0M4, there is. As the answer to this question is a little complex, it deserves - <a href="./../developer/How%20To%20Open%20Compare%20Dialog%20With%20Comparison.html" title="./../developer/How%20To%20Open%20Compare%20Dialog%20With%20Comparison.html">its own page</a>. - </p> - <h2 id="Can_I_use_custom_identifiers_for_my_objects_.3F">Can I use custom identifiers for my objects ?</h2> - <p> - <b>Q</b> : I have my own custom elements, and I'd like to tell EMF Compare what to use to uniquely identify them. For example, their name. - </p> - <p> - <b>A</b> : EMF Compare internally uses a function in order to compute the identifier of an EObject. You can override this function with your own, or compose your own with it so that EMF Compare will use your function for your elements, and fall back to the default behavior for any other element it needs to match. - </p> - <p>How to do this is outlined on the - <a href="./../developer/Default%20Behavior%20and%20Extensibility.html#Defining_custom_identifiers" title="./../developer/Default%20Behavior%20and%20Extensibility.html#Defining custom identifiers">Developer Guide</a>. - </p> - <h2 id="Can_I_ignore_differences_on_a_specific_reference.2C_or_ignore_ordering_differences_.3F">Can I ignore differences on a specific reference, or ignore ordering differences ?</h2> - <p> - <b>Q</b> : I want to ignore all differences on a given structural feature, can I tell EMF Compare not to look at these features? - <br/> - - <b>Q</b> : EMF Compare detects many - <i>ordering</i> differences on my models, but I do not care about them. Is there a way to ignore all ordering changes? - </p> - <p> - <b>A</b> : You can override the - <i>FeatureFilter</i> to tell EMF Compare that some references should be ignored, there is an example doing just that in the - <a href="./../developer/Default%20Behavior%20and%20Extensibility.html##Changing_the_FeatureFilter" title="./../developer/Default%20Behavior%20and%20Extensibility.html##Changing the FeatureFilter">Developer Guide</a>. - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/index.html b/plugins/org.eclipse.emf.compare.doc/doc/index.html deleted file mode 100644 index 1b00f2253..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/index.html +++ /dev/null @@ -1,54 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>index</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="EMF_Compare_Documentation">EMF Compare Documentation</h1> - <ul> - <li> - <a href="overview/Overview.html" title="overview/Overview.html">Overview</a> - </li> - <li> - <a href="user/EMF%20Compare%20User%20Guide.html" title="user/EMF%20Compare%20User%20Guide.html">EMF Compare User Guide</a> - <ul> - <li> - <a href="user/Getting%20Started.html" title="user/Getting%20Started.html">Getting Started</a> - </li> - <li> - <a href="user/Features.html" title="user/Features.html">Features</a> - </li> - <li> - <a href="user/Known%20Bugs%20and%20Limitations.html" title="user/Known%20Bugs%20and%20Limitations.html">Known Bugs and Limitations</a> - </li> - <li> - <a href="user/Other%20Materials.html" title="user/Other%20Materials.html">Other Materials</a> - </li> - </ul> - </li> - <li> - <a href="developer/EMF%20Compare%20Developer%20Guide.html" title="developer/EMF%20Compare%20Developer%20Guide.html">EMF Compare Developer Guide</a> - <ul> - <li> - <a href="developer/Architecture.html" title="developer/Architecture.html">Architecture</a> - </li> - <li> - <a href="developer/Core%20Concepts.html" title="developer/Core%20Concepts.html">Core Concepts</a> - </li> - <li> - <a href="developer/Default%20Behavior%20and%20Extensibility.html" title="developer/Default%20Behavior%20and%20Extensibility.html">Default Behavior and Extensibility</a> - </li> - <li> - <a href="developer/Using%20The%20Compare%20APIs.html" title="developer/Using%20The%20Compare%20APIs.html">Using The Compare APIs</a> - </li> - </ul> - </li> - <li> - <a href="faq/FAQ.html" title="faq/FAQ.html">FAQ</a> - </li> - </ul> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/index.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/index.mediawiki deleted file mode 100644 index 4e28485e6..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/index.mediawiki +++ /dev/null @@ -1,14 +0,0 @@ -= EMF Compare Documentation = - -* [[overview/Overview.html|Overview]] -* [[user/EMF%20Compare%20User%20Guide.html|EMF Compare User Guide]] -** [[user/Getting%20Started.html|Getting Started]] -** [[user/Features.html|Features]] -** [[user/Known%20Bugs%20and%20Limitations.html|Known Bugs and Limitations]] -** [[user/Other%20Materials.html|Other Materials]] -* [[developer/EMF%20Compare%20Developer%20Guide.html|EMF Compare Developer Guide]] -** [[developer/Architecture.html|Architecture]] -** [[developer/Core%20Concepts.html|Core Concepts]] -** [[developer/Default%20Behavior%20and%20Extensibility.html|Default Behavior and Extensibility]] -** [[developer/Using%20The%20Compare%20APIs.html|Using The Compare APIs]] -* [[faq/FAQ.html|FAQ]]
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/overview/Overview.html b/plugins/org.eclipse.emf.compare.doc/doc/overview/Overview.html deleted file mode 100644 index 610d8dfdb..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/overview/Overview.html +++ /dev/null @@ -1,176 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Overview</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <p>The - <a href="http://www.eclipse.org/emf/compare">EMF Compare</a> project is part of EMF (Eclipse Modeling Framework). - </p> - <p> - <img border="0" src="./../images/Emf_logo.png"/> - </p> - <p>EMF Compare brings model comparison to the EMF framework, this tool provides generic support for any kind of metamodel in order to compare and merge models. The objectives of this component are to provide a stable and efficient generic implementation of model comparison and to provide an extensible framework for specific needs. </p> - <h1 id="Overview">Overview</h1> - <p> - <div class="thumb middle"> - <div class="thumbinner" style="width:802px;"> - <a href="./../images/EMF_Compare_Process_Full.png" class="image"> - <img class="thumbimage" width="800" align="middle" border="0" src="./../images/EMF_Compare_Process_Full.png"/> - </a> - </div> - </div> - </p> - <p>The above figure represents the comparison process of EMF Compare. It can be roughly divided in 6 main phases.</p> - <dl> - <dt>Model Resolving</dt> - <dd>From a given "starting point" (the file a user decided to compare), finding all other fragments required for the comparison of the whole logical model.</dd> - <dt>Matching</dt> - <dd>Iterating over the two (or three) loaded logical models in order to map elements together two-by-two (or three-by-three). For example, determine that class - <i>Class1</i> from the first model corresponds to class - <i>Class1</i>' from the second model. - </dd> - <dt>Differencing</dt> - <dd>The matching phase told us which elements were matching together. The differencing phase will browse through these mappings and determine whether the two (or three) elements are equal or if they present differences (for example, the name of the class changed from - <i>Class1</i> to - <i>Class1</i>'). - </dd> - <dt>Equivalences</dt> - <dd>The differencing phases detected a number of differences between the compared models. However, two distinct differences might actually represent the same change. This phase will browse through all differences and link them together when they can be seen as equivalent (for example, differences on opposite references).</dd> - <dt>Requirements</dt> - <dd>For the purpose of merging differences, there might be dependencies between them. For example, the addition of a class - <i>C1</i> in package - <i>P1</i> depends on the addition of package - <i>P1</i> itself. During this phase, we'll browse through all detected differences and link them together when we determine that one cannot be merged without the other. - </dd> - <dt>Conflicts</dt> - <dd>When we're comparing our file with one from a Version Control System (CVS, SVN, Git, Clearcase...), there might actually be conflicts between the changes we've made locally, and the changes that were made to the file on the remote repository. This phase will browse through all detected differences and detect these conflicts.</dd> - </dl> - <p>The Model resolving phase itself can be further decomposed in its own two distinct phases. More on the logical model and its resolution can be found on - <a href="./../developer/Logical%20Model.html" title="./../developer/Logical%20Model.html">the dedicated page</a>. - </p> - <p> - <div class="thumb middle"> - <div class="thumbinner" style="width:802px;"> - <a href="./../images/EMF_Compare_Model_Resolving.png" class="image"> - <img class="thumbimage" width="800" align="middle" border="0" src="./../images/EMF_Compare_Model_Resolving.png"/> - </a> - </div> - </div> - </p> - <h2 id="Compatibility">Compatibility</h2> - <p>The EMF Compare development team does its best to maintain downward compatibility towards Galileo (3.5). Following is the compatibility chart : </p> - <table border="1"> - <tr> - <th>EMF Compare </th> - <th bgcolor="#cccccc" align="center">Eclipse 4.3 - EMF 2.9</th> - <th align="center">Eclipse 4.2 - EMF 2.8</th> - <th align="center">Eclipse 3.8 - EMF 2.8 </th> - <th align="center">Eclipse 3.7 - EMF 2.7 </th> - <th align="center">Eclipse 3.6 - EMF 2.6 </th> - <th align="center">Eclipse 3.5 - EMF 2.5 </th> - <th align="center">Eclipse 3.4 - EMF 2.4</th> - <th align="center">Eclipse 3.3 - EMF 2.3</th> - <th align="center">Eclipse 3.2 - EMF 2.2 </th> - </tr> - <tr> - <td bgcolor="#cccccc" align="center">2.1</td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">2.0</td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.3</td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.2 </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.1 </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.0 </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - </table> - <p>An empty cell indicates that the compatibility hasn't been tested for a particular combination.</p> - <h2 id="Team">Team</h2> - <p>The project developers are: </p> - <ul> - <li>Cedric Brun ( - <a href="http://www.obeo.fr">Obeo</a>), project lead - </li> - <li>Laurent Goubet ( - <a href="http://www.obeo.fr">Obeo</a>) - </li> - <li>Mikael Barbero ( - <a href="http://www.obeo.fr">Obeo</a>) - </li> - <li>Cedric Notot ( - <a href="http://www.obeo.fr">Obeo</a>) - </li> - <li>Axel Richard ( - <a href="http://www.obeo.fr">Obeo</a>) - </li> - </ul> - <p>More information about the code aspects and activity of this project can be found on the - <a href="http://www.eclipse.org/projects/project.php?id=modeling.emf.compare">project page</a> - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/overview/Overview.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/overview/Overview.mediawiki deleted file mode 100644 index 646feb037..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/overview/Overview.mediawiki +++ /dev/null @@ -1,126 +0,0 @@ -The [http://www.eclipse.org/emf/compare EMF Compare] project is part of EMF (Eclipse Modeling Framework). - -[[Image:./../images/Emf_logo.png]] - -EMF Compare brings model comparison to the EMF framework, this tool provides generic support for any kind of metamodel in order to compare and merge models. The objectives of this component are to provide a stable and efficient generic implementation of model comparison and to provide an extensible framework for specific needs. - -= Overview = - -[[Image:./../images/EMF_Compare_Process_Full.png|thumb|center|800px]] - -The above figure represents the comparison process of EMF Compare. It can be roughly divided in 6 main phases. -; Model Resolving -: From a given "starting point" (the file a user decided to compare), finding all other fragments required for the comparison of the whole logical model. -; Matching -: Iterating over the two (or three) loaded logical models in order to map elements together two-by-two (or three-by-three). For example, determine that class ''Class1'' from the first model corresponds to class ''Class1''' from the second model. -; Differencing -: The matching phase told us which elements were matching together. The differencing phase will browse through these mappings and determine whether the two (or three) elements are equal or if they present differences (for example, the name of the class changed from ''Class1'' to ''Class1'''). -; Equivalences -: The differencing phases detected a number of differences between the compared models. However, two distinct differences might actually represent the same change. This phase will browse through all differences and link them together when they can be seen as equivalent (for example, differences on opposite references). -; Requirements -: For the purpose of merging differences, there might be dependencies between them. For example, the addition of a class ''C1'' in package ''P1'' depends on the addition of package ''P1'' itself. During this phase, we'll browse through all detected differences and link them together when we determine that one cannot be merged without the other. -; Conflicts -: When we're comparing our file with one from a Version Control System (CVS, SVN, Git, Clearcase...), there might actually be conflicts between the changes we've made locally, and the changes that were made to the file on the remote repository. This phase will browse through all detected differences and detect these conflicts. - - -The Model resolving phase itself can be further decomposed in its own two distinct phases. More on the logical model and its resolution can be found on [[./../developer/Logical%20Model.html|the dedicated page]]. - -[[Image:./../images/EMF_Compare_Model_Resolving.png|thumb|center|800px]] - -== Compatibility == - -The EMF Compare development team does its best to maintain downward compatibility towards Galileo (3.5). Following is the compatibility chart : - -{| border="1" -|- -! EMF Compare -! bgcolor="#cccccc" align="center" | Eclipse 4.3 - EMF 2.9 -! align="center" | Eclipse 4.2 - EMF 2.8 -! align="center" | Eclipse 3.8 - EMF 2.8 -! align="center" | Eclipse 3.7 - EMF 2.7 -! align="center" | Eclipse 3.6 - EMF 2.6 -! align="center" | Eclipse 3.5 - EMF 2.5 -! align="center" | Eclipse 3.4 - EMF 2.4 -! align="center" | Eclipse 3.3 - EMF 2.3 -! align="center" | Eclipse 3.2 - EMF 2.2 -|- -| bgcolor="#cccccc" align="center" | 2.1 -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -|- -| align="center" | 2.0 -| bgcolor="#ffffff" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -|- -| align="center" | 1.3 -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -|- -| align="center" | 1.2 -| bgcolor="#ffffff" | -| bgcolor="#ffffff" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -|- -| align="center" | 1.1 -| bgcolor="#ffffff" | -| bgcolor="#ffffff" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#9d261d" | -| bgcolor="#9d261d" | -|- -| align="center" | 1.0 -| bgcolor="#ffffff" | -| bgcolor="#ffffff" | -| bgcolor="#ffffff" | -| bgcolor="#ffffff" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#46a546" | -| bgcolor="#9d261d" | -|} - -An empty cell indicates that the compatibility hasn't been tested for a particular combination. - -== Team == - -The project developers are: - -* Cedric Brun ([http://www.obeo.fr Obeo]), project lead -* Laurent Goubet ([http://www.obeo.fr Obeo]) -* Mikael Barbero ([http://www.obeo.fr Obeo]) -* Cedric Notot ([http://www.obeo.fr Obeo]) -* Axel Richard ([http://www.obeo.fr Obeo]) - -More information about the code aspects and activity of this project can be found on the [http://www.eclipse.org/projects/project.php?id=modeling.emf.compare project page] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/toc.xml b/plugins/org.eclipse.emf.compare.doc/doc/toc.xml deleted file mode 100644 index 343ac1dd5..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/toc.xml +++ /dev/null @@ -1,69 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?> -<!-- - Copyright (c) 2013 Obeo - 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: - Obeo - Initial API and implementation ---> -<toc label="EMF Compare"> - <topic href="doc/overview/Overview.html" label="Overview"/> - <topic href="doc/user/EMF Compare User Guide.html" label="EMF Compare User Guide"> - <anchor id="userStart"/> - <topic href="doc/user/Getting Started.html" label="Getting Started"> - <topic href="doc/user/Getting Started.html#InstallingEMFCompare" label="Installing EMF Compare" /> - <topic href="doc/user/Getting Started.html#UserInterfaceBreakdown" label="User Interface Breakdown" /> - <topic href="doc/user/Getting Started.html#Usage" label="Usage" /> - </topic> - <topic href="doc/user/Features.html" label="Features"> - <topic href="doc/user/Features.html#HandlingConflicts" label="Handling Conflicts" /> - <topic href="doc/user/Features.html#FilteringDifferences" label="Filtering Differences" /> - <topic href="doc/user/Features.html#TextAttributeComparison" label="Text Attribute Comparison" /> - <topic href="doc/user/Features.html#GraphicalComparison" label="Graphical Comparison" /> - <topic href="doc/user/Features.html#LogicalModel" label="Logical Model" /> - <topic href="doc/user/Features.html#UMLSpecialization" label="UML Specialization" /> - </topic> - <topic href="doc/user/Known Bugs and Limitations.html" label="Known Bugs and Limitations"> - <topic href="doc/user/Known Bugs and Limitations.html#ProjectNamesAndLocation" label="Project Names And Location" /> - <topic href="doc/user/Known Bugs and Limitations.html#ModelsOutOfTheWorkspace" label="Models Out Of The Workspace" /> - </topic> - <topic href="doc/user/Other Materials.html" label="Other Materials"/> - <anchor id="moreUserRefs"/> - </topic> - <topic href="doc/developer/EMF Compare Developer Guide.html" label="EMF Compare Developer Guide"> - <anchor id="userStart"/> - <topic href="doc/developer/Architecture.html" label="Architecture"> - <topic href="doc/developer/Architecture.html#ComparisonProcess" label="Comparison Process" /> - <topic href="doc/developer/Architecture.html#ProjectArchitecture" label="Project Architecture" /> - <topic href="doc/developer/Architecture.html#TheComparisonModel" label="The Comparison Model" /> - </topic> - <topic href="doc/developer/Core Concepts.html" label="Core Concepts"> - <topic href="doc/developer/Core Concepts.html#ProxyResoluton" label="Proxy Resolution" /> - <topic href="doc/developer/Core Concepts.html#EqualityHelper" label="Equality Helper" /> - <topic href="doc/developer/Core Concepts.html#ComparisonScope" label="Comparison Scope" /> - <topic href="doc/developer/Core Concepts.html#LongestCommonSubsequence" label="Longest Common Subsequence" /> - </topic> - <topic href="doc/developer/Default Behavior and Extensibility.html" label="Default Behavior and Extensibility"> - <topic href="doc/developer/Default Behavior and Extensibility.html#ModelResolving" label="Model Resolving" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Match" label="Match" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Diff" label="Diff" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Equivalences" label="Equivalences" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Requirements" label="Requirements" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Refinement" label="Refinement" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Conflicts" label="Conflicts" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#Merging" label="Merging" /> - <topic href="doc/developer/Default Behavior and Extensibility.html#UserInterface" label="User Interface" /> - </topic> - <topic href="doc/developer/Using The Compare APIs.html" label="Using The Compare APIs"> - <topic href="doc/developer/Using The Compare APIs.html#CompareTwoModels" label="Compare Two Models" /> - <topic href="doc/developer/Using The Compare APIs.html#QueryTheDifferences" label="Query The Differences" /> - <topic href="doc/developer/Using The Compare APIs.html#MergeDifferences" label="Merge Differences" /> - <topic href="doc/developer/Using The Compare APIs.html#OpenACompareEditor" label="Open a Compare Editor" /> - </topic> - <anchor id="moreUserRefs"/> - </topic> - <topic href="doc/faq/FAQ.html" label="FAQ"/> -</toc> diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/EMF Compare User Guide.html b/plugins/org.eclipse.emf.compare.doc/doc/user/EMF Compare User Guide.html deleted file mode 100644 index 626387c77..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/EMF Compare User Guide.html +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>EMF Compare User Guide</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="EMF_Compare_User_Guide">EMF Compare User Guide</h1> - <p>You will find the following sections:</p> - <ul> - <li> - <a href="Getting%20Started.html" title="Getting%20Started.html">Getting Started</a> explains how to install EMF Compare and use the simple UI to your models. - </li> - <li> - <a href="Features.html" title="Features.html">Features</a> shows all the common features of EMF Compare. - </li> - <li> - <a href="Known%20bugs%20and%20limitations.html" title="Known%20bugs%20and%20limitations.html">Known bugs and limitations</a> - </li> - <li> - <a href="Other%20materials.html" title="Other%20materials.html">Other materials</a> - </li> - </ul> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/EMF Compare User Guide.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/user/EMF Compare User Guide.mediawiki deleted file mode 100644 index 1cefeb22c..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/EMF Compare User Guide.mediawiki +++ /dev/null @@ -1,7 +0,0 @@ -= EMF Compare User Guide = - -You will find the following sections: -* [[Getting%20Started.html | Getting Started]] explains how to install EMF Compare and use the simple UI to your models. -* [[Features.html | Features]] shows all the common features of EMF Compare. -* [[Known%20bugs%20and%20limitations.html | Known bugs and limitations]] -* [[Other%20materials.html | Other materials]] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Features.html b/plugins/org.eclipse.emf.compare.doc/doc/user/Features.html deleted file mode 100644 index 2bc456459..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Features.html +++ /dev/null @@ -1,116 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Features</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Features">Features</h1> - <h2 id="Handling_Conflicts">Handling Conflicts</h2> - <p>PENDING</p> - <h2 id="Grouping_Differences">Grouping Differences</h2> - <p>This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides three distinct grouping strategies :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Groups_Choice.png"/> - </p> - <dl> - <dt>Default</dt> - <dd>Do not try and group differences together, display them as they were detected.</dd> - </dl> - <p> - <img border="0" src="./../images/EMF_Compare_Groups_Default.png"/> - </p> - <dl> - <dt>By Kind</dt> - <dd>Group differences by their kind ( - <i>additions</i>, - <i>deletions</i>, - <i>moves</i>, - <i>changes</i>). - </dd> - </dl> - <p> - <img border="0" src="./../images/EMF_Compare_Groups_Kind.png"/> - </p> - <dl> - <dt>By Side</dt> - <dd>Group differences according to their side: left or right and a special group regrouping differences in conflicts with other differences together.</dd> - </dl> - <p> - <img border="0" src="./../images/EMF_Compare_Groups_Side.png"/> - </p> - <p>PENDING UPDATE, this is a demo displaying EMF Compare 1.3 - - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/Groups/groups.htm">Demo</a> - </p> - <p>PENDING : New grouping strategies can be provided to EMF Compare through extension points.</p> - <h2 id="Filtering_Differences">Filtering Differences</h2> - <p>This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides five distinct filters :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Filters_Choice.png"/> - </p> - <dl> - <dt>Pseudo conflicts differences</dt> - <dd>Filter out all pseudo conflicts differences(only in 3-way comparison). Enabled by default.</dd> - <dt>Identical elements</dt> - <dd>Filter out all identical elements (elements with no differences). Enabled by default.</dd> - <dt>Empty Resource Mappings</dt> - <dd>Filter out all resource mappings with no differences from the view. Enabled by default.</dd> - <dt>Cascading differences</dt> - <dd>Filter out all differences that are contained under differences (except when in conflict). Enabled by default.</dd> - </dl> - <p>PENDING UPDATE, this is a demo displaying EMF Compare 1.3 - - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/Filters/filters.htm">Demo</a> - </p> - <p>PENDING : New filters can be provided to EMF Compare through extension points.</p> - <h2 id="Text_Attribute_Comparison">Text Attribute Comparison</h2> - <p>Differences made into - <i>String</i>-typed attributes can be compared and merged directly as text from the compare interface through a simple right-click on the difference. - </p> - <p> - <img border="0" src="./../images/EMF_Compare_Text_Compare.png"/> - </p> - <p>PENDING UPDATE, this demo displays EMF Compare 1.3 - - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/Text%20compare/textCompare.htm">Demo</a> - </p> - <h2 id="Graphical_Comparison">Graphical Comparison</h2> - <p>PENDING UPDATE</p> - <p>Since the 1.2 release EMF compare provides the ability to compare models with graphical modelers. </p> - <p>Have a look on the following demos :</p> - <p> - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html" title="http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html">Demo : Comparing Ecore files with diagrams</a> - </p> - <p> - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html" title="http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html">Demo : Comparing UML files with diagrams</a> - </p> - <p> - <img border="0" src="./../images/Diag_comp_diff.png"/> - </p> - <h2 id="Logical_Model">Logical Model</h2> - <p>EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF - <i>control</i> action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a - <i>genmodel</i> file (that depends on its underlying - <i>ecore</i> file) : - </p> - <p> - <img border="0" src="./../images/EMF_Compare_Logical_Compare_Action.png"/> - </p> - <p>EMF Compare will actually consider both files when comparing :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Logical_Compare_Result.png"/> - </p> - <p>PENDING UPDATE - - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/LogicalModels/LogicalModels.html">Demo</a> - </p> - <h2 id="UML_Specialization">UML Specialization</h2> - <p>PENDING</p> - <p> - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm" title="http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm">Demo : Specific support to encapsulate profiles and stereotypes diffs</a> - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Features.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/user/Features.mediawiki deleted file mode 100644 index 070425840..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Features.mediawiki +++ /dev/null @@ -1,86 +0,0 @@ -= Features = - -== Handling Conflicts == - -PENDING - -== Grouping Differences == - -This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides three distinct grouping strategies : - -[[Image:./../images/EMF_Compare_Groups_Choice.png]] - -; Default : Do not try and group differences together, display them as they were detected. - -[[Image:./../images/EMF_Compare_Groups_Default.png]] - -; By Kind : Group differences by their kind (''additions'', ''deletions'', ''moves'', ''changes''). - -[[Image:./../images/EMF_Compare_Groups_Kind.png]] - -; By Side : Group differences according to their side: left or right and a special group regrouping differences in conflicts with other differences together. - -[[Image:./../images/EMF_Compare_Groups_Side.png]] - -PENDING UPDATE, this is a demo displaying EMF Compare 1.3 -[http://www.eclipse.org/emf/compare/doc/features/videos/Groups/groups.htm Demo] - -PENDING : New grouping strategies can be provided to EMF Compare through extension points. - -== Filtering Differences == - -This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides five distinct filters : - -[[Image:./../images/EMF_Compare_Filters_Choice.png]] - -; Pseudo conflicts differences : Filter out all pseudo conflicts differences(only in 3-way comparison). Enabled by default. -; Identical elements : Filter out all identical elements (elements with no differences). Enabled by default. -; Empty Resource Mappings : Filter out all resource mappings with no differences from the view. Enabled by default. -; Cascading differences : Filter out all differences that are contained under differences (except when in conflict). Enabled by default. - -PENDING UPDATE, this is a demo displaying EMF Compare 1.3 -[http://www.eclipse.org/emf/compare/doc/features/videos/Filters/filters.htm Demo] - -PENDING : New filters can be provided to EMF Compare through extension points. - -== Text Attribute Comparison == - -Differences made into ''String''-typed attributes can be compared and merged directly as text from the compare interface through a simple right-click on the difference. - -[[Image:./../images/EMF_Compare_Text_Compare.png]] - -PENDING UPDATE, this demo displays EMF Compare 1.3 -[http://www.eclipse.org/emf/compare/doc/features/videos/Text%20compare/textCompare.htm Demo] - -== Graphical Comparison == - -PENDING UPDATE - -Since the 1.2 release EMF compare provides the ability to compare models with graphical modelers. - -Have a look on the following demos : - -[[http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html | Demo : Comparing Ecore files with diagrams]] - -[[http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html | Demo : Comparing UML files with diagrams]] - -[[Image:./../images/Diag_comp_diff.png]] - -== Logical Model == - -EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF ''control'' action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a ''genmodel'' file (that depends on its underlying ''ecore'' file) : - -[[Image:./../images/EMF_Compare_Logical_Compare_Action.png]] - -EMF Compare will actually consider both files when comparing : - -[[Image:./../images/EMF_Compare_Logical_Compare_Result.png]] - -PENDING UPDATE -[http://www.eclipse.org/emf/compare/doc/features/videos/LogicalModels/LogicalModels.html Demo] - -== UML Specialization == - -PENDING - -[[http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm | Demo : Specific support to encapsulate profiles and stereotypes diffs]] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Getting Started.html b/plugins/org.eclipse.emf.compare.doc/doc/user/Getting Started.html deleted file mode 100644 index c036302e5..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Getting Started.html +++ /dev/null @@ -1,275 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Getting Started</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Getting_Started">Getting Started</h1> - <h2 id="Installing_EMF_Compare">Installing EMF Compare</h2> - <p> - <b>Marketplace Client</b> - </p> - <p>Using the bundled Eclipse marketplace client you can install EMF Compare in one click. Just type "emf compare", click on search, and then on install. </p> - <p> - <img border="0" src="./../images/Marketplace.png"/> - </p> - <p> - <b>Update Site</b> - </p> - <p>EMF has been part of the Eclipse release train since Galileo, you can install it using the following update sites, depending on your platform. - <b>Note</b> that the following are not meant to be visited in your internet browser; they must be pasted in the - <i>Help > Install New Software</i> dialog of your Eclipse, as p2 repositories. - </p> - <pre> http://download.eclipse.org/releases/juno - http://download.eclipse.org/releases/indigo - http://download.eclipse.org/releases/helios - http://download.eclipse.org/releases/galileo -</pre> - <p>The - <a href="http://www.eclipse.org/emf/compare/downloads/">Download page</a> lists more specific update sites if you wish to try one of the latest integration builds. - </p> - <p> - <b>Compatibility</b> - </p> - <p>Please note that the EMF Compare development team does its best to maintain downward compatibility towards Galileo (Eclipse 3.5). Following is the compatibility chart : </p> - <table border="1"> - <tr> - <th>EMF Compare </th> - <th bgcolor="#cccccc" align="center">Eclipse 4.3 - EMF 2.9</th> - <th align="center">Eclipse 4.2 - EMF 2.8</th> - <th align="center">Eclipse 3.8 - EMF 2.8 </th> - <th align="center">Eclipse 3.7 - EMF 2.7 </th> - <th align="center">Eclipse 3.6 - EMF 2.6 </th> - <th align="center">Eclipse 3.5 - EMF 2.5 </th> - <th align="center">Eclipse 3.4 - EMF 2.4</th> - <th align="center">Eclipse 3.3 - EMF 2.3</th> - <th align="center">Eclipse 3.2 - EMF 2.2 </th> - </tr> - <tr> - <td bgcolor="#cccccc" align="center">2.1</td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">2.0</td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.3</td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.2 </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.1 </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - <tr> - <td align="center">1.0 </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#ffffff"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#46a546"> </td> - <td bgcolor="#9d261d"> </td> - </tr> - </table> - <p>An empty cell indicates that the compatibility hasn't been tested for a particular combination.</p> - <h2 id="User_Interface_Breakdown">User Interface Breakdown</h2> - <p>The main points of interest are highlighted in the following picture :</p> - <p> - <img align="middle" title="EMF Compare's basic user interface" alt="EMF Compare's basic user interface" border="0" src="./../images/CompareUI.png"/> - </p> - <ol> - <li>Overview of the differences detected between the given two (or three) models.</li> - <li>First version of the compared models.</li> - <li>Second version of the compared models.</li> - <li>This button will only be visible in the case of three-way comparisons (for example, comparing with a remote repository). It will make a third version of the compared model (the common ancestor of the two others) visible in the interface.</li> - <li>This button will allow you to group differences together in the structural view. For example, grouping all "Additions" or "Deletions" together.</li> - <li>This button will allow you to filter some differences out of the view according to a set predicate. For example, filtering out all "Additions" or "Moves".</li> - <li>Allows you to merge all non conflicting differences (left to right, or right to left) at once.</li> - <li>Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left).</li> - <li>Allows you to navigate through the detected differences.</li> - </ol> - <h2 id="Usage">Usage</h2> - <p>Once installed, you can compare your files (locally or from any Version Control System) as usual using the - <b>compare with</b> menu. - </p> - <p> - <img align="middle" border="0" src="./../images/EMFC_Compare_With.png"/> - </p> - <p>The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on - <a href="./Sample%20Use%20Case.html" title="./Sample%20Use%20Case.html">Sample Use Case</a> - </p> - <h3 id="Compare_with_latest">Compare with latest</h3> - <p>For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations.</p> - <p>The name of our sample project will be "library". It contains a single folder "model" containing two models :</p> - <ul> - <li>library_Types.uml will contain our primitive types,</li> - <li>library.uml will contain our actual model.</li> - </ul> - <p>The model itself is a very simple library. Graphically speaking :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Model.png"/> - </p> - <p>We commit this initial file as the original model. We then slightly modify it so that it now looks like :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Model_Changed.png"/> - </p> - <p>But how do we know exactly what changed? Let's compare this with the file from the Git Index :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_1.png"/> - </p> - <p>This will open a comparison editor that initially displays empty panels on its bottom half. Let's select one of the differences displayed on its top half :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_3.png"/> - </p> - <ol> - <li>We've selected the difference corresponding to the addition of attribute - <b>alias</b> in the class - <b>Writer</b>. A double-click on this difference updated our two panes below. - </li> - <li> - <b>alias</b> has been added to the properties of Class - <b>Writer</b>. In the model, this corresponds to a change to the reference - <i>ownedAttributes</i> of the - <i>Writer</i> Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context. - </li> - <li>This displays all values of the reference outlined in (2) as they are in the - <i>left</i> model. This is where we see the new value, - <b>alias</b> outlined. - </li> - <li>As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).</li> - <li>This panel displays all values of the reference outlined in (4) as they are in the - <i>right</i> model. In here, we see the location of - <b>alias</b> outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the - <i>right</i> : it is a version located on a repository and is thus non-editable. - </li> - </ol> - <p>This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes on the - <i>master</i> branch. - </p> - <h3 id="Compare_two_differing_branches">Compare two differing branches</h3> - <p>After that, our model can evolve, and evolve separately in multiple branches. Let's consider the case where we would have a - <i>master</i> branch differing from a - <i>borrowables</i> branch such as the two look like this (the branching point was the model we've already displayed above) : - </p> - <table border="1" cellpadding="5" cellspacing="0"> - <tr> - <th align="center">Master</th> - <th align="center">Borrowables</th> - </tr> - <tr> - <td> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_Master.png"/> - </td> - <td> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_5.png"/> - </td> - </tr> - </table> - <p>Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the - <i>Compare With > Branch, Tag or Reference</i> action : - </p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_With_Master_1.png"/> - </p> - <p>and compare with master :</p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_With_Master_2.png"/> - </p> - <p>This shows us all differences between our local copy and the master branch that were made since the 'branching' point.</p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Merge.png"/> - </p> - <p>Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. - <b>Regular</b> elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are - <b>incoming</b> differences, decorated with a blue arrow ( - <img border="0" src="./../images/EMF_Compare_Incoming_Change.gif"/>) or a derived icon, and - <b>outgoing</b> differences decorated with a green arrow ( - <img border="0" src="./../images/EMF_Compare_Outgoing_Change.gif"/>) or a derived icon. - </p> - <p> - <b>Incoming</b> differences are changes that were made in the remote branch (here, - <i>master</i>) since the branching point (common ancestor). - - <b>Outgoing</b> differences are changes taht were made in the local copy (here, the - <i>borrowables</i> branch) since the branching point. - </p> - <p>There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences.</p> - <p>The interface also lets you display the common ancestor of both models through the - <img border="0" src="./../images/EMF_Compare_Ancestor.gif"/> icon. For example, if we select the - <b>Book</b> class, we can see how it looks like on all three versions : - </p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Merge_Book_Ancestor.png"/> - </p> - <p>You can navigate through the differences using the appropriate actions, either the previous ( - <img border="0" src="./../images/EMF_Compare_Prev_Diff.gif"/>) or the next ( - <img border="0" src="./../images/EMF_Compare_Next_Diff.gif"/>) difference. - </p> - <p>The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through - <img border="0" src="./../images/EMF_Compare_Copy_All.gif"/> or merge them one after the other through - <img border="0" src="./../images/EMF_Compare_Copy.gif"/>. - </p> - <p>Merging - <b>all</b> differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on - <i>master</i>, the right side). We will then select all - <i>incoming</i> differences one after the other and merge them one by one. This gives us our merged model : - </p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Merged.png"/> - </p> - <p>Notice that - <i>merged</i> differences are displayed in - <i>italics</i> and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master. - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Known Bugs and Limitations.html b/plugins/org.eclipse.emf.compare.doc/doc/user/Known Bugs and Limitations.html deleted file mode 100644 index 3e8910931..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Known Bugs and Limitations.html +++ /dev/null @@ -1,56 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Known Bugs and Limitations</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Known_Bugs_and_Limitations">Known Bugs and Limitations</h1> - <h2 id="Project_names_and_location">Project names and location</h2> - <p> - <b>Project names should match their location</b> - </p> - <h3 id="Cause">Cause</h3> - <p>If you need to compare models that:</p> - <ul> - <li>reference another model in the same project (or another project which also meets the following point), and</li> - <li>are located in a project which name (as seen in their '.project' file) does not match their containing folder's name (case sensitive).</li> - </ul> - <p>Due to - <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=354801">Bug 354801</a>, we cannot properly support models that are located in Eclipse projects which identifier is distinct from their containing folder, case included. For example, if you have a project named - <i>EcoreModels</i>, it - <b>must</b> be contained in a folder named - <i>EcoreModels</i>. Any other name, even if changing only the case, such as - <i>ecoreModels</i>, will cause issues when comparing fragmented models (or any model which references another). - </p> - <p>Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.</p> - <h3 id="Observed_Symptoms">Observed Symptoms</h3> - <p>Symptoms vary, but they often include a NullPointerException somewhere in EMFSynchronizationModel such as :</p> - <pre>Caused by: java.lang.NullPointerException -at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108) -at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464) -at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165) -at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258) -</pre> - <h2 id="Models_out_of_the_workspace">Models out of the workspace</h2> - <p> - <b>The models should be imported within the workspace</b> - </p> - <h3 id="Cause_2">Cause</h3> - <p>Trying to compare models that are not present in the current Eclipse workspace from either the - <i>Git repositories</i> perspective, or from the - <i>Git Staging</i> view. - </p> - <p>Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface.</p> - <h3 id="Observed_Symptoms_2">Observed Symptoms</h3> - <p>Symptoms are mostly the same here as they would be with the limitation mentionned above regarding project names, and they usually include the same NullPointerException:</p> - <pre>Caused by: java.lang.NullPointerException -at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108) -at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464) -at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165) -at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258) -</pre> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Known Bugs and Limitations.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/user/Known Bugs and Limitations.mediawiki deleted file mode 100644 index 55af7c763..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Known Bugs and Limitations.mediawiki +++ /dev/null @@ -1,45 +0,0 @@ -= Known Bugs and Limitations = - -== Project names and location == - -'''Project names should match their location''' - -=== Cause === - -If you need to compare models that: -* reference another model in the same project (or another project which also meets the following point), and -* are located in a project which name (as seen in their '.project' file) does not match their containing folder's name (case sensitive). - -Due to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=354801 Bug 354801], we cannot properly support models that are located in Eclipse projects which identifier is distinct from their containing folder, case included. For example, if you have a project named ''EcoreModels'', it '''must''' be contained in a folder named ''EcoreModels''. Any other name, even if changing only the case, such as ''ecoreModels'', will cause issues when comparing fragmented models (or any model which references another). - -Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface. - -=== Observed Symptoms === - -Symptoms vary, but they often include a NullPointerException somewhere in EMFSynchronizationModel such as : - - Caused by: java.lang.NullPointerException - at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108) - at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464) - at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165) - at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258) - -== Models out of the workspace == - -'''The models should be imported within the workspace''' - -=== Cause === - -Trying to compare models that are not present in the current Eclipse workspace from either the ''Git repositories'' perspective, or from the ''Git Staging'' view. - -Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface. - -=== Observed Symptoms === - -Symptoms are mostly the same here as they would be with the limitation mentionned above regarding project names, and they usually include the same NullPointerException: - - Caused by: java.lang.NullPointerException - at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108) - at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464) - at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165) - at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258) diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Other Materials.html b/plugins/org.eclipse.emf.compare.doc/doc/user/Other Materials.html deleted file mode 100644 index 82d2836bc..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Other Materials.html +++ /dev/null @@ -1,17 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Other Materials</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <h1 id="Other_Materials">Other Materials</h1> - <ul> - <li> - <a href="http://www.eclipse.org/emf/compare/doc/features/videos/index.html">Videos of 2011 new features</a> - </li> - </ul> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Other Materials.mediawiki b/plugins/org.eclipse.emf.compare.doc/doc/user/Other Materials.mediawiki deleted file mode 100644 index 3fae0caff..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Other Materials.mediawiki +++ /dev/null @@ -1,3 +0,0 @@ -= Other Materials = - -*[http://www.eclipse.org/emf/compare/doc/features/videos/index.html Videos of 2011 new features] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Sample Use Case.html b/plugins/org.eclipse.emf.compare.doc/doc/user/Sample Use Case.html deleted file mode 100644 index bcdee659a..000000000 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Sample Use Case.html +++ /dev/null @@ -1,199 +0,0 @@ -<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/> - <title>Sample Use Case</title> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css"/> - <link type="text/css" rel="stylesheet" href="/help/topic/org.eclipse.emf.compare.doc/doc/resources/custom.css"/> - </head> - <body> - <p>With the following, we'll follow the life cycle of a metamodel describing a very basic library as it evolves separately in different branches. This will allow us to give more concrete examples of how EMF Compare can be used, and how it can help you.</p> - <h1 id="Creating_a_model">Creating a model</h1> - <p>For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations.</p> - <p>The name of our sample project will be "library". It contains a single folder "model" containing two models :</p> - <ul> - <li>library_Types.uml will contain our primitive types,</li> - <li>library.uml will contain our actual model.</li> - </ul> - <p>The two models will be commited to our git clone. The whole thing looks like this :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Setup.png"/> - </p> - <p>The model itself is a very simple library. Graphically speaking :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Model.png"/> - </p> - <p>Now that this initial model file has been committed, we'd like to improve it a little. For example :</p> - <ul> - <li>Add an - <i>alias</i> property to the - <i>Writer</i> class, - </li> - <li>Add a new - <i>History</i> Category, - </li> - <li>Rename the - <i>pages</i> property of - <i>Book</i> into - <i>length</i>. - </li> - </ul> - <p>Our model now looks like this :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Model_Changed.png"/> - </p> - <p>But how do we know exactly what changed? Let's compare this with the file from the Git Index :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_1.png"/> - </p> - <p>This will open a comparison editor that initially looks like the following :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_2.png"/> - </p> - <p>There are three main areas of interest in this editor.</p> - <ol> - <li>Displays a structured list of the differences detected between the current version of the model and the version that lies in the Git Index.</li> - <li>This will react to the selections in (1) and display the - <i>left</i> side of this comparison. As a rule of thumb, the - <i>left</i> is the - <i>local</i> version of the model. In this example, - <i>left</i> will then be the version we have modified in our workspace. This is originally empty, more on this section in the example just below. - </li> - <li>As above, this will react to selections in (1), but this time it will display the - <i>right</i> side of the comparison. This is generally the - <i>remote</i> version of the model; the version to which we've compared ours. In this case, this will represent the version of the model as it is in the Git Index. This is originally empty, more on this section in the example just below. - </li> - </ol> - <p>As stated above, (2) and (3) are initially empty. These two panels are there to display more information about the differences detected between our models. Let's select one of the differences displayed in (1) :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_3.png"/> - </p> - <ol> - <li>We've selected the difference corresponding to the addition of attribute - <b>alias</b> in the class - <b>Writer</b>. A double-click on this difference updated our two panes below. - </li> - <li> - <b>alias</b> has been added to the properties of Class - <b>Writer</b>. In the model, this corresponds to a change to the reference - <i>ownedAttributes</i> of the - <i>Writer</i> Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context. - </li> - <li>This displays all values of the reference outlined in (2) as they are in the - <i>left</i> model. This is where we see the new value, - <b>alias</b> outlined. - </li> - <li>As for (2), this will display the context of the selected difference. The same reference will usually be displayed in both (2) and (4).</li> - <li>This panel displays all values of the reference outlined in (4) as they are in the - <i>right</i> model. In here, we see the location of - <b>alias</b> outlined as an empty space. This rectangle is where the new value will be added if we merge it... Though in this case, it is not possible to merge towards the - <i>right</i> : it is a version located on a repository and is thus non-editable. - </li> - </ol> - <p>This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes.</p> - <h1 id="Branching">Branching</h1> - <p>Now, we'd like to create a new feature for our library : we'd like clients to be able to borrow our books. We'll branch our repository in order to create this new feature and name this new branch - <i>borrowables</i> : - </p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_4.png"/> - </p> - <p>Starting right away, we add the necessary new concepts to our model to represent the possibility of lending books. We "may" later need to have more than books to be lendable, so let's make a - <i>Borrowable</i> interface to hold this concept. We'll also need a - <i>Person</i> class, as well as a new data type to represent the person's birth date : - </p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_5.png"/> - </p> - <p>In a tree viewer, our models now look like (highlighted in red, the concepts we added with this step) :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_6.png"/> - </p> - <p>However, while we are working on our - <i>borrowables</i> branch, the - <i>master</i> branch may still evolve : other people on the project might be adding new concepts of their own, or we could be switching to the main branch for a high priority fix ourselves. Let's imagine that two features have been added since we branched our repository. First, someone needed to have the library hold not only Books, but also Magazines. Second, we needed the publication date of our Books and magazines to be recorded. - </p> - <p>The first of these two commits will add the following concepts to our - <i>master</i> branch's model : - </p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_7.png"/> - </p> - <p>While the second only adds a primitive type and a property :</p> - <p> - <img border="0" src="./../images/EMF_Compare_Use_Compare_8.png"/> - </p> - <h1 id="Merge">Merge</h1> - <p>If you have followed to this point, we now have two diverging branches, - <i>master</i> and - <i>borrowables</i> which both hold a different version of our - <i>library.uml</i> model. Here is how these two models look like at this point : - </p> - <table border="1" cellpadding="5" cellspacing="0"> - <tr> - <th align="center">Master</th> - <th align="center">Borrowables</th> - </tr> - <tr> - <td> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_Master.png"/> - </td> - <td> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_5.png"/> - </td> - </tr> - </table> - <p>Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the - <i>Compare With > Branch, Tag or Reference</i> action : - </p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_With_Master_1.png"/> - </p> - <p>and compare with master :</p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Use_Compare_With_Master_2.png"/> - </p> - <p>This shows us all differences between our local copy and the master branch that were made since the 'branching' point.</p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Merge.png"/> - </p> - <p>Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. - <b>Regular</b> elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are - <b>incoming</b> differences, decorated with a blue arrow ( - <img border="0" src="./../images/EMF_Compare_Incoming_Change.gif"/>) or a derived icon, and - <b>outgoing</b> differences decorated with a green arrow ( - <img border="0" src="./../images/EMF_Compare_Outgoing_Change.gif"/>) or a derived icon. - </p> - <pre>* '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor). -* '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point. -</pre> - <p>There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences.</p> - <p>The interface also lets you display the common ancestor of both models through the - <img border="0" src="./../images/EMF_Compare_Ancestor.gif"/> icon. For example, if we select the - <b>Book</b> class, we can see how it looks like on all three versions : - </p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Merge_Book_Ancestor.png"/> - </p> - <p>You can navigate through the differences using the appropriate actions, either the previous ( - <img border="0" src="./../images/EMF_Compare_Prev_Diff.gif"/>) or the next ( - <img border="0" src="./../images/EMF_Compare_Next_Diff.gif"/>) difference. - </p> - <p>The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through - <img border="0" src="./../images/EMF_Compare_Copy_All.gif"/> or merge them one after the other through - <img border="0" src="./../images/EMF_Compare_Copy.gif"/>. - </p> - <p>Merging - <b>all</b> differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on - <i>master</i>, the right side). We will then select all - <i>incoming</i> differences one after the other and merge them one by one. This gives us our merged model : - </p> - <p> - <img align="middle" border="0" src="./../images/EMF_Compare_Merged.png"/> - </p> - <p>Notice that - <i>merged</i> differences are displayed in - <i>italics</i> and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master. - </p> - </body> -</html>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/help/PLACEHOLDER b/plugins/org.eclipse.emf.compare.doc/help/PLACEHOLDER new file mode 100644 index 000000000..e69de29bb --- /dev/null +++ b/plugins/org.eclipse.emf.compare.doc/help/PLACEHOLDER diff --git a/plugins/org.eclipse.emf.compare.doc/plugin.xml b/plugins/org.eclipse.emf.compare.doc/plugin.xml index 1dca88cac..ead3f38ab 100644 --- a/plugins/org.eclipse.emf.compare.doc/plugin.xml +++ b/plugins/org.eclipse.emf.compare.doc/plugin.xml @@ -1,39 +1,4 @@ -<?xml version="1.0" encoding="UTF-8"?> -<?eclipse version="3.2"?> -<!-- -Copyright (c) 2006, 2013 Obeo. -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 +<?xml version='1.0' encoding='UTF-8' ?><?eclipse version="3.2"?> -Contributors: - Obeo - initial API and implementation ---> <plugin> - - <!-- ====================================================================== --> - <!-- Define primary TOC --> - <!-- ====================================================================== --> - - <extension point="org.eclipse.help.toc"> - <toc file="doc/toc.xml" primary="true"/> - </extension> - - -<!-- ============================================================================= --> -<!-- Define Javadoc locations --> -<!-- ============================================================================= --> - <extension point="org.eclipse.pde.core.javadoc"> - <javadoc path="doc.zip!/references/javadoc" archive="true"> - <plugin id="org.eclipse.emf.compare"/> - <plugin id="org.eclipse.emf.compare.diff"/> - <plugin id="org.eclipse.emf.compare.diff.edit"/> - <plugin id="org.eclipse.emf.compare.match"/> - <plugin id="org.eclipse.emf.compare.ui"/> - </javadoc> - </extension> - - - -</plugin> +</plugin>
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/faq/FAQ.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/FAQ.mediawiki index 165d98088..d59085ca3 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/faq/FAQ.mediawiki +++ b/plugins/org.eclipse.emf.compare.doc/src/FAQ.mediawiki @@ -1,6 +1,8 @@ -This FAQ will be aimed at EMF Compare 2 and subsequent versions. Since this version largely differs from the previous 1.* stream, answers related to version 1 cannot apply in most case. += FAQs = -= Users = +These FAQs will be aimed at EMF Compare 2 and subsequent versions. Since this version largely differs from the previous 1.* stream, answers related to version 1 cannot apply in most case. + +=== Users FAQ === ==== Which files should be compared via EMF Compare ? ==== @@ -10,7 +12,7 @@ This FAQ will be aimed at EMF Compare 2 and subsequent versions. Since this vers You may add your own extension using the <tt>Preferences view / General / Content-types</tt> and adding your file extension in the "XMI" content-type. -[[Image:./../images/EMF_Compare_XMI_Content_Type.png]] +[[Image:images/EMF_Compare_XMI_Content_Type.png]] ==== How to force text comparison? ==== @@ -18,7 +20,7 @@ You may add your own extension using the <tt>Preferences view / General / Conten '''A''' : There is no way to '''force''' textual comparison of EMF files. You can, however, switch back to a plain text comparison through the drop-down menu that is diplayed between the two halves of the compare editor : -[[Image:./../images/EMF_Compare_Text_Comparison.png]] +[[Image:images/EMF_Compare_Text_Comparison.png]] ==== EMF Compare compatibility ? ==== @@ -35,9 +37,9 @@ We strive to keep the [[./../overview/Overview.html#Compatibility|compatibility '''A''' : The [[./../user/Getting%20Started.html#Installing EMF Compare|Installation instruction]] present a set of update sites useable to install. The [http://www.eclipse.org/emf/compare/downloads/ Download page] lists more specific update sites if you wish to try one of the latest integration builds. -= Developers = +== Developers FAQ == -== How can I programmatically add my model file extension in EMF Compare so that it is called automatically ? == +=== How can I programmatically add my model file extension in EMF Compare so that it is called automatically ? === '''Q''' : How can I programatically add my model file extension to EMF Compare so that it is called automatically ? @@ -53,7 +55,7 @@ The [http://www.eclipse.org/emf/compare/downloads/ Download page] lists more spe </extension> </source> -== How can I use EMF Compare programmatically ? == +=== How can I use EMF Compare programmatically ? === '''Q''' : How can I use EMF Compare programmatically, to compare either files or "in-memory" objects? @@ -83,7 +85,7 @@ public void compare(File model1, File model2) { } </source> -== Can EMF Compare be used standalone ? == +=== Can EMF Compare be used standalone ? === '''Q''' : Is EMF Compare able to compare "in-memory" objects, and can it be run without Eclipse ? @@ -97,7 +99,7 @@ The following is the minimal set of dependencies you will need for EMF Compare. * org.eclipse.emf.compare 2.0 or higher * com.google.guava 11.0 (EMF Compare should also be compatible with Guava 12, 13 and 14 as far as we tested our integration) -== Custom data types are always marked as modified by EMF Compare == +=== Custom data types are always marked as modified by EMF Compare === '''Q''' : A model based on a custom meta-model always shows elements of a custom data type as being changed. How can I have EMF Compare behave correctly? @@ -126,13 +128,13 @@ Comparison comparison = EMFCompare.builder().setMatchEngine(new DefaultMatchEngi .createDefaultEObjectMatcher(UseIdentifiers.WHEN_AVAILABLE), comparisonFactory)).build().compare(scope); </source> -== Can I programmatically open a comparison editor or dialog ? == +=== Can I programmatically open a comparison editor or dialog ? === '''Q''' : I need to call EMF Compare programmatically from within my own plugin, but I'd like to be able to show my users a comparison editor. Is there a way? '''A''' : Since EMF Compare 2.1.0M4, there is. As the answer to this question is a little complex, it deserves [[./../developer/How%20To%20Open%20Compare%20Dialog%20With%20Comparison.html|its own page]]. -== Can I use custom identifiers for my objects ? == +=== Can I use custom identifiers for my objects ? === '''Q''' : I have my own custom elements, and I'd like to tell EMF Compare what to use to uniquely identify them. For example, their name. @@ -140,7 +142,7 @@ Comparison comparison = EMFCompare.builder().setMatchEngine(new DefaultMatchEngi How to do this is outlined on the [[./../developer/Default%20Behavior%20and%20Extensibility.html#Defining custom identifiers|Developer Guide]]. -== Can I ignore differences on a specific reference, or ignore ordering differences ? == +=== Can I ignore differences on a specific reference, or ignore ordering differences ? === '''Q''' : I want to ignore all differences on a given structural feature, can I tell EMF Compare not to look at these features?<br/> '''Q''' : EMF Compare detects many ''ordering'' differences on my models, but I do not care about them. Is there a way to ignore all ordering changes? diff --git a/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki new file mode 100644 index 000000000..1c7ad01e4 --- /dev/null +++ b/plugins/org.eclipse.emf.compare.doc/src/developer/developer-guide.mediawiki @@ -0,0 +1,669 @@ += Developer Guide = + +== Architecture == + +=== Comparison Process === + +[[Image:images/EMF_Compare_Process_Full.png|thumb|center|800px]] + +This is the overview of the comparison process as a whole. Each of the six phases of the comparison process of EMF Compare are briefly defined on the [[./../overview/Overview.html|Overview]], and a much more in-depth explanation will be given below, in our explanations of the [[./Default%20Behavior%20and%20Extensibility.html|default behavior]] of EMF Compare. + +=== Project Architecture === + +[[Image:images/EMF_Compare_2_Architecture.png|center]] + +EMF Compare is built on top of the Eclipse platform. We depend on the Eclipse Modeling Framework (EMF), the Eclipse Compare framework and, finally, Eclipse Team, the framework upon which the repository providers (EGit, CVS, Subversive...) are built. + +The EMF Compare extensions target specific extensions of the modeling framework: UML, the Graphical Modeling Framework (and its own extensions, papyrus, ecoretools, ...). + +Whilst we are built atop bricks that are tightly coupled with the eclipse platform, it should be noted that the core of EMF Compare can be run in a standalone application with no runtime dependencies towards Eclipse; as can EMF itself. + +=== The Comparison Model === +EMF Compare uses a single model, which root is a ''Comparison'' object, to represent all of the information regarding the comparison: matched objects, matched resources, detected differences, links between these references, etc. The root ''Comparison'' is created at the beginning of the Match process, and will undergo a set of successive refinings during the remainder of the Comparison: Diff, Equivalence, Dependencies... will all add their own information to the ''Comparison''. + +So, how exactly is represented all of the information the Comparison model can hold, and how to make sense of it all? + +===Match=== + +A ''Match'' element is how we represent that the ''n'' compared versions have elements that are basically the same. For example, if we are comparing two different versions ''v1'' and ''v2'' of a given model which look like: + +{| border="1" cellpadding="5" cellspacing="0" align="center" +|- +! align="center" | Master +! align="center" | Borrowables +|- +| [[Image:images/v1.png|center]] +| [[Image:images/v2.png|center]] +|} + +Comparing these two models, we'll have a Comparison model containing three matches: + +# library <-> library +# Book <-> Novel +# title <-> title + +In other words, the comparison model contains an aggregate of the two or three compared models, in the form of ''Match'' elements linking the elements of all versions together. Differences will then be detected on these ''Match'' and added under them, thus allowing us to know both: + +* what the difference is (for example, "attribute name has been changed from ''Book'' to ''Novel''"), and +* what the original elements were. + +==== Diff ==== + +''Diff'' elements are created during the differencing process in order to represent the actual modifications that can be detected within the source model(s). The ''Diff'' concept itself is only there as the super-class of the three main kind of differences EMF Compare can detect in a model, namely ''ReferenceChange'', ''AttributeChange'' and ''ResourceAttachmentChange''. We'll go back to these three sub-classes in a short while. + +Whatever their type, the differences share a number of common elements: +* a parent ''match'': differences are detected on a given ''Match''. Having a difference basically means that one of the elements paired through this ''Match'' differs from its "reference" side (see ''source'' description below). +* a ''source'': differences are detected on one side of their match. The source really only holds meaning in three-way comparisons, where a difference can be detected in either right or left. All differences detected through two-way comparisons have their source in the left side. This is because we always compare according to a "reference" side. During two-way comparisons, the reference side is the right: differences will always be detected on the left side as compared with the right side. During three-way comparisons though, differences can be detected on either left or right side as compared with their common ancestor; but never as compared to themselves (in other words, this is ''roughly'' equivalent to two two-way comparisons, first the left as compared to the origin, then the right as compared to the origin). +* a current ''state'': all differences start off in their initial ''unresolved'' state. The user can then choose to: +** merge the difference (towards either right or left, applying or reverting the difference in the process), in which case the difference becomes ''merged'', or +** discard it, thus marking the change as ''discarded''. For example, if there is a conflicting edit of a textual attribute, the user can decide that neither right nor left are satisfying, and instead settle for a mix of the two. +* a ''kind'': this is used by the engine to describe the type of difference it detected. Differences can be of four general types: +** ''Add'': There are two distinct things that EMF Compare considers as an "addition". First, adding a new element within the values of a '''multi-valued feature''' is undeniably an addition. Second, any change in a '''containment reference''', even if that reference is mono-valued, that represents a "new" element in the model is considered to be an addition. Note that this second case is an exception to the rule for ''change'' differences outlined below. +** ''Delete'': this is used as the counterpart of ''add'' differences, and it presents the same exception for '''mono-valued containment references'''. +** ''Change'': any modification to a '''mono-valued feature''' is considered as a ''change'' difference by the engine. Take note that containment references are an exception to this rule: no ''change'' will ever be detected on those. +** ''Move'': once again, two distinct things are represented as ''move'' differences in the comparison model. First, '''reordering''' the values of a multi-valued feature is considered as a series of MOVE: one difference for each moved value (EMF Compare computes the smallest number of differences needed between the two sides' values). Second, moving an object from '''one container to another''' (changing the containing feature of the EObject) will be detected as a ''move''. + +In order to ensure that the model stays coherent through individual merge operations, we've also decided to link differences together through a number of associations and references. For example, there are times when one difference cannot be merged without first merging another, or some differences which are exactly equivalent to one another. In no specific order: + +* ''dependency'': EMF Compare uses two oppposite references in order to track dependencies between differences. Namely, ''requires'' and ''requiredBy'' represent the two ends of this association. If the user has added a package ''P1'', then added a new Class ''C1'' within this package, we will detect both differences. However the addition of ''C1'' cannot be merged without first adding its container ''P1''. In such a case, the addition of ''C1'' '''requires''' the addition of ''P1'', and the later is '''requiredBy''' the former. +* ''refinement'': this link is mainly used by extensions of EMF Compare in order to create high-level differences to hide the complexity of the comparison model. For example, this is used by the UML extension of EMF Compare to tell that the three differences "adding an association ''A1''", "adding a property ''P1'' in association ''A1''" and "adding a property ''P2'' in association ''A1''" is actually one single high-level difference, "adding an association ''A1''". This high-level difference is '''refinedBy''' the others, which all '''refines''' it. +* ''equivalence'': this association is used by the comparison engine in order to link together differences which are equivalent in terms of merging. For example, Ecore has a concept of '''eOpposite''' references. Updating one of the two sides of an ''eOpposite'' will automatically update the other. In such an event, EMF Compare will detect both sides as an individual difference. However, merging one of the two will trigger the update of the other side of the ''eOpposite'' as well. In such cases, the two differences are set to be ''equivalent'' to one another. Merging one difference part of an equivalence relationship will automatically mark all of the others as ''merged'' (see ''state'' above). +* ''implication'': implications are a special kind of "directed equivalence". A difference D1 that is linked as "implied by" another D2 means that merging D1 requires us to merge D1 instead. In other words, D2 will be automatically merged if we merge D1, but D1 will not be automatically merged if we merge D2. Implications are mostly used with UML models, where subsets and supersets may trigger such linked changes. +* ''conflict'': during three-way comparisons, we compare two versions of a given model with their common ancestor. We can thus detect changes that were made in either left or right side (see the description of ''source'' above). However, there are cases when changes in the left conflict with changes in the right. For example, a class named "Book" in the origin model can have been renamed to "Novel" in the left model whereas it has been renamed to "Essay" in the right model. In such a case, the two differences will be marked as being in conflict with one another. + +As mentionned above, there are only three kind of differences that we will detect through EMF Compare, which will be sufficient for all use cases. ''ReferenceChange'' differences will be detected for every value of a reference for which we detect a change. Either the value was added, deleted, or moved (within the reference or between distinct references). ''AttributeChange'' differences are the same, but for attributes instead of references. Lastly, the ''ResourceAttachmentChange'' differences, though very much alike the ReferenceChanges we create for containment references, are specifically aimed at describing changes within the roots of one of the compared resources. + +==== Conflict ==== + +'''Conflict''' will only be detected during three-way comparisons. There can only be "conflicts" when we are comparing two different versions of a same model along with their common ancestor. In other words, we need to able to compare two versions of a common element with a "reference" version of that element. + +There are many different kinds of conflicts; to name a few: +* changing an element on one side (in any way, for example, renaming it) whilst that element has been removed from the other side +* changing the same attribute of an element on both sides, to different values (for example, renaming "Book" to "Novel" on the left while be renamed "Book" to "Essay" on the right) +* creating a new reference to an element on one side whilst it had been deleted from the other side + +Conflicts can be of two kinds. We call ''PSEUDO'' conflict a conflict where the two sides of a comparison have changed as compared to their common ancestor, but where the two sides are actually now equal. In other words, the end result is that the left is now equal to the right, even though they are both different from their ancestor. This is the opposite of ''REAL'' conflict where the value on all three sides is different. In terms of merging, pseudo conflicts do not need any particular action, whilst real conflicts actually need resolution. + +There can be more than two differences conflicting with each other. For example, the deletion of an element from one side will most likely conflict with a number of differences from the other side. + +==== Equivalence ==== + +EMF Compare uses '''Equivalence''' elements in order to link together a number of differences which can ultimately be considered to be the same. For example, ecore's ''eOpposite'' references will be maintained in sync with one another. As such, modifying one of the two references will automatically update the second one accordingly. The manual modification and the automatic update are two distinct modifications of the model, resulting in two differences detected. However, merging any of these two differences will automatically merge the other one. Therefore both are marked as being equivalent to each other. + +There can be more than two differences equivalent with each other; in which case all will be added to a single ''Equivalence'' object, representing their relations. + +== Core Concepts == + +=== Proxy Resolution === + +When cross-referencing objects from another resource, EMF may use proxies instead of the actual object. As long as you do not access the element in question, EMF does not need to load the resource in which it is contained. The proxy is kind of a placeholder that tells EMF what resource should be loaded, and which of this resource's objects referenced, when we actually need to access its value. + +Proxy resolution is generally transparent, but a lot of tools based on EMF do not consider these proxies as first-class citizens: they simply resolve it without considering that it might not be needed. On the other hand, EMF Compare will never resolve proxies except for those strictly necessary. Whatever the phase of comparison, we strive to never hold the whole model in memory. + +The [[./Default%20Behavior%20and%20Extensibility.html#Model Resolving|initial resolution phase]] is the most intensive in terms of proxy resolution and I/O operations. Though we will never hold the whole logical model in memory at any given time, we do resolve all cross-references of the compared resources, on all sides of the comparison. Since the logical model may be located in a lot of different files on disk, it might also be very heavy in memory if loaded at once. However, even if EMF Compare does resolve all fragments composing that logical model, it also unloads them as soon as the cross-references are registered. In other words, what we create is a dependency graph between the resources, not a loaded model. Afterwards, we only reload in memory those resources that have actually changed, and can thus contain differences. There will be proxies between these "changed" resources and the unchanged ones we have decided not to reload, but EMF Compare will never resolve these proxies again (and, in fact, will prevent their resolving from other tools). + +At the time of writing, the user interface will never resolve any proxies either. This might change in the future for a better user experience since proxies usually end up displayed in strange manners. + +=== Equality Helper === + +The equality helper is a very central concept of EMF Compare. Of course, EMF Compare's aim is to be able to compare objects together, objects which comparison is not trivial and cannot be done through a mere "equal or not" concept. However, we still need to be able to compare these objects at all time and, whenever possible, without a full-fledged comparison. + +The equality helper will be used in all phases of the comparison, from matching to merging (please see the [[./../overview/Overview.html|overview]] for a bird's eye view of the different comparison phases, or their detailled descriptions down below). The matching phase is precisely the time when EMF Compare is trying to match two-by-two the elements from one side to the elements from the other side. As such, we do not have -yet- the knowledge of whichi element matches with which other. However, for all subsequent phases, the equality helper will rely on information from the comparison itself (the ''Match'' elements) to make a fail-fast test for element 'equality'. + +When we do not have this information, the equality helper will resort to less optimal algorithms. For any object that is not an EMF EObject, we will use strict equality through ''=='' and ''Object#equals()'' calls. One of the cause for EMF Compare failing to match attribute values together is in fact the lack of implementation of the ''equals'' method on custom datatypes (see the [[FAQ.html#Custom data types are always marked as modified by EMF Compare|FAQ]] for more on that particular issue). + +Note that the equality helper will be used extensively, and that any performance hit or improvement here will make a huge difference for the whole comparison process. Likewise, any mistake you make when implementing a custom equality helper will introduce a lot of bugs. + +=== Comparison Scope === + +As seen above, EMF Compare consider proxies as real citizens of the EMF realm. This mainly shows in the matching mechanism. EMF Compare uses a scoping mechanism to determine which elements should be matched together, and which others should be ignored. Any element that is outside of the comparison scope will be ignored by the comparison engine and left alone (if it is a proxy, it won't even be loaded). This also means that we won't really have a way to compare these proxy (or otherwise out-of-scope values) when the Diff process encounters them. + +For example, an element that is outside of the comparison scope, but referenced by another element which ''is'' in the scope will need specific comparison means: we've ignored it during the matching phase, so we don't know which 'out-of-scope' element corresponds to which 'other out-of-scope' element. Consider the following: in the first model, a package ''P1'' contains another package ''P2''. In the right, a package ''P1' '' contains a package ''P2' ''. We've told EMF Compare that ''P2'' and ''P2' '' are out of the comparison scope. Now how do we determine that the reference from ''P1'' to ''P2'' has changed (or, in this example, that it did not change)? + +This is a special case that is handled by the IEqualityHelper. Specifically, when such cases are encountered, EMF Compare falls back to using the URI of the two objects to check for equality. This behavior can be changed by customizing the IEqualityHelper (see [[#Equality Helper|above]]). + +By default, the only thing that EMF Compare considers "out of scope" are Ecore's "EGenericType" elements. These are usually meaningless as far as comparison is concerned (as they are located in derived references and will be merged along with their "true" difference anyway). Please take note that, when used from the user interface, EMF Compare will narrow down the scope even further through the resolution of the [[developer/logical-model.html|logical model]] and determining which resources are actually candidates for differences. + +The comparison scope provides EMF Compare with information on the content of ResourceSets, Resources or EObjects, according to the entry point of the comparison. Take note that '''the scope is only used during the matching phase'''. The differencing phase only uses the result of the matching phase to proceed. + +=== Longest Common Subsequence === + +PENDING description of the algorithm, why do we use it, references + +== Default Behavior and Extensibility == + +All main components of EMF Compare have been designed for extensibility. Some are only extensible when comparing models through your own actions, some can be customized globally for a given kind of model or metamodel... We'll outline the customization options of all 6 comparison phases in this section. (Any dead link? Report them on the [http://www.eclipse.org/forums/index.php/f/164/ forum]!) + +=== Model Resolving === + +PENDING description of the phase, extensibility (use of the modelProviders extension point, custom ext point of compare) + +=== Match === + +Before we can compute differences between two versions of a same Object, we must determine which are actually the "same" Object. For example, let's consider that my first model contains a Package P1 which itself contains a class C1; and that my second model contains a package P1 which contains a class C1. It may seem obvious for a human reader that "P1" and "C1" are the same object in both models. However, since their features might have changed in-between the two versions (for example, the "C1" might now be abstract, or it could have been converted to an Interface), this "equality" is not that obvious for a computer. + +The goal of the "Match" phase is to discover which of the objects from model 2 match with which objects of model 1. In other words, this is when we'll say that two objects are one and the same, and that any difference between the two sides of this couple is actually a difference that should be reported as such to the user. + +By default, EMF Compare browses through elements that are within the scope, and matches them through their identifier if they have one, r through a distance mechanism for all elements that have none. If the scope contains resources, EMF Compare will first match those two-by-two before browsing through all of their contained objects. + +EMF Compare "finds" the identifier of given object through a basic function that can be found in [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/eobject/IdentifierEObjectMatcher.java#n268 IdentifierEObjectMatcher.DefaultIDFunction]. In short, if the object is a proxy, its identifier is its URI fragment. Otherwise its functional ID (in ecore, an attribute that serves as an identifier) takes precedence over its XMI ID (the identifier it was given in the XMI file). If the object is not a proxy and has neither functional nor XMI identifier, then the default behavior will simply pass that object over to the proximity algorithms so that it can be matched through its distance with other objects. + +PENDING: brief description of the proximity algorithm + +This behavior can be customized in a number of ways. + +==== Overriding the Match engine ==== + +The most powerful (albeit most cumbersome) customization you can implement is to override the match engine EMF Compare uses. To this end you can either [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/IMatchEngine.java implement the whole contract, ''IMatchEngine''], in which case you will have to carefully follow the javadoc's recommandations, or extend the [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java default implementation, ''DefaultMatchEngine'']. + +A custom match engine can be used for your model comparison needs: + +<source lang="java"> +// for standalone usage +IMatchEngine.Factory.Registry registry === MatchEngineFactoryRegistryImpl.createStandaloneInstance(); +// for OSGi (IDE, RCP) usage +// IMatchEngine.Factory.Registry registry === EMFCompareRCPPlugin.getMatchEngineFactoryRegistry(); +final IMatchEngine customMatchEngine === new MyMatchEngine(...); +IMatchEngine.Factory engineFactory === new MatchEngineFactoryImpl() { + public IMatchEngine getMatchEngine() { + return customMatchEngine; + } +}; +engineFactory.setRanking(20); // default engine ranking is 10, must be higher to override. +registry.add(engineFactory); +EMFCompare.builder().setMatchEngineFactoryRegistry(registry).build().compare(scope); +</source> + +==== Changing how resources are matched ==== + +By default, the logic EMF Compare uses to match resources together is very simple: if two resources have the same name (strict equality on the name, without considering folders), they match. When this is not sufficient, EMF Compare will look at the XMI ID of the resources' root(s). If the two resources share at least one root with an equal XMI ID, they match. + +This can be changed only by implementing your own subclass of the DefaultMatchEngine and overriding its resource matcher. The method of interest here is [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/match/DefaultMatchEngine.java#n319 DefaultMatchEngine#createResourceMatcher()]. + +==== Defining custom identifiers ==== + +In some cases, there might be ways to identify your objects via the use of "identifiers" that cannot be identified as such by the default mechanism. For example, you might want each of your objects to be matched through their name alone, or through the composition of their name and their type... This can be achieved through code by simply redefining the function EMF Compare uses to find the ID of an object. The following code will tell EMF Compare that the identifier of all "MyEObject" elements is their name, and that any other element should go through the default behavior. + +<source lang="java"> +Function<EObject, String> idFunction === new Function<EObject, String>() { + public String apply(EObject input) { + if (input instanceof MyEObject) { + return ((MyEObject)input).getName(); + } + // a null return here tells the match engine to fall back to the other matchers + return null; + } +}; +// Using this matcher as fall back, EMF Compare will still search for XMI IDs on EObjects +// for which we had no custom id function. +IEObjectMatcher fallBackMatcher === DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.WHEN_AVAILABLE); +IEObjectMatcher customIDMatcher === new IdentifierEObjectMatcher(fallBackMatcher, idFunction); + +IComparisonFactory comparisonFactory === new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); + +IMatchEngine matchEngine === new DefaultMatchEngine(customIDMatcher, comparisonFactory); +IMatchEngine.Factory.Registry registry === MatchEngineFactoryRegistryImpl.createStandaloneInstance(); +// for OSGi (IDE, RCP) usage +// IMatchEngine.Factory.Registry registry === EMFCompareRCPPlugin.getMatchEngineFactoryRegistry(); +engineFactory.setRanking(20); // default engine ranking is 10, must be higher to override. +registry.add(engineFactory); +EMFCompare.builder().setMatchEngineFactoryRegistry(registry).build().compare(scope); +</source> + +==== Ignoring identifiers ==== + +There are some cases where you do not want the identifiers of your elements to be taken into account when matching the objects. This can easily be done when calling for comparisons programmatically: + +'''Through code''' + +<source lang="java"> +IEObjectMatcher matcher === DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); +IComparisonFactory comparisonFactory === new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); + +IMatchEngine matchEngine === new DefaultMatchEngine(matcher , comparisonFactory); +EMFCompare.builder().setMatchEngine(matchEngine).build().compare(scope); +</source> + +'''From the user interface''' + +PENDING: preference page + +==== Refine the default Match result ==== + +If you are happy with most of what the default behavior does, but would like to refine some of it, you can do so by post-processing the result of the match phase. The original models are only used when matching, and will never be queried again afterwards. All remaining phases are incremental refinings of the "Comparison" model that's been created by the matching phase. + +As such, you can impact all of the differencing process through this. Within this post-processing implementation, you can: +* Remove ''Match'' elements +: no difference will be detected on those: neither additions, nor deletions, nor conflicts... They'll simply be entirely ignored by the remaining process. Do note that elements for which we have no match will be considered "distinct" by the innards of EMF Compare: if a couple "B<->B'" references a couple "C<->C'" through one of their references, but you have removed the ''Match'' "C<->C'", we will consider that this reference has been "changed" from C to C' and this difference within the references of B will be shown as such. +* Add new ''Match'' element +: the new couples of elements will be considered by the remaining comparison process and difference may be detected on them. +* Change existing ''Match'' elements +: unmatched elements have two or three associated ''Match'' objects. For example if you are comparing three version of a model which all contain a different version of a given package, and all three version change the name of this package: version 1 has package "P1", version 2 has package "P2" and version three has package "P3". This package is actually the same, but EMF Compare did not manage to match it. We will thus have three ''Match'' objects: one that references "P1" as ''left'', one that references "P2" as ''right'' and one that references "P3" as ''origin''. +: You may remove two of those three elements and change the third one so that it references P1 as ''left'', P2 as ''right'' and P3 as ''origin''. In such a case, those three will be considered to Match for the remainder of the comparison process. Make sure that there are not two different ''Match'' referencing the same object though, as this would yield unspecified results. + +Defining a custom post-processor requires you to implement [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/postprocessor/IPostProcessor.java IPostProcessor] and registering this sub-class against EMF Compare. The latter can be done via either an extension point, in which case it will be considered for '''all''' comparisons on models that match its enablement, or programmatically if you only want it active for your own actions: + +'''Through code''' + +The following registers a post-processor for all UML models. This post-processor will not be triggered if there are no UML models (matching the given namespace URI) within the compared scope. + +<source lang="java"> +IPostProcessor customPostProcessor === new CustomPostProcessor(); +IPostProcessor.Descriptor descriptor === new BasicPostProcessorDescriptorImpl(customPostProcessor, Pattern.compile("http://www.eclipse.org/uml2/\\d\\.0\\.0/UML"), null); + +PostProcessor.Registry registry === new PostProcessorDescriptorRegistryImpl(); +registry.put(CustomPostProcessor.class.getName(), descriptor); +Comparison comparison === EMFCompare.builder().setPostProcessorRegistry(registry).build().compare(scope); +</source> + +'''Through extension point''' + +This accomplishes the exact same task, but it registers the post-processor globally. Any comparison through EMF Compare on a scope that contains models matching the given namespace URI will trigger that post-processor. + +<source lang="xml"> +<extension point="org.eclipse.emf.compare.rcp.postProcessor"> + <postProcessor class="my.package.CustomPostProcessor"> + <nsURI value="http://www.eclipse.org/uml2/\\d\\.0\\.0/UML"> + </nsURI> + </postProcessor> +</source> + +=== Diff === + +Now that the Matching phase has completed and that we know how our objects are coupled together, EMF Compare no longer requires the two (or three) input models. It will no longer iterate over them or the comparison's input scope. From this point onward, only the result of our comparison, the ''Comparison'' object, will be refined through the successive remaining phases, starting by the '''Diff'''. + +The goal of this phase is to iterate over all of our ''Match'' elements, be they unmatched (only one side has this object), couples (two of the three sides contain this object) or trios (all three sides have this object) and compute any difference that may appear between the sides. For example, an object that is only on one side of the comparison is an object that has been added, or deleted. But a couple might also represent a deletion: during three way comparisons, if we have an object in the common ancestor (origin) and in the left side, but not in the right side, then it has been deleted from the right version. However, this latter example might also be a conflict: we have determined that the object has been removed from the right side... but there might also be differences between the original version and the "left" version. + +The differencing phase does not care about conflicts though: all it does is refine the comparison to tell that this particular ''Match'' has ''n'' diffs: one ''DELETE'' difference on the right side, and ''n'' differences on the left. Detecting conflicts between these differences will come at a later time, during the conflict resolution phase. + +Customizations of this phase usually aim at ignoring specific differences. + +==== Overriding the Diff engine ==== + +As is the case for the Match phase, the most powerful customization you can implement for the differencing process is to override the diff engine EMF Compare uses. To this end you can either [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffEngine.java implement the whole contract, ''IDiffEngine''], in which case you will have to carefully follow the javadoc's recommandations, or extend the [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DefaultDiffEngine.java default implementation, ''DefaultDiffEngine'']. + +A custom diff engine can then be used for your comparisons: + +<source lang="java"> +IDiffEngine customDiffEngine === new MyDiffEngine(...); +EMFCompare.builder().setDiffEngine(customDiffEngine).build().compare(scope); +</source> + +==== Changing the FeatureFilter ==== + +One of the differencing engine's responsibilities is to iterate over all features of a given object in order to check for potential differences on its value(s). However, there are some features that we decide do ignore by default: derived features, transient features... or some features on which we would like to check for ordering changes even though they are marked as non-ordered. + +The logic to determine whether a feature should be checked for differences has been extracted into its own class, and is quite easy to alter. For example, if you would like to ignore the ''name'' feature of your elements or never detect any ordering change: + +<source lang="java"> +IDiffProcessor diffProcessor === new DiffBuilder(); +IDiffEngine diffEngine === new DefaultDiffEngine(diffProcessor) { + @Override + protected FeatureFilter createFeatureFilter() { + return new FeatureFilter() { + @Override + protected boolean isIgnoredReference(Match match, EReference reference) { + return reference ==== EcorePackage.Literals.ENAMED_ELEMENT__NAME || + super.isIgnoredReference(match, reference); + } + + @Override + public boolean checkForOrderingChanges(EStructuralFeature feature) { + return false; + } + }; + } +}; +EMFCompare.builder().setDiffEngine(diffEngine).build().compare(scope); +</source> + +You could also [[#Changing the Diff Processor|change the diff processor]] to achieve a similar goal. The difference between the two approaches is that changing the ''FeatureFilter'' will ignore the structural feature altogether, whereas replacing the diff processor would let EMF Compare check the feature and detect that diff, but ignore the notification that there is a change. + +==== Changing the Diff Processor ==== + +The diff engine browses over all of the objects that have been matched, and checks all of their features in order to check for changes between the two (or three) versions' feature values. When it detects a change, it delegates all of the corresponding information to its associated ''Diff Processor'', which is in charge of actually creating the ''Diff'' object and appending it to the resulting ''Comparison''. + +Replacing the ''Diff Processor'' gives you a simple entry point to ignore some of the differences the default engine detects, or to slightly alter the ''Diff'' information. You might want to ignore the differences detected on some references for example. Or you might want to react to the detected diff without actually creating the ''Comparison'' model... The implementation is up to you. You can either reimplement the [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/IDiffProcessor.java whole contract] or extend the default implementation, [http://git.eclipse.org/c/emfcompare/org.eclipse.emf.compare.git/tree/plugins/org.eclipse.emf.compare/src/org/eclipse/emf/compare/diff/DiffBuilder.java ''DiffBuilder''] + +Here is a simple example that provides EMF Compare with a diff processor that will ignore all differences detected on the "name" attribute of our objects, yet keep the default behavior for all other differences. + +<source lang="java"> +IDiffProcessor customDiffProcessor === new DiffBuilder() { + @Override + public void attributeChange(Match match, EAttribute attribute, Object value, DifferenceKind kind, DifferenceSource source) { + if (attribute !== EcorePackage.Literals.ENAMED_ELEMENT__NAME) { + super.attributeChange(match, attribute, value, kind, source); + } + } +}; + +IDiffEngine diffEngine === new DefaultDiffEngine(customDiffProcessor); +EMFCompare.builder().setDiffEngine(diffEngine).build().compare(scope); +</source> + +==== Refine the default Diff result ==== + +The last possibility offered by EMF Compare to alter the result of the differencing phase is to post-process it. The remaining comparison phases -equivalence detection, detection of dependencies between diffs and conflict detection- all use the result of the Diff engine and refine it even further. As such, all of these phases can be impacted through the refining of the Diff result. + +Example uses of the post-processing would include: + +* Remove ''Diff'' elements +: If you'd rather code your logic to ignore differences here as a post-process instead of changing the ''FeatureFilter'' or ''IDiffProcessor''. Though that is not the best way to ignore differences, it can still be done here. + +* Add new ''Diff'' elements +: If you want to create new differences without implementing a whole differencing engine, new differences can still be created here as a post-process. You will need to implement the iteration over model elements and specific checks yourself though. This workaround can also be used to create new differences that the default differencing engine does not know. + +* Alter the detected differences +: If some of the differences have been detected in a way you do not like, and you did not use a custom ''IDiffProcessor'' to change the ''Diff'' information, you can do so here. + +The post-processor for the diff engine is implemented exactly in the same way as for the match engine post-processors (the interface and extension point are the same). Please refer to [[#Refine the default Match result|Refining the Match result]]. + +=== Equivalences === + +Now that the Differencing phase has ended, we've computed all of the individual differences within the compared models. However, all of these differences are still isolated, we now need to determine if there are any connections between them. + +An ''equivalence'' is one kind of potential connections between differences. For example, Ecore has a concept of ''eOpposite'' references, which be maintained in sync with one another. Modifying one of the two references will automatically update the other side of the opposition accordingly. Both the manual modification and the automatic update are considered as distinct modifications of the model when looking at it after the fact, resulting in two differences detected. However, merging any of these two differences will automatically merge the other one. Therefore, both are marked as being ''equivalent'' to each other. + +Though that is an example with two, more than two differences can be considered equivalent with each other. When we merge one difference, all of the other diffs that have been marked as being equivalent to it will be marked as ''MERGED'', though no actual work needs to be done to merge them : EMF will have automatically updated them when merging the first. + +Do note that EMF Compare detects and understand two different kind of relations that could be considered "equivalences". Described above are plain equivalences, when merging one of the differences will automatically update the model in such a way that all other sides of the equivalence are redundant and automatically merged. However, equivalences might not always be that easy. Let's take for example the case of UML : UML has concepts of ''subset'' and ''superset'' references. Adding an object into a subset will automatically update the related superset so that it also contains the added element. However, adding that same element to the superset will _not_ automatically update the related subset. + +This can be seen as a "directional" equivalence, where one difference D1 ''implies'' another D2, but is not ''implied by'' D2. Implications will be detected at the same time as the equivalences, but they do not use an ''Equivalence'' element, they are filled under the ''Diff#implies'' reference instead. + +==== Refine the default equivalences ==== + +This phase does not offer as many customization options as the previous ones; though post-processing should be enough for most needs. All of the phases that come after the differencing are further refinements of the comparison model, totally independent from one another. From here, any client of the API can refine the comparison model any way he'd like to, even by removing all of the default results. + +A few examples of customizations that could be made from here : +* Partly break existing equivalences +: You can modify the equivalences we've detected by default by removing elements from individual differences' equivalences (Diff#getEquivalence()) or by changing the ''Equivalence'' elements directly. +* Remove existing ''Equivalence'' elements +: If you'd rather remove the ''Equivalence'' elements altogether, it can also be done from here without impact down the line. The individual differences will be merged individually (potentially twice if EMF automatically updates the references) if the mergers do not have this to tell them what's equivalent to what. +* Detect your own equivalences +: If you have specific rules on your metamodel or implementation that make some differences redundant or otherwise fully equivalent to one another, you can add your own equivalences from here. + +The post-processor for the equivalence detection engine is implemented exactly in the same way as for the match engine post-processors (the interface and extension point are the same). Please refer to [[Refine the default Match result|Refining the Match result]]. + +=== Requirements === + +A requirement will be used to deal with structural constraints (to prevent dangling references or objects without parent) and to insure the model integrity. +A difference requires other ones if the merge of this one needs the other ones not to "break" the model. +The merge of a difference involves the merge of the required differences. All these differences will be merged by EMF Compare. +For example, the add of a reference requires the add of the referenced object and the add of the object containing this reference. + +{| cellspacing="1" cellpadding="1" border="1" +|- +! align="center" | Change kind +! align="center" | Reference kind to a graphical object +! align="left" | Requires: +|- +| rowspan="2" align="center" | ADD +| align="center" | content +| ADD of its container<br> DELETE of the origin value on the same containment mono-valued reference +|- +| align="center" | reference +| ADD of the target object<br> ADD of the source object e.g. The ADD of a reference to the target or source of an edge requires the ADD of the edge itself and the ADD of the target and source objects, the ADD of a reference to the semantic object from a graphical one requires the ADD of the graphical and semantic object. +|- +| align="center" | DELETE +| align="center" | content +| DELETE of the outgoing references and contained objects<br> DELETE/CHANGE of the incoming references<br> MOVE of the contained objects +|- +| align="center" | MOVE +| align="center" | content +| ADD of the new container of the object<br> MOVE of the new container of the object +|- +| align="center" | CHANGE +| align="center" | reference permutation +| ADD of the target object +|} + + +Requirements can be added during a post-process. + +=== Refinement === + +A refinement enables to group a set of unit differences into a macroscopic change. +<br>A unit difference refines a macroscopic one if it belongs to this macroscopic change. In other words, a macroscopic change is refined by a set of unit differences. +<br>The merge of a macroscopic change involves the merge of the refining differences. All these differences will be merged by EMF Compare. +<br>The use of the refinement allows to improve (simplify) the reading of the comparison from a business viewpoint, to accelerate the manual merging for the end-user and to insure some consistency. +<br>For example, the add of an association, in UML, is refined by the add of the UML Association itself but also the add of the UML properties with the update of references... + +Refinement can be added during a post-process. + +=== Conflicts === + +PENDING description of the phase, extensibility options (post-process) + +=== Merging === + +==== Which references are followed during merging ==== + +{| border="1" +|- +! +! Merge from Left to Right +! Merge from Right to Left +|- +! Source === Left +| align="center" | requires +| align="center" | requiredBy +|- +! Source === Right +| align="center" | requiredBy +| align="center" | requires +|} + + +PENDING how to provide custom mergers, override existing ones? + +=== User Interface === + +PENDING customize display of custom differences, add custom menu entries, add groups, add filters, add export options, provide custom content viewer + +== Using The Compare APIs == + +The main entry point of EMF Compare is the ''org.eclipse.emf.compare.EMFCompare'' class. It is what should be used in order to configure and launch a comparison. That is not all though. Once you have compared two models, you want to query the differences, maybe merge some of them, display the comparison result in the comparison editor... The following section will list the main entry points for each of these actions, along with a brief description of what can be done and what should be avoided. + +Most of these examples are set-up as "standalone" examples, and will include extra instructions for IDE use: pay attention to the environment in which you are using EMF Compare. Are you using it from an Eclipse plugin, in which case you'd like all of the extra features provided through extension points and contribution to be available to you? Or are you using it from a standalone environment, in which case you'd need to reduce the dependencies to the bare minimum and avoid OSGi-related code and extensions? + +=== Compare two models === + +==== Loading your models ==== + +Whether you wish to compare two or three models, the first thing you need is to load them. We won't detail in-depth how to do that as this is standard EMF practice, you might want to look at EMF tutorial for detailled instructions on this point. Here, we'll use a simple method that loads an xmi file at a given URL into a resourceSet, expecting the given URL to be an absolute file URL: + +<source lang="java"> +public void load(String absolutePath, ResourceSet resourceSet) { + URI uri === URI.createFileURI(absolutePath); + + resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); + + // Resource will be loaded within the resource set + resourceSet.getResource(uri, true); +} +</source> + +==== Creating the comparison scope ==== + +EMF Compare uses a scoping mechanism to determine which elements should be compared, and which others should be ignored. Any element that is outside of the comparison scope will be ignored by the comparison engine and left alone (if it is a proxy, it won't even be loaded). As such, extra care should be taken to determine the proper scope of the comparison or customize the IEqualityHelper to handle the specific elements you remove from the scope. Refer to the [[./Core%20Concepts.html#Comparison Scope|appropriate section]] above for more on the scoping mechanism. + +By default, the only thing that EMF Compare considers "out of scope" are Ecore's "EGenericType" elements. These are usually meaningless as far as comparison is concerned (as they are located in derived references and will be merged along with their "true" difference anyway). Other than that, Please note that EMF Compare will leave unresolved proxies alone: more on this can be found in the [[./Core%20Concepts.html#Proxy Resolution|related section]]. + +The default scope can be easily created through: + +<source lang="java"> +IComparisonScope scope === EMFCompare.createDefaultScope(resourceSet1, resourceSet2); +</source> + +==== Configuring the comparison ==== + +EMF Compare can be customized in a number of ways, the most important of which were described [[./Default%20Behavior%20and%20Extensibility.html|above]]. Most of them re-use the same entry point, the ''org.eclipse.emf.compare.EMFCompare'' class. We won't customize much here, please see the afore-mentionned section for extensibility means. + +All we will tell EMF Compare is not to use identifiers, and rely on its proximity algorithms instead (after all, we're comparing plain XMI files): + +<source lang="java"> +IEObjectMatcher matcher === DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); +IComparisonFactory comparisonFactory === new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); + +IMatchEngine.Factory matchEngineFactory === new MatchEngineFactoryImpl(matcher, comparisonFactory); +matchEngineFactory.setRanking(20); +IMatchEngine.Factory.Registry matchEngineRegistry === new MatchEngineFactoryRegistryImpl(); +matchEngineRegistry.add(factory); + +EMFCompare comparator === EMFCompare.builder().setMatchEngineFactoryRegistry(matchEngineRegistry).build(); + +</source> + +==== Putting it all together ==== + +The following takes two input xmi files, loads them in their own resource sets, then calls the comparison without using identifiers: + +<source lang="java"> +public Comparison compare(File model1, File model2) { + // Load the two input models + ResourceSet resourceSet1 === new ResourceSetImpl(); + ResourceSet resourceSet2 === new ResourceSetImpl(); + String xmi1 === "path/to/first/model.xmi"; + String xmi2 === "path/to/second/model.xmi"; + load(xmi1, resourceSet1); + load(xmi2, resourceSet2); + + // Configure EMF Compare + IEObjectMatcher matcher === DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); + IComparisonFactory comparisonFactory === new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); + IMatchEngine.Factory matchEngineFactory === new MatchEngineFactoryImpl(matcher, comparisonFactory); + matchEngineFactory.setRanking(20); + IMatchEngine.Factory.Registry matchEngineRegistry === new MatchEngineFactoryRegistryImpl(); + matchEngineRegistry.add(matchEngineFactory); + EMFCompare comparator === EMFCompare.builder().setMatchEngineFactoryRegistry(matchEngineRegistry).build(); + + // Compare the two models + IComparisonScope scope === EMFCompare.createDefaultScope(resourceSet1, resourceSet2); + return comparator.compare(scope); +} + +private void load(String absolutePath, ResourceSet resourceSet) { + URI uri === URI.createFileURI(absolutePath); + + resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xmi", new XMIResourceFactoryImpl()); + + // Resource will be loaded within the resource set + resourceSet.getResource(uri, true); +} +</source> + +==== Comparing from an Eclipse plugin ==== + +The above example is for standalone usage, and as such will require extra work if you wish to compare UML models, benefit from EMF Compare extensions, provide your own mergers... The following represents the same example, but uses IDE-specific utilities (can you spot the two differences?): + +<source lang="java"> +public Comparison compare(File model1, File model2) { + // Load the two input models + ResourceSet resourceSet1 === new ResourceSetImpl(); + ResourceSet resourceSet2 === new ResourceSetImpl(); + String xmi1 === "path/to/first/model.xmi"; + String xmi2 === "path/to/second/model.xmi"; + load(xmi1, resourceSet1); + load(xmi2, resourceSet2); + + // Configure EMF Compare + IEObjectMatcher matcher === DefaultMatchEngine.createDefaultEObjectMatcher(UseIdentifiers.NEVER); + IComparisonFactory comparisonFactory === new DefaultComparisonFactory(new DefaultEqualityHelperFactory()); + IMatchEngine matchEngine === new DefaultMatchEngine(matcher, comparisonFactory); + IMatchEngine.Factory.Registry matchEngineRegistry === EMFCompareRCPPlugin.getDefault().getMatchEngineFactoryRegistry(); + IPostProcessor.Descriptor.Registry<String> postProcessorRegistry === EMFCompareRCPPlugin.getDefault().getPostProcessorRegistry(); + EMFCompare comparator === EMFCompare.builder() + .setMatchEngineFactoryRegistry(matchEngineRegistry) + .setPostProcessorRegistry(postProcessorRegistry) + .build(); + + // Compare the two models + IComparisonScope scope === EMFCompare.createDefaultScope(resourceSet1, resourceSet2); + return comparator.compare(scope); +} + +private void load(String absolutePath, ResourceSet resourceSet) { + URI uri === URI.createFileURI(absolutePath); + + // Resource will be loaded within the resource set + resourceSet.getResource(uri, true); +} +</source> + +=== Query the differences === + +Once you have the result of a comparison (in the form of a ''Comparison'' object), what you are interested in are most likely the differences between your models. We will detail the merging process later on it its own section, but before anything we need to retrieve the list of differences of interest. Within the Comparison model, differences are spread under the elements on which they've been detected, more precisely, under the ''Match'' of the element on which they were detected. + +Let's use a complex example as reference. Consider the three following models: + +{| border="1" cellpadding="5" cellspacing="0" align="center" +|- +! colspan="2" align="center" | Origin +|- +| colspan="2" align="center" | [[Image:images/EMF_Compare_Origin_Model.png|center]] +|- +! align="center" | Left +! align="center" | Right +|- +| [[Image:images/EMF_Compare_Use_Compare_Master.png|center]] +| [[Image:images/EMF_Compare_Use_Compare_5.png|center]] +|} + +==== All differences ==== + +What we need is usually to retrieve the list of ''all'' differences, wherever they were detected, or whatever their source (the left model, or the right model). Instead of iterating all over the Comparison model to collect them, you can use: + +<source lang="java"> +List<Diff> differences === comparison.getDifferences(); +</source> + +==== Differences related to element X ==== + +Sometimes, we need to retrieve all of the differences that were detected on (or that are related to) a given model element. For example, with the above example, we might want to retrieve the list of all differences that relate to ''Borrowable''. Well, there are a number of them, which can all be collected through: + +<source lang="java"> +// borrowable is a reference on the like-named EObject +List<Diff> differencesOnBorrowable === comparison.getDifferences(borrowable); +</source> + +This will return a list containing a number of differences: + +* ''Borrowable'' has been added in the right model +* ''copies'' has been added to reference ''ownedProperties'' of Borrowable +* ''Borrowable'' has been added to the generalization reference of ''Book'' +* ''Borrowable'' has been added as the ''borrowed'' target of an association with ''Person'' + +In other words, this method will return differences '''under''' the target (here, ''copies'' has been added), as well as differences which '''changed value''' is the target. + +==== Filtering differences ==== + +EMF Compare depends on guava for many of its internals. A number of "common" difference filtering predicates have been extracted to the ''org.eclipse.emf.compare.utils.EMFComparePredicates'' utility class. Using this class, it is trivial to filter the list of differences so as to keep only those we are interested in. For example, what if we wish to retrieve the list of all '''non-conflictual''' differences that originate from the '''left''' side? (This is the case when you use the "copy all non-conflicting from left to right" action from the comparison editor for example.) + +<source lang="java"> +// Construct the predicate +Predicate<? super Diff> predicate === and(fromSide(DifferenceSource.LEFT), not(hasConflict(ConflictKind.REAL, ConflictKind.PSEUDO)); +// Filter out the diff that do not satisfy the predicate +Iterable<Diff> nonConflictualDifferencesFromLeft === filter(comparison.getDifferences(), predicate); +</source> + +Note that for clarity, we've made static references to a number of methods here. This particular snippet requires the following imports: + +<source lang="java"> +import static com.google.common.base.Predicates.and; +import static com.google.common.base.Predicates.not; +import static com.google.common.collect.Iterables.filter; +import static org.eclipse.emf.compare.utils.EMFComparePredicates.fromSide; +import static org.eclipse.emf.compare.utils.EMFComparePredicates.hasConflict; +</source> + +We strongly encourage you to look around more in these classes: ''Predicates'' provides a number of basic, general-purpose predicates while ''EMFComparePredicates'' provides EMF Compare specific predicates used throughout both core and user-interface of EMF Compare. + +=== Merge differences === + +PENDING how to re-implement ''copyDiff'' and ''copyAllNonConflicting'' + +entry points: org.eclipse.emf.compare.merge.IMerger and org.eclipse.emf.compare.merge.IBatchMerger + +=== Open a compare editor === + +PENDING description of the need (dialog and editor), link to [[developer/how-to-open-compare-dialog.html|appropriate page]] diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/How To Open Compare Dialog With Comparison.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/developer/how-to-open-compare-dialog.mediawiki index a76fa8891..0beaaeb47 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/How To Open Compare Dialog With Comparison.mediawiki +++ b/plugins/org.eclipse.emf.compare.doc/src/developer/how-to-open-compare-dialog.mediawiki @@ -1,4 +1,4 @@ -= How To Open Compare Dialog With Comparison = += How To Open Compare Dialog = This is only valid since release 2.1M4. diff --git a/plugins/org.eclipse.emf.compare.doc/doc/developer/Logical Model.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/developer/logical-model.mediawiki index 4ec5997fe..894d32846 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/developer/Logical Model.mediawiki +++ b/plugins/org.eclipse.emf.compare.doc/src/developer/logical-model.mediawiki @@ -1,6 +1,8 @@ = Logical Model = -== What is a logical model ? == +== Eclipse == + +=== What is a logical model ? === We name "logical model" a set of '''physical resources''' that form a coherent business-related model. For example, we could say that a given Java class forms a coherent logical model only when it is linked with all of its imported classes. @@ -10,7 +12,7 @@ If we take it in reverse, a logical model is a set of elements that reference ea {| |- -| align="center" | [[Image:./../images/Logical_Model.png|frame|center]] +| align="center" | [[Image:../images/Logical_Model.png|frame|center]] |- | align="center" | A Logical Model is a set of inter-related elements. |} @@ -19,36 +21,36 @@ When these elements are serialized on disk, they may be split across multiple fi {| |- -| align="center" | [[Image:./../images/Logical_Model_Split.png|frame|center]] +| align="center" | [[Image:../images/Logical_Model_Split.png|frame|center]] |- | align="center" | Logical Model split in the files ''A'', ''B'', ''C'', ''D'', ''E'', ''F'' and ''G''. |} -== Eclipse Team == +=== Eclipse Team === The Eclipse Team project (referred as "Team" in this document) provides an API named "model providers". This API allows implementers to define the semantics of what is a "logical model" in his case. In short, it allows us to link any number of physical resources to a given "starting" file. Technically, this is done through an extension point that can be implemented by anyone and that will adapt a file (a workspace ''IResource'') to a set of files (a Team ''ResourceTraversal''). The model providers can be queried by anyone who calls actions on workspace files in order to determine if this action can be done against a single file or if it should be executed against a set of files. -== Limitations == +=== Limitations === Team only provides the API to define logical models. It is then the responsibility of its clients to properly query the model provider when calling an action. In the context of EMF Compare, we are interested in the "compare" actions. These actions are contributed by the repository providers (CVS, EGit, Subversive, Subclipse, Clearcase...). It is their responsibility, within the code of these actions, to query the model providers in order to determine if the selected files can be compared alone... or if they need to be compared along with a set of others. * The CVS plugin does not consistently use it. For example, when using "compare with > latest from HEAD" on a file that is part of a logical model, it will 'see' the logical model and open the "synchronize" perspective instead of a compare editor : this is what's expected. However, when the user, from the synchronization view, asks to see the differences (right-click then select 'open in compare editor')... CVS will not query the logical model, comparing the file alone (see also [https://bugs.eclipse.org/bugs/show_bug.cgi?id=345415 bug 345415]). * The EGit, Subversive and Subclipse plugins never query the model providers for any comparison action. -= EMF Compare = +== EMF Compare == In the case of EMF Compare, the above limitations were a show-stopper. EMF models cannot simply be reduced to single files as that would totally break their consistency when trying to merge them. -== Chosen solution == +=== Chosen solution === EMF Compare now uses its own implementation aiming at this same goal, that we named ''synchronization model''. In short, instead of expecting the repository providers to query the model providers, EMF Compare will take the file (or set of files) that it is fed and expand it to the full logical model by querying the synchronization model. This custom implementation also allows us to not only resolve the whole logical model of a given physical file, but also to determine which '''parts''' of this model should be included in the comparison scope. Indeed, under the semantics of EMF, if we can determine that two physical files are binary identical in their two distinct revisions, then we also know that the part of the logical model they represent are identical themselves. There would be no need to compare them. This allows us to save both time and memory, killing two birds with one stone. -== How it works == +=== How it works === When the user selects a file ''A'' in his workspace and asks to compare it with a remote revision (for example, the "latest from HEAD"), the repository provider (CVS in this case) fetches the remote content of ''A'' in the selected revision (we'll call it ''A'''). Once the remote revision fetched, the repository provider considers his work finished and feeds EMF Compare the two files (A and A') and lets it begin his own work. This is fine and dandy when the logical model of A only spans a single file ... but if A references another file B, then the comparison will not be coherent as EMF Compare operates on the logical model, not on its serialized form. @@ -62,7 +64,7 @@ However, even if we can launch EMF Compare at this point, the synchronization mo In other words, the synchronization model allows us to compare models with a time and memory cost that is relative to the size of the actual changeset instead of having it depend on the input models size. -=== Example === +==== Example ==== Let's consider the following sample : @@ -70,24 +72,24 @@ Let's consider the following sample : |- ! colspan="2" align="center" | Origin |- -| colspan="2" align="center" | [[Image:./../images/EMFC_Logic_origin.png|center]] +| colspan="2" align="center" | [[Image:../images/EMFC_Logic_origin.png|center]] |- ! align="center" | Left ! align="center" | Right |- -| [[Image:./../images/EMFC_Logic_left.png|center]] -| [[Image:./../images/EMFC_Logic_right.png|center]] +| [[Image:../images/EMFC_Logic_left.png|center]] +| [[Image:../images/EMFC_Logic_right.png|center]] |} Each of the three sides is an EMF model composed of 7 fragments. ''Origin'' is the common ancestor of ''left'' and ''right''. The blue-colored fragments are those that actually present differences (so D and G have been modified in the "left" copy while only B has been modified in the "right" copy). In order to compare these three models together, we would normally need to load all 21 fragments in memory. However, with the help of the synchronization model we can narrow it down to the modified fragments only. What we'll really load, then, are the following fragments for each three sides : -[[Image:./../images/EMFC_Logic_loaded_fragments.png|center]] +[[Image:../images/EMFC_Logic_loaded_fragments.png|center]] In other words, we are actually only loading 9 fragments out of the initial 21. This amounts to 58% less memory usage if we consider all fragments to be of equal "weight". And this is only for small models; the ratio of saved memory really going up for extremely large models. Of course, all of these objects that we are not loading in memory are all objects that we no longer need to compare, bringing an incredible performance boost along with the memory gain. -=== Some numbers === +==== Some numbers ==== When we got EMF Compare 1.3 out, we did some performance snapshots of what we had on some UML models with known counts of elements. Here were the specifications of the structure of the three test models. "fragments" are the number of fragmented files, the rest are the UML elements contained by the samples (spread out within the fragments) : @@ -124,7 +126,7 @@ When we got EMF Compare 1.3 out, we did some performance snapshots of what we ha Following are the time and memory required to compare each of the model sizes (the model is copied, randomly modified, then the copy is compared with its original) with two versions of EMF Compare. The 'old' 1.3, and the 2.1 that fully uses the logical model capabilities. -==== EMF Compare 1.3 ==== +===== EMF Compare 1.3 ===== Note that these were "CPU time" measures : we used a Java profiler to measure the duration of the comparison process, without regard to the actual wall time : we measured the time that the CPU was active during this process. As EMF Compare 1 was not multi-threaded, this means that these figures are slightly lower than the time actually perceived by the user for the same action. (See [http://en.wikipedia.org/wiki/Wall_clock_time Wall Time] and [http://en.wikipedia.org/wiki/System_time System Time] on wikipedia.) @@ -139,13 +141,13 @@ Note that these were "CPU time" measures : we used a Java profiler to measure th These figures could be broken down in the following three main phases : -[[Image:./../images/EMFC_1.3_Perf_Breakdown.png|center]] +[[Image:../images/EMFC_1.3_Perf_Breakdown.png|center]] This meant that the memory management of EMF Compare was really limiting as soon as we were dealing with large models (more than 2GB of heap space needed to load models that "weigh" 50 MB on disk). Furthermore, the main time sink was the differencing process, and that could also be narrowed down to the fact that there were plainly too many object to compare : for two-way comparisons, we were loading the model twice, for three-way comparisons, three instances of the model were loaded in memory. Not only that, but we were iterating twice on all models (one for matching, one for differencing). The full report can be downloaded from [http://www.eclipse.org/emf/compare/doc/compare_scalability.pdf here]. -==== EMF Compare 2.1 ==== +===== EMF Compare 2.1 ===== Note that these are "wall time" measures : we used a stopwatch to time the duration of the comparison, from a click on the "compare with > each other" action to the opening of the comparison editor. @@ -166,16 +168,16 @@ These figures can be broken down in 5 main phases : # Differencing : The matching phase told us which elements were matching together (Class C1 in the left logical model with Class C1' in the right logical model for example). The differencing phase will try and determine whether those two elements are equal or if they present differences (for example, the name of the class changed from ''C1'' to ''C1''') # Post-processing : Now that we know all differences between the models, we still need to determine equivalences -two differences that represent the same change (for example, differences on opposite references)-, requirements -a difference depends on another (for example, the addition of a class C1 in package P1 depends on the addition of package P1)-, conflicts -a conflictual change has been made in the ''left'' and ''right'' models as compared to the origin... -[[Image:./../images/EMFC_2.1_Perf_Breakdown.png|center]] +[[Image:../images/EMFC_2.1_Perf_Breakdown.png|center]] Okay, this graph does not leave much to interpretation. The model resolving time totally dwarfs the other comparison phases. That was actually our aim for EMF Compare 2 : ''model resolving'' represents the bulk of the I/O operations of EMF Compare, and we aimed at reducing the actual comparison to the utmost minimum time. So not only are we greatly improving the memory cost (only 400MB of heap space to compare something that required more than 2GB with EMF Compare 1), but we also reduced the comparison time (and the scalability) to a great extent. -== Limitations == +=== Limitations === The use of our own implementation effectively allows us to bypass some of the aforementioned limitations since we no longer rely on the repository providers in our specific case. However, if we can enforce the coherence of the models during the comparison, this approach still does not take into account the other aspects of collaboration with models. Even if comparing and merging two linked models is fine, it is still the repository provider's responsibility to query Team's model providers in order to "commit", "push", or even "replace" the models as a whole instead of acting on single physical files. Thus, most of the limitations mentioned above still hold, though we fixed those that applied to comparison actions. -== Improvement Axes == +=== Improvement Axes === As shown with the [[#EMF Compare 2.1|above graphs]], the most important remaining time sink is the resolution of the logical model. This is partly due to the I/O operations performed during this phase, but first and foremost it is due to the parsing of the XMI representation of the files we used (UML fragments) as EMF models. EMF Compare needs to actually load all fragments of the logical model as EMF model fragments in order to determine their cross-resource references, which represent other parts of the logical model that will need in turn. This phase could be improved by parsing the raw XMI data to find all of these cross-resource references without parsing the actual EMF elements of which they are a part. diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/CompareUI.png b/plugins/org.eclipse.emf.compare.doc/src/images/CompareUI.png Binary files differindex 846a52457..846a52457 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/CompareUI.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/CompareUI.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/Diag_comp_diff.png b/plugins/org.eclipse.emf.compare.doc/src/images/Diag_comp_diff.png Binary files differindex 5e4a2dddd..5e4a2dddd 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/Diag_comp_diff.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/Diag_comp_diff.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_1.3_Perf_Breakdown.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_1.3_Perf_Breakdown.png Binary files differindex 5aa2f830c..5aa2f830c 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_1.3_Perf_Breakdown.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_1.3_Perf_Breakdown.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_2.1_Perf_Breakdown.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_2.1_Perf_Breakdown.png Binary files differindex f11a27e7f..f11a27e7f 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_2.1_Perf_Breakdown.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_2.1_Perf_Breakdown.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Compare_With.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Compare_With.png Binary files differindex d0182ffa6..d0182ffa6 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Compare_With.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Compare_With.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_left.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_left.png Binary files differindex 008a660a7..008a660a7 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_left.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_left.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_loaded_fragments.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_loaded_fragments.png Binary files differindex 059565945..059565945 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_loaded_fragments.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_loaded_fragments.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_origin.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_origin.png Binary files differindex 67d67322c..67d67322c 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_origin.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_origin.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_right.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_right.png Binary files differindex cd69468a1..cd69468a1 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMFC_Logic_right.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMFC_Logic_right.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_2_Architecture.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_2_Architecture.png Binary files differindex 46dba823b..46dba823b 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_2_Architecture.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_2_Architecture.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Ancestor.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Ancestor.gif Binary files differindex ff06855e7..ff06855e7 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Ancestor.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Ancestor.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Copy.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Copy.gif Binary files differindex db2b1e3d5..db2b1e3d5 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Copy.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Copy.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Copy_All.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Copy_All.gif Binary files differindex e029948cf..e029948cf 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Copy_All.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Copy_All.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Filters_Choice.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Filters_Choice.png Binary files differindex 7c7bc464f..7c7bc464f 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Filters_Choice.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Filters_Choice.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Choice.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Choice.png Binary files differindex a17fcbeb6..a17fcbeb6 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Choice.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Choice.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Default.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Default.png Binary files differindex 3e78a5bbe..3e78a5bbe 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Default.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Default.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Kind.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Kind.png Binary files differindex 512f7a7a0..512f7a7a0 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Kind.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Kind.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Side.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Side.png Binary files differindex 301b942c6..301b942c6 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Groups_Side.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Groups_Side.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Incoming_Change.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Incoming_Change.gif Binary files differindex c330c0c9f..c330c0c9f 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Incoming_Change.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Incoming_Change.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Logical_Compare_Action.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Logical_Compare_Action.png Binary files differindex c16d65367..c16d65367 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Logical_Compare_Action.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Logical_Compare_Action.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Logical_Compare_Result.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Logical_Compare_Result.png Binary files differindex 985193a18..985193a18 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Logical_Compare_Result.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Logical_Compare_Result.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Merge.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge.png Binary files differindex 6179809ca..6179809ca 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Merge.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Merge_Book_Ancestor.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge_Book_Ancestor.png Binary files differindex d2d62cc20..d2d62cc20 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Merge_Book_Ancestor.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merge_Book_Ancestor.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Merged.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merged.png Binary files differindex e760a5041..e760a5041 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Merged.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Merged.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Model_Resolving.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Model_Resolving.png Binary files differindex 3b2bfdb24..3b2bfdb24 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Model_Resolving.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Model_Resolving.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Next_Diff.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Next_Diff.gif Binary files differindex 79cda1359..79cda1359 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Next_Diff.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Next_Diff.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Origin_Model.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Origin_Model.png Binary files differindex 4fbcbba85..4fbcbba85 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Origin_Model.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Origin_Model.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Outgoing_Change.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Outgoing_Change.gif Binary files differindex 17ba1af4f..17ba1af4f 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Outgoing_Change.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Outgoing_Change.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Prev_Diff.gif b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Prev_Diff.gif Binary files differindex d5a96ec97..d5a96ec97 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Prev_Diff.gif +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Prev_Diff.gif diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Process_Full.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Process_Full.png Binary files differindex 331f8f9de..331f8f9de 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Process_Full.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Process_Full.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Text_Compare.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Compare.png Binary files differindex fe6cfe76c..fe6cfe76c 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Text_Compare.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Compare.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Text_Comparison.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Comparison.png Binary files differindex cccf3764f..cccf3764f 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Text_Comparison.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Text_Comparison.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_1.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_1.png Binary files differindex cb376a60f..cb376a60f 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_1.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_1.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_2.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_2.png Binary files differindex 782b2b389..782b2b389 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_2.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_2.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_3.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_3.png Binary files differindex 46b685086..46b685086 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_3.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_3.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_4.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_4.png Binary files differindex 8c185f460..8c185f460 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_4.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_4.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_5.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_5.png Binary files differindex 14258d3c1..14258d3c1 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_5.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_5.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_6.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_6.png Binary files differindex 5f5204bbc..5f5204bbc 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_6.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_6.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_7.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_7.png Binary files differindex b7f708de3..b7f708de3 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_7.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_7.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_8.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_8.png Binary files differindex 618d084b1..618d084b1 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_8.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_8.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_Master.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_Master.png Binary files differindex e5e13e1a2..e5e13e1a2 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_Master.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_Master.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_With_Master_1.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_With_Master_1.png Binary files differindex e97a3711e..e97a3711e 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_With_Master_1.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_With_Master_1.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_With_Master_2.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_With_Master_2.png Binary files differindex 7d0e58e91..7d0e58e91 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Compare_With_Master_2.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Compare_With_Master_2.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Model.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Model.png Binary files differindex 4a454c8fa..4a454c8fa 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Model.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Model.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Model_Changed.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Model_Changed.png Binary files differindex 3410e0c47..3410e0c47 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Model_Changed.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Model_Changed.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Setup.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Setup.png Binary files differindex 4c447f995..4c447f995 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_Use_Setup.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_Use_Setup.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_XMI_Content_Type.png b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_XMI_Content_Type.png Binary files differindex 74d662e86..74d662e86 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/EMF_Compare_XMI_Content_Type.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/EMF_Compare_XMI_Content_Type.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/Emf_logo.png b/plugins/org.eclipse.emf.compare.doc/src/images/Emf_logo.png Binary files differindex e5e02a210..e5e02a210 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/Emf_logo.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/Emf_logo.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/Logical_Model.png b/plugins/org.eclipse.emf.compare.doc/src/images/Logical_Model.png Binary files differindex bfe0be1e1..bfe0be1e1 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/Logical_Model.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/Logical_Model.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/Logical_Model_Split.png b/plugins/org.eclipse.emf.compare.doc/src/images/Logical_Model_Split.png Binary files differindex 226983b14..226983b14 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/Logical_Model_Split.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/Logical_Model_Split.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/Marketplace.png b/plugins/org.eclipse.emf.compare.doc/src/images/Marketplace.png Binary files differindex 797ba342e..797ba342e 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/Marketplace.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/Marketplace.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/V1.png b/plugins/org.eclipse.emf.compare.doc/src/images/V1.png Binary files differindex 70e0663ce..70e0663ce 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/V1.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/V1.png diff --git a/plugins/org.eclipse.emf.compare.doc/doc/images/V2.png b/plugins/org.eclipse.emf.compare.doc/src/images/V2.png Binary files differindex d83f133cd..d83f133cd 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/images/V2.png +++ b/plugins/org.eclipse.emf.compare.doc/src/images/V2.png diff --git a/plugins/org.eclipse.emf.compare.doc/src/index.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/index.mediawiki new file mode 100644 index 000000000..854b2cf70 --- /dev/null +++ b/plugins/org.eclipse.emf.compare.doc/src/index.mediawiki @@ -0,0 +1,16 @@ += Documentation = + +== User documentation == + +* [user/user-guide.html|User guide] +* [user/sample-use-case.html|Sample use case] + +== Developer documentation == + +* [developer/developer-guide.html|Developer guide] +* [developer/logical-model.html|Logical model] +* [developer/how-to-open-compare-dialog.html|How to open compare dialog] + +== FAQ == + +* [FAQ.html|FAQ]
\ No newline at end of file diff --git a/plugins/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css b/plugins/org.eclipse.emf.compare.doc/src/resources/bootstrap.css index 7d519a608..7d519a608 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/resources/bootstrap.css +++ b/plugins/org.eclipse.emf.compare.doc/src/resources/bootstrap.css diff --git a/plugins/org.eclipse.emf.compare.doc/doc/resources/bootstrap.js b/plugins/org.eclipse.emf.compare.doc/src/resources/bootstrap.js index 49aceca34..49aceca34 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/resources/bootstrap.js +++ b/plugins/org.eclipse.emf.compare.doc/src/resources/bootstrap.js diff --git a/plugins/org.eclipse.emf.compare.doc/doc/resources/custom.css b/plugins/org.eclipse.emf.compare.doc/src/resources/custom.css index 7bc3b38d1..7bc3b38d1 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/resources/custom.css +++ b/plugins/org.eclipse.emf.compare.doc/src/resources/custom.css diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Sample Use Case.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/user/sample-use-case.mediawiki index 0d1c6eba4..3ba7a571c 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Sample Use Case.mediawiki +++ b/plugins/org.eclipse.emf.compare.doc/src/user/sample-use-case.mediawiki @@ -1,6 +1,8 @@ += Sample use case = + With the following, we'll follow the life cycle of a metamodel describing a very basic library as it evolves separately in different branches. This will allow us to give more concrete examples of how EMF Compare can be used, and how it can help you. -= Creating a model = +== Creating a model == For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations. @@ -10,11 +12,11 @@ The name of our sample project will be "library". It contains a single folder "m The two models will be commited to our git clone. The whole thing looks like this : -[[Image:./../images/EMF_Compare_Use_Setup.png]] +[[Image:../images/EMF_Compare_Use_Setup.png]] The model itself is a very simple library. Graphically speaking : -[[Image:./../images/EMF_Compare_Use_Model.png]] +[[Image:../images/EMF_Compare_Use_Model.png]] Now that this initial model file has been committed, we'd like to improve it a little. For example : * Add an ''alias'' property to the ''Writer'' class, @@ -23,15 +25,15 @@ Now that this initial model file has been committed, we'd like to improve it a l Our model now looks like this : -[[Image:./../images/EMF_Compare_Use_Model_Changed.png]] +[[Image:../images/EMF_Compare_Use_Model_Changed.png]] But how do we know exactly what changed? Let's compare this with the file from the Git Index : -[[Image:./../images/EMF_Compare_Use_Compare_1.png]] +[[Image:../images/EMF_Compare_Use_Compare_1.png]] This will open a comparison editor that initially looks like the following : -[[Image:./../images/EMF_Compare_Use_Compare_2.png]] +[[Image:../images/EMF_Compare_Use_Compare_2.png]] There are three main areas of interest in this editor. # Displays a structured list of the differences detected between the current version of the model and the version that lies in the Git Index. @@ -40,7 +42,7 @@ There are three main areas of interest in this editor. As stated above, (2) and (3) are initially empty. These two panels are there to display more information about the differences detected between our models. Let's select one of the differences displayed in (1) : -[[Image:./../images/EMF_Compare_Use_Compare_3.png]] +[[Image:../images/EMF_Compare_Use_Compare_3.png]] # We've selected the difference corresponding to the addition of attribute '''alias''' in the class '''Writer'''. A double-click on this difference updated our two panes below. # '''alias''' has been added to the properties of Class '''Writer'''. In the model, this corresponds to a change to the reference ''ownedAttributes'' of the ''Writer'' Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context. @@ -50,31 +52,31 @@ As stated above, (2) and (3) are initially empty. These two panels are there to This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes. -= Branching = +== Branching == Now, we'd like to create a new feature for our library : we'd like clients to be able to borrow our books. We'll branch our repository in order to create this new feature and name this new branch ''borrowables'' : -[[Image:./../images/EMF_Compare_Use_Compare_4.png]] +[[Image:../images/EMF_Compare_Use_Compare_4.png]] Starting right away, we add the necessary new concepts to our model to represent the possibility of lending books. We "may" later need to have more than books to be lendable, so let's make a ''Borrowable'' interface to hold this concept. We'll also need a ''Person'' class, as well as a new data type to represent the person's birth date : -[[Image:./../images/EMF_Compare_Use_Compare_5.png]] +[[Image:../images/EMF_Compare_Use_Compare_5.png]] In a tree viewer, our models now look like (highlighted in red, the concepts we added with this step) : -[[Image:./../images/EMF_Compare_Use_Compare_6.png]] +[[Image:../images/EMF_Compare_Use_Compare_6.png]] However, while we are working on our ''borrowables'' branch, the ''master'' branch may still evolve : other people on the project might be adding new concepts of their own, or we could be switching to the main branch for a high priority fix ourselves. Let's imagine that two features have been added since we branched our repository. First, someone needed to have the library hold not only Books, but also Magazines. Second, we needed the publication date of our Books and magazines to be recorded. The first of these two commits will add the following concepts to our ''master'' branch's model : -[[Image:./../images/EMF_Compare_Use_Compare_7.png]] +[[Image:../images/EMF_Compare_Use_Compare_7.png]] While the second only adds a primitive type and a property : -[[Image:./../images/EMF_Compare_Use_Compare_8.png]] +[[Image:../images/EMF_Compare_Use_Compare_8.png]] -= Merge = +== Merge == If you have followed to this point, we now have two diverging branches, ''master'' and ''borrowables'' which both hold a different version of our ''library.uml'' model. Here is how these two models look like at this point : @@ -83,40 +85,40 @@ If you have followed to this point, we now have two diverging branches, ''master ! align="center" | Master ! align="center" | Borrowables |- -| [[Image:./../images/EMF_Compare_Use_Compare_Master.png|center]] -| [[Image:./../images/EMF_Compare_Use_Compare_5.png|center]] +| [[Image:../images/EMF_Compare_Use_Compare_Master.png|center]] +| [[Image:../images/EMF_Compare_Use_Compare_5.png|center]] |} Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the ''Compare With > Branch, Tag or Reference'' action : -[[Image:./../images/EMF_Compare_Use_Compare_With_Master_1.png|center]] +[[Image:../images/EMF_Compare_Use_Compare_With_Master_1.png|center]] and compare with master : -[[Image:./../images/EMF_Compare_Use_Compare_With_Master_2.png|center]] +[[Image:../images/EMF_Compare_Use_Compare_With_Master_2.png|center]] This shows us all differences between our local copy and the master branch that were made since the 'branching' point. -[[Image:./../images/EMF_Compare_Merge.png|center]] +[[Image:../images/EMF_Compare_Merge.png|center]] -Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:./../images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:./../images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon. +Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:../images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:../images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon. * '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor). * '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point. There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences. -The interface also lets you display the common ancestor of both models through the [[Image:./../images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions : +The interface also lets you display the common ancestor of both models through the [[Image:../images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions : -[[Image:./../images/EMF_Compare_Merge_Book_Ancestor.png|center]] +[[Image:../images/EMF_Compare_Merge_Book_Ancestor.png|center]] -You can navigate through the differences using the appropriate actions, either the previous ([[Image:./../images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:./../images/EMF_Compare_Next_Diff.gif]]) difference. +You can navigate through the differences using the appropriate actions, either the previous ([[Image:../images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:../images/EMF_Compare_Next_Diff.gif]]) difference. -The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:./../images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:./../images/EMF_Compare_Copy.gif]]. +The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:../images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:../images/EMF_Compare_Copy.gif]]. Merging '''all''' differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on ''master'', the right side). We will then select all ''incoming'' differences one after the other and merge them one by one. This gives us our merged model : -[[Image:./../images/EMF_Compare_Merged.png|center]] +[[Image:../images/EMF_Compare_Merged.png|center]] Notice that ''merged'' differences are displayed in ''italics'' and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master. diff --git a/plugins/org.eclipse.emf.compare.doc/doc/user/Getting Started.mediawiki b/plugins/org.eclipse.emf.compare.doc/src/user/user-guide.mediawiki index 8a86b758c..0e9cb577d 100644 --- a/plugins/org.eclipse.emf.compare.doc/doc/user/Getting Started.mediawiki +++ b/plugins/org.eclipse.emf.compare.doc/src/user/user-guide.mediawiki @@ -1,12 +1,14 @@ -= Getting Started = += User Guide = -== Installing EMF Compare == +== Getting Started == + +=== Installing EMF Compare === '''Marketplace Client''' Using the bundled Eclipse marketplace client you can install EMF Compare in one click. Just type "emf compare", click on search, and then on install. -[[Image:./../images/Marketplace.png]] +[[Image:images/Marketplace.png]] '''Update Site''' @@ -105,11 +107,11 @@ Please note that the EMF Compare development team does its best to maintain down An empty cell indicates that the compatibility hasn't been tested for a particular combination. -== User Interface Breakdown == +=== User Interface Breakdown === The main points of interest are highlighted in the following picture : -[[Image:./../images/CompareUI.png|center|EMF Compare's basic user interface]] +[[Image:images/CompareUI.png|center|EMF Compare's basic user interface]] # Overview of the differences detected between the given two (or three) models. # First version of the compared models. @@ -121,15 +123,15 @@ The main points of interest are highlighted in the following picture : # Allows you to merge the single, currently selected difference in a given direction (left to right, or right to left). # Allows you to navigate through the detected differences. -== Usage == +=== Usage === Once installed, you can compare your files (locally or from any Version Control System) as usual using the '''compare with''' menu. -[[Image:./../images/EMFC_Compare_With.png|center]] +[[Image:images/EMFC_Compare_With.png|center]] The following displays the important part of a model life cycle with regards to the comparison. The full life cycle can be followed on [[./Sample%20Use%20Case.html| Sample Use Case]] -=== Compare with latest === +==== Compare with latest ==== For this test, we'll suppose that you are trying to use EMF Compare on UML models shared under git. This will not go in details about UML and Git. We'll assume that you know how to manipulate an UML model, create or clone a git repository, share a project under it and use standard Git operations. @@ -139,19 +141,19 @@ The name of our sample project will be "library". It contains a single folder "m The model itself is a very simple library. Graphically speaking : -[[Image:./../images/EMF_Compare_Use_Model.png]] +[[Image:images/EMF_Compare_Use_Model.png]] We commit this initial file as the original model. We then slightly modify it so that it now looks like : -[[Image:./../images/EMF_Compare_Use_Model_Changed.png]] +[[Image:images/EMF_Compare_Use_Model_Changed.png]] But how do we know exactly what changed? Let's compare this with the file from the Git Index : -[[Image:./../images/EMF_Compare_Use_Compare_1.png]] +[[Image:images/EMF_Compare_Use_Compare_1.png]] This will open a comparison editor that initially displays empty panels on its bottom half. Let's select one of the differences displayed on its top half : -[[Image:./../images/EMF_Compare_Use_Compare_3.png]] +[[Image:images/EMF_Compare_Use_Compare_3.png]] # We've selected the difference corresponding to the addition of attribute '''alias''' in the class '''Writer'''. A double-click on this difference updated our two panes below. # '''alias''' has been added to the properties of Class '''Writer'''. In the model, this corresponds to a change to the reference ''ownedAttributes'' of the ''Writer'' Class. This sub-panel indicates the actual reference that was changed in oder to remind us of the context. @@ -161,7 +163,7 @@ This will open a comparison editor that initially displays empty panels on its b This is useful in order to determine exactly what changed in our version, but serves no other purpose : merging changes here would only mean reverting back our modifications to the "clean" state from the repository. Let's commit our changes on the ''master'' branch. -=== Compare two differing branches === +==== Compare two differing branches ==== After that, our model can evolve, and evolve separately in multiple branches. Let's consider the case where we would have a ''master'' branch differing from a ''borrowables'' branch such as the two look like this (the branching point was the model we've already displayed above) : @@ -170,39 +172,177 @@ After that, our model can evolve, and evolve separately in multiple branches. Le ! align="center" | Master ! align="center" | Borrowables |- -| [[Image:./../images/EMF_Compare_Use_Compare_Master.png|center]] -| [[Image:./../images/EMF_Compare_Use_Compare_5.png|center]] +| [[Image:images/EMF_Compare_Use_Compare_Master.png|center]] +| [[Image:images/EMF_Compare_Use_Compare_5.png|center]] |} Before we continue working on our Borrowables branch, we'd like to retrieve all modifications that have been pushed to master. With the "Borrowables" branch checked out, we'll use the ''Compare With > Branch, Tag or Reference'' action : -[[Image:./../images/EMF_Compare_Use_Compare_With_Master_1.png|center]] +[[Image:images/EMF_Compare_Use_Compare_With_Master_1.png|center]] and compare with master : -[[Image:./../images/EMF_Compare_Use_Compare_With_Master_2.png|center]] +[[Image:images/EMF_Compare_Use_Compare_With_Master_2.png|center]] This shows us all differences between our local copy and the master branch that were made since the 'branching' point. -[[Image:./../images/EMF_Compare_Merge.png|center]] +[[Image:images/EMF_Compare_Merge.png|center]] -Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:./../images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:./../images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon. +Same as previously, you can navigate through the differences via the top panel, the structural view. There are three main kind of elements displayed here. '''Regular''' elements, that mimic the containment tree of your input models, are there to separate the various differences and let you know where they were actually detected. Then there are '''incoming''' differences, decorated with a blue arrow ([[Image:images/EMF_Compare_Incoming_Change.gif]]) or a derived icon, and '''outgoing''' differences decorated with a green arrow ([[Image:images/EMF_Compare_Outgoing_Change.gif]]) or a derived icon. '''Incoming''' differences are changes that were made in the remote branch (here, ''master'') since the branching point (common ancestor). '''Outgoing''' differences are changes taht were made in the local copy (here, the ''borrowables'' branch) since the branching point. There are no conflicts here, since UML uses computed identifiers (XMI ID) for the model elements. Thus, what looks like a conflict (the "Date" type that's been added on both branch in the types packages) is actually two distinct differences. -The interface also lets you display the common ancestor of both models through the [[Image:./../images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions : +The interface also lets you display the common ancestor of both models through the [[Image:images/EMF_Compare_Ancestor.gif]] icon. For example, if we select the '''Book''' class, we can see how it looks like on all three versions : -[[Image:./../images/EMF_Compare_Merge_Book_Ancestor.png|center]] +[[Image:images/EMF_Compare_Merge_Book_Ancestor.png|center]] -You can navigate through the differences using the appropriate actions, either the previous ([[Image:./../images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:./../images/EMF_Compare_Next_Diff.gif]]) difference. +You can navigate through the differences using the appropriate actions, either the previous ([[Image:images/EMF_Compare_Prev_Diff.gif]]) or the next ([[Image:images/EMF_Compare_Next_Diff.gif]]) difference. -The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:./../images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:./../images/EMF_Compare_Copy.gif]]. +The remaining two actions are those that actually interest us here we can either merge all non-conflicting differences to the local copy through [[Image:images/EMF_Compare_Copy_All.gif]] or merge them one after the other through [[Image:images/EMF_Compare_Copy.gif]]. Merging '''all''' differences is not what we seek : we want to keep the changes we made locally, not revert them to the state they had before the branching point (which is their current state on ''master'', the right side). We will then select all ''incoming'' differences one after the other and merge them one by one. This gives us our merged model : -[[Image:./../images/EMF_Compare_Merged.png|center]] +[[Image:images/EMF_Compare_Merged.png|center]] Notice that ''merged'' differences are displayed in ''italics'' and have a distinct icon. All that's left is to save, our model now contains both our local changes and the changes that were made on master. + +== Features == + +=== Handling Conflicts === + +PENDING + +=== Grouping Differences === + +This feature allows you to group differences together in the structural view according to a set predicate. By default, EMF Compare provides three distinct grouping strategies : + +[[Image:images/EMF_Compare_Groups_Choice.png]] + +; Default : Do not try and group differences together, display them as they were detected. + +[[Image:images/EMF_Compare_Groups_Default.png]] + +; By Kind : Group differences by their kind (''additions'', ''deletions'', ''moves'', ''changes''). + +[[Image:images/EMF_Compare_Groups_Kind.png]] + +; By Side : Group differences according to their side: left or right and a special group regrouping differences in conflicts with other differences together. + +[[Image:images/EMF_Compare_Groups_Side.png]] + +PENDING UPDATE, this is a demo displaying EMF Compare 1.3 +[http://www.eclipse.org/emf/compare/doc/features/videos/Groups/groups.htm Demo] + +PENDING : New grouping strategies can be provided to EMF Compare through extension points. + +=== Filtering Differences === + +This features allows you to filter differences out of the structural view according to a set predicate. By default, EMF Compare provides five distinct filters : + +[[Image:images/EMF_Compare_Filters_Choice.png]] + +; Pseudo conflicts differences : Filter out all pseudo conflicts differences(only in 3-way comparison). Enabled by default. +; Identical elements : Filter out all identical elements (elements with no differences). Enabled by default. +; Empty Resource Mappings : Filter out all resource mappings with no differences from the view. Enabled by default. +; Cascading differences : Filter out all differences that are contained under differences (except when in conflict). Enabled by default. + +PENDING UPDATE, this is a demo displaying EMF Compare 1.3 +[http://www.eclipse.org/emf/compare/doc/features/videos/Filters/filters.htm Demo] + +PENDING : New filters can be provided to EMF Compare through extension points. + +=== Text Attribute Comparison === + +Differences made into ''String''-typed attributes can be compared and merged directly as text from the compare interface through a simple right-click on the difference. + +[[Image:images/EMF_Compare_Text_Compare.png]] + +PENDING UPDATE, this demo displays EMF Compare 1.3 +[http://www.eclipse.org/emf/compare/doc/features/videos/Text%20compare/textCompare.htm Demo] + +=== Graphical Comparison === + +PENDING UPDATE + +Since the 1.2 release EMF compare provides the ability to compare models with graphical modelers. + +Have a look on the following demos : + +[[http://www.eclipse.org/emf/compare/doc/features/videos/EcoreTools-v2/EMFCompareEcoreTools.html | Demo : Comparing Ecore files with diagrams]] + +[[http://www.eclipse.org/emf/compare/doc/features/videos/Papyrus/EMFComparePapyrus.html | Demo : Comparing UML files with diagrams]] + +[[Image:images/Diag_comp_diff.png]] + +=== Logical Model === + +EMF Compare does not act simply on the selected files, but on their whole logical model (a given model can be split through multiple files through EMF ''control'' action). Thanks to that, if you try and compare a model file that reference other model files, the comparison will still be able to take these "other" files into account. For example, if you try and compare a ''genmodel'' file (that depends on its underlying ''ecore'' file) : + +[[Image:images/EMF_Compare_Logical_Compare_Action.png]] + +EMF Compare will actually consider both files when comparing : + +[[Image:images/EMF_Compare_Logical_Compare_Result.png]] + +PENDING UPDATE +[http://www.eclipse.org/emf/compare/doc/features/videos/LogicalModels/LogicalModels.html Demo] + +=== UML Specialization === + +PENDING + +[[http://www.eclipse.org/emf/compare/doc/features/videos/UML%20comparison/compareUml.htm | Demo : Specific support to encapsulate profiles and stereotypes diffs]] + +== Known Bugs and Limitations == + +=== Project names and location === + +'''Project names should match their location''' + +==== Cause ==== + +If you need to compare models that: +* reference another model in the same project (or another project which also meets the following point), and +* are located in a project which name (as seen in their '.project' file) does not match their containing folder's name (case sensitive). + +Due to [https://bugs.eclipse.org/bugs/show_bug.cgi?id=354801 Bug 354801], we cannot properly support models that are located in Eclipse projects which identifier is distinct from their containing folder, case included. For example, if you have a project named ''EcoreModels'', it '''must''' be contained in a folder named ''EcoreModels''. Any other name, even if changing only the case, such as ''ecoreModels'', will cause issues when comparing fragmented models (or any model which references another). + +Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface. + +==== Observed Symptoms ==== + +Symptoms vary, but they often include a NullPointerException somewhere in EMFSynchronizationModel such as : + + Caused by: java.lang.NullPointerException + at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108) + at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464) + at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165) + at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258) + +=== Models out of the workspace === + +'''The models should be imported within the workspace''' + +==== Cause ==== + +Trying to compare models that are not present in the current Eclipse workspace from either the ''Git repositories'' perspective, or from the ''Git Staging'' view. + +Note that this only applies to comparisons launched from within Eclipse, which would trigger the opening of the EMF Compare user interface. + +==== Observed Symptoms ==== + +Symptoms are mostly the same here as they would be with the limitation mentionned above regarding project names, and they usually include the same NullPointerException: + + Caused by: java.lang.NullPointerException + at org.eclipse.emf.compare.ide.ui.logical.RevisionedURIConverter.<init>(RevisionedURIConverter.java:108) + at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.resolveTraversal(EMFSynchronizationModel.java:464) + at org.eclipse.emf.compare.ide.ui.logical.EMFSynchronizationModel.createSynchronizationModel(EMFSynchronizationModel.java:165) + at org.eclipse.emf.compare.ide.ui.internal.structuremergeviewer.EMFCompareStructureMergeViewer.compareInputChanged(EMFCompareStructureMergeViewer.java:258) + +== Other Materials == + +*[http://www.eclipse.org/emf/compare/doc/features/videos/index.html Videos of 2011 new features] +
\ No newline at end of file |
