Latest revision as of 12:24, 5 March 2014

THIS PAGE IS ARCHIVED. IT IS PROBABLY OUTDATED AND WILL NOT BE UPDATED

Evolution Specification: Provide an adapter factory extension mechanism

Current status is ARCHIVED

Preamble

It enables to provide his own match adapter factory implementation.

Bug 404274 - Provide an adapter factory extension mechanism
Review 11551

Introduction

There is no actual mechanism to provide his own adapter factory. An extension point mechanism will be useful to allow users to provide their own adapter factories.

Detailed Specification

The aim is to provide a mechanism that allow users to provide their own adapter factory with a specific rank.

The AdapterFactory interface will be extended in order to manage ranking. The new extended AdapterFactory that the users will have to implement will be named RankedAdapterFactory.

The ComposedAdapterFactory will interrogate first the newly created emf compare adapter factory registry (composed of RankedAdapterFactories) to find an appropriate RankedAdapterFactory. If no appropriate adapter factory is found in the first registry, then registry will delegate his research to the "default" ComposedAdapterFactory registry.

With this mechanism you will able to provide, for example, your own CompareItemProviderAdapterFactory that will overrides the default CompareItemProviderAdapterFactory, in order to customize the labels, images... of the emf compare metamodel elements. Another use case you will be able to provide, is to extends the EcoreItemProviderAdapterFactory, in order to customize the labels, images... of the ecore metamodel elements.

Backward Compatibility and Migration Paths

Metamodel Changes

N/A

API Changes

New extension point:
- org.eclipse.emf.compare.edit

<extension-point id="adapterFactory" name="EMF Compare Adapter Factory" schema="schema/adapterFactory.exsd"/>

Example of use:

<extension 
   point="org.eclipse.emf.compare.edit.adapterFactory">
      <factory
            uri="http://www.eclipse.org/emf/compare"
            class="org.eclipse.emf.compare.test.adapterfactory.MyCompareItemProviderAdapterFactorySpec"
            ranking="10"
            supportedTypes=
              "org.eclipse.emf.edit.provider.IEditingDomainItemProvider
               org.eclipse.emf.edit.provider.IStructuredItemContentProvider
               org.eclipse.emf.edit.provider.ITreeItemContentProvider
               org.eclipse.emf.edit.provider.IItemLabelProvider
               org.eclipse.emf.edit.provider.IItemPropertySource
               org.eclipse.emf.compare.provider.IItemStyledLabelProvider
               org.eclipse.emf.compare.provider.IItemDescriptionProvider"/>
</extension>

New interfaces:
- org.eclipse.emf.compare.edit
  - org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactory

public interface RankedAdapterFactory extends AdapterFactory {
 
	int getRanking();
 
	void setRanking(int ranking);
}

- - org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactoryDescriptor
  - org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactoryDescriptor.Registry

public interface RankedAdapterFactoryDescriptor extends ComposedAdapterFactory.Descriptor {
 
        int getRanking();
 
	interface Registry extends ComposedAdapterFactory.Descriptor.Registry {
 
	}
}

New implementations:
- org.eclipse.emf.compare.rcp
  - org.eclipse.emf.compare.rcp.internal.adapterfactory.RankedAdapterFactoryDescriptorImpl

- org.eclipse.emf.compare.edit
  - org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactoryDescriptorRegistryImpl

User Interface Changes

N/A

Documentation Changes

This documentation will have to be updated:

New and Noteworthy
Developer Guide

Example of use

Suppose you want to customize the labels of the Matches elements of your emf compare model.

First, you will have to provide your own CompareItemProviderAdapterFactory that will overrides the CompareItemProviderAdapterFactory used by emf compare, and implements the new interface RankedAdapterFactory. You will need to overrides the createMatchAdapter() method to and provide your own MatchItemProvider.

public class MyCompareItemProviderAdapterFactorySpec extends CompareItemProviderAdapterFactorySpec implements RankedAdapterFactory {
 
        private int ranking;
 
        public int getRanking() {
		return ranking;
	}
 
	public void setRanking(int ranking) {
		this.ranking = ranking;
	}
 
	@Override
	public Adapter createMatchAdapter() {
		if (matchItemProvider == null) {
			matchItemProvider = new MyMatchItemProviderSpec(this);
		}
		return matchItemProvider;
	}
}
 
public class MyMatchItemProviderSpec extends MatchItemProviderSpec implements IItemStyledLabelProvider, IItemDescriptionProvider {
 
        @Override
	public String getText(Object object) {
             return " Customized Match : " + super.getText(object);
        }
}

Last, contribute a new extension of type org.eclipse.emf.compare.edit.adapterFactory in your plugin.xml:

<extension 
   point="org.eclipse.emf.compare.edit.adapterFactory">
      <factory
            uri="http://www.eclipse.org/emf/compare"
            class="org.eclipse.emf.compare.test.adapterfactory.MyCompareItemProviderAdapterFactorySpec"
            ranking="10"
            supportedTypes=
              "org.eclipse.emf.edit.provider.IEditingDomainItemProvider
               org.eclipse.emf.edit.provider.IStructuredItemContentProvider
               org.eclipse.emf.edit.provider.ITreeItemContentProvider
               org.eclipse.emf.edit.provider.IItemLabelProvider
               org.eclipse.emf.edit.provider.IItemPropertySource
               org.eclipse.emf.compare.provider.IItemStyledLabelProvider
               org.eclipse.emf.compare.provider.IItemDescriptionProvider"/>
</extension>

You can see the result of the example below. The right image shows the emf compare editor with the custom contribution:

Tests and Non-regression strategy

JUnit tests: EMFCompareAdapterFactoryTest.java in o.e.e.c.tests.

Implementation choices and tradeoffs

N/A

@@ Line 1: / Line 1: @@
+{{Template:EMF Compare Archive Notice}}
 = Evolution Specification: Provide an adapter factory extension mechanism  =
-Current status is '''DRAFT'''
+Current status is '''ARCHIVED'''
 == Preamble  ==
@@ Line 8: / Line 10: @@
 *[https://bugs.eclipse.org/bugs/show_bug.cgi?id=404274 Bug 404274]&nbsp;- Provide an adapter factory extension mechanism
+*[https://git.eclipse.org/r/#/c/11551/ Review 11551]
 == Introduction ==
@@ Line 15: / Line 18: @@
 == Detailed Specification  ==
-We propose to provide an adapter factory extension mechanism.
+The aim is to provide a mechanism that allow users to provide their own adapter factory with a specific rank.
-Any extension will be able to contribute an adapter factory.
+The AdapterFactory interface will be extended in order to manage ranking.
+The new extended AdapterFactory that the users will have to implement will be named RankedAdapterFactory.
-TODO
+The ComposedAdapterFactory will interrogate first the newly created emf compare adapter factory registry (composed of RankedAdapterFactories) to find an appropriate RankedAdapterFactory.
+If no appropriate adapter factory is found in the first registry, then registry will delegate his research to the "default" ComposedAdapterFactory registry.
+With this mechanism you will able to provide, for example, your own CompareItemProviderAdapterFactory that will overrides the default CompareItemProviderAdapterFactory, in order to customize the labels, images... of the emf compare metamodel elements. Another use case you will be able to provide, is to extends the EcoreItemProviderAdapterFactory, in order to customize the labels, images... of the ecore metamodel elements.
 == Backward Compatibility and Migration Paths ==
@@ Line 29: / Line 36: @@
 === API Changes ===
-* Add extension point:
+* New extension point:
+** org.eclipse.emf.compare.edit
 <source lang="xml">
 <extension-point id="adapterFactory" name="EMF Compare Adapter Factory" schema="schema/adapterFactory.exsd"/>
@@ Line 51: / Line 59: @@
 </extension>
 </source>
+* New interfaces:
+** org.eclipse.emf.compare.edit
+*** org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactory
+<source lang="java">
+public interface RankedAdapterFactory extends AdapterFactory {
+	int getRanking();
+	void setRanking(int ranking);
+}
+</source>
+*** org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactoryDescriptor
+*** org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactoryDescriptor.Registry
+<source lang="java">
+public interface RankedAdapterFactoryDescriptor extends ComposedAdapterFactory.Descriptor {
+        int getRanking();
+	interface Registry extends ComposedAdapterFactory.Descriptor.Registry {
+	}
+}
+</source>
+*New implementations:
+** org.eclipse.emf.compare.rcp
+*** org.eclipse.emf.compare.rcp.internal.adapterfactory.RankedAdapterFactoryDescriptorImpl
+** org.eclipse.emf.compare.edit
+*** org.eclipse.emf.compare.internal.adapterfactory.RankedAdapterFactoryDescriptorRegistryImpl
 === User Interface Changes ===
@@ Line 61: / Line 100: @@
 *New and Noteworthy
 *Developer Guide
+== Example of use ==
+Suppose you want to customize the labels of the Matches elements of your emf compare model.
+First, you will have to provide your own CompareItemProviderAdapterFactory that will overrides the CompareItemProviderAdapterFactory used by emf compare, and implements the new interface RankedAdapterFactory. You will need to overrides the createMatchAdapter() method to and provide your own MatchItemProvider.
+<source lang="java">
+public class MyCompareItemProviderAdapterFactorySpec extends CompareItemProviderAdapterFactorySpec implements RankedAdapterFactory {
+        private int ranking;
+        public int getRanking() {
+		return ranking;
+	}
+	public void setRanking(int ranking) {
+		this.ranking = ranking;
+	}
+	@Override
+	public Adapter createMatchAdapter() {
+		if (matchItemProvider == null) {
+			matchItemProvider = new MyMatchItemProviderSpec(this);
+		}
+		return matchItemProvider;
+	}
+}
+public class MyMatchItemProviderSpec extends MatchItemProviderSpec implements IItemStyledLabelProvider, IItemDescriptionProvider {
+        @Override
+	public String getText(Object object) {
+             return " Customized Match : " + super.getText(object);
+        }
+}
+</source>
+Last, contribute a new extension of type org.eclipse.emf.compare.edit.adapterFactory in your plugin.xml:
+<source lang="xml">
+<extension
+   point="org.eclipse.emf.compare.edit.adapterFactory">
+      <factory
+            uri="http://www.eclipse.org/emf/compare"
+            class="org.eclipse.emf.compare.test.adapterfactory.MyCompareItemProviderAdapterFactorySpec"
+            ranking="10"
+            supportedTypes=
+              "org.eclipse.emf.edit.provider.IEditingDomainItemProvider
+               org.eclipse.emf.edit.provider.IStructuredItemContentProvider
+               org.eclipse.emf.edit.provider.ITreeItemContentProvider
+               org.eclipse.emf.edit.provider.IItemLabelProvider
+               org.eclipse.emf.edit.provider.IItemPropertySource
+               org.eclipse.emf.compare.provider.IItemStyledLabelProvider
+               org.eclipse.emf.compare.provider.IItemDescriptionProvider"/>
+</extension>
+</source>
+You can see the result of the example below. The right image shows the emf compare editor with the custom contribution:
+[[Image:EMFCompare2_AdapterFactory_Default.png|alt Default Item Provider Adapter Factory]]
+[[Image:EMFCompare2_AdapterFactory_Custom.png|alt Custom Item Provider Adapter Factory]]
 == Tests and Non-regression strategy ==
@@ Line 69: / Line 169: @@
 N/A
-[[Category:EMF Compare]]

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "EMF Compare/Specifications/ExtensionPointForAdapterFactories"

Latest revision as of 12:24, 5 March 2014

Contents

Evolution Specification: Provide an adapter factory extension mechanism

Preamble

Introduction

Detailed Specification

Backward Compatibility and Migration Paths

Metamodel Changes

API Changes

User Interface Changes

Documentation Changes

Example of use

Tests and Non-regression strategy

Implementation choices and tradeoffs

Breadcrumbs

Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Difference between revisions of "EMF Compare/Specifications/ExtensionPointForAdapterFactories"

Latest revision as of 12:24, 5 March 2014

Contents

Evolution Specification: Provide an adapter factory extension mechanism

Preamble

Introduction

Detailed Specification

Backward Compatibility and Migration Paths

Metamodel Changes

API Changes

User Interface Changes

Documentation Changes

Example of use

Tests and Non-regression strategy

Implementation choices and tradeoffs