Package org.eclipse.emf.cdo.etypes.provider.annotation

# Class AnnotationItemProviderAdapterFactory

java.lang.Object
org.eclipse.emf.common.notify.impl.AdapterFactoryImpl
org.eclipse.emf.cdo.etypes.provider.annotation.AnnotationItemProviderAdapterFactory

All Implemented Interfaces:
  `AdapterFactory`, `ComposeableAdapterFactory`, `IChangeNotifier`, `IDisposable`

Direct Known Subclasses:
  `AnnotationItemProviderAdapterFactory.Reflective`

public abstract class AnnotationItemProviderAdapterFactory extends AdapterFactoryImpl implements ComposeableAdapterFactory, IChangeNotifier, IDisposable
A base class for supporting the specialization of `AnnotationItemProvider` and `StringToStringMapEntryItemProvider`.

The `EtypesItemProviderAdapterFactory` has a specialized `adapt` method that uses this class' `create(String)` method to create specialized implementations of this factory depending on the `annotation's source`. Before `creating` an AnnotationItemProvider or `creating` an StringToStringMapEntryItemProvider, EtypesItemProviderAdapterFactory will call `createAnnotationAdapter()` or `createStringToStringMapEntryAdapter()` on this factory. If this factory returns one, that one will be used. When EtypesItemProviderAdapterFactory creates an instance of this class, it calls `setParentAdapterFactory(EtypesItemProviderAdapterFactory)` so that this factory has a path back to the `getRootAdapterFactory()`. When EtypesItemProviderAdapterFactory is `disposed` it will `dispose` this factory.

By default, the `createAnnotationAdapter()` and the `createStringToStringMapEntryAdapter()` simply create an AnnotationItemProvider or an StringToStringMapEntryItemProvider, passing in this factory to the constructors.

All methods are implemented by this class, but the factory is abstract because it's expected that a derived class will specialize some of the methods. A derived class could override `doCreateAnnotationAdapter()`, `doCreateStringToStringMapEntryAdapter()`, or both in order to support specialized stateless adapters. A derived class could instead override `createAnnotationAdapter()`, `createStringToStringMapEntryAdapter()`, or both in order to support specialized stateful adapters. However, based on `AnnotationItemProvider.getAnnotationItemProviderAdapterFactory()` and `StringToStringMapEntryItemProvider.getAnnotationItemProviderAdapterFactory()`, both existing implementations are specialized to delegate back to this factory's `getPropertyDescriptor`, `getPropertyDescriptors`, and `createPropertyDescriptorDecorator` methods, so those are the methods most likely to be specialized.

It's generally expected that there will be a corresponding `AnnotationValidator` also associated with the annotation source which which this factory provides specialized adapters. That annotation validator's `assistant` is used to drive much of the specialized behavior.

Since:
  4.6

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static final class`
`AnnotationItemProviderAdapterFactory.DecategorizingItemPropertyDescritorDecorator`
A property descriptor created by `AnnotationItemProviderAdapterFactory#getPropertyDescriptors` and used by
invalid reference

    AnnotationItemProvider.SourcePropertyDescriptor#createPropertyValueWrapper(Object, Object)

.
`static final class`
`AnnotationItemProviderAdapterFactory.Group`
A convenient implementation of a property source with an explicit list of property descriptors that can be `populated` after construction.
`static class`
`AnnotationItemProviderAdapterFactory.ModeledItemPropertyDescriptorDecorator`
An item property descriptor decorator implementation used by `AnnotationItemProviderAdapterFactory.createPropertyDescriptorDecorator` to create an `assistant`-aware decorator.
`static class`
`AnnotationItemProviderAdapterFactory.Reflective`
A reflective implementation of an annotation item provider adapter factory.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected Adapter`
`annotationItemProvider`
This keeps track of the one adapter used for all `Annotation` instances.
`protected final BasicAnnotationValidator.Assistant`
`assistant`
The assistant provided in the constructor and returned by `getAssistant()`.
`protected final IChangeNotifier`
`changeNotifier`
This is used to implement `IChangeNotifier`.
`protected final Disposable`
`disposable`
This is used to implement `IDisposable`.
`protected EtypesItemProviderAdapterFactory`
`etypesItemProviderAdapterFactory`
This keeps track of the Etypes item provider adapter factory that delegates to this adapter factory.
`protected final EtypesSwitch<Adapter>`
`modelSwitch`
The switch that delegates to `createAnnotationAdapter()` or `createStringToStringMapEntryAdapter()` as appropriate.
`static final String`
`PRODUCT_GROUP`
`protected final ResourceLocator`
`resourceLocator`
The resource locator provided in the constructor and returned by `getResourceLocator()`.
`protected Adapter`
`stringToStringMapEntryItemProvider`
This keeps track of the one adapter used for all `Map.Entry` instances.
`protected final Collection<Object>`
`supportedTypes`
This keeps track of all the supported types checked by `isFactoryForType`.

## Constructor Summary

Constructors
Constructor
Description
`AnnotationItemProviderAdapterFactory(ResourceLocator resourceLocator, BasicAnnotationValidator.Assistant assistant)`
This constructs an instance given a resource locator and an annotation assistant.

## Method Summary

Modifier and Type
Method
Description
`Object`
`adapt(Object object, Object type)`
`Adapter`
`adapt(Notifier notifier, Object type)`
`void`
`addListener(INotifyChangedListener notifyChangedListener)`
This adds a listener.
`protected void`
`associate(Adapter adapter, Notifier target)`
`static AnnotationItemProviderAdapterFactory`
`create(String annotationSoure)`
Creates an annotation item provider adapter factory for the given `annotation source`.
`protected Adapter`
`createAdapter(Notifier target)`
`Adapter`
`createAnnotationAdapter()`
This creates an adapter for a `Annotation` by calling `doCreateAnnotationAdapter()`.
`IItemPropertyDescriptor`
`createPropertyDescriptorDecorator(IItemPropertyDescriptor propertyDescriptor, EObject eObject, String key, EStructuralFeature eStructuralFeature, Annotation annotation, ResourceLocator resourceLocator, EditingDomain domain)`
Creates a property descriptor decorator for the property descriptor of a `property` of the `modeled object` corresponding to the given key and feature for the given annotation.
`Adapter`
`createStringToStringMapEntryAdapter()`
This creates an adapter for a `Map.Entry` by calling `doCreateStringToStringMapEntryAdapter()`.
`void`
`dispose()`
This disposes all of the item providers created by this factory.
`protected Adapter`
`doCreateAnnotationAdapter()`
Creates the adapter for an `Annotation`.
`protected Adapter`
`doCreateStringToStringMapEntryAdapter()`
Creates the adapter for an annotation's `details`.
`void`
`fireNotifyChanged(Notification notification)`
This delegates to `changeNotifier` and to `etypesItemProviderAdapterFactory`.
`BasicAnnotationValidator.Assistant`
`getAssistant()`
Returns the assistant.
`String`
`getGroupName(EObject instance)`
Returns the group name associated with the given instance object.
`IItemPropertyDescriptor`
`getPropertyDescriptor(EObject eObject, String key, EStructuralFeature eStructuralFeature, Annotation annotation, ResourceLocator resourceLocator)`
Creates a property descriptor for a `property` of the `modeled object` corresponding to the given key and feature for the given annotation.
`List<IItemPropertyDescriptor>`
`getPropertyDescriptors(EObject eObject, Annotation annotation, ResourceLocator resourceLocator)`
Returns a list of property descriptors for the `modeled object` representing the given annotation.
`ResourceLocator`
`getResourceLocator()`
Returns the resource locator uses by this annotation item provider adapter factory.
`ComposeableAdapterFactory`
`getRootAdapterFactory()`
This returns the root adapter factory that contains this factory.
`boolean`
`isFactoryForType(Object type)`
`boolean`
`isShowInstances(Annotation annotation)`
Returns whether
invalid reference

    AnnotationItemProvider.SourcePropertyDescriptor#createPropertyValueWrapper(Object, Object)

should show the `modeled object` in the property tree.
`void`
`removeListener(INotifyChangedListener notifyChangedListener)`
This removes a listener.
`void`
`setParentAdapterFactory(EtypesItemProviderAdapterFactory etypesItemProviderAdapterFactory)`
Sets the Etypes item provider adapter factory that uses this factory.
`void`
`setParentAdapterFactory(ComposedAdapterFactory parentAdapterFactory)`
This operation is not supported.

### Methods inherited from class org.eclipse.emf.common.notify.impl.AdapterFactoryImpl

`adaptAllNew, adaptNew, createAdapter, resolve`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Methods inherited from interface org.eclipse.emf.common.notify.AdapterFactory

`adaptAllNew, adaptNew`

## Field Details

### PRODUCT_GROUP

public static final String PRODUCT_GROUP

See Also:
  - Constant Field Values

### changeNotifier

protected final IChangeNotifier changeNotifier
This is used to implement `IChangeNotifier`.

### supportedTypes

protected final Collection<Object> supportedTypes
This keeps track of all the supported types checked by `isFactoryForType`.

### disposable

protected final Disposable disposable
This is used to implement `IDisposable`.

### modelSwitch

protected final EtypesSwitch<Adapter> modelSwitch
The switch that delegates to `createAnnotationAdapter()` or `createStringToStringMapEntryAdapter()` as appropriate.

### assistant

protected final BasicAnnotationValidator.Assistant assistant
The assistant provided in the constructor and returned by `getAssistant()`.

### resourceLocator

protected final ResourceLocator resourceLocator
The resource locator provided in the constructor and returned by `getResourceLocator()`.

### etypesItemProviderAdapterFactory

protected EtypesItemProviderAdapterFactory etypesItemProviderAdapterFactory
This keeps track of the Etypes item provider adapter factory that delegates to this adapter factory.

### annotationItemProvider

protected Adapter annotationItemProvider
This keeps track of the one adapter used for all `Annotation` instances.

### stringToStringMapEntryItemProvider

protected Adapter stringToStringMapEntryItemProvider
This keeps track of the one adapter used for all `Map.Entry` instances.

## Constructor Details

### AnnotationItemProviderAdapterFactory

public AnnotationItemProviderAdapterFactory(ResourceLocator resourceLocator, BasicAnnotationValidator.Assistant assistant)
This constructs an instance given a resource locator and an annotation assistant.

## Method Details

### getAssistant

public BasicAnnotationValidator.Assistant getAssistant()
Returns the assistant.

The assistant is used by the implementations of `AnnotationItemProvider` and `StringToStringMapEntryItemProvider`.

Returns:
  the assistant.
See Also:
  - invalid reference

        AnnotationItemProvider.SourcePropertyDescriptor#getAssistant()

  - `AnnotationItemProvider.addReferencesPropertyDescriptor(Object)`
  - `StringToStringMapEntryItemProvider.createValuePropertyDescriptor(Map.Entry)`
  - `StringToStringMapEntryItemProvider.getKeyChoiceOfValues(Map.Entry)`

### isShowInstances

public boolean isShowInstances(Annotation annotation)
Returns whether
invalid reference

    AnnotationItemProvider.SourcePropertyDescriptor#createPropertyValueWrapper(Object, Object)

should show the `modeled object` in the property tree.

This implementation always returns `true` if `BasicAnnotationValidator.Assistant.getPropertyClasses(ModelElement)` returns more than one class.

Returns:
  whether the modeled objects should be explicitly shown in the property tree or should be omitted.
See Also:
  - invalid reference

        AnnotationItemProvider.SourcePropertyDescriptor#createPropertyValueWrapper(Object, Object)

### createAnnotationAdapter

public Adapter createAnnotationAdapter()
This creates an adapter for a `Annotation` by calling `doCreateAnnotationAdapter()`. Override this to create stateful adapters.

Returns:
  the adapter or `null`.

### doCreateAnnotationAdapter

protected Adapter doCreateAnnotationAdapter()
Creates the adapter for an `Annotation`. Typically this will be a subclass of `AnnotationItemProvider`. Override this to create stateless adapters. This implementation always simply creates an AnnotationItemProvider.

Returns:
  the adapter or `null`.

### createStringToStringMapEntryAdapter

public Adapter createStringToStringMapEntryAdapter()
This creates an adapter for a `Map.Entry` by calling `doCreateStringToStringMapEntryAdapter()`. Override this to create stateful adapters.

Returns:
  the adapter or `null`.

### doCreateStringToStringMapEntryAdapter

protected Adapter doCreateStringToStringMapEntryAdapter()
Creates the adapter for an annotation's `details`. Typically this will be a subclass of `StringToStringMapEntryItemProvider`. Override this to create stateless adapters. This implementation always simply creates an StringToStringMapEntryItemProvider.

Returns:
  the adapter or `null`.

### getRootAdapterFactory

public ComposeableAdapterFactory getRootAdapterFactory()
This returns the root adapter factory that contains this factory.

Specified by:
  `getRootAdapterFactory` in interface `ComposeableAdapterFactory`

### setParentAdapterFactory

public void setParentAdapterFactory(ComposedAdapterFactory parentAdapterFactory)
This operation is not supported. An AnnotationItemProviderAdapterFactory should not be directly composed. Instead `setParentAdapterFactory(EtypesItemProviderAdapterFactory)` should be called to set the Etypes item provider adapter factory that uses this factory.

Specified by:
  `setParentAdapterFactory` in interface `ComposeableAdapterFactory`

### setParentAdapterFactory

public void setParentAdapterFactory(EtypesItemProviderAdapterFactory etypesItemProviderAdapterFactory)
Sets the Etypes item provider adapter factory that uses this factory.

Parameters:
  `etypesItemProviderAdapterFactory` - the Etypes item provider adapter factory that uses this factory.

### getResourceLocator

public ResourceLocator getResourceLocator()
Returns the resource locator uses by this annotation item provider adapter factory.

Returns:
  the resource locator.

### isFactoryForType

public boolean isFactoryForType(Object type)

Specified by:
  `isFactoryForType` in interface `AdapterFactory`
Overrides:
  `isFactoryForType` in class `AdapterFactoryImpl`

### createAdapter

protected Adapter createAdapter(Notifier target)

Overrides:
  `createAdapter` in class `AdapterFactoryImpl`

### adapt

public Adapter adapt(Notifier notifier, Object type)

This implementation substitutes the factory itself as the key for the adapter.

Specified by:
  `adapt` in interface `AdapterFactory`
Overrides:
  `adapt` in class `AdapterFactoryImpl`

### adapt

public Object adapt(Object object, Object type)

Specified by:
  `adapt` in interface `AdapterFactory`
Overrides:
  `adapt` in class `AdapterFactoryImpl`

### associate

protected void associate(Adapter adapter, Notifier target)

This implementation also adds the adapter to the `disposable`, if it's an `IDisposable`.

Overrides:
  `associate` in class `AdapterFactoryImpl`

### addListener

public void addListener(INotifyChangedListener notifyChangedListener)
This adds a listener.

Specified by:
  `addListener` in interface `IChangeNotifier`

### removeListener

public void removeListener(INotifyChangedListener notifyChangedListener)
This removes a listener.

Specified by:
  `removeListener` in interface `IChangeNotifier`

### fireNotifyChanged

public void fireNotifyChanged(Notification notification)
This delegates to `changeNotifier` and to `etypesItemProviderAdapterFactory`.

Specified by:
  `fireNotifyChanged` in interface `IChangeNotifier`

### dispose

public void dispose()
This disposes all of the item providers created by this factory.

Specified by:
  `dispose` in interface `IDisposable`

### getPropertyDescriptors

public List<IItemPropertyDescriptor> getPropertyDescriptors(EObject eObject, Annotation annotation, ResourceLocator resourceLocator)
Returns a list of property descriptors for the `modeled object` representing the given annotation.

This implementation uses the `applicable properties` of the modeled object, calling `getPropertyDescriptor` to create each property descriptor. If that method returns one, it calls `createPropertyDescriptorDecorator` to decorate it, and then wraps that in a `AnnotationItemProviderAdapterFactory.DecategorizingItemPropertyDescritorDecorator`. This implementation is likely sufficient for most purposes.

Parameters:
  `eObject` - the modeled object.
  `annotation` - the annotation that it models.
  `resourceLocator` - the resource locator from which to acquire resources.

### getPropertyDescriptor

public IItemPropertyDescriptor getPropertyDescriptor(EObject eObject, String key, EStructuralFeature eStructuralFeature, Annotation annotation, ResourceLocator resourceLocator)
Creates a property descriptor for a `property` of the `modeled object` corresponding to the given key and feature for the given annotation.

This method adapts the object to an `IItemPropertySource`, `fetching` the property descriptor from that, if available. This implementation is sufficient if the model is generated or if the `ReflectiveItemProviderAdapterFactory` is available and provides sufficient support.

Parameters:
  `eObject` - the modeled object.
  `key` - the key of the property.
  `eStructuralFeature` - the structure feature of the property.
  `annotation` - the annotation that the modeled object models.
  `resourceLocator` - the resource locator from which to acquire resources.
Returns:
  a property descriptor or `null`.

### createPropertyDescriptorDecorator

public IItemPropertyDescriptor createPropertyDescriptorDecorator(IItemPropertyDescriptor propertyDescriptor, EObject eObject, String key, EStructuralFeature eStructuralFeature, Annotation annotation, ResourceLocator resourceLocator, EditingDomain domain)
Creates a property descriptor decorator for the property descriptor of a `property` of the `modeled object` corresponding to the given key and feature for the given annotation.

This implementation creates an instance of `AnnotationItemProviderAdapterFactory.ModeledItemPropertyDescriptorDecorator` which uses the assistant to `convert` the model object's value to a literal.

Parameters:
  `propertyDescriptor` - the property descriptor to be decorated.
  `eObject` - the modeled object.
  `key` - the key of the property.
  `eStructuralFeature` - the structure feature of the property.
  `annotation` - the annotation that the modeled object models.
  `resourceLocator` - the resource locator from which to acquire resources.
  `domain` - the editing domain to be used to modify the annotation.
Returns:
  a property descriptor or `null`.

### getGroupName

public String getGroupName(EObject instance)
Returns the group name associated with the given instance object. This will typically be the name of the `instances's class`. If instances are `shown`, this name will be shown for the `group of properties` associated with that instance.

Parameters:
  `instance` -
Returns:
  the group name associated with the given instance object.
See Also:
  - `isShowInstances(Annotation)`
  - `AnnotationItemProvider.SourcePropertyDescriptor.createPropertyValueWrapper(Object, Object)`

### create

public static AnnotationItemProviderAdapterFactory create(String annotationSoure)
Creates an annotation item provider adapter factory for the given `annotation source`.

Parameters:
  `annotationSoure` - the annotation source.
Returns:
  an annotation item provider adapter factory or `null` if there is no registered factory.